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/OptionsMenu.test.SPEC.md

@@ -0,0 +1,13 @@
+What the tests cover: the gear marks that options are on with a dot rather than a number, and names the count only on hover; toggling an option writes its new value through; a row that cannot be switched is greyed, states its reason in place, and writes nothing when clicked.
+
+The "Run on" list: it is one flat list — the three run targets, then the saved devices, then "Add a device…" — with no section header and no separate duplicate row for the local machine; it is absent entirely where no run target can be chosen (a composer inside a running agent), and its device half is absent when no saved devices are available. "Claude web" is a real, selectable target.
+
+The single checkmark: it follows the chosen run target while no device is selected; selecting a device moves it onto that device and quiets the run-target rows; being connected to a remote daemon puts it on that daemon's device. Choosing any run target also clears a selected device, so the mark never appears twice.
+
+Device rows: clicking one selects it as the run target without navigating anywhere and without writing a preference; its remove control drops the saved device without also selecting it; an unreachable device is dimmed and its address annotated "offline", while a reachable one shows its status dot and is not dimmed; "Add a device…" opens the add flow.
+
+"This machine": on the local daemon it writes the run target and clears any selected device; while connected to a remote daemon it instead returns to the local daemon and writes no run target.
+
+## 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/SettingsPage.SPEC.md

@@ -0,0 +1,122 @@
+The dashboard's Settings page: every one of the user's own preferences in one place, grouped into sections, plus the onboarding checklist. Its subtitle states the page's own scope — "Your defaults, everywhere. A repo can override them in its own the-framework.yml."
+
+## User story
+
+- The user wants to find a setting by looking for it, rather than remembering which menu in the header it was hidden behind.
+- The user wants the page to tell the truth about what will actually happen: a notification the browser has blocked, an option another option overrides, a Discord channel that has no webhook yet.
+- A user part-way through onboarding wants to pick it back up from here.
+
+## Business logic — TL;DR
+
+- **Only the user's own settings are writable here** - a repo-shaped value belongs in that repo's committed `the-framework.yml`, edited in the repo, so everything this page writes is a default that a repo may override.
+- **Onboarding lives here** - the checklist sits at the top of the page and cannot be dismissed, since this is where the Overview sends a user who wants to resume it.
+- **Appearance** - theme (follow the system, or pin light or dark) and which editor "Open in editor" launches, chosen from the editors detected on the machine or left on auto-detect.
+- **Agent** - which coding-agent CLI does the work, which model to pass through to it, and where an agent executes: this machine, a fresh GitHub Actions runner, or a Claude Code cloud session. The saved devices this daemon can run on are listed right after, since a device is the other place an agent can run.
+- **Run options** - the same option table the launcher's gear shows, with the same rules already applied, so a rule cannot hold in one place and not the other.
+- **A rule-disabled row is shown, not hidden** - an option another option overrides stays in place, greyed, and its description is replaced by the reason it cannot be changed.
+- **Notifications** - browser and Discord as the delivery channels, and the two categories that can be sent: an agent awaiting an answer or a pull request ready to review, and agents starting and finishing.
+- **A toggle never promises delivery it cannot make** - a channel the browser or the daemon cannot deliver on says so instead, and the Discord row carries the button that supplies what it is missing.
+- **Automation** - whether Auto PM starts queued work on its own, and how far from the quota boundary unattended work is allowed to sit.
+- **Claude web** - the browser bridge switch and its settings, introduced by why the bridge exists at all.
+
+## Business logic
+
+### Only the user's own settings are writable here
+
+#### User story
+
+See `## User story`.
+
+#### Business logic
+
+Every control on the page writes the user's own preferences. The page never edits a repo's committed configuration; a value that belongs to a repo is edited in that repo, so a settings page can only ever mean "the default". The page says exactly that under its title.
+
+### Appearance
+
+#### User story
+
+See `## User story`.
+
+#### Business logic
+
+Theme follows the system by default and can be pinned to light or dark. The editor setting decides which editor "Open in editor" launches: auto-detect, or one of the editors detected on this machine.
+
+### Agent
+
+#### User story
+
+See `## User story`.
+
+#### Business logic
+
+The driver setting picks which coding-agent CLI runs the work. The model is passed through to that CLI, and left empty means the CLI's own default. The run target picks where an agent executes: this machine, a fresh GitHub Actions runner, or a Claude Code cloud session.
+
+Immediately after, the saved devices this daemon can run an agent on are listed and managed, since a device is the other answer to "where does this run".
+
+### Run options
+
+#### User story
+
+The user comes here to check what a new agent will start with, and needs the answer to match what the launcher would do.
+
+#### Business logic
+
+The section renders the same option table the launcher's gear does, with the same interactions between options already resolved, so the effective value of every option reads identically in both places. Its own description says as much, and adds that an agent's own action bar can still change how that agent ends.
+
+A row that the rules have turned off keeps its place, greyed, and shows the reason it is off in place of its usual description, rather than disappearing.
+
+#### Rationale
+
+Hiding a disabled row defeats the point of the page: this is where a user comes to look for a setting, and a setting that vanishes reads as a missing feature rather than as an override.
+
+### Notifications
+
+#### User story
+
+See `## User story`.
+
+#### Business logic
+
+Two channels and two categories. The browser channel sends desktop notifications while the dashboard is open; when the browser has blocked notifications, the row is greyed, reads as off whatever the stored preference says, and its description says it is blocked in the browser's settings. The Discord channel delivers where no dashboard needs to be open; without a webhook configured on the daemon, it says it is not configured, and the row carries a button that opens the webhook setup — labelled "Set up" when there is none and "Webhook" once there is. Saving a credential there settles every surface that shows the channel's state at once.
+
+The categories: "Human Queue" covers an agent awaiting the user's answer or a pull request ready to review, and is on by default; "New activity" additionally pings when an agent starts or finishes, and is off by default.
+
+### Automation
+
+#### User story
+
+See `## User story`.
+
+#### Business logic
+
+The Auto PM switch decides whether queued work is started on its own while quota is left in the week. The spend offset is how far unattended work sits from the quota boundary, in percentage points: negative holds it back, positive lets it borrow from the days ahead. It is bounded to the same range the usage bar's handle and the daemon's own sanitizer use, and a typed value is held to that range as it is entered.
+
+With no offset saved, the box shows the default actually in force rather than zero, rounded to one decimal.
+
+#### Rationale
+
+The box used to keep displaying a typed 9999 while the saved value had been clamped, and used to show 0 for an unset preference the daemon was not using. Both made the page disagree with what the daemon does.
+
+### Claude web
+
+#### User story
+
+See `## User story`.
+
+#### Business logic
+
+The section explains why the bridge exists: a Claude web agent hands off and ends, so the questions its cloud session asks never reach this dashboard, and the browser bridge carries them back. Its switch opens one route on this daemon that a browser extension can reach, guarded by the token shown with the bridge's own settings below it.
+
+### Controls that cannot be operated are not rendered
+
+#### User story
+
+See `## User story`.
+
+#### Business logic
+
+A setting picked from a list with no options to pick renders nothing at all, rather than an empty picker that reads as broken.
+
+## 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/SettingsPage.test.SPEC.md

