Install SDD: next slice of per-file specs

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CSM4FVUbnP4PJJ9sawMfLb

Author: claude

packages/the-framework/dashboard/components/Composer.test.SPEC.md

@@ -0,0 +1,40 @@
+What the tests cover: the shared prompt box and the controls around it.
+
+The control row:
+
+- The full form shows the presets button, the driver and model choice naming the current driver, the options gear, and — only once the box has text — the submit control.
+- The compact navbar form keeps the driver and model choice and the options gear, and still starts an agent from what is typed.
+- Inside an agent the driver and model choice is dropped while the rest of the row stays usable.
+- An option's explanation matches what it actually does, and Browser is disabled with a stated reason when the chosen driver is not Claude Code.
+
+Submitting:
+
+- Submit is absent until the box has text, then enabled, and hands the text out as an ordinary task.
+- The editor's keyboard shortcut submits the same way.
+- What is typed is mirrored out to the host as it changes.
+
+Presets:
+
+- A preset that must open an agent of its own marks its submission as such; an ordinary preset does not. What is submitted is the preset's rendered prompt, not its menu label.
+- Emptying the box drops the preset and its new-agent rule, so the next message is an ordinary task in the same agent.
+
+Carried drafts:
+
+- The launcher restores a draft carried from another device, as an ordinary task, taking it exactly once.
+- The carried draft is really in the editor and not merely in what submitting would send.
+- A composer sitting inside an agent does not consume a carried draft.
+
+Where the work runs:
+
+- A selected device that is offline blocks starting by both button and keyboard, and names the device in the reason, with no automatic fallback.
+- An online selected device leaves starting enabled with no warning.
+
+The in-agent options gear:
+
+- A live agent drops the gear entirely rather than opening an empty menu.
+- An ended agent offers exactly the options a resume can still arm — the publish ladder, auto-merge and Browser — while the prompt-shaping options and the choice of where the work runs stay out.
+- Changing one of those options writes the shared preference the resumed leg resolves when it starts.
+
+## Before modifying/creating SPEC.md files
+
+You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md

packages/the-framework/dashboard/components/NotificationsMenu.SPEC.md

@@ -0,0 +1,40 @@
+The single Notifications bell in the sidebar's utility footer, and the menu behind it. It makes the notification model legible by separating the two questions it used to blur: where a notification goes (Browser, Discord) and what the user wants to be notified about (Human Queue, New activity).
+
+## Business logic — TL;DR
+
+- **Two groups, one model** - "Deliver to" lists the delivery methods; "Notify me about" lists the categories. Every entry is a toggle stored in the user's preferences.
+- **The bell reflects reality, not intent** - it lights up (filled bell plus a dot) only when a method can actually deliver: Browser counts only once the browser has granted permission, Discord only once a webhook is configured. Otherwise it shows a crossed-out bell.
+- **Permission is asked at the moment of consent** - switching Browser on is what prompts the browser for notification permission; a browser that has blocked notifications shows the toggle disabled and says so.
+- **Both categories are optional** - "Human Queue" (an agent awaiting the user, or a pull request to review) defaults on as the baseline, but is a real toggle like any other; "New activity" (an agent started or finished) is the second category.
+
+## Business logic
+
+### The bell tells the truth about delivery
+
+#### User story
+
+The user wants one glance to answer "will The Framework actually reach me?" — not "did I once click a toggle".
+
+#### Business logic
+
+A delivery method counts as active only when it can deliver. Browser is active when the toggle is on and the browser has granted permission. Discord is active when the toggle is on and the daemon has a Discord webhook configured. The bell is filled and dotted when at least one method is active, and crossed out otherwise.
+
+Whether a webhook exists is read from the daemon and shared with the settings page, so configuring the credential there settles the bell here too. Until that first read lands the setup is assumed capable, so a correctly configured dashboard does not flicker to "off" on load.
+
+#### Rationale
+
+A Discord toggle switched on without a webhook configured used to light the bell for a channel that delivered nothing.
+
+### Each toggle explains itself
+
+#### User story
+
+The user opens the menu and should not have to guess what a method reaches them through or why it is unavailable.
+
+#### Business logic
+
+Every toggle carries a one-line description under its name. Browser says whether notifications are blocked in browser settings, whether the user still needs to allow them, or that it delivers desktop notifications while the dashboard is open. Discord either says it reaches the user with no dashboard open, or that it is not configured and points at Settings for the webhook. Human Queue and New activity each name the events they cover. A browser that does not support notifications at all simply omits the Browser method.
+
+## Before modifying/creating SPEC.md files
+
+You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md

