From c87c06f3f2ee1442465972f41d8c6d7d2c1bb5b3 Mon Sep 17 00:00:00 2001
From: Rahim <rahim.alwer@gmail.com>
Date: Tue, 14 Jul 2026 16:00:31 -0700
Subject: [PATCH] docs(design): organize decision records

---
 internal/decisions/README.md                  | 21 ++++++++++++++-----
 .../{ => player}/context-media-discovery.md   |  0
 .../player-container-separation.md            |  0
 .../decisions/{ => player}/provider-attach.md |  0
 .../signal-ownership.md}                      |  0
 .../reactive-state.md}                        |  0
 internal/decisions/{ => ui}/captions.md       |  0
 .../{ => ui}/gestures-as-components.md        |  0
 internal/design/spf/conventions/signals.md    |  2 +-
 9 files changed, 17 insertions(+), 6 deletions(-)
 rename internal/decisions/{ => player}/context-media-discovery.md (100%)
 rename internal/decisions/{ => player}/player-container-separation.md (100%)
 rename internal/decisions/{ => player}/provider-attach.md (100%)
 rename internal/decisions/{spf-signal-ownership.md => spf/signal-ownership.md} (100%)
 rename internal/decisions/{store-reactive-state.md => store/reactive-state.md} (100%)
 rename internal/decisions/{ => ui}/captions.md (100%)
 rename internal/decisions/{ => ui}/gestures-as-components.md (100%)

diff --git a/internal/decisions/README.md b/internal/decisions/README.md
index bad5a7d1..ac0ce8d6 100644
--- a/internal/decisions/README.md
+++ b/internal/decisions/README.md
@@ -1,4 +1,4 @@
-# Decisions
+# Internal decisions
 
 ADR-style records of single tactical decisions.
 
@@ -48,14 +48,25 @@ Why this came up. What problem triggered the decision. Link related decisions.
 Why this choice wins. Keep concise.
 ```
 
-## File Naming
+## Layout
+
+| Area | Decisions |
+| --- | --- |
+| `player/` | Provider, container, media discovery, and player composition |
+| `spf/` | Stream-processing ownership and coordination |
+| `store/` | State-management contracts |
+| `ui/` | Components, gestures, captions, and interaction |
+
+Put new records in the narrowest existing area. Add an area only when several related decisions belong together.
+
+## File naming
 
 Lowercase with hyphens, name after the subject of the decision:
 
 ```
-captions.md
-gestures-as-components.md
-provider-attach.md
+ui/captions.md
+ui/gestures-as-components.md
+player/provider-attach.md
 ```
 
 ## See Also
diff --git a/internal/decisions/context-media-discovery.md b/internal/decisions/player/context-media-discovery.md
similarity index 100%
rename from internal/decisions/context-media-discovery.md
rename to internal/decisions/player/context-media-discovery.md
diff --git a/internal/decisions/player-container-separation.md b/internal/decisions/player/player-container-separation.md
similarity index 100%
rename from internal/decisions/player-container-separation.md
rename to internal/decisions/player/player-container-separation.md
diff --git a/internal/decisions/provider-attach.md b/internal/decisions/player/provider-attach.md
similarity index 100%
rename from internal/decisions/provider-attach.md
rename to internal/decisions/player/provider-attach.md
diff --git a/internal/decisions/spf-signal-ownership.md b/internal/decisions/spf/signal-ownership.md
similarity index 100%
rename from internal/decisions/spf-signal-ownership.md
rename to internal/decisions/spf/signal-ownership.md
diff --git a/internal/decisions/store-reactive-state.md b/internal/decisions/store/reactive-state.md
similarity index 100%
rename from internal/decisions/store-reactive-state.md
rename to internal/decisions/store/reactive-state.md
diff --git a/internal/decisions/captions.md b/internal/decisions/ui/captions.md
similarity index 100%
rename from internal/decisions/captions.md
rename to internal/decisions/ui/captions.md
diff --git a/internal/decisions/gestures-as-components.md b/internal/decisions/ui/gestures-as-components.md
similarity index 100%
rename from internal/decisions/gestures-as-components.md
rename to internal/decisions/ui/gestures-as-components.md
diff --git a/internal/design/spf/conventions/signals.md b/internal/design/spf/conventions/signals.md
index 71cac4aa..8f8a1c2e 100644
--- a/internal/design/spf/conventions/signals.md
+++ b/internal/design/spf/conventions/signals.md
@@ -51,7 +51,7 @@ If a slot has more than one writer and **doesn't** fit one of these shapes, that
 
 **When the multi-writer is a behavior-decomposition smell** rather than a slot-decomposition smell: the writers share a decision-making domain (same inputs, same options) rather than reflecting genuinely different inputs. That's a signal of one purpose split across two behaviors, not one slot that needs splitting. See [`behaviors.md` → Decomposition check](behaviors.md#6-decomposition-check) for the diagnostic.
 
-A future lint rule may make shared writers more visible, but it must allow documented intent. See the [signal ownership decision](../../../decisions/spf-signal-ownership.md) for why composition does not enforce a writer-count invariant.
+A future lint rule may make shared writers more visible, but it must allow documented intent. See the [signal ownership decision](../../../decisions/spf/signal-ownership.md) for why composition does not enforce a writer-count invariant.
 
 ## Seeding 0-writer slots: `initialState` / `initialContext`