@hybridlabor-api/aos 4.13.2 → 4.14.0

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/examples/showcase/builder/plan.mdx

@@ -0,0 +1,208 @@
+---
+title: Harbor Notes - Team Notes MVP
+status: draft
+needs-auth: foundations
+needs-notes-api: foundations, auth
+needs-editor: notes-api
+needs-sharing: notes-api, auth
+needs-settings: auth, notes-api
+needs-export: notes-api, sharing
+needs-launch: editor, sharing, settings, export
+---
+
+# Harbor Notes: Team Notes MVP
+
+## Goal
+
+Harbor Notes is a team notes app. A small team signs up, creates a workspace, writes notes together and shares a read-only link with someone outside the team. The first private beta ships in six weeks. All names and data in this plan are invented.
+
+- A new user reaches a working workspace in under two minutes.
+- Two teammates edit the same note without losing text.
+- A shared link works without an account and can be revoked at any time.
+
+## Decision
+
+<Decision title="How do users verify their email?" question="Which proof do we ask for after the signup form?" options={[
+  { id: "code", label: "Six digit code", detail: "Survives a device switch, which is the common failure for links.", recommended: true },
+  { id: "link", label: "Magic link", detail: "One tap, but breaks when the link opens in a different browser." },
+  { id: "none", label: "No verification in the beta", detail: "Fastest, but invites cannot be trusted and bounces go unnoticed." },
+]}>
+
+A code works on the phone and the laptop alike, and costs one extra input box. We can add magic links later without changing the data model.
+
+</Decision>
+
+## Architecture
+
+<Archify src="00_architecture.html" label="Harbor Notes system" height={600} />
+
+<Callout tone="note" title="Why a queue and a worker">
+
+Exports and invitation emails can take seconds. Running them off the request path keeps the editor responsive and lets us retry a failed job without the user waiting.
+
+</Callout>
+
+## Acceptance {#acceptance}
+
+<Checklist title="Done when" items={[
+  { label: "Signup to an empty dashboard takes six screens or fewer", checked: true },
+  { label: "Back from any signup step keeps the typed values" },
+  { label: "Autosave survives a reload while typing" },
+  { label: "A revoked share link shows the Gone page within one minute" },
+  { label: "A viewer cannot edit, invite or delete" },
+  { label: "Notes list loads in under one second for 2,000 notes" },
+]} />
+
+## Build map
+
+### Foundations {#foundations}
+
+Repository, CI, design tokens and the database schema.
+
+<Checklist title="Foundations tasks" items={[
+  { label: "Repository, CI and deploy previews", checked: true },
+  { label: "Design tokens and base components", checked: true },
+  { label: "Schema for users, workspaces, notes and share links" },
+]} />
+
+<ImplementationMap files={[
+  { path: "db/schema.sql", change: "added", note: "Users, workspaces, notes, members, share_links" },
+  { path: "ui/tokens.css", change: "added", note: "Colour, spacing and type tokens" },
+  { path: ".github/workflows/ci.yml", change: "added", note: "Lint, test, preview deploy" },
+]} />
+
+### Auth and invites {#auth}
+
+Sessions, six digit codes and invite tokens.
+
+<Checklist title="Auth tasks" items={[
+  { label: "Create account and send the code" },
+  { label: "Verify the code, expire after ten minutes" },
+  { label: "Session cookies with rotation" },
+  { label: "Invite tokens with a role" },
+]} />
+
+<ImplementationMap files={[
+  { path: "api/auth/signup.ts", change: "added", note: "Create user and send code" },
+  { path: "api/auth/verify.ts", change: "added", note: "Check code, start session" },
+  { path: "api/auth/session.ts", change: "added", note: "Cookie rotation and logout" },
+  { path: "app/signup/verify.tsx", change: "added", note: "Six code boxes with paste handling" },
+]} />
+
+### Notes API {#notes-api}
+
+Create, read, update, archive and search notes.
+
+<Checklist title="Notes API tasks" items={[
+  { label: "CRUD endpoints with revision check" },
+  { label: "Search by title, body and tag" },
+  { label: "Attachment upload with a 10 MB limit" },
+]} />
+
+<ImplementationMap files={[
+  { path: "api/notes/index.ts", change: "added", note: "List, create and search" },
+  { path: "api/notes/item.ts", change: "added", note: "Read, update, archive with revision check" },
+  { path: "api/files/upload.ts", change: "added", note: "Signed upload to object storage" },
+]} />
+
+### Editor and notes list {#editor}
+
+The editor with autosave and the list with tag filter.
+
+<Checklist title="Editor tasks" items={[
+  { label: "Markdown editor with toolbar" },
+  { label: "Autosave every two seconds" },
+  { label: "Title lock while someone edits" },
+  { label: "Notes list with tags and sort" },
+]} />
+
+<ImplementationMap files={[
+  { path: "app/notes/list.tsx", change: "added", note: "List, filter and preview pane" },
+  { path: "app/notes/editor.tsx", change: "added", note: "Toolbar, autosave and presence" },
+  { path: "app/notes/use-autosave.ts", change: "added", note: "Debounced save with revision" },
+]} />
+
+### Sharing {#sharing}
+
+Read-only links with an expiry date, and member roles.
+
+<Checklist title="Sharing tasks" items={[
+  { label: "Create and revoke share links" },
+  { label: "Gone page for expired or revoked links" },
+  { label: "Roles: owner, editor, viewer" },
+]} />
+
+<ImplementationMap files={[
+  { path: "api/share/index.ts", change: "added", note: "Create, list and revoke links" },
+  { path: "app/s/shared-note.tsx", change: "added", note: "Public read-only page" },
+  { path: "app/notes/share-dialog.tsx", change: "added", note: "Expiry options and people list" },
+]} />
+
+### Workspace settings {#settings}
+
+General settings, members and the danger zone.
+
+<Checklist title="Settings tasks" items={[
+  { label: "General tab with name and defaults" },
+  { label: "Members tab with invites" },
+  { label: "Danger zone with typed confirmation" },
+]} />
+
+<ImplementationMap files={[
+  { path: "app/settings/index.tsx", change: "added", note: "Tabs and forms" },
+  { path: "app/settings/members.tsx", change: "added", note: "Member list and invite dialog" },
+]} />
+
+### Export {#export}
+
+A workspace as a ZIP of Markdown files, built by the worker.
+
+<Checklist title="Export tasks" items={[
+  { label: "Queue the export job" },
+  { label: "Worker writes the ZIP to storage" },
+  { label: "Email a download link that expires in a day" },
+]} />
+
+<ImplementationMap files={[
+  { path: "worker/jobs/export.ts", change: "added", note: "Collect notes and write the ZIP" },
+  { path: "worker/jobs/email.ts", change: "added", note: "Send the download link" },
+  { path: "api/export.ts", change: "added", note: "Enqueue and report status" },
+]} />
+
+### Launch {#launch}
+
+<Checklist title="Launch tasks" items={[
+  { label: "Load test with 2,000 notes and 20 editors" },
+  { label: "Accessibility pass: keyboard and contrast" },
+  { label: "Private beta with five invited teams" },
+]} />
+
+<ImplementationMap files={[
+  { path: "tests/load/notes.k6.js", change: "added", note: "Load script for the notes list and saves" },
+  { path: "docs/beta-checklist.md", change: "added", note: "Go or no-go list" },
+]} />
+
+## Agent trail
+
+<AgentTrail live="http://localhost:5331" />
+
+## Risks
+
+<Table title="Risk register" columns={["Risk", "Likelihood", "Impact", "Mitigation"]} rows={[
+  ["Concurrent edits overwrite text", "Medium", "High", "Title lock, revision check, conflict banner"],
+  ["Share links leak in forwarded mail", "Medium", "Medium", "Expiry by default, one click revoke"],
+  ["Email deliverability is poor", "Medium", "High", "Dedicated sending domain, resend limit"],
+  ["Export jobs pile up", "Low", "Medium", "Queue depth alert, per workspace rate limit"],
+  ["Scope grows before the beta", "High", "Medium", "Freeze this list after week two"],
+]} />
+
+## Open questions
+
+<QuestionForm title="Open Questions" questions={[
+  { title: "Can viewers download attachments from a shared note?", mode: "single", options: [
+    { label: "No, view only", recommended: true }, { label: "Yes, if the owner allows it" } ] },
+  { title: "Default expiry for share links?", mode: "single", options: [
+    { label: "7 days", recommended: true }, { label: "30 days" }, { label: "Never" } ] },
+  { title: "Which beta extras do we want?", mode: "multi", options: [
+    { label: "Audit log of link opens" }, { label: "Dark mode" }, { label: "Keyboard shortcuts sheet" } ] },
+]} />

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/examples/showcase/recap/plan.mdx