packages/the-framework/dashboard/components/NotificationsMenu.test.SPEC.md

@@ -0,0 +1,9 @@
+What the tests cover: the menu presents delivery methods ("Deliver to": Browser, Discord) and categories ("Notify me about": Human Queue, New activity) as separate groups, with Human Queue a real toggle rather than a fixed always-on row; toggling any of them writes that preference through, including turning Human Queue off from its on-by-default state.
+
+Browser permission: switching Browser on while permission has not yet been decided prompts the browser for it, and a browser that has blocked notifications shows the "Blocked in your browser settings" hint.
+
+The bell's state read-out: it reads "Notifications on" when a method that can actually deliver is enabled and plain "Notifications" otherwise — Discord enabled with no webhook configured does not light it and instead explains that a webhook must be added in Settings, while a configured webhook does light it.
+
+## Before modifying/creating SPEC.md files
+
+You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md

packages/the-framework/dashboard/components/PromptEditor.SPEC.md

@@ -0,0 +1,90 @@
+The rich prompt editor: the box the user writes an agent's prompt in, with live markdown, typed triggers that pull in presets, macro tags, projects and files, and the send-key bindings.
+
+## Glossary
+
+- **chip** - an inserted reference or tag shown as one inline pill the user can select and delete in a single step. A chip is only a display: the prompt handed to the agent contains the plain text the chip stands for.
+- **macro tag** - one of the framework's repeated prompt tags, all written `<NAME>` (for example `<AWAIT>`, `<REVIEW_FILE>`).
+- **agent action** - a call the prompt can ask the agent to make, for example `showMultiSelect()`.
+
+## User story
+
+- The user writes what to build, and wants formatting, canned prompts, and references to repos and files without leaving the keyboard or memorising exact spellings.
+- The user wants to point an agent at a specific repo or file simply by mentioning it.
+
+## Business logic — TL;DR
+
+- **Four typed triggers** - `/` opens commands (presets, "New preset…", agent actions), `<` opens the macro tags, `@` opens the registered projects, `#` opens the open project's files. The placeholder spells all four out, so the editor teaches itself.
+- **Chips that mean plain text** - anything inserted from a menu shows as a chip but leaves the prompt text exactly as the agent will read it, so nothing downstream is affected by how it was typed.
+- **Mentioning is focusing** - picking a project or a file with `@` or `#` also adds it to the agent context; deleting that chip takes it back out, so the prompt and the Context list can never disagree.
+- **Presets load in place** - picking a preset replaces the editor's content with the preset's prompt, with no blocking confirmation; the surrounding form is told whether a typed draft was overwritten so it can point out that a single undo brings it back.
+- **Enter sends** - Enter and Ctrl/Cmd+Enter send; Shift+Enter inserts a line break. Enter yields wherever it already means something else: choosing from an open suggestion menu, a newline inside a code block, or confirming a text-input-method composition.
+- **Markdown while you type** - markdown shortcuts apply live and survive the round trip, and a single newline stays a line break so a preset's one-per-line block does not collapse into a paragraph.
+- **Grows with the prompt** - the box rests short and grows with its content up to a cap, then scrolls; a compact variant starts one line tall for the navbar's quick launch.
+- **Opening text is a draft, not a value** - text the editor is opened with is applied once, the moment the editor is ready, and never re-applied over what the user has since typed.
+
+## Business logic
+
+### Four typed triggers
+
+#### User story
+
+See `## User story`.
+
+#### Business logic
+
+Typing one of four characters opens a filtered menu:
+
+- `/` — commands. It lists the built-in presets under their slash names, then the user's own custom presets (hinted "saved preset"), then the open project's shared custom presets (hinted "project preset"), then "New preset…" which opens the create dialog with the prompt the user has written so far, then the agent actions. "New preset…" appears only on surfaces that have a create dialog, so the navbar's compact launch does not offer it.
+- `<` — the macro tags. Typing a character that matches nothing, or a space, closes the menu, so a stray `<` in ordinary prose is not a trap.
+- `@` — the registered projects, at most eight at a time; with none registered the menu says so instead of showing an empty list.
+- `#` — the open project's tracked files, repo-relative, at most eight at a time; with no files indexed the menu says so.
+
+Picking a preset loads its prompt; picking anything else inserts a chip followed by a space, ready to keep typing.
+
+### Mentioning is focusing
+
+#### User story
+
+The user names a repo or a file in the prompt and expects the agent to actually be pointed at it — and expects removing that mention to undo it.
+
+#### Business logic
+
+Picking a project adds that project's checkout to the agent context; picking a file adds its repo-relative path. The editor keeps watch over which project and file chips are present: when one disappears — deleted by hand, or wiped out by loading a preset — the context entry it added is removed again.
+
+#### Rationale
+
+The chip was the only visible sign that the agent had been focused on that repo or file. A prompt that silently carried the focus after its chip was gone told the user something untrue.
+
+### Presets load in place
+
+#### User story
+
+The user has typed a draft, then decides to start from a preset instead.
+
+#### Business logic
+
+Loading a preset replaces whatever is in the editor and does not ask for confirmation first. The editor reports back whether it overwrote a non-empty draft, so the surrounding form can note that undo brings the draft back — the replacement is grouped as a single undo step. Loading a built-in preset also passes along whether that preset must start an agent of its own rather than continue the open one.
+
+### Enter sends
+
+#### User story
+
+The user expects the send key to behave the way it does in the coding-agent chat interfaces they already use.
+
+#### Business logic
+
+Enter alone sends the prompt, Shift+Enter inserts a line break, and Ctrl/Cmd+Enter sends from anywhere. Enter does not send while a suggestion menu is open (it picks the highlighted entry), inside a code block (it adds a line), or while a text input method is composing a character (it confirms the composition).
+
+### Accessibility
+
+#### User story
+
+A user on a screen reader gets a properly announced, labelled, multi-line prompt field.
+
+#### Business logic
+
+The editing surface announces itself as a multi-line text box named "Prompt" and carries the placeholder as its announced placeholder; the visible placeholder text is decoration on top of that.
+
+## Before modifying/creating SPEC.md files
+
+You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md

