# Duct App — agent instructions

Next.js App Router report viewer and agent interface.

## Stack

- **Framework:** Next.js 16 App Router, React 19, TypeScript 6, Node 22 (pinned in `app/.nvmrc` — the OpenNext/wrangler toolchain requires ≥22; dev runs on port 3003)
- **UI:** shadcn/ui + Radix UI primitives, Tailwind CSS 4, lucide-react, next-themes (light/dark)
- **Charts:** Nivo (heatmaps, complex) + Recharts (general) — both intentionally present
- **State:** React Context (`InsightContext.js`) + component-level state only. No Redux/Zustand.
- **HTTP:** Native `fetch` wrapped in `lib/api.js`. No type-safe client or OpenAPI generation.
- **Auth:** Custom API key (`NEXT_PUBLIC_DUCT_API_KEY`) sent to backend + Google Sign-In (`GoogleSignInButton.jsx`). No next-auth/Clerk/Supabase.
- **Observability:** PostHog behind a swappable seam (`lib/analytics/`; `NEXT_PUBLIC_ANALYTICS_PROVIDER` picks, unset runs every provider whose variable is set: `NEXT_PUBLIC_POSTHOG_KEY`), gated on consent. No tag manager in this code: Cloudflare's Google tag gateway adds Google Tag Manager and GA4 at the edge, outside this seam and outside consent ([`site/AGENTS.md`](../site/AGENTS.md)); Cloudflare Turnstile bot protection. Nothing outside `lib/analytics/` names a vendor.
  PostHog runs in two modes on one client (`lib/analytics/posthog.js`). **Errors** starts for every browser session from `instrumentation-client.ts`: early `error`/`unhandledrejection` listeners at once, the library on idle, in-memory persistence, so it stores nothing and needs no banner; error boundaries call `reportError`. **Full** starts on consent: cookie across `.getduct.ai`, page views, autocapture, heatmaps, replay. In the desktop shell the Preferences switch (`lib/telemetry.js`) replaces both the banner and the errors-before-consent rule: off sends nothing at all, on runs full mode in memory and never records a replay. Three rules a change here must keep: the `no-external` build only (the shell's IPC trusts every script on this origin, and it keeps `script-src` at `'self'`); `lib/analytics/scrub.js` on every event (query strings and the `/invite/` and `/open/audit/` path tokens go); and the replay masks all text and blocks images, embeds and canvases, plus `mask_all_text` on clicks, because a human watching a replay of a customer's GA4 numbers breaks Google's Limited Use rule. Server render errors go through `instrumentation.ts` → `lib/analytics/server.js` (posthog-node). Events reach PostHog through the same-origin `/ingest` rewrite in `next.config.mjs`, which the marketing site uses too.
- **Overrides:** `package.json` forces `lodash-es` to ^4.18.1. `mermaid` 12.0.0 depends on `chevrotain` 11.1.2, which pins `lodash-es` 4.17.23 exactly, and that version carries a high advisory (code injection via `_.template`) and a moderate one (prototype pollution in `_.unset`/`_.omit`). Delete the override once `mermaid` moves to `chevrotain` 12 or later, which no longer uses lodash.

## Deployment

- **Host:** Cloudflare Workers via `@opennextjs/cloudflare` adapter + wrangler CLI.
- `npm run deploy:cf` → OpenNext build + `wrangler deploy` (do not run directly — all deploys go through CI/CD on merge to main).
- **CI/CD:** GitHub Actions (`app.yml`) — lint, typecheck, `next build` on every PR; on push to `main` the `deploy` job runs `opennextjs-cloudflare build` + `wrangler deploy`. (Replaced the Cloudflare "Workers Builds" git integration, which failed on its Node 20 builder — wrangler@4.99 needs ≥22.)
- **Security headers** are `SECURITY_HEADERS` in `next.config.mjs`, applied by OpenNext's routing layer to every response the worker renders. `/_next/static` and `public/` never reach the worker, so their `nosniff` is in `public/_headers`. The CSP's `script-src` is `SCRIPT_SOURCES` there: this origin (the edge's Google tag is served from it, so it passes) and the sign-in bot check, plus `'unsafe-eval'` in dev. A script from any other host is refused, so loading one means adding its host there. It keeps `'unsafe-inline'` with no nonce, and not because a nonce would make pages dynamic (every route already is: the root layout reads the locale cookie) but because an `about:srcdoc` frame inherits its parent's policy, and the brief and artifact frames run model-authored inline `<script>` that no nonce can reach. Every `srcDoc` iframe (briefs, the audit report, slides) inherits the policy, so a directive added there also governs model-authored HTML. Dev allows same-origin framing only because `/preview` frames `/preview/frame`.

## Route structure

Four route groups under `app/` (the fourth, `(public)/lead/seo-audit`, is the token-gated lead-magnet audit with its own chrome and no auth):

- `(start)/start` — onboarding: the audit *is* the onboarding. One field
  (URL — the root page read back in a second, crawl continuing in the
  background via `/api/audit/prefetch`) → a model (an API key verified by
  spending it, or on desktop "Continue with ChatGPT", or skipped) → the
  session at `/audit/seo/[sessionId]` with `crawl_id` and `draft_project`
  set. The "Found it" card also offers documents
  (`components/onboarding/DocumentPicker.jsx`): files read on upload by
  `/api/audit/documents`, their ids sent as `document_ids`. It lives on that
  card and not beside the URL field because the landing page's hand-off
  skips the field, and it blocks "continue" only while a file is being read.
  Submitting the URL mints a **guest** (`lib/guest.js`): a real account
  with a synthetic email, so everything the audit makes has an owner before
  anyone signs in; Google sign-in later links or merges it. No `AuthGuard`
  and none of the app shell. Layout is the threshold split: the `salve`
  mosaic and the aqueduct strip (`components/onboarding/Aqueduct.jsx`) on
  the left, the step on the right. The aqueduct is the progress indicator —
  water reaches an arch when that step's data does; blue is water and
  nothing else on the page is blue; the six-stone palette lives as
  `--tessera-*` tokens in `styles/onboarding.css` and the one celebration
  (`TesseraBurst`) is made of them. Provider choice is a radio-card list
  (`ProviderStep.jsx`), OpenAI first. Design and phases:
  `docs/engineering/2026-09-08-smart-onboarding-plan.md`.
  Nothing is **written** until the user confirms the site card: for someone
  already signed in, the crawl's draft would otherwise land in whichever
  project happened to be active and overwrite it. The card says which
  project this becomes, offers a separate one, and asks when two projects
  share the site. The audit that follows says so again from the workspace,
  because that write happens while the user is reading the report.
- `(auth)/` — the front door, and it is a landing page before it is a login
  page: the wide half (`components/onboarding/FrontDoor.jsx`) is the free
  audit — one URL field that hands off to `/start` — and the narrow dark half
  is sign-in for someone who already has an account. It passes a guest's link
  code to the authorize URL so the account keeps their work.
  When `lib/signInSources.js` has armed the onboarding bundle it also passes
  `sources=onboarding` (Search Console + Analytics read scopes in the same
  consent) and says so under the button. Only the connector prompt on the
  onboarding audit arms it, and the arming expires; the Share dialog, an
  invitation and a plain visit here stay identity-only.
  Two things the offer half deliberately does **not** show, both of which read
  as a demand rather than an offer to someone who has not decided yet: the
  connector list as pills under the field (it survives as one sentence below
  the fold, with a "when you're ready" clause), and `/start`'s aqueduct strip
  rendered dry, which is three chores shown before the first click. **The
  `FONS` mosaic is in the sign-in half, not this one**, and putting it back
  beside the copy is a regression however well it reads at 1440: a 280px panel
  only fits there above 1280px, and the rule that hid it below that blanked it
  across the whole band the desktop window occupies (1200px default, 900px
  minimum), so the desktop app never once showed it. The field and its button
  are **one row**, not a stack — a single-field form over a full-width button
  reads as two steps — and they stack again below 30rem.
  **The sign-in half is one heading, one button and one line of legal, and
  each thing missing from it was removed on purpose:** the "Already using
  Duct?" kicker and the "Continue with your Google account" sub-line (three
  lines introducing a button that says what it does on its face — the sub-line
  is back only for an expired session, which carries something the button
  cannot); and four of the five notices that could
  stack under the button, now one slot filled by `signInNotice()`. The
  "Keep me signed in for 30 days" checkbox was removed on the same argument
  and **put back on request** — it is a deliberate keep, not an oversight, so
  leave it. Turnstile
  renders `appearance: "interaction-only"`, so the box exists only for a
  visitor actually challenged, and the button is never disabled waiting for a
  token — `awaitTurnstileToken` holds the click, because a disabled sign-in
  button on first paint is indistinguishable from a broken one. Its ink is
  semantic tokens only — the ground is `--start-ground`, which flips with the
  theme, and the fixed `--navy` brand hexes it used to paint with measured
  1.05:1 on it in dark.
- `(app)/` — authenticated app shell:
  - `insights/organic-growth/` + `[slug]/` + `generate/` — the Desk, stored
    insights, generate entry; `insights/session/` — the insights agent
    workspace
  - `audit/seo/` + `audit/seo/[sessionId]/` — SEO audit hub and live workspace
  - `content/` — Content Studio hub; `content/plan/` the planner board on
    its own full-bleed route;
    `content/posts/[postId]`, `posts/new`, `sessions/new` — the content agent
    workspace over a post or a plan. The hub's Plans tab (`?tab=plans`; the
    old `?tab=plan` still lands there) is the board: list, Kanban and
    calendar, titled by the plan picker (`components/content/PlanPicker.jsx`),
    a menu of every plan as a rich row (state, dates, progress, channels),
    current first, then upcoming, then ended (`orderPlans`). A plan session's
    pane shows the plan being made with no day actions; drafting from a day
    is the board's. A proposal that changes some days (`only_days`) shows
    those days alone, before and after (`PlanChanges.jsx`, `planChanges`). A plan session is the plan manager for
    one period: `?plan=<id>` revises that plan, `?start=<day>&days=<n>` plans
    that period, and neither manages the plan covering today (or makes one
    for the month in progress). The board's Revise plan is the first;
    New plan and Plan ahead ask how far ahead (`PlanPeriodPicker.jsx`: the
    month, 1 or 2 weeks, 30 days) and are the second. The dates come from
    `lib/contentSchedule.js`, which mirrors `agents/content/plan_period.py`
    and must keep agreeing with it. The hub's Posts tab opens on its Waiting
    chip while any draft is unanswered: that view is the drafts queue (#266,
    `components/content/DraftsQueue.jsx`), read from `status=draft` rather
    than a route of its own. Approve opens `PublishModal` on the channel's
    best slot (`suggestedAt`), Skip takes a `SkipReason` the content agent's
    next draft reads as a feedback memory. Its one notice a day is
    `components/content/DailyDraftsReminder.jsx`, mounted once in the app
    layout inside `AuthGuard`; its time and switch are per device
    (`lib/dailyReminder.js`). The Brand tab's Writing samples and Voice rules
    (#271, `WritingSamples.jsx`, `VoiceRulesFields.jsx`, caps in
    `lib/voiceRules.js`) save into `content_brand`; the rules are stored only
    once changed, so an untouched project keeps following Duct's defaults
  - `execute/` — change-set review queue: diffs, approve, apply, roll back
  - `connections/` — the **Toolbox**: one searchable catalogue of native
    connectors and MCP servers
    (`components/connections/ConnectorBrowser.jsx` over
    `lib/connectorCatalog.js`). A new native connector needs a category in
    `NATIVE_CATEGORY`, a new MCP preset one in `MCP_CATEGORY`; without it the
    source is filed under Other. A search also asks the MCP Registry, whose
    results are a section of their own under the catalogue's
    (`useMcpConnectors`' `registry`, through `ConnectorBrowser`'s
    `moreResults`), never entries in it: they are not ours to file or rank.
    A search runs out in that order, then to adding by address. While browsing
    the whole list, `BringAnyTool` is that way in, beside the starters: the same
    offer as the last tile in the list went unseen.
    A connected server that needs attention says why on its tile, from the
    `problem` the server recorded (`lib/mcpServers.js`, `PROBLEM_SHORT`).
    It was called Connections until November 2026; the route kept the old
    name because every OAuth callback and the desktop shell's deep link land
    on `/connections`, and a rename would break connects already in flight
  - `artifacts/` + `[artifactId]/`, `activity/`, `usage/`, `memory/` — the
    library, the cross-agent feed, usage, and memory. An agent's
    edit to the project (MCP `update_project`, #512) carries Undo in the
    feed: that button is what the consent page's "every edit can be undone
    in Duct" stands on, so it stays wherever that promise is made
  - `settings/models/` + `settings/profile/` — tiers, providers, usage; profile
  - `settings/agents/` — Connect your AI agent. The why comes first: a
    drawing of repo → agent → Duct project, what that profile feeds, and
    the can / can never lists from `settings/AgentAbilities.jsx`, which the
    consent page renders too, so the two cannot promise different things
    (change it when the MCP server gains a tool). Every setup line is global,
    because the page says one setup works in every repo. Then pick the agent
    by its logo (`AGENT_LOGOS` in `connections/logos.jsx`) and three tracked
    steps — the line to paste into Claude Code, Codex or OpenCode, or a one-click
    install link for Cursor and VS Code (hidden in the desktop shell, which
    opens only http(s) links outside itself); the browser sign-in, which the
    page watches for by polling the agent list while visible, from the first
    copy until an agent it did not know about appears (ten minutes at most);
    the first prompt. No secret in any step. Below: the agents that signed
    in, and personal tokens for one that cannot
    (`components/settings/AgentAccess.jsx`, `lib/mcpTokensApi.js`). A new
    token's plaintext lives in page state only
  - `generate/` — the retired wizard, now a bare redirect to `/insights/session`
  - `projects/` — project management
  - `project/[projectId]/` — **Project context**, the editor for one
    project: the wizard's five sections, kept, minus creation (a project
    starts at `/start`). Drafted fields carry a provenance chip ("From your
    site" / "Duct's guess") with a one-click confirm; typing confirms too.
    Deep-link a section with `#about` / `#targets` / `#audience` /
    `#competition` / `#brand`. There is no `/onboarding` route any more —
    "new project" everywhere means `/start`.
  - `project/[projectId]/members/` + `project/[projectId]/memory/` — members
    and invitations (owner/collaborator); memory. Both memory routes are one
    page (`components/memory/MemoryPage.jsx`) with a Project / Only you tab:
    the project route opens on the shared tab, `/memory` on the private one
    with the active project beside it. Kinds are filtered as the groups in
    `lib/memoryApi.js` (Goals, Facts, Numbers…), never as the backend's
    eleven-plus-six kinds.

Plus three top-level routes outside every group, because their visitor is
usually signed out and the app shell's guard would lose where they were going:
`invite/[token]/` (the invitation landing page), `authorize/` (where an
agent's browser sign-in asks the person, `components/settings/AgentConsent.jsx`;
the backend has checked the agent and parked the request, and the page sends
the browser back to the agent with the answer) and `open/audit/[conversationId]/`
(the share link for a report — parks the destination, sends through sign-in,
then resumes the conversation; the backend hands it only to project members).
`?kickoff=sources` on that link makes the resumed workspace open by asking
the agent to check what the bundled sign-in connected and bind the property
(`KICKOFF_MESSAGES` in `AuditWorkspace.jsx`; it rides the session's `client`
bag and is spent once).

**Every routable segment renders `LocalBackendGate`.** The desktop shell
bundles its own backend and only learns its loopback port at runtime, so
`BASE` is repointed once at boot (`lib/localBackend.js`) and the gate holds
*hydration* until then. It does not hold the HTML: the server renders the
page, a browser hydrates it at once, and the shell suspends hydration with
`use()`, which keeps the server's HTML on screen and runs no effect or handler
below the gate until the backend is named. Two consequences. A gated page's
first render has to match the server's, so browser state (`localStorage`,
`isLocalBackendActive()`, `isMac()`) is read in an effect, not during render;
the front door's Turnstile flag is the worked example. And a member opening
`/` must not see the front door the server drew for everyone, so
`lib/sessionHint.js` marks `<html data-session="member">` before paint and the
page clears it if it stays. Skipping the gate is not a slow path, it is a sign-out: the
session token is stored under one key but signed by whichever backend minted
it, so a token from the wrong one comes back 401 "Invalid token" and
`authFetch.endSession` reads any 401 as a dead session. That is what `/start`
did — it was ungated and mints a guest, so "Audit a site" from inside the
desktop app replaced the signed-in session with a token the sidecar would
never accept, and the next request bounced the user to the front door.
`scripts/check-backend-gate.mjs` (in `npm run check:parity`) holds the rule;
its `ALLOWED` list is for subtrees that reach no backend at all, and adding to
it is a claim about the code, not a way to quiet the check.

