Re-voice SPEC.md files to the user-story axis of the current sdd.md

.github/workflows/SPEC.md

@@ -1,9 +1,13 @@
-The repo's GitHub Actions workflows: continuous integration, the dispatchable agent runner, and website deployment.
+The repo's three GitHub Actions workflows — one is part of the product (the agent runner), two are repo plumbing (continuous integration and website deployment).
+
+## User Stories
+
+- The user runs an agent on a fresh GitHub Actions runner instead of their own machine.
 
 ## Flows
 
-- `framework-agent.yml` is the only workflow that is part of the product runtime — the daemon dispatches it to run agent turns on cloud runners; the rest is repo plumbing.
-- `ci.yml` builds, typechecks, and tests every push and PR; `website-deploy.yml` publishes the-framework.ai.
+- When the user runs an agent on GitHub Actions instead of their own machine, the framework dispatches `framework-agent.yml` — one dispatch per agent turn, each on a fresh GitHub-hosted runner.
+- `ci.yml` builds, typechecks, and tests every push and PR; `website-deploy.yml` publishes the-framework.ai whenever a change to the website lands on `main`.
 
 ## Rationales
 

.github/workflows/framework-agent.SPEC.md

@@ -1,20 +1,22 @@
-The workflow the product dispatches to run one coding-agent turn on a disposable GitHub-hosted runner — how an agent runs "elsewhere" on GitHub Actions.
+The workflow the framework dispatches to run one coding-agent turn on a disposable GitHub-hosted runner — the runner-side half of running an agent on GitHub Actions instead of the user's machine.
 
 ## User Stories
 
 - The user runs an agent on a fresh GitHub Actions runner instead of their own machine, and follows it from the same dashboard.
 
 ## Flows
 
-- One dispatch is one agent turn. The daemon tags the run with a correlation id of its own making and finds the run by that tag.
-- The run spends the user's own driver subscription, not an API key, and the agent runs unrestricted.
-- The turn's work — including anything left uncommitted — is pushed to the branch the driver chose, so the next turn continues exactly where this one stopped.
-- The transcript comes back as an uploaded artifact, the only channel out of a run; a failed turn still uploads it.
+- One dispatch is one agent turn. The framework tags the run with a correlation id of its own making and finds the run by that tag.
+- The run spends the user's own Claude subscription — an OAuth token the user minted and the repository holds — never an API key.
+- The agent runs unrestricted: it edits files and runs commands without waiting on permission prompts that nobody is there to answer.
+- The turn's work — including anything the agent left uncommitted — is pushed to the branch the framework chose, so nothing is lost with the runner and the next turn continues exactly where this one stopped. A failed turn's work is pushed too. A turn that changed nothing pushes nothing, so a no-op run creates no branch.
+- The run's report comes back as one uploaded artifact: the transcript, which branch was pushed, and the agent's session id so a later turn can resume the same conversation. Besides the pushed branch, that artifact is the only thing that leaves the runner; a failed turn still uploads it.
 
 ## Rationales
 
-- The daemon invents its own correlation id because GitHub's dispatch call never reveals which run it started.
+- The framework invents its own correlation id because GitHub's dispatch call never reveals which run it started.
 - The agent runs unrestricted because the runner is disposable: nothing on it outlives the turn.
+- The workflow pushes the branch itself because the action that runs the agent creates none for a dispatched run — and publishing is the framework's job, as it is locally: the agent only commits.
 - A failed turn still uploads its transcript because a failure is exactly when the transcript is most wanted.
 
 ## Before modifying/creating SPEC.md files

SPEC.md

@@ -12,7 +12,7 @@ Autonomous AI programming: humans make the important decisions while The Framewo
 
 ## Flows
 
-- The product is a local daemon plus a dashboard. The user registers repos, and from then on coding agents (Claude Code today, other CLIs pluggable behind the same driver interface) work on them: each agent gets a throwaway copy of the repo, does its work, and hands the result off as a pull request.
+- The product is a local daemon plus a dashboard. The user registers repos, and from then on coding agents work on them: each agent gets a throwaway copy of the repo, does its work, and hands the result off as a pull request. Claude Code does the coding today; other CLIs can plug in behind the same adapter, the *driver*.
 - The human's job shrinks to decisions: answer the questions an agent parks on, accept or reject proposed tickets, review PRs. Everything else — picking the next task, triaging, planning, fixing red CI, merging on green — the daemon does by itself when nobody is at the keyboard, as long as the account's quota allows it.
 - The driver is a black box: The Framework prompts it, lets it run a full turn, then reads the code and the turn's final message. It never micro-manages individual tool calls, and the CLI keeps its own subscription login — The Framework adds orchestration, not another AI bill.
 - Two satellites complete the family: a browser extension that bridges claude.ai cloud sessions back to the daemon, and the product's website.