@@ -0,0 +1,102 @@
+---
+title: Share links with expiry and revoke
+subtitle: Notes can be shared through a read-only link that expires after seven days and can be revoked in one click. Invented example.
+kind: recap
+pr: "#318"
+branch: feat/share-links
+base: main
+commit: 9b3e7d2
+files: 8
+additions: 642
+deletions: 57
+author: sample-author
+date: 2026-02-03
+---
+
+## Summary
+
+Until now a note could only be read by workspace members. This change adds read-only share links for people outside the team. A link carries a random token, expires after seven days unless the owner picks another period, and can be revoked at any time. Recipients see a clean read-only page; expired or revoked links show a Gone page instead of an error.
+
+- Tokens are 128 bit random values stored hashed; the plain token only appears in the URL.
+- The public page never loads the editor bundle, so it opens fast on slow connections.
+- Owners see who opened a link and how often, without personal data.
+
+## Before and after
+
+<Compare>
+<Before>
+<Screen surface="web" caption="Share dialog before: members only">
+  <FrameScreen>
+    <Row><Title text="Share note" /><Btn label="Close" /></Row>
+    <Chips items={[{ label: "People", active: true }]} />
+    <Row><IconSquare active /><Lines n={2} widths={[60, 36]} /></Row>
+    <Row><IconSquare /><Lines n={2} widths={[54, 30]} /></Row>
+    <Row><IconSquare /><Lines n={2} widths={[66, 34]} /></Row>
+    <Box dashed><Text value="Only workspace members can open this note." tone="muted" /></Box>
+    <Divider />
+    <Row><Btn label="Invite member" primary /></Row>
+  </FrameScreen>
+</Screen>
+</Before>
+<After>
+<Screen surface="web" caption="Share dialog after: link tab with expiry">
+  <FrameScreen>
+    <Row><Title text="Share note" /><Btn label="Close" /></Row>
+    <Chips items={[{ label: "Link", active: true }, { label: "People" }]} />
+    <Box><Text value="Anyone with the link can view" /><Lines n={1} widths={[72]} /></Box>
+    <SectionLabel label="Link expires" />
+    <TaskRow title="In 7 days" done note="default" />
+    <TaskRow title="In 30 days" />
+    <TaskRow title="Never" />
+    <Row><IconSquare active /><Lines n={2} widths={[60, 36]} /></Row>
+    <Divider />
+    <Row><Btn label="Revoke link" /><Btn label="Copy link" primary /></Row>
+  </FrameScreen>
+</Screen>
+</After>
+</Compare>
+
+## Files
+
+<ImplementationMap title="Changed files" files={[
+  { path: "db/migrations/0012_share_links.sql", change: "added", note: "share_links table with hashed token and expiry" },
+  { path: "api/share/index.ts", change: "added", note: "Create, list and revoke links" },
+  { path: "api/share/resolve.ts", change: "added", note: "Public lookup, returns note or Gone" },
+  { path: "app/s/shared-note.tsx", change: "added", note: "Read-only page without the editor bundle" },
+  { path: "app/notes/share-dialog.tsx", change: "modified", note: "Link tab, expiry options, revoke" },
+  { path: "api/notes/item.ts", change: "modified", note: "Expose share count on the note" },
+  { path: "app/notes/legacy-share-modal.tsx", change: "removed", note: "Replaced by the new dialog" },
+  { path: "tests/share-links.test.ts", change: "added", note: "Expiry, revoke and permission cases" },
+]} />
+
+## Behaviour
+
+<Table title="Link states" columns={["State", "Recipient sees", "Owner sees", "Next step"]} rows={[
+  ["Active", "Read-only note", "Open count", "Revoke or wait for expiry"],
+  ["Expired", "Gone page", "Expired badge", "Create a new link"],
+  ["Revoked", "Gone page within one minute", "Revoked badge", "Create a new link"],
+  ["Note archived", "Gone page", "Link paused", "Restore the note to resume"],
+]} />
+
+<CodeTabs tabs={[
+  { label: "share/index.ts", language: "ts", code: "export async function createLink(noteId: string, days = 7) {\n  const token = randomToken(16);\n  await db.insert('share_links', {\n    note_id: noteId,\n    token_hash: sha256(token),\n    expires_at: addDays(now(), days),\n  });\n  return `${BASE_URL}/s/${token}`;\n}" },
+  { label: "share/resolve.ts", language: "ts", code: "export async function resolve(token: string) {\n  const link = await db.findOne('share_links', { token_hash: sha256(token) });\n  if (!link || link.revoked_at || link.expires_at < now()) return null;\n  return db.get('notes', link.note_id);\n}" },
+  { label: "0012_share_links.sql", language: "sql", code: "CREATE TABLE share_links (\n  id BIGSERIAL PRIMARY KEY,\n  note_id BIGINT NOT NULL REFERENCES notes(id),\n  token_hash TEXT NOT NULL UNIQUE,\n  expires_at TIMESTAMPTZ NOT NULL,\n  revoked_at TIMESTAMPTZ\n);" },
+]} />
+
+## Decision
+
+<Decision title="Token storage" question="How do we store share tokens?" options={[
+  { id: "hash", label: "Store only a hash", detail: "A database leak does not expose working links.", recommended: true },
+  { id: "plain", label: "Store the token", detail: "Lets us show the link again, but a leak exposes every link." },
+]}>
+
+The dialog shows the full link once. After that only the owner can revoke it and create a new one, which is an acceptable cost for the safer default.
+
+</Decision>
+
+<Callout tone="note" title="Review focus">
+
+Check that revoke is visible to the public resolver within one minute, and that an archived note never leaks through an active link.
+
+</Callout>

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/examples/showcase/standard/plan.md

