@terreno/mcp 58.0.0-beta.3 → 58.0.0

package/dist/docs/versioned/57.22.0/implementationPlans/lifecycle-user-guide.md

@@ -0,0 +1,60 @@
+# An end-user guide that grows with every feature
+
+**Status:** Proposed
+**Roadmap:** Area=`dx`, Target=`Next`, Impact=`Feature`
+**Branch:** user-guide
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1642
+**Owner:** Josh Gachnang
+**Created:** 2026-10-26
+**Depends on:** [e2e-and-regression-testing](e2e-and-regression-testing.md)
+
+Chat agents cannot answer "how do I…" questions about an app today, because no text
+describes its features in the words users see. Developer docs explain APIs, not how to
+reset a password or what a screen is for, and a guide written once at the end drifts
+from the app the first time a label changes. This plan makes the end-user guide a
+required part of every IP, written by the same task that ships the feature, so the guide
+stays true and a chat agent can be pointed at it.
+
+## The idea
+
+- One plain-text page per feature at `docs/user-guide/<area>/<feature>.md`, with
+  frontmatter a retriever can use: `title`, `area`, `audience` (`user`, `admin`, or
+  `staff`), `platforms`, one to five `questions` users would ask, optional `screens`,
+  and `added`. The body has three fixed sections: What it does, How to use it, Intended
+  use.
+- Every IP gains a required `## User guide` section (rows or `None — <reason>`). Grow
+  plans the rows, Pick writes each page with its feature, Roast checks the steps against
+  the shipped screens, Brew gates on pages and the index, and Taste updates pages after
+  fixes.
+- A repository with no end users opts out with `| User guide | none — <reason> |` under
+  `## User guide conventions` in AGENTS.md or CLAUDE.md.
+- `backfill-user-guide` drafts pages for features that shipped before the contract and
+  writes only the pages a human approves. `bun run check:user-guide` validates the pages
+  and index in CI.
+- Terreno keeps a guide for the example app; brewery mirrors the contract and opts out.
+
+Contract: [`user-guide.md`](../../plugins/terreno-planning/references/user-guide.md).
+Implementation: [#1633](https://github.com/TerrenoLabs/terreno/pull/1633), stacked on
+[#1628](https://github.com/TerrenoLabs/terreno/pull/1628).
+
+## Open questions for discussion
+
+| ID | Question | Recommendation |
+| --- | --- | --- |
+| Q1 | [support-agent](support-agent.md) plans AI-authored docs in `support/kb/**/*.md` with its own frontmatter. Is the user guide that corpus, a source it ingests, or separate? | Make the user guide one `KnowledgeSource` the support agent ingests, and align the frontmatter (`audience`, `questions`) so one page serves both. |
+| Q2 | Should guide pages ship inside the app bundle, or be served by the backend? | Serve from the backend through the support agent, so pages update without an app release. |
+| Q3 | Who reviews guide wording: developers in the PR, or product? | Developers in the PR; product reviews the backfill sets. |
+
+## E2E tests
+
+None — tooling and documentation contract; `bun test scripts/userGuide` and
+`bun run check:lifecycle-skills` prove it.
+
+## Regression cases
+
+None — no hard-to-automate change.
+
+## User guide
+
+None — the guide contract itself; the seeded example-app pages are listed in
+`docs/user-guide/README.md`.

package/dist/docs/versioned/57.22.0/implementationPlans/list-detail-layout.md

@@ -0,0 +1,297 @@
+# ListDetailLayout: a route-driven list/detail layout for phone and tablet
+
+**Status:** Approved
+**Roadmap:** Area=`ui`, Target=`Next`, Impact=`Feature`
+**Branch:** list-detail-layout
+**Owner:** Josh Gachnang
+**Created:** 2026-10-20
+
+`@terreno/ui` ships `SplitPage` for list/detail screens. It keeps the selected item in
+local state, so a selected item has no URL. Deep links and browser or Android back
+don't work for it. The native build has no tablet layout at all; its first line is a
+TODO. This adds `ListDetailLayout`, which is used from an Expo Router `_layout.tsx`.
+On a phone it is a scrolling list that pushes a detail screen. On a tablet or wide
+browser the list stays in a left pane and the detail opens on the right. The URL always
+names the open item. App developers building mail-, inbox- or records-style screens get
+one layout that behaves correctly on every device. SplitPage stays as it is, but its
+docs point to the new layout as the preferred choice.
+
+## The idea
+
+A route group owns the list/detail pair, so the router (not component state) holds the
+selection:
+
+```tsx
+// app/mail/_layout.tsx
+export const unstable_settings = {initialRouteName: "index"};
+const MailLayout: React.FC = () => (
+  <ListDetailLayout
+    detailHref={(id) => `/mail/${id}`}
+    indexHref="/mail"
+    emptyDetail={<Text>Select a message</Text>}
+    list={<MailList />}
+  />
+);
+// app/mail/index.tsx: the list on a phone, the empty state on a tablet
+const MailIndex: React.FC = () => <ListDetailIndex />;
+// app/mail/[id].tsx: an ordinary route screen
+// MailList rows: const {selectedId, select} = useListDetail();
+```
+
+`ListDetailLayout` always renders one Expo Router `<Stack>`, inside a detail-pane
+wrapper that is present at every width. When the layout's own measured width is at
+least `splitAtWidth` (default 768), it also renders the `list` as a sibling pane to the
+left. The width is measured with `onLayout`; before the first layout it falls back to
+the window width. Measuring the container means the layout still decides correctly
+inside a sidebar or admin rail. The Stack's position in the tree never changes, so it
+never remounts, and rotating a tablet or resizing a browser keeps the open item. On a
+phone you get native push animations and swipe-back.
+
+Rejected alternatives:
+
+- A custom `Navigator` like `SidebarNavigation`: it has no native push animation or
+  iOS swipe-back on phones.
+- Swapping `<Stack>` and `<Slot>` at the breakpoint: it remounts the navigator and
+  drops deep-linked routes (`example-frontend/app/_layout.tsx:285-290`).
+- Expo Router's `unstable-split-view`: iOS only. Elsewhere it is a plain Slot, and it
+  can't sit inside another navigator.
+
+## The plan
+
+| # | Task | Depends on | Lands in | Proves it |
+| --- | --- | --- | --- | --- |
+| T1 | Layout switch: list pane beside a never-remounted Stack | none | ui | bun tests: panes at 375/1024 px, Stack mount count 1 |
+| T2 | Selection lives in the route: `useListDetail` select/clear/selectedId, plus a how-to | T1 | ui, docs | bun tests on router calls and params |
+| T3 | Crossing the breakpoint keeps the open item | T2 | ui | bun tests on selectedId and the narrow detail |
+| T4 | Demo mail example, standalone and inside SidebarNavigation | T2 | demo | registration + coverage tests, screenshot script |
+| T5 | Example-frontend todo browser: Playwright phone/tablet + Maestro flow | T3 | example-frontend | Playwright spec at 390 and 1024 px; Maestro flow |
+| T6 | Guidance: skills, rules, guidelines, changelog prefer ListDetailLayout | T2 | plugins, rules | `skills:check`, `rules:check`, `check:changelog` |
+| T7 | Native proof on iOS and Android phone + tablet (demo build), best effort | T4 | .maestro | native Maestro flow on the available devices (D4) |
+
+Tracer: T1 cuts through the new layout seam, from the measured width to the rendered
+panes.
+Out of scope: a built-in third (folders) pane; a non-router controlled variant; native
+iOS UISplitViewController; changes to SplitPage behaviour (see Expansions).
+Open risks:
+- Native proof is best effort (D4). A device with no simulator available is reported as skipped, not proven.
+
+## Contract
+
+Props live in `ui/src/Common.ts` next to `SplitPageProps`.
+
+| Export | Shape | Notes |
+| --- | --- | --- |
+| `ListDetailLayout` | `React.FC<ListDetailLayoutProps>` | Used as a route group's `_layout.tsx` default export |
+| `ListDetailLayoutProps.list` | `ReactElement` | Rendered in the left pane when split; by `ListDetailIndex` when not |
+| `ListDetailLayoutProps.detailHref` | `(id: string) => Href` | Where `select(id)` navigates |
+| `ListDetailLayoutProps.indexHref` | `string` | The group's own path (e.g. `/mail`); `clear()` target and the scope for `selectedId` |
+| `ListDetailLayoutProps.emptyDetail` | `ReactElement?` | Right pane when split and nothing is selected |
+| `ListDetailLayoutProps.splitAtWidth` | `number?`, default 768 | Split when the layout's measured width is ≥ this |
+| `ListDetailLayoutProps.listWidth` | `number?`, default 360 | Left pane width when split |
+| `ListDetailLayoutProps.detailRoute` | `string?`, default `"[id]"` | The child route name that holds the detail |
+| `ListDetailLayoutProps.paramName` | `string?`, default `"id"` | Route param holding the item id |
+| `ListDetailLayoutProps.screenOptions`, `children` | passthrough to `<Stack>` | `Stack.Screen` children and options |
+| `ListDetailIndex` | `React.FC` | The group's `index.tsx`: `list` when not split, `emptyDetail` when split |
+| `useListDetail()` | `{isSplit, selectedId?, select(id), clear()}` | Throws outside a `ListDetailLayout` |
+
+`selectedId` comes from `useGlobalSearchParams()[paramName]`. It counts only while
+`usePathname()` is exactly one segment below `indexHref` and `useSegments()` ends with
+`detailRoute`. That way an `id` param from a parent dynamic segment or another route
+never leaks in.
+
+testIDs (fixed, for app e2e): `list-detail-layout`, `list-detail-list-pane`,
+`list-detail-detail-pane`, `list-detail-empty`.
+
+## Tasks
+
+- [x] **T1** — Render the list pane beside a never-remounted Stack on wide layouts
+  - Depends on: none
+  - Files: ui/src/ListDetailLayout.tsx, ui/src/isolated/ListDetailLayout.isolated.tsx, ui/src/Common.ts, ui/src/index.tsx, ui/src/SplitPage.tsx, ui/src/SplitPage.native.tsx, scripts/check-demo-coverage.ts, docs/reference/ui.md
+  - Delivers: `ListDetailLayout`, `ListDetailIndex`, `useListDetail().isSplit`, and the props in the Contract table except selection. `ListDetailLayout` and `ListDetailIndex` get temporary `DEMO_COVERAGE_ALLOWLIST` entries ("story lands in T4") so `check:demo-coverage` stays green.
+  - Criteria:
+    - `list-detail-detail-pane` wraps the `<Stack>` at every width.
+    - At a measured width of 1024, `list-detail-list-pane` (width `listWidth`, default 360) renders as a sibling before it, and `isSplit` is true.
+    - At 375 there is no list pane, and `isSplit` is false.
+    - Width comes from the root's `onLayout`, falling back to `useWindowDimensions` before the first layout event. A 1024 window with a 600 px layout event is not split.
+    - `splitAtWidth={1200}` at 1024 is not split. At exactly 768 with the default, it is split.
+    - Re-rendering 1024 → 375 → 1024 mounts the `<Stack>` exactly once (a mount-counting Stack mock).
+    - `ListDetailIndex` renders `list` when not split, and `emptyDetail` (wrapped in `list-detail-empty`) when split.
+    - `screenOptions` and `Stack.Screen` children reach the Stack.
+    - `useListDetail()` outside the layout throws a descriptive error.
+    - The left pane has a theme border divider. Colors come from theme tokens (no hex).
+  - Docs:
+    - `docs/reference/ui.md` gets a `### ListDetailLayout` section (a props table and the `_layout`/`index`/`[id]` example).
+    - The `### SplitPage` section and the `SplitPage` JSDoc (`ui/src/SplitPage.tsx`) say `ListDetailLayout` is preferred for new screens.
+    - In `ui/src/SplitPage.native.tsx`, the stale tablet TODO on line 1 is replaced by the same note.
+    - SplitPage keeps working and is not marked `@deprecated`.
+  - Verification: `cd ui && bun test ./src/isolated/ListDetailLayout.isolated.tsx` passes, using the mocked `useWindowDimensions` and `expo-router` from `ui/src/bunSetup.ts` and firing `layout` events. `bun run compile` and `bun run lint` pass.
+
+- [x] **T2** — Keep the selected item in the route with useListDetail
+  - Depends on: T1
+  - Files: ui/src/ListDetailLayout.tsx, ui/src/isolated/ListDetailLayout.isolated.tsx, ui/src/Common.ts, ui/src/Box.tsx, ui/src/Box.test.tsx, docs/reference/ui.md, docs/how-to/build-list-detail-screens.md, docs/how-to/README.md
+  - Added in Pick: `Box` `accessibilityState.selected`, sent as `aria-current="true"` on a clickable row (ARIA forbids `aria-selected` on a button) and as `aria-selected` on selectable roles (`tab`, `option`, `row`, ...), so list rows can report selection; T4/T5 rows rely on it.
+  - Criteria:
+    - With `useSegments` mocked to end in `[id]` and `useGlobalSearchParams` returning `{id: "3"}`, `selectedId` is `"3"`.
+    - With segments ending in `index`, `selectedId` is `undefined` even if the params contain `id`.
+    - With `indexHref="/orgs/9/mail"`, a pathname of `/orgs/9/mail` and params `{id: "9"}` (a parent dynamic segment), `selectedId` is `undefined`.
+    - When not split, `select(id)` calls `router.push(detailHref(id))`.
+    - When split with nothing open, `select(id)` pushes.
+    - When split with a detail open, `select(id)` calls `router.replace(detailHref(id))`, so the stack is never deeper than index + one detail (D6).
+    - When split, `select(selectedId)` is a no-op.
+    - `clear()` calls `router.dismissTo(indexHref)` when an item is open, so it never leaves the group, and does nothing when none is open. (Changed in Pick: `router.back()` asks the root navigator and can leave the group.)
+    - When split, Stack screens get `headerBackVisible: false` and `animation: "none"`. (Added in T4: also a `headerLeft`, because expo-router's web header ignores `headerBackVisible`. Changed after T5's Roast: that `headerLeft` is a `list-detail-leave` back button that leaves the group through the parent navigator, or nothing when the parent cannot go back, so a tablet is never stuck inside the group.) The caller's `screenOptions` win where they set the same key.
+  - Docs:
+    - The `ui.md` section documents `useListDetail` and the history rule.
+    - New `docs/how-to/build-list-detail-screens.md`, linked from `docs/how-to/README.md`, covers:
+      - the route group (`_layout`/`index`/`[id]`)
+      - `unstable_settings.initialRouteName` for deep links on phones
+      - selecting rows with `accessibilityState.selected`
+      - nesting inside `SidebarNavigation`
+      - when to use SplitPage instead (non-route list/detail)
+  - Verification: `bun test ./src/isolated/ListDetailLayout.isolated.tsx` asserts the router mock calls and screen options at 375 and 1024 px.
+
+- [x] **T3** — Keep the open item when crossing the breakpoint
+  - Depends on: T2
+  - Files: ui/src/ListDetailLayout.tsx, ui/src/isolated/ListDetailLayout.isolated.tsx, docs/reference/ui.md
+  - Criteria:
+    - With a detail open (segments `[id]`, `id: "3"`), layout events 1024 → 375 → 1024 leave `selectedId` `"3"` throughout.
+    - At 375 with segments ending in `[id]`, there is no list pane and the detail route stays mounted. The mocked Stack renders no routes; T5's Playwright resize check proves the rendered detail.
+    - Changed in Pick: `ListDetailIndex` keeps rendering `list` at 375 while the detail is open, because it is the index screen under the detail and swipe-back must reveal the list.
+    - No router call is made during a resize.
+  - Docs: the `ui.md` section notes that rotation and resize keep the open item, and that the list pane remounts (its scroll position resets; X5).
+  - Verification: `bun test ./src/isolated/ListDetailLayout.isolated.tsx`.
+
+- [x] **T4** — Add the demo mail example, standalone and inside SidebarNavigation
+  - Depends on: T2
+  - Files: demo/app/demo/_layout.tsx, demo/app/demo/list-detail/_layout.tsx, demo/app/demo/list-detail/index.tsx, demo/app/demo/list-detail/[id].tsx, demo/components/MailList.tsx, demo/components/MailMessage.tsx, demo/components/mailFixtures.ts, demo/app/demo/sidebar-navigation/_layout.tsx, demo/app/demo/sidebar-navigation/mail/_layout.tsx, demo/app/demo/sidebar-navigation/mail/index.tsx, demo/app/demo/sidebar-navigation/mail/[id].tsx, demo/story-config/ListDetailLayout.config.tsx, demo/demoConfig.tsx, demo/p0Stories.registration.test.ts, scripts/check-demo-coverage.ts, scripts/captureListDetail.ts
+  - Added in Pick: demo/stories/ListDetailLayout.stories.tsx (route launcher), demo/components/MailLayout.tsx (shared by both mounts), package.json `ui:list-detail:capture` + knip.jsonc entry, and ui/src/ListDetailLayout.tsx `headerLeft: () => null` in split mode (the web header ignored `headerBackVisible` and still drew a back arrow).
+  - Delivers:
+    - An inbox of about 30 static messages (sender, subject, preview, a date via Luxon) in shared `MailList` / `MailMessage` components.
+    - Rows highlight the selected message and set `accessibilityState={{selected: true}}`.
+    - The same group is mounted twice: standalone at `/demo/list-detail`, and at `/demo/sidebar-navigation/mail` as a new "Mail" sidebar item, proving the composition D1 relies on.
+    - A `ListDetailLayoutConfiguration` story (`component: ListDetailLayout`) links to both routes, like `SidebarNavigationExpoRouterConfiguration`.
+    - T1's temporary allowlist entry for `ListDetailLayout` is removed. `ListDetailIndex` keeps an allowlist entry with the reason "Covered by the ListDetailLayout story".
+    - `demo/app/demo/_layout.tsx` registers `list-detail` with `headerShown: false`, as it already does for `sidebar-navigation`, so phones don't show a double header.
+  - Criteria:
+    - `demo/p0Stories.registration.test.ts` asserts `ListDetailLayoutConfiguration` is registered.
+    - From the repo root, `bun run scripts/check-demo-coverage.ts` reports nothing missing for `ListDetailLayout` or `ListDetailIndex`.
+    - Root `scripts/captureListDetail.ts` uses `@playwright/test`'s `chromium` (like `scripts/charts/compareRenderedSnapshots.ts`) against the running demo web server. It captures screenshots to `/opt/cursor/artifacts/list-detail-demo-*.png` and exits non-zero when any expected testID is missing:
+      - `/demo/list-detail` at 390×844: the list, no list pane.
+      - `/demo/list-detail/3` at 390×844: only message 3.
+      - `/demo/list-detail/3` at 1024×768: both panes, row 3 selected.
+      - `/demo/sidebar-navigation/mail/3` at 1280×800: both panes beside the sidebar.
+  - Verification:
+    - `cd demo && bun test --only-failures p0Stories.registration.test.ts`
+    - `bun run scripts/check-demo-coverage.ts` from the repo root
+    - `cd demo && bun run web`, then `bun run ui:list-detail:capture` from the repo root
+    - `bun run check:knip` passes
+    - Behaviour against a real router and data is proven in T5; this script is the visual evidence.
+
+- [x] **T5** — Browse todos in a list/detail layout in example-frontend
+  - Depends on: T3
+  - Files: example-frontend/app/todo-browser/_layout.tsx, example-frontend/app/todo-browser/index.tsx, example-frontend/app/todo-browser/[id].tsx, example-frontend/components/TodoBrowserList.tsx, example-frontend/components/SyncTodosScreen.tsx, example-frontend/app/_layout.tsx, example-frontend/e2e/todo-browser.spec.ts, .maestro/flows/todo-browser.yaml, .maestro/flows/config.yaml
+  - Delivers:
+    - `/todo-browser` lists the user's todos with syncdb `useEntityIds`, and shows one todo's title, status and created date with `useTodo`.
+    - The detail has a complete toggle.
+    - It is linked from the todos screen (`todos-browse-button`) and registered in the root Stack as `todo-browser`. The root Stack already sets `headerShown: false`, and the group's own Stack supplies the header.
+    - testIDs: `todo-browser-item-{id}` (with `aria-current="true"` when selected), `todo-browser-detail-{id}`, `todo-browser-detail-toggle`.
+  - Criteria (Playwright, `loginAs` in `beforeEach`, seeded todos):
+    - Phone (390×844): tapping an item shows `todo-browser-detail-{id}` with no `list-detail-list-pane`. Browser back returns to the list.
+    - Tablet (1024×768):
+      - `list-detail-list-pane` and `list-detail-empty` are visible.
+      - Tapping item A shows its detail, the list stays visible, the URL is `/todo-browser/{A}`, and item A has `aria-current="true"`.
+      - Tapping item B replaces the detail and moves `aria-current` to B.
+      - Browser back then returns to `/todo-browser`.
+    - Deep link: `/todo-browser/{id}` at 1024×768 shows the list with that row `aria-current="true"`, plus the detail.
+    - Resize: with a detail open at 1024×768, `setViewportSize(390×844)` keeps `todo-browser-detail-{id}` visible.
+    - Keyboard: at 1024×768, Tab from the last list row moves focus into `list-detail-detail-pane`.
+    - The Maestro web flow `.maestro/flows/todo-browser.yaml` passes under `bun run maestro:test`:
+      - It is listed in `.maestro/flows/config.yaml` after `create-todo`.
+      - It reuses the session from `login.yaml`, so it has no login of its own.
+      - Steps: open the browser, tap a todo, assert the detail, go back, assert the list.
+  - Verification:
+    - `cd example-frontend && bunx playwright test e2e/todo-browser.spec.ts`
+    - `bun run maestro:test`
+    - A terreno:verify-ui-changes run saves screenshots to `/opt/cursor/artifacts/`. Native devices are T7.
+  - Added in Pick: docs/explanation/example-coverage.md gets a List/detail row. The Maestro web flow could not run in this sandbox (the existing `login.yaml` flow also fails here: headless Chromium under gVisor); CI's `run-maestro` job runs it.
+
+- [ ] **T7** — Prove the layout on native phones and tablets
+  - Depends on: T4
+  - Status: follow-up after this PR (D4: best effort). No simulator was available, so the flow, the script, and the native runs are not in the PR. The demo marks iOS and Android `inProgress` until this task passes.
+  - Files: .maestro/flows/native/list-detail.yaml, package.json, docs/how-to/build-list-detail-screens.md
+  - Delivers:
+    - A native Maestro flow (`appId: com.terreno.demo`) over the demo mail example, which needs no backend.
+    - A root script `maestro:native:list-detail` to run it.
+  - Criteria, each recorded with a screenshot in `/opt/cursor/artifacts/`:
+    - **iPhone simulator:** opening a message pushes it with no list pane, and an edge swipe-back returns to the list.
+    - **iPad simulator (≥ 768pt), landscape:** list and message side by side.
+    - **iPad, rotated to portrait and back with a message open:** the message stays open.
+    - **Android phone emulator:** opening a message pushes it, and hardware back (`pressKey: back`) returns to the list.
+    - **Android tablet emulator (≥ 768dp):** both panes, and rotating with a message open keeps it.
+  - Docs: the how-to's verification section names the flow and the four devices.
+  - Verification:
+    - `bun run maestro:native:list-detail` on each device, using a demo dev build (`demo` `ios` / `android` scripts).
+    - The Android emulator comes from the cloud toolchain (`install-cloud-dev-tools.sh`).
+    - Best effort (D4): run on every device that is available. The stage result lists each device as passed, failed, or skipped (no device). A skipped device does not block the PR, and the PR body names it. A device that ran and failed does block.
+
+- [x] **T6** — Point framework guidance at ListDetailLayout
+  - Depends on: T2
+  - Files: plugins/terreno-planning/skills/terreno-ui/SKILL.md, plugins/terreno-planning/skills/terreno-ui/references/layout.md, plugins/terreno-planning/skills/building-terreno-apps/references/route-structure.md, .rulesync/rules/00-root.md, .rulesync/rules/01-claudecode-root.md, .rulesync/rules/ui/00-ui.md, ui/.ai/guidelines/core.md, mcp-server/src/docs/resources/ui.md, changelog/unreleased/list-detail-layout.md. Regenerated, not hand-edited: skills/, plugins/terreno-claude/, the rulesync outputs (AGENTS.md, CLAUDE*.md, .claude/, .cursor/, .devin/, .github/), mcp-server/src/docs/guidelines/.
+  - Criteria:
+    - In the terreno-ui skill, the line 153 row `| Two-column layout | \`SplitPage\` |` recommends `ListDetailLayout` for route-backed list/detail, and SplitPage for non-route uses.
+    - `route-structure.md` shows the `_layout`/`index`/`[id]` group.
+    - `- **Layout**: Box, Page, SplitPage, Card` (`.rulesync/rules/00-root.md:325`, `01-claudecode-root.md:222`, and the same line in `ui/.ai/guidelines/core.md:5`) gains `ListDetailLayout`. So does the `### Layout` list at `.rulesync/rules/ui/00-ui.md:81`.
+    - The changelog entry is `category: Added`.
+    - Added in Pick: root `AGENTS.md` and the per-package `AGENTS.md` / `.claude/CLAUDE.local.md` / `.cursor` / `.github` copies are hand-maintained (no generator writes them), so the same Layout line was updated in each.
+  - Verification:
+    - Run `bun run skills:sync`, `bun run rules`, and `cd mcp-server && bun run sync-package-guidelines`. Then `bun run skills:check` and `bun run rules:check` pass.
+    - `bun run check:changelog` passes.
+    - `grep -rn ListDetailLayout plugins/terreno-claude/skills/terreno-ui skills/terreno-ui` matches.
+
+## Assumptions
+
+- `@terreno/ui` already depends on `expo-router` (`ui/package.json`), and `SidebarNavigation` is an expo-router precedent, so no new dependency or subpath export is needed.
+- Tablets are detected by width only, as elsewhere in ui (there is no `Platform.isPad` use).
+  - Under the default, iPads at least 768pt wide in portrait split.
+  - iPad mini portrait (744pt) and narrow iPad Split View get the phone layout.
+- Apps set `unstable_settings = {initialRouteName: "index"}` in the group layout so that a deep link on a phone has the list to go back to. The how-to and both examples do this.
+- The demo static export lists each fixture id from `generateStaticParams` on both `[id]` routes. The Netlify demo deploy also rewrites unknown paths to `index.html`. Without those, `/demo/list-detail/2` and `/demo/sidebar-navigation/mail/2` 404 on the static host.
+- The list pane remounts when crossing the breakpoint, so its scroll position resets. The open item does not.
+- No backend, model, or SDK change: T5 reuses existing synced todos. No PHI is involved.
+
+Supporting skills: terreno:terreno-ui, terreno:building-terreno-apps,
+terreno:terreno-data-fetching (T5), terreno:update-docs, terreno:verify-ui-changes,
+accessibility-testing.
+
+## Open questions (recommendation assumed)
+
+None.
+
+## Expansions (follow up later)
+
+| ID | Idea | Why it came up | Rough size | Depends on |
+| --- | --- | --- | --- | --- |
+| X1 | Built-in third pane (folders / nav \| list \| detail) | "side bar" in the request; you chose two panes | M | T3 |
+| X2 | Controlled, no-router variant (`selectedId`/`onSelect`) for modals and tabs | You chose router-only | S | T1 |
+| X3 | Use `expo-router/unstable-split-view` on iOS for a native UISplitViewController | Exists in expo-router 57, iOS only | M | T3 |
+| X4 | Migrate SplitPage's demo stories, or deprecate it, once apps have moved | You chose to keep both | S | T6 |
+| X5 | Keep list scroll position across the breakpoint | List pane remounts on resize | S | T3 |
+| X6 | Tablet/phone Playwright projects for the whole example-frontend suite | Today there is only one 1280×900 viewport (`example-frontend/playwright.config.ts:91`) | S | T5 |
+
+## Decisions
+
+| ID | Question asked | Answer | What it changes |
+| --- | --- | --- | --- |
+| D1 | How many panes should the tablet layout have? | Two panes (list \| detail) | No built-in nav column; T4 proves it composes with `SidebarNavigation`; a third pane is X1 |
+| D2 (durable) | Should the selected item live only in the URL, or also be usable without routes? | Router layout only | The selection is always a route; no controlled variant (X2) |
+| D3 | What should happen to SplitPage? | Keep both, but note in SplitPage that the new component is the preferred system | T1 adds a "prefer ListDetailLayout" note to SplitPage's JSDoc and docs; there is no `@deprecated` tag and no removal |
+| D4 | Must native phone + tablet proof (iOS and Android) pass before the PR, even if it waits on a human for a simulator? | Best effort | T7 runs on the available devices and reports skips; skipped devices don't block the PR |
+| D5 | At what width should it split? | 768 (layout width, overridable with `splitAtWidth`) | As planned. iPad mini portrait and 600–767dp Android tablets get the phone layout |
+| D6 | In split mode, should picking a second item add a history entry? (approved with the plan) | No, replace it | As planned in T2/T5 |
+| D7 | Name? (approved with the plan) | `ListDetailLayout` / `ListDetailIndex` / `useListDetail` | As planned |
+| D8 | Which example app proves it end to end? (approved with the plan) | example-frontend todos plus a static demo inbox | As planned in T4/T5 |
+
+## Sign-off
+
+Status: approved 2026-10-20 (chat)
+Cut: 2 rounds, 20 findings: 19 fixed, 1 moved to questions or expansions (native proof → T7, settled as D4), 0 rebutted

package/dist/docs/versioned/57.22.0/implementationPlans/login-redesign/HANDOFF.md

@@ -0,0 +1,211 @@
+# Login screen redesign — build handoff
+
+**Repo:** `TerrenoLabs/terreno`, branch `auth-experience` (PR #1613)
+**Design canvas:** https://claude.ai/artifact/4AExCVaPYePwyRym9twPsn (12 boards; static HTML copies are in `boards/` next to this file)
+**Scope:** visual and layout changes to the login flow in `@terreno/ui` and `@terreno/rtk`. No API, auth-logic or server changes.
+
+Build everything with existing `@terreno/ui` primitives (`Box`, `Text`, `Heading`, `Button`, `TextField`, `Banner`, `Avatar`, `Icon`, `IconButton`, `Badge`, `Spinner`) and theme roles. Never hard-code hex values; the boards use raw hex only because they are static mockups. The role each color maps to is listed under "Tokens" below.
+
+---
+
+## 1. What is wrong today (current `ui/src/login/LoginScreen.tsx`)
+
+1. Up to three section dividers ("Or sign in another way", "Or log in with email", "Or continue with") on one screen.
+2. The passkey button is stranded at the very bottom, below "Sign up".
+3. The `error` text renders under the password field even when the failure came from a social button at the top ("Auth cancelled").
+4. Each remembered account is its own bordered card with a grey "Forget" pill button and a third "Uses Apple" line.
+5. `LastUsedBadge` floats right-aligned *above* the button it labels.
+6. Social buttons are three different fills (black, white, near-black).
+7. "Forgot password?" is a `muted` pill button and "Need an account? Sign Up" is a full-width outline button, so secondary actions look like primary ones.
+
+---
+
+## 2. Target layout
+
+Mobile-first, centered column, `maxWidth={400}`, screen padding `spacing4` horizontally. Vertical rhythm: `gap={6}` (24px) between blocks, `gap={3}` (12px) inside a button stack, `gap={4}` (16px) between form fields.
+
+Order, top to bottom (each block only renders when it applies):
+
+1. **Logo** (`logo` prop, unchanged).
+2. **Heading block** — `Heading size="xl"` + one line of `Text color="secondaryLight"` subtitle.
+   - With continue-as accounts: "Welcome back" / "Pick up where you left off."
+   - Without: "Sign in" / "Choose how you want to sign in."
+   - Add a `subtitle?: string` prop; keep `title` overridable. Default titles above replace "Welcome Back".
+3. **Feedback banner** — the single place for `notice` *and* `error` (see §4). Never under a field, except field-level errors (§4.3).
+4. **Continue-as list** (§3.1), if there are accounts.
+5. **Methods**:
+   - With accounts: collapsed behind one `Button variant="muted" fullWidth text="Sign in another way"`. Pressing it expands, in place, a divider "or sign in another way" followed by the method stack and the email form. (Local `useState`; reset to collapsed on unmount.)
+   - Without accounts: always expanded.
+6. **Method stack** — every social provider, generic provider and passkey as identical full-width outline pills (§3.2), in this order: last-used method first, then branded providers in their given order, then generic providers, then passkey.
+7. **One divider** — "or use your email" (only when there is a form *and* at least one method above it).
+8. **Email form** — fields, then the primary submit. "Forgot password?" is a text link on the password field's label row (§3.3).
+9. **Footer** — pushed to the bottom: `Text`: "New here? " + link "Create an account" (`onSignUpPress`). Not a button.
+
+There is never more than **one visible divider** above the form (two total in the expanded returning state: one before methods, one before email).
+
+---
+
+## 3. Components
+
+### 3.1 Continue-as list (rewrite `LoginAccountCard.tsx`, add a list wrapper)
+
+- Section header row: `Heading size="sm"` "Continue as" on the left; text link "Edit" on the right (only when `onForget` is set and at least one remembered account exists).
+- One container: `border="default"`, `rounding="lg"` (16px), `overflow hidden`. Rows separated by a 1px `border-hover` top border, no per-row borders.
+- Row (whole row is the `Pressable`, min height 68, padding `spacing3`/`spacing4`):
+  - `Avatar size="sm"` (40px) or the `circle-user` icon fallback.
+  - Line 1: name, `Text bold`, truncate; if this account's method equals `lastUsedMethod`, an inline "Last used" pill right after the name (§3.4).
+  - Line 2 (`size="sm" color="secondaryLight"`): provider icon (12px, brands set: `apple`/`google`/`github`; `key` for passkey; `envelope` for email) + "`{Provider} · {masked email}`". For a session row: green presence dot + "Signed in · {email}".
+  - Trailing `chevron-right` icon, `color="secondaryLight"`.
+  - Remove the "Uses Apple" line and the "Forget" button from the row.
+- **Edit mode** (new local state, header link toggles "Edit" ↔ "Done"):
+  - Header text becomes "Accounts on this device".
+  - Rows stop being pressable; chevron is replaced by a `Button variant="ghost"` with `text="Remove"` in error text color, 44px touch height, `accessibilityLabel="Remove {name}, {Provider}, from this device"`. Calls `onForget`.
+  - Session rows show `Text size="sm" color="secondaryLight"` "Can't remove" instead (sessions were never forgettable — keep that rule).
+  - Under the list: `Text size="sm" color="secondaryLight"`: "Removing an account only forgets it on this device. It doesn't sign you out anywhere else or delete the account."
+  - If the last remembered account is removed, exit edit mode automatically.
+- Keep testIDs: `${testID}-continue-${index}` on each row; `${testID}-forget-${index}` moves to the Remove button. Add `${testID}-accounts-edit`.
+
+### 3.2 Method buttons (`OAuthButtons` / `SocialLoginButton`)
+
+- Use `SocialLoginButton variant="outline"` for every provider (Apple, Google, GitHub) — it already exists. Do not use the black/`#24292e` fills on the login screen.
+- Icons: monochrome, `text.primary`, 18px, pinned left at 20px inside the pill; label centered. Height 48, `radius3xl`.
+- Passkey: same style, `iconName="key"`, "Sign in with a passkey". It lives in the method stack, never below the form.
+- Generic providers: same style; use their icon if provided, else none.
+- `OAuthButtons` currently draws its own divider (`dividerPosition`/`dividerText`). On the login screen pass `dividerPosition="none"`; `LoginScreen` owns the single divider.
+
+### 3.3 Email form
+
+- `TextField` titles: "Email", "Password". Email placeholder "you@example.com"; password has no placeholder.
+- "Forgot password?" → text link (`Text`/`Link` in `text.link`, bold, 14px) right-aligned on the same row as the Password label. If `TextField` cannot take a label accessory, render the label row yourself above a title-less `TextField` and keep `accessibilityLabel`.
+- Submit: `Button variant="primary" fullWidth` text **"Sign in"** (was "Log In"). `loading` shows the spinner inside the button with text "Signing in"; all fields and other buttons `disabled`; wrap the screen with `aria-busy`.
+- Keep the `FormContainer`, Enter-moves-focus and autofill behaviour from this PR untouched.
+
+### 3.4 "Last used" pill (replace `LastUsedBadge.tsx`)
+
+- Inline pill, not a stacked badge: `Text size="sm" bold`, `color="secondaryDark"`, background `surface.secondaryExtraLight`, 1px border `surface.secondaryLight`, `radius3xl`, padding 2×8.
+- On a method button: absolutely positioned on the right inside the pill, and the button itself gets `surface.secondaryExtraLight` fill with a 2px `surface.secondaryLight` border. The button also moves to the top of the stack (existing behaviour).
+- On an account row: inline after the name.
+- Email last used: pill on the "Email" label row instead of above the fields.
+- Keep the testIDs `${testID}-last-used-${method}` and the `withLastUsedLabel` accessibility label.
+
+### 3.5 Continue as an email account (password-only step)
+
+When a remembered/ session account with `method === "email"` and a usable email is tapped (today `useLoginController` just sets `initialValues`):
+
+- Replace the whole screen body with:
+  - Top-left back link: `chevron-left` + "All sign-in options" (returns to the list, clears the prefill).
+  - `Heading` "Enter your password".
+  - Identity chip: `Box` with `surface.secondaryExtraLight` fill, 1px `surface.secondaryLight` border, `rounding="lg"`: avatar, name (bold), email (`sm`, secondaryLight), trailing "Not you?" link (same action as back).
+  - Hidden email input with `autocomplete="username"` so password managers still pair correctly; visible password field autofocused; "Forgot password?" on its label row; "Sign in" primary button.
+  - Footer unchanged.
+- Implement as a `step` in `LoginScreen` (e.g. a new optional prop `continuingAccount?: LoginAccountOption` + `onCancelContinue?: () => void`), set by `useLoginController` instead of only `initialValues`. Fall back to today's info notice when the account has no usable email.
+
+---
+
+## 4. Feedback
+
+### 4.1 Placement
+`notice` and `error` both render as a banner directly under the heading block, above accounts and methods. Remove the `<Text color="error">` under the fields. Only one banner at a time; `notice` wins if both are set.
+
+### 4.2 Banner styles (extend `NoticeBox`, or use `Banner` if it can take a title and an action)
+
+| Tone | Fill | Border | Icon (left, 20px) | Text |
+|---|---|---|---|---|
+| info | `surface.secondaryExtraLight` | `surface.secondaryLight` | `circle-info`, `text.secondaryDark` | `text.secondaryDark` |
+| warning | `surface.warningLight` | `border.warning` | `triangle-exclamation`, `text.warning` | `text.primary` |
+| error | `surface.errorLight` | `border.error` | `circle-exclamation`, `text.error` | `text.primary` |
+
+- `rounding="lg"`, padding `spacing3`/`spacing4`, 16px text.
+- Optional bold title line (add `title?: string` to `LoginNotice`).
+- Optional action: small outline pill button under the text (`actionLabel`/`onAction`, already in the type).
+- Info banners are dismissible (`IconButton` "xmark", `accessibilityLabel="Dismiss"`); warnings/errors are not.
+- `role="status"` for info, `role="alert"` for warning/error.
+
+### 4.3 Copy and which tone (edit `rtk/src/auth/loginErrors.ts` and `useLoginController.ts`)
+
+| Situation | Tone | Title | Text | Action |
+|---|---|---|---|---|
+| Social sign-in cancelled by the user (today: "Auth cancelled") | info | — | "{Provider} sign-in was cancelled. Tap an account to try again." (no accounts: "…Try again or choose another way.") | — |
+| `account_not_linked`, mode `explicit` | warning | "You already have an account" | "That email is already used with {originalMethod}. Sign in with {originalMethod}, then link {Provider} from Security." | "Sign in with {originalMethod}" (focuses that method / email field) |
+| `account_not_linked`, mode `never` | warning | "You already have an account" | "That email already has an account. Sign in with {originalMethod} instead." | same |
+| `account_not_linked`, `verified-email` | warning | "Verify your email first" | keep current text | — |
+| Verify email / linking disabled / sign-up closed | warning | short noun title | keep current text | existing |
+| Provider not found / generic failure | error | — | keep current text | — |
+| Wrong email or password | **field error**, not a banner | — | "That password doesn't match. Try again or reset it." under the password field; field gets a 2px `border.error`, `aria-invalid`, `aria-describedby` | — |
+| Continue with email account but no usable email | info | — | keep current "Enter your email and password to continue as {who}." | — |
+
+The cancelled case needs a distinct failure code from the social flow so it isn't treated as an error; check how "Auth cancelled" reaches `getLoginFeedback` today and map it to the info notice.
+
+---
+
+## 5. Two-factor challenge (`ui/src/login/TwoFactorChallengeScreen.tsx`)
+
+- Top-left back link `chevron-left` "Back" (`onCancel`).
+- 56px badge: `rounding="lg"`, `surface.secondaryExtraLight`, `shield-halved` icon (TOTP) / `lock` icon (backup) in `text.secondaryDark`.
+- `Heading` "Enter your code" (TOTP) / "Use a backup code" (backup). Default `title` changes from "Two-factor authentication".
+- Subtitle: "Open your authenticator app and enter the 6-digit code for {masked email}." (add optional `accountLabel` prop; omit "for …" without it). Backup: "Enter one of the backup codes you saved when you turned on two-factor sign-in. Each code works once."
+- `OtpField`: six boxes 48×56, 8px gaps, `radiusMd`, centered bold 24px digits; the active box gets the focus ring. Error: all boxes 2px `border.error` + message below with icon: "That code didn't work. Codes change every 30 seconds, so enter the one your app shows now." Keep single tab stop, paste and `one-time-code` autofill.
+- Backup field: monospace, letter-spacing 2px, placeholder "xxxxx-xxxxx", helper "Dashes and spaces are optional."
+- Trust device: checkbox + "Trust this device", helper line `sm` secondaryLight "We won't ask for a code here for {trustDeviceDays} days." Checked by default for TOTP. Only rendered with `trustDeviceDays`.
+- Primary "Verify" button; below it a centered text link toggling "Use a backup code instead" / "Use your authenticator app"; bottom of screen a grey text link "Sign in a different way" (`cancelText` default changes from "Use another method").
+
+---
+
+## 6. Tokens used (light / dark come from the theme automatically)
+
+| Role | Use |
+|---|---|
+| `surface.base` | screen, rows, outline buttons |
+| `surface.baseAlternate` | "Sign in another way" muted button; disabled field fill |
+| `surface.primary` | primary "Sign in"/"Verify", focus border |
+| `surface.secondaryExtraLight` / `surface.secondaryLight` | last-used pill & highlighted button, identity chip, info banner, 2FA badge |
+| `surface.warningLight` + `border.warning` | warning banner |
+| `surface.errorLight` + `border.error`, `text.error` | error banner, field errors |
+| `text.primary`, `text.secondaryLight`, `text.secondaryDark`, `text.link` | body, captions, pill/info text, links |
+| `text.extraLight` | placeholders only |
+| `border.default` | inputs, outline buttons, account list |
+| `border.hover` | row separators |
+| `border.focus` | 3px focus ring |
+| `status.active` | session dot |
+
+Type: `Heading` (Titillium Web) for titles: `xl` 32px page title, `sm` section titles. `Text` (Nunito) 16px body, 12px (`sm`) metadata. Primary buttons follow the library's 19px bold for contrast on `surface.primary`. Radii: inputs `radiusMd` 4px, lists/banners/chips `radiusLg` 16px, buttons and pills `radius3xl`. No shadows.
+
+---
+
+## 7. Implementation plan
+
+1. `ui/src/login/loginTypes.ts`: add `subtitle`, `LoginNotice.title`, `LoginNotice.tone: "info" | "warning" | "error"`, `continuingAccount`, `onCancelContinue`; add `accountLabel` to the 2FA props. All optional; keep backwards compatibility.
+2. `LastUsedBadge.tsx` → inline `LastUsedPill`.
+3. `LoginAccountCard.tsx` → row component; new `LoginAccountList.tsx` with header + edit mode.
+4. `LoginScreen.tsx`: new block order (§2), single banner (§4.1), collapse/expand with accounts, one divider, link-style forgot/sign-up, "Sign in" copy, continuing-account step (§3.5). Pass `dividerPosition="none"` and `variant="outline"` to `OAuthButtons`.
+5. `NoticeBox`: tones, title, action, dismiss (§4.2).
+6. `TwoFactorChallengeScreen.tsx` + `OtpField`: §5.
+7. `rtk/src/auth/loginErrors.ts`, `useLoginController.ts`, `TerrenoLoginScreen.tsx`: copy table §4.3, cancelled-as-info, field-level wrong password, set `continuingAccount`.
+8. Update tests and snapshots: `LoginScreen.test.tsx`, `TwoFactorChallengeScreen.test.tsx`, `loginErrors` tests, rtk `TerrenoLoginScreen` tests, and Playwright specs `login`, `login-form`, `two-factor` in `example-frontend`. About 33 test references use the old strings ("Log In", "Forget", "Or sign in another way", etc.). Keep testIDs stable wherever listed above so most selectors still work; only update text assertions.
+9. Update the `LoginScreen` and `TwoFactorChallengeScreen` story configs in `ui/demo/story-config/` with one story per state in §8.
+10. `bun run compile`, lint, the ui/rtk test suites, and the Playwright login shards must pass. Changelog entry under ui and rtk.
+
+---
+
+## 8. Acceptance: one story / screenshot per state
+
+Match each against its board in `boards/` (and the canvas):
+
+| # | State | Board |
+|---|---|---|
+| 1 | Returning, accounts, methods collapsed | `Main.html` |
+| 2 | First visit, last used provider on top | `FirstVisit.html` |
+| 3 | Returning, "Sign in another way" expanded | `AnotherWay.html` |
+| 4 | Edit accounts | `ManageAccounts.html` |
+| 5 | Continue as email account | `ContinueEmail.html` |
+| 6 | Signing in (loading) | `SigningIn.html` |
+| 7 | Social sign-in cancelled (info) | `Cancelled.html` |
+| 8 | Account not linked (warning + action) | `NotLinked.html` |
+| 9 | Wrong password (field error) | `WrongPassword.html` |
+| 10 | 2FA authenticator code | `TwoFactor.html` |
+| 11 | 2FA wrong code | `TwoFactorError.html` |
+| 12 | 2FA backup code | `BackupCode.html` |
+
+Also check every state in dark mode, at 320px width, and with only email+password enabled (no providers: no dividers at all) and with no form (providers only: no "or use your email" divider).
+
+Out of scope: sign-up screen, account security screen, admin panels. "LOGO" in the boards is the app's own `logo` prop.