@@ -0,0 +1,5 @@
+What the tests cover: on a machine with no stored preferences, no saved devices and no editors detected, the Settings page renders its controls and none of its pickers is empty — an empty picker can be opened but not used, which reads as broken. In particular the Editor row, whose choices are the only ones assembled at run time, stays usable with nothing detected, offering auto-detect as a real choice rather than a placeholder.
+
+## 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/TicketsPanel.SPEC.md

@@ -0,0 +1,111 @@
+One project's `tickets/` backlog as a list of one-line rows, scannable without opening anything, with three agent-starting actions on it: work a ticket, plan a ticket, and bring the whole backlog up to date with GitHub.
+
+## User story
+
+The user wants to read a project's backlog at a glance — what each ticket is, how urgent, whether it is already planned or already being worked, how old — and to put an agent on any of it in one click. On a project with no tickets yet, they want the backlog filled from the repo's GitHub issues rather than a dead end.
+
+## Business logic — TL;DR
+
+- **A ticket is one row** - title, project (in the cross-project list), topics, claim, effort, uncertainty, priority, age, plan, and the GitHub item behind it, all on one line; the row opens the ticket's detail page.
+- **Start work from the row** - a play control on the row's left edge starts an unattended agent on that one ticket and nothing else, with the ticket named on the agent.
+- **The plan column is either a plan or an offer to write one** - a planned ticket links to its plan; an unplanned one offers to start an agent that writes it.
+- **Claimed rows say who holds them** - a ticket an agent has claimed shows a hammer and the holder's name, meaning an agent is planning or implementing it.
+- **Update from GitHub** - one action brings `tickets/` up to date with the repo's issues; on a project with no import on record it brings everything open across. It runs unattended, as the same routine does when the daemon starts it.
+- **Empty is not the same as filtered** - a backlog filtered down to nothing says how many tickets the filters hide and offers to clear them; only a genuinely empty `tickets/` offers the GitHub update.
+
+## Glossary
+
+- **start column** - the row's left-edge control that starts an agent working that ticket.
+- **plan column** - the row's control that either opens the ticket's plan or starts an agent to write it.
+
+## Business logic
+
+### A ticket is one row
+
+#### User story
+
+See `## User story`.
+
+#### Business logic
+
+Every ticket occupies a single line. The title takes whatever width the row has to spare and truncates when it runs out; clicking it opens the ticket's detail page. In the flat cross-project list the row also names its project, since there is no section heading saying it. The rest of the line, from left to right: the ticket's topics, its claim, its effort and uncertainty estimates, its priority — coloured by how urgent it is, and spelled out as "Priority: 8" — and its age, with the exact date and time on hover. Priority, age and the plan column keep fixed widths, and a ticket with no GitHub item still reserves that column's width, so the columns line up down the whole list regardless of what any one ticket carries.
+
+Where the surrounding page supports filtering, a row's topics and its claim marker are clickable: a topic filters the page to that topic, the claim marker filters to claimed tickets. Where the page has no filters, they are plain labels.
+
+### Start work from the row
+
+#### User story
+
+The user reads the backlog, sees the ticket that should be done next, and wants an agent on it immediately.
+
+#### Business logic
+
+The start column asks an agent to work `tickets/<file>` and to start no other ticket. The agent runs unattended — ending when it settles and firing its armed handoff — because one agent on one ticket is exactly the work the queue-draining routine starts, and it should run the same way. The ticket is named on the agent itself, so the agent's record says which ticket it implements.
+
+### The plan column
+
+#### User story
+
+Before committing an agent to a big ticket, the user wants a plan written for it, and afterwards wants to read that plan.
+
+#### Business logic
+
+A planned ticket's plan column links to the rendered plan, marked prominently so planned rows are scannable at a glance. An unplanned ticket's plan column instead starts an agent asked to create the ticket's plan file beside the ticket, and is drawn quietly — an action still available rather than something already there.
+
+The planning agent runs attended, unlike the work agent and the GitHub update: a plan is written for a human to read and act on, so it stays a conversation the user can land in and steer.
+
+### Claimed rows say who holds them
+
+#### User story
+
+The user needs to know a ticket is already being worked before starting a second agent on it.
+
+#### Business logic
+
+A ticket an agent has claimed shows a hammer and the holder's name inline, truncated to keep the row aligned, with the full holder and the explanation on hover: an agent is working on this ticket, planning it or implementing it. Where filtering is available, the hover also says the marker leads to all claimed tickets.
+
+#### Rationale
+
+The holder is named on the row rather than only in the tooltip: a control that only reveals itself after a second of hovering is one nobody discovers.
+
+### Update from GitHub
+
+#### User story
+
+The user's real backlog lives in the repo's GitHub issues and they want `tickets/` to reflect it — the first time, and every time since.
+
+#### Business logic
+
+A bar above the list says when `tickets/` last caught up with GitHub, or that there is no record of an import yet, with the update action beside it. The action asks for `tickets/` to be brought up to date with the issues and comments changed since the last import; with no import on record, everything open comes across instead. It runs unattended, since an update fired by a button is routine work rather than a conversation.
+
+The same instruction sits behind the same label everywhere it is offered, including the onboarding checklist, so one label always means one instruction.
+
+### Starting anything hands the user to the agent
+
+#### User story
+
+The user presses a button and wants to watch the work, not stare at a list that has not changed yet.
+
+#### Business logic
+
+Whenever any of the three actions starts an agent, the dashboard shell is told, so the user lands on the agent doing the work rather than on a panel showing stale rows until files land. Every action is blocked while another start is in flight, and a failed start leaves its reason in the panel: the update, the planning agent, or the work agent could not be started.
+
+### Empty is not the same as filtered
+
+#### User story
+
+See `## User story`.
+
+#### Business logic
+
+A panel whose tickets were all hidden by the surrounding page's filters says how many are hidden and, where the page allows it, clears the filters from right there. It never offers the GitHub update in that state.
+
+A genuinely empty backlog explains that tickets live in `tickets/` and are what the agent plans from, and offers the GitHub update as the way to fill it. Until the project's tickets have been read, the panel says it is loading.
+
+#### Rationale
+
+Offering an import to a user who has merely filtered their backlog away would ask for work that has already been done.
+
+## Before modifying/creating SPEC.md files
+
+You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md