packages/chrome-extension/SPEC.md

@@ -8,10 +8,10 @@ A Chrome extension bridging Claude Code cloud sessions on claude.ai to the local
 
 ## Flows
 
-- A cloud agent hands off and ends, so when its session later asks something, nothing streams back and the question strands on claude.ai; the extension reads the session page the user is already signed into and carries the question — plus a mirror of the transcript — to the daemon.
+- A cloud agent hands off and ends, so when its session later asks something, nothing streams back — the question strands on claude.ai. The extension reads the session page the user is already signed into and carries the question — plus a mirror of the transcript — to the daemon, so the dashboard shows both.
 - Two halves with a strict trust line: the page script reads claude.ai and types into it but never holds a secret; the background worker holds the bridge token and is the only part that talks to the daemon.
-- Answers go the long way round: dashboard pick → daemon queue → worker → typed into the session's composer and submitted; the extension can only ever type a label the session itself offered, and the pick was confirmed in the dashboard first.
-- It keeps one pinned background tab per session the daemon watches, so the bridge works with nobody looking at claude.ai — closing tabs when watching stops, and never reopening one the user closed.
+- The user's answer goes the long way round: dashboard pick → daemon queue → worker → typed into the session's composer and submitted. The extension can only ever type a label the session itself offered, and the pick was confirmed in the dashboard first.
+- The bridge works with nobody looking at claude.ai: the extension keeps one pinned background tab per session the daemon watches, closes them when watching stops, and never reopens one the user closed.
 - Reading is driven by page changes with a slow heartbeat backstop, and every stage reports its status — on the page's panel and in the settings page's connection test — so a silent misconfiguration is visible.
 - The extension and the daemon insist on matching versions: every call states the extension's version, and a daemon expecting another blocks it with an error naming both and the update path.
 

packages/chrome-extension/background.SPEC.md

@@ -2,10 +2,10 @@ The extension's daemon half: the only part holding the bridge token and talking
 
 ## Flows
 
-- Questions forward with a dedupe: the page re-reports on every change, and an unchanged question for the same session costs nothing.
-- Answers travel back: queued picks are fetched on a fast beat, handed to the page in that session's tab to type, and the outcome reported — typing before reporting, so a pick is never marked sent that a dying tab never typed; failed deliveries and reports are retried, not dropped.
-- One pinned, inactive tab opens per session the daemon says to watch; stale ones close, and a tab the user closed is never reopened.
-- Every sweep records why it did or didn't act, so "tabs are not opening" is answerable from the options page.
+- Questions forward with a dedupe: the page half re-reports on every page change, and an unchanged question for the same session is not re-sent to the daemon.
+- Answers travel back: each answer the user picks in the dashboard is queued at the daemon, fetched on a fast beat, and handed to the page half in that session's tab to type, and the outcome is reported back. Typing comes before the report, so an answer is never marked sent that a dying tab never typed. Failed deliveries and failed reports are retried, not dropped.
+- One pinned, inactive tab opens per session the daemon says to watch; a tab whose session is no longer watched closes, and a tab the user closed is never reopened.
+- Every sweep — each pass that opens and closes these tabs — records why it did or didn't act, so "tabs are not opening" is answerable from the options page.
 - Every daemon call states this extension's version; a daemon expecting another refuses outright with both versions named, so a stale install blocks loudly instead of half-working.
 
 ## Rationales

packages/chrome-extension/content.SPEC.md

@@ -2,9 +2,10 @@ The extension's page half: injected into claude.ai session pages, it finds the q
 
 ## Flows
 