## Key utilities

- `lib/api.js` — fetch wrapper for backend calls
- `lib/signInSources.js` — the onboarding sign-in bundle: `armSignInSources()`
  (one caller: `ConnectionRequest` on the onboarding audit), `consume…` on the
  sign-in page, `resumeAuditPath()` for the way back into the conversation
- `lib/guest.js` — the guest account: `ensureGuest()` mints one on first use,
  `isGuestToken()` / `isSignedInUser()` read the `guest` claim. A guest is a
  real user everywhere else in the app; only the sidebar footer and the
  sign-in page treat it specially.
- `lib/onboardingApi.js` — prefetch, documents, verify, link code: the calls
  only `/start` makes. Errors carry the backend's `reason`. The document
  limits are mirrored here (`localDocumentError`) only so a file that will be
  refused says so before it uploads; the server checks every one.
- `lib/chatgpt.js` — "Continue with ChatGPT", desktop only: the shell runs
  the OAuth and holds the refresh token; this module gets an hour-long access
  token and account id from it, and `providerKeyHeaders()` sends them as the
  OpenAI credential when no API key is pasted (`X-Provider-OpenAI` +
  `X-OpenAI-Account-Id`). Gated on `capabilities.chatgptAuth` from the shell
  and `chatgpt_auth_enabled` from `/api/providers/status` — both, always.