@@ -0,0 +1,136 @@
+# Harbor Notes: Team Notes MVP
+
+> Invented example project. Every name, number and date is made up.
+
+**Status:** draft for review  **Owner:** product team  **Target:** first private beta in six weeks
+
+## 1. Goal
+
+Harbor Notes is a team notes app. A small team signs up, creates a workspace, writes notes together and shares a read-only link with someone outside the team.
+
+**Success looks like**
+
+- A new user reaches a working workspace in under two minutes.
+- Two teammates can edit the same note without losing text.
+- A shared link works without an account and can be revoked at any time.
+- Notes list loads in under one second for 2,000 notes.
+
+**Out of scope for the beta:** comments, version history, native mobile apps, offline editing.
+
+## 2. Decisions
+
+| # | Question | Options | Recommendation | Why |
+|---|----------|---------|----------------|-----|
+| D1 | How do users verify their email? | Six digit code / magic link | **Six digit code** | Survives a device switch, the common failure for links |
+| D2 | How are notes stored? | Markdown text / block JSON | **Markdown text** | Simple export, easy diffs, no migration lock-in |
+| D3 | How do edits merge? | Last write wins / CRDT | **Last write wins per note, field locks on title** | Cheapest option that avoids lost text for small teams |
+| D4 | How are files stored? | Database blobs / object storage | **Object storage** | Keeps the database small and backups fast |
+| D5 | How do jobs run? | In request / queue and worker | **Queue and worker** | Exports and emails must not block the editor |
+
+## 3. Scope and build order
+
+### 3.1 Foundations
+
+- [x] Repository, CI and a deploy preview per branch
+- [x] Design tokens and the base component set
+- [ ] Database schema for users, workspaces, notes and share links
+- [ ] Auth service with sessions and invite tokens
+
+### 3.2 Notes core
+
+- [ ] Notes API: create, read, update, archive, search
+- [ ] Editor with autosave every two seconds
+- [ ] Notes list with tag filter and sort by last edit
+- [ ] Attachment upload with a 10 MB limit
+
+### 3.3 Sharing and settings
+
+- [ ] Read-only share links with an expiry date
+- [ ] Member invites by email with roles: owner, editor, viewer
+- [ ] Workspace settings: name, members, danger zone
+- [ ] Export a workspace as a ZIP of Markdown files
+
+### 3.4 Launch
+
+- [ ] Load test with 2,000 notes and 20 concurrent editors
+- [ ] Accessibility pass: keyboard navigation and contrast
+- [ ] Private beta with five invited teams
+
+## 4. Request flow
+
+```mermaid
+flowchart LR
+  U[User] --> W[Web app]
+  W --> A[API]
+  A --> AU{Session valid?}
+  AU -- no --> L[Sign in screen]
+  AU -- yes --> DB[(Database)]
+  A --> Q[[Job queue]]
+  Q --> K[Worker]
+  K --> S[(File storage)]
+  K --> M[Email service]
+  DB --> A
+  A --> W
+```
+
+## 5. Sharing a note
+
+```mermaid
+sequenceDiagram
+  participant O as Owner
+  participant W as Web app
+  participant A as API
+  participant D as Database
+  participant R as Recipient
+  O->>W: Click Share
+  W->>A: POST /notes/42/share (expires in 7 days)
+  A->>D: Insert share token
+  D-->>A: token abc123
+  A-->>W: share URL
+  W-->>O: Copy link
+  O->>R: Sends the link
+  R->>A: GET /s/abc123
+  A->>D: Look up token and expiry
+  alt token valid
+    A-->>R: Read-only note
+  else expired or revoked
+    A-->>R: 410 Gone page
+  end
+```
+
+## 6. Acceptance criteria
+
+- [ ] Signup to empty dashboard takes six screens or fewer
+- [ ] Back from any signup step keeps the typed values
+- [ ] An expired code shows a resend action
+- [ ] Autosave survives a reload during typing
+- [ ] A revoked share link returns the Gone page within one minute
+- [ ] A viewer cannot edit, invite or delete
+
+## 7. Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| Concurrent edits overwrite text | Medium | High | Field lock on title, revision check on save, conflict banner |
+| Share links leak in forwarded mail | Medium | Medium | Expiry by default, one click revoke, view counter |
+| Email deliverability is poor | Medium | High | Dedicated sending domain, plain text fallback, resend limit |
+| Export jobs pile up | Low | Medium | Queue depth alert, per workspace rate limit |
+| Scope grows before beta | High | Medium | Freeze the list in section 3 after week two |
+
+## 8. Open questions
+
+1. Should viewers be able to download attachments from a shared note?
+2. Is a 7 day default expiry right, or should links never expire unless set?
+3. Do we need an audit log of share link opens for the beta?
+4. Which region hosts the first workspaces?
+
+## 9. Timeline
+
+| Week | Milestone |
+|------|-----------|
+| 1 | Schema, auth, signup screens |
+| 2 | Notes API and editor |
+| 3 | Notes list, search, attachments |
+| 4 | Sharing and settings |
+| 5 | Export, load test, accessibility |
+| 6 | Private beta |

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/examples/signup-storyboard/canvas.mdx