-- The question is the JSON options block our agents emit, brace-matched out of surrounding prose wherever it hides — code elements, shadow roots, split across highlighter spans — and the page's rendered copy of our own protocol is a decoy three ways (#1568): nothing inside the transcript's opening message counts (that is the prompt rendering, examples included), a placeholder-shaped title is the spec talking even when punctuation joins the placeholders, and the protocol's two literal examples are matched verbatim; the last real question among what survives wins.
-- The transcript mirrors as per-message blocks when the page marks them, else as the visible conversation text from the newest end (application chrome and our own panel stripped); only what changed since the last look is sent.
-- Delivering an answer is the one action taken: the pick is typed into the composer and submitted, after patiently waiting for a slow page to render the composer; only the top frame types, so nothing submits twice — and only labels the session itself offered can ever be typed.
+- The question is the JSON options block an agent emits when it parks on a decision, brace-matched out of surrounding prose wherever the page hides it — code elements, shadow roots, split across highlighter spans.
+- The page also renders the run's own prompt, which quotes that block's protocol — examples included — so the dashboard is never handed a decoy (#1568): nothing inside the transcript's opening message counts (that is the prompt rendering), a placeholder-shaped title is the protocol description talking (even when punctuation joins the placeholders), and the protocol's two literal examples are matched verbatim. The last real question among what survives wins.
+- The transcript mirrors to the dashboard as per-message blocks when the page marks them, else as the visible conversation text read from the newest end — claude.ai's surrounding UI and the extension's own panel stripped out. Only what changed since the last look is sent.
+- Delivering an answer is the one action taken: the answer the user picked in the dashboard is typed into the composer and submitted, after waiting out a slow page still rendering the composer. Only the top frame types, so nothing submits twice — and only a label the session itself offered can ever be typed.
 - It re-reads on page mutation with a slow heartbeat backstop, and its collapsible panel reports every stage's status — found, sent, delivered, and why not.
 
 ## Rationales

packages/chrome-extension/options.SPEC.md

@@ -1,10 +1,15 @@
-The settings page: the daemon address, the bridge token, and the tab-opening switch live in extension storage — never in the page — and saving immediately proves the connection instead of just storing it.
+The settings page: the daemon address, the bridge token, and the tab-opening switch live in extension storage — out of reach of any web page — and saving immediately proves the connection instead of just storing it.
+
+## User Stories
+
+- The user saves the daemon address and the bridge token, and immediately sees the connection proven or the exact failure named.
+- The user switches automatic tab-opening on or off, and opens the tabs on demand instead of waiting on the timer.
 
 ## Flows
 
-- The test names the exact failure: Chrome not actually granting site access (declared is not granted, and without it the daemon sees nothing), daemon unreachable, token rejected, a version the daemon refuses (its answer, naming both versions and the way out, is shown verbatim), bridge switched off, or a dashboard too old to have a bridge — whose look-alike success page is not accepted as connected.
+- The test names the exact failure: Chrome not actually granting site access (a site the extension declares is not automatically a site Chrome granted, and without the grant no request ever leaves the browser), daemon unreachable, token rejected, a version the daemon refuses (its answer, naming both versions and the way out, is shown verbatim), the bridge switched off in The Framework, or a dashboard too old to have a bridge — that last one answers with its own app page, a look-alike success not accepted as connected.
 - Success also says how many cloud sessions the daemon is watching, so "connected but nothing happens" answers itself.
-- A button runs the tab sweep on demand and reports what it did, sparing the wait on the timer.
+- A button runs the tab sweep — the pass that opens a pinned tab per watched cloud session — on demand and reports what it did, sparing the wait on the timer.
 
 ## Before modifying/creating SPEC.md files
 

packages/the-framework.ai/SPEC.md

@@ -10,7 +10,7 @@ The product's marketing website, the-framework.ai — it pitches The Framework a
 ## Flows
 
 - One long landing page carries the whole pitch: stop babysitting AI, make the important decisions, let AI do the rest.
-- The main call to action everywhere is a copy-pasteable terminal command that runs The Framework; visitors pick their package manager once and every command site-wide shows in that flavor, remembered across visits.
+- The main call to action everywhere is a copy-pasteable terminal command that runs The Framework. Visitors pick their package manager once, every command site-wide switches to it, and the choice is remembered across visits.
 - Three side pages support it: a press page with brand material, a go-to-dashboard page explaining that the dashboard runs on the visitor's own machine, and a hidden banner page that gets screenshotted into the social-preview image.
 - The whole site is pre-rendered into plain static pages — no server.