- `lib/projectDraft.js` — merges `PROJECT_DRAFT` events into the project
  with provenance (`user` / `crawl` / `document` / `inferred`, in that rank).
  Three rules: a user value is never overwritten, a filled field gives way
  only to an equal or higher rank (the site beats the user's files, which
  beat a model's guess; an unknown provenance ranks lowest), and **a
  non-empty field with no recorded provenance counts as the user's** —
  every project made before drafts existed is in that state, and without
  that rule the first draft to reach one replaced a human's name, pitch and
  industry with guesses. Which project a draft lands on is the caller's
  `projectId`; without one it resolves by the drafted site and creates,
  never "whatever is active". `/start` and `AuditWorkspace` apply them;
  nothing else writes drafts. Each draft is merged here for an instant
  answer and sent as a draft (`pushDraftToBackend`, one at a time per
  project, in order) to be merged again on the server, which keeps the
  labels and holds the same rules (`backend/service/project_draft.py`). A
  save sends the labels too, and the server settles it by them, so **an
  edit has to mark its field `user`** (`own()` on the project page): an
  unmarked empty field reads as a copy that never had the value.
- `lib/projects.js` — `siteKey()` / `projectsForSite()` are how a site
  address finds its project: lowercase host, no leading `www.`, subdomains
  kept distinct. `projectsForSite` returns every match, because two is a
  question for the user and not a thing to guess at.
- `lib/auditSession.js` — the `sessionStorage` hand-off into
  `/audit/seo/[sessionId]`. The request goes to the backend verbatim (an
  unknown field is a 422), so client-only state — the "connect a model"
  card, a kickoff message, which project this run writes to — is nested
  under one `client` key rather than stripped by name on arrival.
- `lib/membersApi.js` — project members + invitations (server-only; no localStorage mirror, unlike `lib/projects.js`)
- `lib/modelSettings.js` — the tier map and the fallback switch, on the server.
  `lib/modelTiers.js` still owns the vocabulary and the `localStorage` copy;
  the two coexist because the local copy paints the page before the network
  answers and is what a signed-out install runs on, while the server copy is
  what every run reads — including the scheduled brief, which has no browser.
  On disagreement the server wins, and every write is a partial so a stale tab
  cannot put back a control it never saw.
- `components/models/` — the Models & providers page, in parts, because
  `/preview` can only document a component it can import. `TierSummary` is
  what the Tiers tab opens with: the setup you already have, in three lines,
  with the three-way choice behind Customise — **most people bring one key**,
  and the page it replaced asked all three questions before answering any.
  Two rules that page is one careless change away from losing, both of which
  it had already lost once: **say the credential answer once** (`sourcesAgree`
  decides whether the summary says it for the page or the cards say it each),
  and **state the fall-through rule once**, in the drawn chain. `UsagePanel`
  is the whole Usage view and has two homes — the `/usage` route and this
  page's third tab — so change it there, never fork it into either caller.
  `ModelPicker` is the **only `SelectGroup` in the app**, and it must keep
  `position="popper"`: Radix's default `item-aligned` positions the list by
  aligning the selected item over the trigger and never resolves one inside a
  group, so the list opens at the viewport's bottom-left corner and the
  control reads as dead. `DeskComposer` carries the same prop for the same
  reason. The **Images row is a picker, not a report**: `image_model` on
  `user_model_settings` names which model draws, and `resolve_image_run`
  treats it as a preference — an unknown id, or one whose provider has no
  spendable key, falls through to `IMAGE_PROVIDER_ORDER` rather than failing
  the run. `/providers/status` takes the same argument and must keep giving
  the same answer, because that row is a promise about what the run will do.
  The **Videos row** under it is the same picker on the same rule
  (`video_model`, `resolve_video_run`, `VIDEO_PROVIDER_ORDER`), and the two
  share one divider because neither is a rung of the ladder above.
  Its `UsageEmpty` is exported for one reason: `/preview` renders fixtures and
  never the API, and this panel's first paint is a fetch, so without that seam
  the two states most worth reviewing would be the two nobody could open.
- `lib/engines.js` — `DEFAULT_ENGINE` and the agent-type list. The engine is
  no longer a user choice: v3 is gone, every agent runs v1, so the Runtime
  tab, the `ENGINES` list and the agent↔engine support map went with it.
  Pass `DEFAULT_ENGINE` where the server wants an engine
- `lib/insightData.js` — insight fetching and management
- `lib/localInsights.js` — client-side insight storage
- `lib/reports.js` — report generation helpers
- `lib/appVersion.js` — is this tab running the build that is currently
  deployed. `NEXT_PUBLIC_BUILD_ID` is baked at build time (CI sets it to
  `github.sha`; see `.github/workflows/app.yml`) and compared against
  `/api/version`. Everything in it is written to stay quiet on doubt: an
  unknown deployed build, a failed poll and a build with no baked id all read
  as "no new version", because a reload prompt nobody needed is what teaches
  people to ignore the one they do. **Never reload for the user** — this app
  holds long agent runs and unsent input.
- `lib/userProfile.js` + `/settings/profile` — who Duct is answering and how
  they want to be written to: name, role, one writing preset, the language Duct
  writes *to them* in, and their own instructions. Server-owned, on the
  `lib/modelSettings.js` pattern (localStorage paints, the server wins, writes
  are partial), because the scheduled brief has no browser to send a preference
  from. One preset where the dialog had two grids: `service/profile.py` derives
  the `communication_style`/`report_depth` pair from it, so no prompt changed.
  The page's sample is canned on purpose — a live rewrite is a model call per
  click. **Communication language is not the project's output language (#125)
  and not interface localisation (#126):** chat follows this, an artifact
  follows the project's output language when it has one.
- `lib/userPreferences.js` — what is left after the profile moved to the
  server: the per-run dials the composer writes (`thinking`, `tier`,
  `preferred_artifact_format`, `context_compression`), plus the three fields an agent request still carries
  for signed-out runs, mirrored from the profile rather than edited here
- `lib/consent.js` — the consent *rule* and the stored decision. Names no vendor.
- `lib/analytics/` — the seam. `index.js` selects a provider from
  `NEXT_PUBLIC_ANALYTICS_PROVIDER` (unset → `posthog` when its key is
  set, else `none`); `posthog.js` is the only file that knows the vendor;
  `none.js` is a complete implementation, not a stub. Adding a provider is one
  file plus a line in `PROVIDERS`. **Nothing outside this directory may
  reference a tag vendor** — that is what lets a self-host build measure nothing
  without editing our consent logic, and it mirrors
  `desktop/src-tauri/src/telemetry/` on the Rust side.
- `ProductAnalytics` owns the flow. The desktop shell is never asked: the
  Preferences switch in `lib/telemetry.js` stands in for the banner there.
  Never load a tag manager from this code: the shell's IPC trusts every script
  on this origin, and a tag container exists to run scripts configured outside
  this repository. The one the edge adds is a known exception, not a precedent.
- `lib/format.js` — dates, numbers and labels: `relativeTime`, `relativeDays`,
  `formatDate`, `formatTime`, `toDate`, `dayKey`, `compactNumber`,
  `formatNumber`, `formatPercent`, `titleCase`, `formatTitle`, `capitalize`,
  `initials`.
  Use these instead of a component-local `fmtDate`/`fmtNum`/`prettify` — the
  per-component copies had drifted apart before they were consolidated.
- `lib/analyticsReport.js` + `components/content/AnalyticsReport.jsx` +
  `components/content/report/GrowthReportView.jsx` — the Analytics tab's
  growth report. The backend answers one payload (`getAnalyticsReport`); the
  lib reads it into the one state the tab is in (`reportState`: no sources,
  empty, generating, failed, fresh, stale), the sources a person may tick
  (`reconcileSelection` never leaves nothing ticked while something is
  ready) and the rows a block can draw (`chartRows` coerces the measure and
  drops rows without one; `drawableBlocks` skips a block type the app does
  not know rather than crashing the report). `AnalyticsReport` owns the
  pickers, the states and the wait (polling the read while a run writes,
  `pollWhileVisible`); `GrowthReportView` draws the blocks and is what the
  artifact library renders for `GROWTH_REPORT_JSON` too, so the stored copy
  and the live one cannot diverge. Model text fills clamped slots under
  translated labels; the only large type is the verdict. Nothing here
  regenerates on its own: Refresh is the one thing that spends a model run.
  Every state is a scene in `/preview` over `lib/__fixtures__/growthReport.mjs`.
- `lib/contentMetrics.js` — a content post's numbers, read the same way on
  every screen: `metricValue` / `metricsOf` walk `METRIC_ALIASES`, the mirror
  of `backend/service/content_metrics.py` that a backend test parses and holds
  equal, order included. Never read `post.perf.view_count` directly.
  `PostMetricsForm` is the one place numbers are typed in, and sends only what
  changed (`metricChanges`), because a sent value is marked manual and no sync
  refreshes it again.
- `lib/sse.js` — `consumeSseStream` / `parseSseDataFrame`, shared by every
  streaming endpoint (audit, content, insights)
- `lib/visibility.js` — `pollWhileVisible(tick, ms)` / `pageHidden()`. Every
  poller goes through it: the desktop window sits open all day behind other
  apps, and a tick nobody can see costs battery and wakes the backend. It
  re-checks on return, so a skipped tick loses nothing.
- `hooks/useNearViewport.js` — latches true once an element nears the screen.
  For list items that are expensive to fill (a fetch, a document in a frame);
  the artifact library is why it exists.
- `lib/authFetch.js` — the one home for the auth token: `AUTH_TOKEN_KEY`,
  `authToken`, `hasAuthToken`, `authedHeaders`, `authedRequest`, plus
  `decodeJwtPayload` / `isTokenValid`. Never hardcode `"duct_auth_token"`.
  It also owns **what a 401 means**, and that is not a per-page decision. The
  shared `X-API-Key` fails with 403, so a 401 is always the *user* half of the
  credential: missing, expired, or well-formed and correctly signed but naming
  someone the answering backend's database has never seen ("User not found").
  `AuthGuard` cannot see any of that — it reads `exp` on a token it never
  verifies — so `throwForStatus` retires the session instead: clears the right
  key for this shell, parks the current path, and fires `SESSION_EXPIRED_EVENT`
  for `AuthProvider` to sign out on. New user-scoped clients go through
  `authedRequest` / `authedFetch`, or call `throwForStatus` /
  `endSessionIfUnauthorized` if they parse errors themselves; a client that
  hand-rolls `if (!res.ok) throw` puts the backend's 401 prose on the page and
  leaves the app believing it is signed in. Opt out with `retireSession: false`
  only where signing out costs the user something they just did — the connector
  save does, because its 401 lands on the way back from the provider.
  It also records **which backend minted the session** (`AUTH_BACKEND_KEY`,
  written by `setAuthToken`), because the shell addresses two — its sidecar and
  the hosted API — and a token from the wrong one is well-formed, unexpired and
  correctly signed, so nothing else on the client can tell it apart.
  `reconcileStoredSession()` runs once, when `lib/localBackend.js` settles the
  backend (before anything below the gate renders), and discards a
  mismatch *quietly*: no event, no parked redirect, no "your session ended".
  That is the distinction — a mismatch is not an expiry, and treating it as one
  is what signed people out mid-use. A session with no recorded issuer predates
  this and is left alone, so upgrading signs nobody out.

## UI conventions

Full reasoning in `docs/engineering/2026-09-01-desktop-adaptive-ui-review.html` (in `duct`).

**[`DESIGN.md`](DESIGN.md) is the design & UX companion to this section** —
the look/feel/voice layer: design tokens as built, the canonical pattern per
job (cards, spinners, badges, empty/loading/error states, confirmations),
layout & density principles, microcopy voice, the anti-generated-UI
checklist, and a close-on-touch gap list. Read it before building or
restyling any screen. This section stays the home of the mechanical rules
below (sizing, units, CSS layout, accessibility).

Its **"Go and look"** section lists the reference builds to open in a browser
when a screen is off and the reason will not come — shadcn's components,
blocks, charts and typeset pages, which are the reference implementation of
the primitives we vendor. Compare a screenshot of the real thing against your
`/preview` frame; that is usually faster than reasoning from a stylesheet.

**Sizing: ask the container, not the window.** The viewport is the wrong ruler
here — the sidebar takes 16rem out of it, and the agent panes are user-resizable,
so `lg:` can be true while the box you are in is 300px. Each layout REGION
declares a container (`.app-main`, `.app-main-wide`, the full-bleed wrapper, both
`SplitWorkspace` panes), so components use `@`-variants and are correct wherever
they are placed.

- Content: `@container` variants on Tailwind's `@`-scale — `@md` 28rem, `@lg` 32rem,
  `@xl` 36rem, `@2xl` 42rem, `@4xl` 56rem. Roughly 224px per grid column.
- Viewport (`sm:`/`md:`/…) only for genuine device concerns: the sign-in page,
  the sidebar's mobile sheet, and `md:text-sm` on chat inputs (which exists to
  stop iOS zooming a sub-16px field). The pane toggle used to be on this list
  and was wrong there: `SplitWorkspace` now splits at `@xl/split`, its own
  width, because `md:` said "split" with the sidebar's 16rem already gone and
  clipped the right pane on an iPad in portrait and an iPhone in landscape.
- **Safe areas are applied once, at the edge.** The body pads left and right
  only (`styles/theme.css`); the top and bottom insets belong to whatever
  touches that edge — `.app-header`, the composer, the sidebar container,
  sheets, the corner notices. A full-height layout (`h-svh`, `h-dvh`) never
  adds them again, and an element that is `fixed` pads itself, because the
  body's padding does not reach it. Left and right are separate values on
  purpose: iPhone Duo's are asymmetric.
- No hand-picked pixel breakpoints. There are currently zero; keep it that way.
- Before adding `container-type` anywhere new: it implies `contain: layout`, which
  makes that element the containing block for `position: fixed` descendants.
  Overlays must be portalled (they are — see below) or they will shrink to it.

**Heavy code loads when it is on screen.** A library that only one kind of
surface uses — charts (Recharts, Nivo), syntax highlighting, Mermaid, the
slide rasteriser — is a `lazy()` import behind a placeholder of the same size,
never a static import in a module that common screens reach. A static one in
`ArtifactRenderer` put ~110 KB of charts on every screen that drew a markdown
card. Import a package's single file by path, not from its index: one Prism
theme from `styles/prism` shipped all ~45. Measure a route the way
`docs/engineering/2026-10-28-performance-review.md` did before and after.

**Long transcripts stay flat.** The chat pane re-renders on every token and
every clock tick, so anything it draws per row is `memo`ised and takes props
that keep their identity (the reducer preserves unchanged rows). A stream that
re-parses everything so far (a brief, a report) is throttled, never debounced:
a debounce never fires while chunks keep coming.

**Platform hooks.** The root layout sets `data-platform` (mac, windows, linux,
other) and `data-shell="desktop"` on `<html>` before first paint;
`styles/base.css` holds the rules that read them. Use them for platform fit
(Linux drops backdrop blur, WebKitGTK's slow path), never for features, which
gate on `getShellInfo()` capabilities.

**Units.** Type, spacing and sticky offsets in `rem` so they follow the reader's
text size. Device units stay `px`: borders, outlines, shadows, radii, 1px optical
nudges. Prose gets `max-width: var(--measure)` (68ch) or the `.measure` utility —
never tables, code, or column layouts.

**Every screen is built from the page frame.** `components/ui/page` gives
`Page`, `PageHeader`, `Section`, `TileGrid` and `HelpTip`; `ui/card` and
`ui/textarea` are the card and the multi-line field. A routed screen is
`<Page><PageHeader title=… status=… actions=… help=… />…</Page>`, nothing
else draws an `<h1>`, and there is no slot for a paragraph under the title:
one line of state goes in `status`, how the page works goes in `help`.
DESIGN.md's "The page frame" has the parts, the spacing table and the type
ramp. If a screen needs something the frame does not do, change the
primitive (and its `/preview` entry), never the one screen — that is the
whole difference between a design system and 139 bordered boxes.

**Generated content fills slots; it never shapes the layout.** Most text on
an agent screen was written at run time, by a model or by the person (a
thread's title is its first message, verbatim), so its count, length, mix
and age are unknown when the screen is built. A page's headline comes from
its state, lists are ranked and bounded in a pure function, repeated facts
merge, old ones file away, the person's words are quoted, and the surface
ships with scenario fixtures across those axes, rendered in `/preview` and
asserted on in a check. DESIGN.md's "Content awareness" has the rules;
`arrangeDesk` in `lib/desk.js` with `lib/__fixtures__/deskScenarios.mjs` is
the worked example. Orange text is `text-brand`, never `text-primary`:
`--primary` is the fill, and in dark no one orange can be both.

**Four checks hold the design system, and they are not advisory.** The first
three run in `npm run check:parity`, so CI has them; the fourth is its own CI
job (`app-layout` in `app.yml`):

- `scripts/check-design-system.mjs` (`npm run check:design`) fails on
  `text-[Npx]`, a raw Tailwind palette class, a hex in JSX, `window.confirm`,
  `Loader2`, `text-muted-foreground/NN`, a hand-rolled scrollbar
  (`::-webkit-scrollbar`, `scrollbar-thin`), a viewport prefix in a
  container region, an `<h1>` outside `PageHeader`, `.page-toolbar`, a raw
  `<textarea>`, a capsule-radius field, and a new hand-rolled card (that one
  is a burn-down `budget` that can only go down). It is a **ratchet**: each rule carries an `allow` map of the files
  that are genuinely exceptions, each with its reason. Removing a name is
  permanent. Adding one is a decision you write a sentence for — it is not how
  you quiet the check, any more than adding a file to
  `test_harness_boundaries.py`'s allowlist is how you fix a red test.
- `scripts/check-page-frame.mjs` (in `npm run check:design`) fails any routed
  screen under `app/(app)` that does not render `PageHeader`. Full-bleed agent
  workspaces are exempt by `FULL_BLEED_PREFIXES` in the layout, read from
  that file so the two cannot disagree.
- `scripts/check-layout.mjs` (`npm run check:layout`, needs the dev server)
  renders every framed screen at 390, 1100 and 1440px against the fixture
  backend and fails on a title out of line or off-size, a page wider than
  the window, a status that wraps, and a row of cards whose footers do not
  share a baseline. **Run it before calling any UI change done**; a worktree
  without `site/node_modules` passes `PLAYWRIGHT_FROM=<repo>/site`.
- `scripts/check-contrast.mjs` (`npm run check:contrast`) does the WCAG maths
  on the real oklch values in `tokens.css`/`theme.css` and fails when a pair
  the app paints drops below its threshold. It also asserts that every
  `--color-*` utility the app writes is actually **mapped** in `@theme inline`
  — the defect that started all of this was three correct token values that no
  class could reach, which is invisible to every other kind of review.

Why both exist rather than a paragraph asking nicely: every finding in
`docs/engineering/2026-09-06-design-system-contrast-review.md` had been fixed
once before and had come back. `ui/spinner`'s own docblock records consolidating
twelve hand-rolled rings; seventeen `Loader2`s had arrived since.

**CSS lives in `src/app/styles/`.** `globals.css` is a manifest of imports and
nothing else; order is load-bearing (see its header). Add a partial for a new
concern rather than growing an existing one, and put page-specific styling with
the page.

**Shared UI primitives — use them, don't re-fork.**

- Page frame: `ui/page` (`Page`, `PageHeader`, `Section`, `TileGrid`,
  `HelpTip`), `ui/card` (`Card`, `CardFooter`, `cardLinkClass`),
  `ui/textarea`. See "Every screen is built from the page frame" above.

- Overlays: `ui/dialog` (Radix — portal, focus trap, Escape, scroll lock) and
  `ui/lightbox`. Never hand-roll a `fixed inset-0` backdrop.
- Busy state: `ui/spinner`. Colour comes from `currentColor`. For content
  that has a shape, the wait is `ui/skeleton` (`Skeleton`, `SkeletonText`,
  `SkeletonList`, `SkeletonDocument`) — its shimmer is one CSS rule in
  `styles/skeleton.css`, and `check:design` rejects a hand-rolled
  `animate-pulse bg-muted` box.
- Asking "are you sure?": `ui/confirm-dialog`. `useConfirm()` returns
  `{ confirm, dialog }` — await `confirm({ title, description, action,
  destructive })` and render `{dialog}`, which is deliberately close enough to
  `window.confirm` that moving a call site is one line. `<ConfirmDialog>`
  directly when the caller already holds what is being confirmed in state.
- Truncated text (2+ lines): `ui/clamp-text`'s `ClampText` — `line-clamp-N`
  plus a Radix tooltip carrying the full string, capped separately. Full
  reasoning (including why a bare `line-clamp` or a native `title` isn't
  enough) is in `DESIGN.md`'s canon table.
- Corner notices: `ui/corner-notice`. The bottom-right card that tells you
  something without interrupting you — `UpdateToast` (desktop build available)
  and `ReloadToast` (new web build) are both built from it. Extracted at the
  third copy of the anatomy, not after it. It is **not** a toast system: no
  queue, no timers, no imperative `notify()`, because every notice here is a
  persistent condition its owner already tracks in state. `ConnectionBanner`
  deliberately takes the opposite corner (`sm:left-4`) so the two never fight;
  below `sm` it is a full-width bar and wins on DOM order, which is correct —
  a lost backend outranks a pending refresh. **Precedence is one rule: a
  notice that tells outranks one that asks.** Tellers (every `CornerNotice`,
  plus `ConnectionBanner` and `CookieConsent` through `useHoldCorner`) hold the
  corner while mounted; an asker passes `yields`, reads `useCornerTaken()`,
  never appears while it is held and steps aside when a teller arrives.
  `StarAsk` (#539) is the only asker: the GitHub star request after a run that
  made something, on the rules in `lib/starAsk.js` (three good runs, never day
  one, never mid-run, never over the message box, which is why `ChatInput`
  carries `data-composer`; two showings ever, 60 days apart, never after a
  star or a second no). Its permanent home is "Star Duct on GitHub" in the
  account menu, which is what lets the corner ask stay rare. A new notice
  that asks for something yields; one that tells does nothing extra.
- Agent shells: `hooks/useAgentSession` (the session lifecycle),
  `workspace/AgentChat` (the transcript pane), `workspace/SplitWorkspace`
  (split + responsive), `PipelineProgress` (the working ladder),
  `workspace/CodeBlock`. See "Agent workspaces" below before touching any of
  them.
- Shortcuts: `lib/shortcuts`' `useShortcut("mod+k", fn)` — platform-neutral, owned
  by the surface that needs it. An Enter-to-send handler checks
  `isComposing(e)` first: Enter confirms a Japanese, Chinese or Korean
  candidate, and without the check it sent half-written messages.
- Commands: `useRegisterCommands` from `components/commands/CommandRegistry`. A
  route contributes its own commands and they withdraw on unmount.
- Navigation: `lib/navigation`'s `NAV_SECTIONS` is the single source of truth for
  the sidebar and the palette.

**Agent workspaces — one lifecycle, one chat pane, agent-specific slots.**

Three agents (content, audit, insights) share a session protocol: create,
stream, park on a pause, chat, reconnect, resume. That protocol lives in two
places and nowhere else:

- `lib/agentSession.js` — the pure reducer over the shared `AgentEvent`
  vocabulary (`lib/agentEvents.js`) and the `Phase` enum (`lib/agentPhase.js`).
  No React, no network. Tested by replaying recorded streams from
  `lib/__fixtures__/*.json` (`npm test`).
- `hooks/useAgentSession.js` — the effects: session creation with orphan
  cleanup, transcript hydration before the live stream, the reconnect loop
  (reattach to the live session, then resume the conversation), pause answers
  by `interrupt_id`, and the per-tab reload handle (`lib/agentSessionHandle.js`)
  that lets a reloaded tab reattach instead of re-running the prompt. Leaving
  the page mid-turn detaches rather than closes: the handle stays, the run is
  noted in `lib/liveRuns.js` (the sidebar pulses its entry, `hooks/useLiveRuns.js`
  polls the session until the turn ends), and a return hydrates the rows and
  reattaches from the segment after the ones it has (`hydratedThroughSegment`),
  so the backlog is not drawn twice. Only Stop cancels a run. Its
  `onHydrate` hands a workspace the stored rows verbatim, for a pane the
  transcript does not cover. No workspace needs it today: insights derives its
  Data pane from the transcript's own activity rows (`dataSourceRollup` in
  `lib/toolActivity.js`), so a reload rebuilds it without fetching the thread
  twice.

A workspace composes `useAgentSession` + `workspace/AgentChat` +
`workspace/SplitWorkspace` and keeps only what its agent owns: the right pane,
the events the reducer returns unchanged (a plan payload, an artifact version,
a slide render request) handled in `onEvent`, and the copy. Read
`components/content/ContentWorkspace.jsx` as the reference — it is the
shortest of the three.

To see it run without a backend: `npm run mock:agents` replays the fixtures
over SSE on :8012 (pausing where the real backend would), and
`scripts/smoke-agent-workspaces.mjs` drives all three workspaces through a
headless browser against it — pause, reload-and-reattach, answer, follow-up,
turn failure — and screenshots each state. Run it after touching the shell.
The same mock takes `FIXTURES_DIR` (another set of streams with the same
filenames), `ROUTES_FILE` (canned JSON for the non-agent routes it would
otherwise answer with `[]`) and `MEDIA_DIR` (a folder served as
`/uploads/story/*`, so a post can have a cover); `scripts/shots/shoot.mjs` at
the repo root uses all three to shoot the README's product images from one
story, `lib/__fixtures__/solo-story.mjs`, whose `shot-*` scenes in
`/preview` are the component halves of the same week.

The shell borrows deliberately from harnesses built in the open.
[`docs/engineering/agent-harness-references.md`](../docs/engineering/agent-harness-references.md)
records which ones, at which revision, and the gaps they expose in ours (a
status row with elapsed time, typed error codes, queued follow-ups, context
left). Check it before adding a lifecycle feature — the answer is often
already pinned to a `file:line` there.

Rules that follow:

- **Do not fork the chat pane or the lifecycle.** A new agent gets a new
  workspace file of ~150 lines, not a new `*Chat.jsx`. Two forks of the chat
  had drifted 600 lines apart while rendering the same thing; a third had
  none of the fixes. That is the failure this structure exists to prevent.
- **A new pause is one entry in `workspace/PauseCard.jsx`.** The reducer, the
  hook and the backend route already carry any pause event that arrives with
  an `interrupt_id`; the card is the only agent-visible part.
- **A new protocol event goes in the reducer, with a fixture.** Agent-specific
  payloads stay in the workspace's `onEvent`. The backend holds the other end:
  `backend/tests/test_app_event_contract.py` parses `lib/agentEvents.js`,
  `lib/insightsEvents.js` and every fixture here and fails when an event
  name, error code, step id or memory kind exists on one side only (legacy
  `LEGACY_*` values excepted, since the app deploys first). Add the member to
  both enums in the same change, and record only kinds the backend stores.
- **Phases are the protocol, not a UI mood.** Only the reducer moves `phase`;
  a workspace that needs a different input policy passes `inputDisabled`
  rather than inventing a state. The default policy keeps the box open while
  the agent works or a card waits: a message then is *queued* (the row carries
  a mark until `user_input_consumed` releases it), not refused and not a new
  turn.
- **Failures are typed; copy comes from the code.** `friendlyErrorMessage(raw,
  code)` and `errorAction(code)` in `lib/agentSession.js` are the only places
  a failure becomes words or a button. A new failure kind is a new `ErrorCode`
  (mirrored from the backend) with a row in `ERROR_COPY`, never a regex on the
  message. The rows are `msg` descriptors — the reducer has no locale — and
  the state holds a descriptor or, when a provider's own sentence passes
  through, a string; a component renders either with `errorText(i18n,
  value)`, never `i18n._` on the value, because a raw sentence with a brace
  in it is not an ICU message. The literal-string check cannot see a string
  in an object literal or a `dispatch`, so a sentence in `lib/` or `hooks/`
  is translated by this rule, not by the check.
- **The status row says what is happening, with a clock.** While the agent
  works the header reads `Working · 1m 12s · Collecting source data` — phase,
  elapsed, and the step in progress (or "Reconnecting to the model (2/4)",
  "Compacting context"). The context ring sits in the composer beside Send —
  `workspace/ContextRing` over the reducer's `usage`, empty and labelled "New
  thread" until the first call reports — the same place and the same ring
  the insights desk shows. The composer (`workspace/ChatInput`) is the desk
  composer's card: text on top, a footer with attach and the shell's
  `composerTools` (`workspace/ComposerDials` for insights: the posture, Ask /
  Assisted / Auto, folded to the current choice and unfolding on hover,
  focus or a tap) on the left, and `composerAside` (`TierDial`: the model
  tier as quiet text, whose popover holds the tier list and thinking as a
  stepped slider), the ring and Send on the right. The ring carries no
  label; percent, tokens, cost and the cached share are its tooltip (a dash
  where the backend has no price for the model), and it is a gauge, not a
  button — it answers hover and Tab and does nothing on click. Placement
  follows when a dial binds: the posture applies to the next message, so it
  is inline;
  tier and thinking bind at the next session, so they are one tap away; the
  tier is the one choice people look for by name, so it stands at the
  corner of the box like every chat app's model name, and thinking is a
  property of that choice, so it lives under it. That panel is a
  `ui/popover`, not a menu — a menu swallows Tab and a slider inside one is
  mouse-only. The brief's shape (`preferred_artifact_format`) has no
  composer control any more; the preference and the backend's reading of it
  remain. A retry counts down (`retrying.until`, anchored on this
  client's clock at receipt), and the tooltip carries cost and the cached
  share beside the tokens. After a compaction the ring is empty and says so
  (`usage.last.stale`) until the next call on the thread reports its size.
- **The right pane is one strip and one document.** `ArtifactPaneHeader`
  carries everything about the document — the tab, its title, the version
  picker, and the grid button back to the thread's other documents — so the
  pane below it is the artifact and nothing else: full bleed, full height,
  scrolling itself, never a card inside a margin and never a `vh` height,
  which caps a document inside a pane that already has a size. A markdown
  brief gets a centred page (`DocumentPage`) because `card` and `background`
  are the same white in the light theme and something has to say "document"
  next to the chat; an HTML brief is its own white page already. The strip's
  two document controls are download and full screen: the download saves the
  bytes the pane already holds (`briefFile` names the file, `lib/download.js`
  hands it to the browser — never a second fetch for content that is on
  screen), and full screen opens `DocumentFocus`, the same `BriefPane` on the
  app's dialog. Reading mode keeps only what a reader needs — the name, the
  download, the way out — and never grows tabs or a version picker.
- **The transcript has a row vocabulary, and every agent gets it for free.**
  A run is mostly tool calls, and a harness that renders none of them is a
  text box in front of a black box. `workspace/ActivityRow` draws one row per
  allowlisted call where it happened — connector logo and name, what it read,
  the window, the verdict — one line until clicked, with the kind's own detail
  behind the chevron (row counts, source chips with favicons, the picture, the
  sub-agent's answer) and, for a failure, the provider's own sentence plus the
  link that fixes it. It sits beside the other rows of the same register:
  artifact card, change-set card, memory note, image, notice.
  - The rows arrive as one event (`TOOL_ACTIVITY`), land through the reducer
    (`Row.ACTIVITY`, upserted by `activity_id`) and come back on a reopened
    thread from stored tool traffic (`lib/toolActivity.js`) — **live and replay
    build the same shape**, and `test_app_event_contract.py` holds the app's
    allowlist to the backend's.
  - **A new visible tool is two lines and a scene**: a mapper in
    `agents/core/activity.py`, an entry in `ACTIVITY_TOOLS` here, and a
    `/preview` scene. Never a per-agent pane, never a second card component.
    The backend sends fields, never a sentence: a tool whose card has no
    sentence of its own (a read of the brand context, a post published) gets
    its verb from `TOOL_WORDS` in `ActivityRow`, so it is translated with the
    rest. Twelve kinds now — the seven tool families (a video clip since
    #284) plus memory, context, artifact, action and a tool on an MCP
    server the user connected (#345) — and the run's own
    "Read project context" row (`contextActivity`, from the stored CONTEXT
    row on replay) says which
    blocks the opening turn was enriched with. Memory's "Recalled" and
    "Remembered" rows come back from their stored rows the same way.
  - **Where a fact belongs**: in the transcript when it is something the agent
    *did* (there once, in order), in a pane when it is something the thread
    *has* (the Data tab's roll-up, grouped by connector — built from the same
    rows, so the two cannot disagree).
- **The wait and the seams are said in words, never mimed.** Three rows in
  `workspace/AgentChat`, each a fact the reader could not otherwise learn:
  - `WorkingIndicator` replaces the bouncing dots. It shows the running
    step's label when the ladder has one, "Compacting context" or
    "Reconnecting" when the harness is doing that, and otherwise rotates a
    few generic verbs — generic on purpose, because a verb naming a step the
    run is not on is a lie the reader can catch. Still under reduced motion.
  - `ThinkingBlock` folds the reasoning under "Thought for 6s": measured on
    this client between the first reasoning token and the first word of prose
    (`thinkingStartedAt` / `thinkingEndedAt` on the assistant row), never a
    token count the client would have to estimate. A row from history has no
    clock and says "Reasoning".
  - `Notice` dividers (`lib/agentSession.js`): a compaction is a rule across
    the transcript that learns what it freed from the next thread-scoped
    `TOKEN_USAGE`; a run starting on a different model draws "Switched to
    Claude Sonnet 5.5" from the `model_label` every `PIPELINE_STARTED` now
    carries (`agents/models.run_model_fields`), and replay draws it from the
    stored CONTEXT rows. The compaction rule folds the summary the backend
    sent (`summary` on `CONTEXT_COMPACTED`, an `EventKind.COMPACTED` row on
    replay) behind a chevron, set in italic: it is the model's notes, not
    something the agent said to the person. Anything true of everything
    after it is a divider, not a bubble.
- **Two registers, not two bubbles.** The person's message is the one bubble
  in the transcript — it came from outside the run and the shape says so;
  past a screen's worth (`LONG_TEXT_LINES` / `LONG_TEXT_CHARS`) it folds
  behind Show more with the whole text still in the DOM. The reply is prose
  on the page, no box. Under either, on hover, `RowMeta`: when it was sent
  as "5 min ago" with the full date and time in the tooltip (from `at`,
  stamped by the reducer on this client's clock live and from `created_at`
  on replay, and drawn only after mount so a server render cannot disagree),
  plus one action on a reply — copy. Always visible where there is no hover.
  Do not add reactions, regenerate, or a menu there; the row is not a toolbar.
- **A file on a message is one tile, both sides.** `workspace/Attachments`
  draws it in the composer (with remove) and on the user's row (read-only,
  image opens the lightbox); `lib/attachments.js` is the one parser between
  them — `contentBlocks` builds what the chat route takes (a plain string
  when nothing is attached, else text plus an image block, a `file` block for
  a PDF, or a text block wrapped in `<attachment name= type=>` for anything
  textual) and `describeContent` reads that same list back for the live row
  and the reopened thread, so the two cannot show different things. The
  composer takes files three ways into that one shape: the paperclip, a
  drop anywhere on the card (`DropHint` while a file is over it), and a
  paste — an image from the clipboard, or text past `PASTE_ATTACH_LINES` /
  `PASTE_ATTACH_CHARS`, which becomes a tile named for what it looks like
  (`sniffPaste`: JSON, HTML, CSV, Markdown, else plain text). What cannot
  be read — a binary, a file over `ATTACH_MAX_BYTES` — says so under the
  tiles rather than vanishing.
- **Stop hands a queued message back.** A user row still marked queued when
  the run is stopped never reached the model: the reducer takes it out of the
  transcript and puts its text in `draft`, which `ChatInput` applies once per
  `draft.key`. Losing a typed message is worse than losing the run.
- **The box keeps what was typed.** `ChatInput` saves its text per
  `draftKey` — the shell's `handleKey`, so a reload of this thread finds
  this thread's draft — through `lib/composerDraft.js`, which the desk
  composer's Settings round-trip uses too, and clears it on send. The
  store is `sessionStorage`, per tab, for the reason the session handle
  gives: the key names a thread, not a user, so anything that outlived the
  tab would follow a shared browser into the next sign-in. Esc in
  the box stops a streaming turn (scoped to the box: a window-level Escape
  would also fire while someone closes a popover); Shift+Enter is a new
  line; the footer names both while the box has focus.
- **Notifications come from phase transitions, never from a workspace.** A
  workspace names itself (`notifyAs`) and `hooks/useAgentNotifications.js`
  turns done / needs-input / failed into a system notice — only while the
  window is not focused, never for a stop the user asked for. The transport is
  `lib/notify.js`: the shell's `notify` command when `getShellInfo()` reports
  `notifications`, the browser's `Notification` behind the sidebar's permission
  item otherwise. Do not call `new Notification` from a component. That sidebar
  item asks `notificationSurface()` rather than testing `"Notification" in
  window` — no desktop webview has that constructor, so the test hid the row on
  desktop and left the one surface that always notifies looking like the one
  that never did. On the shell it reads "System", because the OS owns the
  switch and there is nothing for the page to request.
- **A stored failure is a row, not a blank.** `agentHistory.js` maps the
  `failure` event kind to the same send-error row the live client showed (with
  its code, so the action under it is the right one), and a `cancelled` one to
  the "Stopped here" notice. Thread lists read `run_status` off the list route
  for their badge (`DeskLists`, the audit history); the desk routes `paused`
  and `failed` threads to "Needs you" (`lib/desk.js`).
- **Streaming markdown is settled plus a healed tail.** `AssistantMarkdown`
  with `streaming` splits at the last block boundary (`lib/markdownStream.js`):
  the settled part is memoised and parsed once per closed block; only the tail
  re-renders per delta, after `healTail` closes an open fence or emphasis and
  drops a table's partial row. That is what keeps a table's columns still while
  it streams. Do not reintroduce a per-token parse of the whole reply.

**Accessibility.** Desktop keyboard and screen-reader basics, not a full audit.

- Every form control needs an accessible name. A `placeholder` is not one — it
  disappears on focus and is skipped by some readers. Use a visible `<label>`,
  or `aria-label` where the design has no room for one.
- Anything clickable is a `<button>`. A `<div onClick>` cannot be tabbed to or
  triggered with Enter/Space, and the focus ring comes free with the element.
  For a whole card, put the button on the title and stretch it with an
  `after:absolute after:inset-0` pseudo-element — one tab stop, one readable
  name, and the card stays a container.
- Live regions are rationed. The agent's phase label (`role="status"`) is the
  one in each chat shell; streaming tokens and the rotating `PipelineProgress`
  subtitle are deliberately silent, because announcing them talks over the user.
- `html { scroll-padding-top: 4rem }` in `styles/base.css` keeps a focused
  element out from under the sticky header (WCAG 2.2 AA 2.4.11).
- Decorative icons take `aria-hidden`; an icon-only button takes an `aria-label`.

**Look at it before you call it done.** CSS written and never rendered is a
guess, and guesses compound: three plausible-sounding rules in a row produce a
layout nobody would have drawn on purpose. If a change touches layout, spacing,
alignment or colour, render it and check — do not use the person reviewing the
PR as your renderer.

Two things about *where* to look, both learned on the front door. The desktop
shell is WKWebView, so a screen judged in the desktop app is verified in
Playwright's `webkit`, not only `chromium` — `site/node_modules` has both. And
a long-lived Duct Dev window is not a fresh page load: it takes Turbopack's
hot updates, and on 2026-09-21 it took the JSX updates for a change but not
the stylesheet, and sat showing new copy on an old layout while every fresh
load was correct. Its cache (`~/Library/Caches/ai.getduct.desktop.dev/WebKit/
NetworkCache`) held a stylesheet from before the edits. After a CSS change,
reload the dev window before trusting what it shows, and before telling
anyone the layout is broken — or fixed.

**Use `/preview`.** `src/app/preview/` is a dev-only route (404s in production,
no auth, no backend) that mounts one component at a time in the real app's CSS.
Add scenes to `preview/scenes.jsx`; pick a **surface** (in place, dialog, sheet,
drawer, alert, notification, page, toolbar) and a **device** (phone, iPad either
way up, desktop-min, desktop, wide), in light, dark, or both at once.

**A new component gets a preview entry in the same change, not a follow-up.**
This project is open source, so `/preview` is not only a working tool — it is
the component library's documentation, the one place a contributor or a future
agent can see what exists and how it is meant to look without reading every
call site. Ship one of: a `PRIMITIVES` entry in `preview/system.jsx` for a new
`components/ui/*` part that has a variant to choose between (the narrow
exception — a single-appearance part like `separator`, folded into the
specimens that use it instead of standing alone — is explained at the top of
that file); a canon row in `DESIGN.md` plus its matching example in
`preview/catalogue.jsx` for a new canonical pattern; or, short of either, a
`preview/scenes.jsx` entry so the component can at least be seen in isolation.
A component with none of these is undocumented, whatever comment describes it.

Two modes, because there are two jobs:

- **Working** — the workbench. Seed a component by adding a scene to
  `preview/scenes.jsx`: `{ id, group, title, state, note, render }`, importing
  the real component and passing real props. That is the whole API. Ad hoc and
  skewed to the last thing touched, which is correct for what it is for.
- **Design system** — the durable catalogue, in three sections:
  **Foundations** (`preview/system.jsx` — colour/type/shape via `TokenSheet`,
  spacing, icons), **Primitives** (same file — every `ui/*` part with its
  variants), and **Patterns** (`preview/catalogue.jsx` — one entry per row of
  DESIGN.md's canon table). Pattern rules are **parsed from DESIGN.md**
  (`preview/canon.js`), never retyped, so the screen cannot disagree with the
  doc. A rule with no example is listed as a **gap** and counted in the header,
  so coverage is a number rather than an impression.

Adding a canon row to DESIGN.md therefore adds a gap. Close it with an example,
or leave it visible; do not delete the row to make the count look better.

Frames **mount only when scrolled near** and the catalogue crops them to their
specimen. Both are load-bearing, not polish: each frame is a whole Next document
(app bundle, analytics, HMR client), and 27 entries × 2 devices eagerly mounted is
not slow, it is `ERR_INSUFFICIENT_RESOURCES` and a half-loaded page. Keep the
lazy mount if you touch `Frame`.

`/preview/frame?scene=…&surface=…&theme=…` renders one scene alone, so any state
is reachable by URL with nothing to click, and every frame exposes
`window.__preview` — `measure`, `contrast`, `aligned`, `smallTargets`,
`unnamed`, `overflowing`, `typeScale`, `tokens`, `overlay`. Prefer those over
retyping measurement code; they answer the same question the same way twice.
Full detail in the `component-preview` skill.

**Lenses** are the third axis, after surface and device: a device changes what
the component is, a lens changes who is looking at it. All are URL parameters.

- `vision=protanopia|deuteranopia|tritanopia|greyscale` — colour-vision
  simulation. WCAG 1.4.1 says colour is never the only channel, and this is what
  makes that checkable instead of assumed: under `deuteranopia` the connected
  green dot and the partial amber one converge, which is why the word stays
  beside the dot.
- `text=125|150|200` — the reader's text size, as a percentage. Type and spacing
  are in `rem` by house rule precisely so they follow it, which is only worth
  anything if someone moves it. A layout that holds at 100% and collapses at
  150% has a `px` in it.
- `inspect=outline|spacing|grid` — debug paint. `grid` is the spacing scale
  drawn, in `rem`, so it stays in phase with the layout under the text lens.

The **`tokens` scene** is the palette as the app actually resolves it — every
semantic pair with its live contrast ratio, the colours used as ink on the page,
the type ladder and the radii. It is read from computed style, so it cannot
drift from `tokens.css`, and the value shown is the one after the cascade: open
it in a dark frame to see the dark half. Check a new or changed token here
before shipping it. It earned that on its first render, catching
`--destructive-foreground` missing from the `.dark` block — white on the lifted
coral, 2.89:1, where its three neighbours sat at 7.8–9.9.

The preview chrome is built from `ui/*` like anything else. It shipped once with
native `<select>`s, and a native `<select>` draws its option list in the OS: it
ignored every class on the element and rendered a system-font, system-light menu
over a dark app. A harness for judging our components must not be the one screen
that does not use them.

Scenes render in **iframes, not resized divs**: media queries read the viewport,
so a `<div style="width:390px">` answers the container question and silently
gets `sm:`/`md:`/`dvh` wrong. Each frame also sets `container-type`, so both
rulers are right at once.

Do **not** rebuild a component's markup in a scratch HTML file next to a copy of
its stylesheet. That is a replica, and replicas drift: the first one written
that way was missing Tailwind's preflight, measured every box 34px too wide, and
sent a correct layout back for a fix it did not need.

- **Render every state, not just the happy one.** Partial, empty, loading,
  failed, disabled, and a name long enough to wrap are where layouts break, and
  they are the ones nobody opens by accident. A long account name is what
  revealed a status row wrapping onto three lines.
- **Widths are container widths, not devices.** The `@`-scale boundaries the
  code branches on, and each frame declares `container-type` so the variants
  respond to the frame rather than the window. Frames drag-resize; sweep the
  448–720 band rather than sampling it.
- **Measure, do not squint.** `getBoundingClientRect()` answers alignment
  exactly, and answers questions eyes are bad at: two glyphs can share a
  vertical centre and still look wrong because their boxes are 7px and 24px with
  padding on only one. Assert what the guides make checkable — shared rails,
  equal slots, the 24×24 target floor, rows that must stay on one line,
  `getComputedStyle` proving a destructive action is tinted, not filled.
- **A component that fetches gets an injectable loader** with a real default
  (`loadEntities` on `ProjectEntitySelect`), so a scene can stub it. One
  optional prop beats a hand-copied render of the same markup.

**Full-app visual review is a different, heavier job — do it only when asked**,
or when the change is to a whole screen's composition rather than to a
component. Opening real screens needs a signed-in session and a live backend,
and it answers a question isolation cannot: whether the piece fits its
surroundings. In-place work does not need that question answered, and paying
for it every time is why "look at it" gets skipped.

## Interface language

The interface is translated (English, Spanish, Brazilian Portuguese, German,
Japanese, Simplified Chinese) and stays translated mechanically, not by anyone remembering. Copy
is written in English inline, as before; Lingui derives each message's id
from that English, `npm run i18n:extract` writes the catalogues, and
`scripts/i18n/fill.py` fills what is missing with a model, glossary in hand.
A changed English string invalidates its own translations and gets refilled.
`check:i18n` fails on an untranslated string, a stale catalogue, or a literal
the catalogue cannot see — so a half-translated page cannot merge.

**The loop, for any change that touches copy** (`make i18n` at the repo root
runs it for the app and the site together):

```bash
npm run i18n:extract                 # catalogues pick up the new/changed strings
python3 ../scripts/i18n/fill.py      # translates only what is missing (needs a key,
                                     # or --provider manual to hand the entries to an agent)
npm run check:i18n                   # stale? missing? literal outside Lingui? → red
python3 ../scripts/i18n/fill.py --check src/locales/*/messages.po   # a brand name translated? → red
```

Product and brand names (Duct, Content Studio, every connector and vendor)
stay in English in every language: they are `keep` in
`scripts/i18n/glossary.json`, `fill.py` rejects a translation that drops one,
and the `--check` above fails CI on one already in a catalogue. A new product
name in the UI goes into `keep` in the same change.

Staleness is `lingui check sync`: it compares each catalogue with what
extract would write, **byte for byte**, and writes nothing. Two consequences:

- `scripts/i18n/po.py` writes an app catalogue back in Lingui's own layout,
  so `fill.py` output passes the check. If the check fails straight after a
  fill run with nothing else changed, that writer has drifted; fix it rather
  than re-running extract to paper over it.
- Run it on Node 22, the version in `.nvmrc` and CI. Lingui 6.8 starts every
  subcommand behind `import.meta.main`, which Node 23 does not have, so there
  `extract`, `compile` and `check` all exit 0 having done nothing: a green
  gate that ran no check.

**How to write copy so the catalogue sees it.** One import per file:
`import { Trans, useLingui } from "@lingui/react/macro";`

| Copy | Write |
|---|---|
| JSX text | `<Trans>Restart to update</Trans>` |
| Text with markup or values | `<Trans>You’re on {version}. <b>Restart</b> to update.</Trans>` — keep the element and the value inside one `<Trans>`; a sentence split across three Trans cannot be reordered by a translator |
| Attribute, prop, or any string in code | `const { t } = useLingui();` then `` t`Dismiss update notification` `` |
| Values in a string | `` t`Duct ${version} is available` `` — a plain identifier. Assign `update.version` to `const version` first; a member expression becomes `{0}` in the catalogue and the translator cannot tell what it is |
| Plurals in JSX | `<Plural value={count} one="# message" other="# messages" />` from `@lingui/react/macro` |
| Plurals in a string | `plural(count, { one: "# message", other: "# messages" })` from `@lingui/core/macro`, client components only |
| A label in a module-level list (`lib/*.js` option tables) | `` label: msg`Executive` `` from `@lingui/core/macro`, rendered with `const { i18n } = useLingui(); i18n._(option.label)` — `t` at module level returns one fixed string forever |
| A message the same word means two things | `` t({ message: "Post", context: "verb" }) `` |
| Dates and numbers | `formatDate(d, { locale: i18n.locale })` from `lib/format.js`; never pin `"en"` next to translated copy |

Do not translate: enum values, keys, kinds, API fields, class names, routes,
log lines, anything a test asserts on by string, and the `/preview` scenes and
`__fixtures__` (fictional data, English by design). The check exempts those
paths; everything else it flags is copy.

Two modules deliberately carry no words: `lib/desk.js` returns codes and
facts (`{ code: "waiting" }`, `{ state, needsYou, found }`) that the desk
components map to `msg` tables, because `scripts/check-desk.mjs` runs it
under plain Node where no macro exists; `desk/useRelativeTime.js` renders its
times. Passing `t` into a plain helper is silently NOT transformed — nothing
is extracted and the helper receives a raw template — so a helper that needs
words takes `i18n` and a `msg` descriptor, or returns a code.

Tests: vitest has no macro pass, so `vitest.config.mjs` aliases the macro
entry points to `src/lib/__tests__/stubs/lingui-macro.js`, which returns the
English. A `lib/*.js` module with a `msg` label therefore imports cleanly in
a test; assert on the English string as before.

Server components: the root layout calls `activateRequestI18n()` from
`src/i18n/server.js`, and so must any server page or layout that renders
translatable text, because a client-side navigation renders the page without
its parents. `<Trans>` and `useLingui` then work in both worlds.

Where the language comes from: the `duct_lang` cookie, else the browser's
`Accept-Language`, else English — resolved once per request in the root layout.
The cookie shadows `interface_language` on the profile (`lib/userProfile.js`
writes it on every load and save) so a second device follows the first; the
signed-out selector on `/start` and sign-in writes only the cookie.
`components/LanguageMenu.jsx` is the one switcher, and `router.refresh()` is
how a switch takes effect without a reload.

Three language fields, kept apart (#125, #126, #127): `interface_language`
is this one, a catalogue tag; `communication_language` is what Duct writes
*to you* in, any language a model speaks; a project's output language is the
deliverable's. Adding an interface language is one entry in
`lingui.config.mjs`, one in `src/i18n/locales.js`, one in
`service/profile.py`'s `INTERFACE_LANGUAGES`, and a fill run.

The SWC macro plugin is a locked pair with Next: `@lingui/swc-plugin` is
pinned exact because its `swc_core` must fall in the range Next's runtime
accepts, and a semver bump broke the build with "failed to run Wasm plugin"
(6.7.0 against Next 16.3.5). Next 16.4 moved the other way and failed the
same way against 6.6.0, so the pair is now Next 16.4 with 6.7.1 (#336).
Bumping Next means re-testing the plugin.
`.github/dependabot.yml` ignores version updates for it so the bump is not
re-proposed weekly — a security advisory still opens its own PR. Lifting the
pin is a deliberate act that travels with a Next bump, and the gate is
`npm --prefix app run build` completing, not CI going green on the install.

To see a screen in another language: `/preview` has a locale switch, and the
`pseudo` locale (dev only) stretches every string so clipping shows without a
German speaker. The preview is English by default whatever the browser's
Accept-Language or the app's cookie say — its frame takes `?lang=` and
nothing else, so a scene's language is in its URL like every other lens.

## What's not here

- No dedicated auth library (next-auth, Clerk, Supabase)
- No form library (React Hook Form, Formik)
- No global state library (Redux, Zustand, Jotai)
- **Vitest** (`npm test`) covers the pure-logic layer only:
  `src/lib/__tests__/*.test.js`. No jsdom, no component tests, no E2E — the
  config pins `environment: "node"` deliberately ("the hook and the
  components are checked by `next build` and by looking at them"), and E2E
  tests live in `site/`, not `app/`. A module that touches `window` or
  `document` is still testable this way if it's plain functions, not
  components: stub the pieces it reads (`localStorage`, `document.cookie`,
  `fetch`) on `globalThis` in a `beforeEach` — see `authFetch.test.js` and
  `consent.test.js` for the pattern. A module whose surface *is* a React
  component (`AuthProvider`, `AuthGuard`) needs `@testing-library/react` and a
  `jsdom` environment, neither of which is set up yet — that's a real
  infrastructure step, not just another test file, so treat adding it as its
  own change. This rules out *committed* browser tests; it does not rule out
  driving a browser to look at what you just built. See "Look at it before you
  call it done" above — read as a blanket ban, this line is why UI arrives
  unrendered. `src/app/preview/` is not a test suite either: it is a route
  that renders components, with no runner, no assertions and no dependency.
- No Supabase anywhere in this project

<!-- BEGIN:nextjs-agent-rules -->

## This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.

<!-- END:nextjs-agent-rules -->