@@ -0,0 +1,124 @@
+<DesignBoard title="Lumen Notes - signup storyboard" version={1} transitions={[
+  { from: "welcome", to: "create", label: "tap Continue" },
+  { from: "create", to: "verify", label: "submit" },
+  { from: "verify", to: "workspace", label: "code accepted" },
+  { from: "workspace", to: "invite", label: "create workspace" },
+  { from: "invite", to: "dashboard", label: "send or skip" },
+]}>
+<Section id="account" title="Create the account" subtitle="Three steps from first launch to a verified address. Every screen is a low-fidelity sketch, not final UI.">
+<Artboard id="welcome" label="Welcome" surface="mobile" x={80} y={120} width={320} height={580} order={1}>
+<Screen surface="mobile" caption="First launch, signed out.">
+  <FrameScreen>
+    <StatusBar />
+    <Col full>
+      <Box dashed>
+        <Row><IconSquare active /><Title text="Lumen Notes" /></Row>
+        <Lines n={2} widths={[70, 48]} />
+      </Box>
+      <Text value="Notes that stay in sync on every device." tone="muted" />
+      <Lines n={3} widths={[90, 76, 60]} />
+      <Btn label="Continue with email" primary />
+      <Text value="Already have an account? Sign in" tone="muted" />
+    </Col>
+  </FrameScreen>
+</Screen>
+</Artboard>
+<Artboard id="create" label="Create account" surface="mobile" x={600} y={120} width={320} height={580} order={2}>
+<Screen surface="mobile">
+  <FrameScreen>
+    <StatusBar />
+    <Col full>
+      <Title text="Create account" />
+      <Box>
+        <Text value="Email" tone="muted" />
+        <Lines n={1} widths={[58]} />
+      </Box>
+      <Box>
+        <Text value="Password" tone="muted" />
+        <Lines n={1} widths={[36]} />
+      </Box>
+      <Row><IconSquare active /><Text value="I agree to the terms" /></Row>
+      <Divider />
+      <Btn label="Create account" primary />
+    </Col>
+  </FrameScreen>
+</Screen>
+</Artboard>
+<Artboard id="verify" label="Verify email" surface="mobile" x={1120} y={120} width={320} height={580} order={3}>
+<Screen surface="mobile">
+  <FrameScreen>
+    <StatusBar />
+    <Col full>
+      <Title text="Check your inbox" />
+      <Text value="We sent a six digit code." tone="muted" />
+      <Row><IconSquare /><IconSquare /><IconSquare /><IconSquare /><IconSquare /><IconSquare /></Row>
+      <Lines n={2} widths={[84, 52]} />
+      <Btn label="Open mail app" primary />
+      <Text value="Resend code" tone="muted" />
+    </Col>
+  </FrameScreen>
+</Screen>
+</Artboard>
+</Section>
+<Section id="first-run" title="First run" subtitle="Workspace setup and the empty state a new user lands on.">
+<Artboard id="workspace" label="Name your workspace" surface="mobile" x={1120} y={980} width={320} height={580} order={4}>
+<Screen surface="mobile">
+  <FrameScreen>
+    <StatusBar />
+    <Col full>
+      <Title text="Name your workspace" />
+      <Box><Lines n={1} widths={[44]} /></Box>
+      <SectionLabel label="Use it for" />
+      <TaskRow title="Personal" done note="default" />
+      <TaskRow title="Team" />
+      <TaskRow title="School" />
+      <Btn label="Create workspace" primary />
+    </Col>
+  </FrameScreen>
+</Screen>
+</Artboard>
+<Artboard id="invite" label="Invite teammates" surface="mobile" x={600} y={980} width={320} height={580} order={5}>
+<Screen surface="mobile">
+  <FrameScreen>
+    <StatusBar />
+    <Col full>
+      <Title text="Invite teammates" />
+      <Row><IconSquare active /><Lines n={1} widths={[70]} /></Row>
+      <Row><IconSquare /><Lines n={1} widths={[56]} /></Row>
+      <Row><IconSquare /><Lines n={1} widths={[64]} /></Row>
+      <Divider />
+      <Btn label="Send invites" primary />
+      <Text value="Skip for now" tone="muted" />
+    </Col>
+  </FrameScreen>
+</Screen>
+</Artboard>
+<Artboard id="dashboard" label="Empty dashboard" surface="mobile" x={80} y={980} width={320} height={580} order={6}>
+<Screen surface="mobile" caption="Nothing is created for the user yet.">
+  <FrameScreen>
+    <StatusBar />
+    <Col full>
+      <Row><Title text="Today" /><IconSquare active /></Row>
+      <Box dashed>
+        <Skeleton lines={3} widths={[80, 64, 72]} />
+      </Box>
+      <Text value="No notes yet" tone="muted" />
+      <Btn label="New note" primary />
+    </Col>
+  </FrameScreen>
+</Screen>
+</Artboard>
+</Section>
+
+<Annotation id="note-password" title="Password rules" targetId="create" placement="bottom">
+
+Show the rule list only after the first keystroke, so the form starts calm.
+
+</Annotation>
+
+<Annotation id="note-code" title="Code entry" targetId="verify" placement="right">
+
+Paste fills all six boxes at once. The code expires after ten minutes.
+
+</Annotation>
+</DesignBoard>

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/examples/signup-storyboard/plan.mdx