packages/the-framework/dashboard/components/PromptEditor.test.SPEC.md

@@ -0,0 +1,5 @@
+What the tests cover: the prompt editor's send keys. Plain Enter sends the prompt while Shift+Enter and Alt+Enter stay editing keys; Ctrl+Enter and Cmd+Enter send as well; Enter is left alone while a suggestion menu is open, which uses it to pick the highlighted entry, and sends again once the menu closes; Enter pressed while a text input method is composing a character never sends.
+
+## Before modifying/creating SPEC.md files
+
+You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md

packages/the-framework/dashboard/components/RightRail.test.SPEC.md

@@ -0,0 +1,13 @@
+What the tests cover: which tabs the right sidebar offers, and when it is shown at all.
+
+- **A fixed width** — the sidebar holds the same width for every tab, including when a document the agent published pulls it to the Views tab and when the user switches away again.
+- **No project, no sidebar.**
+- **The Browser tab** is offered for an agent running on this machine with the browser preview on, and never for an agent running on a GitHub Actions runner, even when the preview was requested.
+- **Hovering a tab** says what it holds.
+- **Every tab is earned** — with no PLAN/TODO documents there is no Docs tab, and when nothing else qualifies either the sidebar itself disappears; a live agent that published a document keeps the sidebar even when every read comes back empty. While the first read is still out the Docs tab stays, so switching projects does not blink the sidebar out and back in.
+- **When the launcher shows the documents in its main column**, the sidebar withholds the Docs tab and does not even read them, leaving the rest of the sidebar untouched — and shows no sidebar at all when documents were the only thing it had to offer.
+- **A tab that loses its content** does not leave an empty panel: even after the user picked that tab by hand, the sidebar falls back to the first tab that still has content.
+
+## Before modifying/creating SPEC.md files
+
+You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md