@@ -0,0 +1,37 @@
+---
+title: Lumen Notes - Signup Storyboard
+status: draft
+---
+
+# Signup flow
+
+## Goal
+
+A new visitor reaches an empty, ready-to-use dashboard in six screens or fewer. All names and data in this example are invented.
+
+## Decision
+
+<Decision title="Verification method" question="How do we verify the email address?" options={[
+  { id: "code", label: "Six digit code", detail: "Works when the mail app opens on another device.", recommended: true },
+  { id: "link", label: "Magic link", detail: "One tap, but breaks when the link opens in a different browser." },
+]}>
+
+A code survives a device switch, which is the common failure for links.
+
+</Decision>
+
+## Acceptance {#acceptance}
+
+<Checklist title="Done when" items={[
+  { label: "Every screen fits one viewport without scrolling", checked: true },
+  { label: "Back from any step keeps the typed values" },
+  { label: "Expired codes show a resend action" },
+]} />
+
+## Build map {#build-map}
+
+<ImplementationMap files={[
+  { path: "app/signup/welcome.tsx", change: "added", note: "Entry screen and sign-in link" },
+  { path: "app/signup/verify.tsx", change: "added", note: "Code boxes with paste handling" },
+  { path: "app/auth/session.ts", change: "modified", note: "Create the workspace after the first verified session" },
+]} />