Merge main into paper ink bleed

Author: Chris0Jeky

.paper-issues/00-tracker.md

@@ -0,0 +1,94 @@
+# PAPER-00 · Master Tracker · Paper & Graphite, Ember Edition Overhaul
+
+## Thesis
+
+Adopt the **Paper & Graphite, Ember Edition** visual + interaction system across the Taskdeck frontend. The system encodes the product's core thesis — capture → review → apply with no silent mutations — directly in materials (cream paper, hairline rules, italic serif, single seal-red ember accent) rather than helper labels. Trust signals are physical: applied stamps emboss, undo windows literally erase as the 6-hour grace closes.
+
+Source of truth: `design_handoff_taskdeck_paper/` checked into the repo (README + JSX prototypes + `paper/tokens.css`).
+
+## Strategic intent
+
+- Replace the current Obsidian-toned shell across all primary surfaces with Paper-Light as canonical, Paper-at-Night as the dark companion (strict mirror of metaphor).
+- Make Review the centerpiece: implement the *deep* version with provenance, side-effects, conflicts, history, confidence dial, undo timeline, similar-past decisions.
+- Replace every `loading…` / spinner state in LLM flows with **Ink Bleed** — a 5-phase, 4.6s motion that dries to a stamp.
+- Keep behavior unchanged: this is presentation + interaction polish, not a backend rewrite. All capture / proposal / approval semantics remain the same.
+
+## Non-goals
+
+- No backend changes beyond what surface needs require (e.g., new fields the dossier needs).
+- No new product features beyond what the design implies (e.g., "Seal day", "A line for tomorrow", undo timer).
+- No removal of the existing `--td-*` token system in this overhaul. Paper sits parallel under `.paper` / `.paper-night` scope until migration is ready to flip canonical.
+- Multiplayer/CRDT explicitly out of scope.
+
+## Phasing
+
+### Phase 1 · Foundation (must land first, blocks everything else)
+- **PAPER-01** Tokens + theme classes + fonts + paper substrate
+- **PAPER-02** Component primitives (Stamp, HLBtn, Tagstamp, Card, kbd, hairline icons)
+
+### Phase 2 · Shell
+- **PAPER-03** Sidebar + TopBar in Paper
+
+### Phase 3 · Surfaces (parallelizable after Phase 1+2)
+- **PAPER-04** Home / morning reset
+- **PAPER-05** Board / kanban with index card variant
+- **PAPER-06** Review *deep* — central surface
+- **PAPER-07** Inbox / capture (composer + nib)
+- **PAPER-08** Today / end-of-day dossier
+- **PAPER-09** Misc surfaces (Card detail, ⌘K palette, Shortcuts overlay, Toasts, Empty states)
+
+### Phase 4 · Motion + responsive + dark
+- **PAPER-10** Ink Bleed motion system (signature LLM thinking state)
+- **PAPER-11** Narrow companions (375 phone, 768 tablet)
+- **PAPER-12** Paper at Night dark theme verification across all surfaces
+
+## Acceptance gates per slice
+
+Every slice must:
+- Land behind the Paper feature flag (or `.paper` body class scope) so existing Obsidian surfaces remain green during migration.
+- Ship vitest unit/component tests for new primitives + DOM-level assertions for view changes.
+- Pass `npm run typecheck` + `npm run lint` (max 20 warnings) + backend `dotnet build` if backend touched.
+- Pass an adversarial review pass that explicitly checks: token misuse, ember-accent overuse (must remain ≤5% of any surface's surface area), serif italic in non-decision copy, missing reduced-motion fallback for any animation, focus rings replacing browser default, hairlines surviving zoom 200%.
+- Update `docs/STATUS.md` if user-visible behavior changes; cross-link the master tracker.
+
+## Risk register
+
+- **Token collision** — `--td-*` and Paper variables both define ember/paper hues. Mitigation: scope all Paper variables under `.paper`/`.paper-night` and namespace anything new (`--td-paper-*`).
+- **Serif loading** — Fraunces is heavy and italic-variable. Self-host with `font-display: swap` to avoid FOUC; pre-cache critical weights.
+- **Density** — Paper is a high-density system. 200-card boards must remain frame-stable. Re-verify the perf budget (`docs/PERFORMANCE_BUDGETS.md`).
+- **Accent overuse** — single-pigment metaphor breaks if ember leaks into incidental UI. Linter rule: ember class allow-list per surface.
+- **Motion accessibility** — Ink Bleed is bold motion. `@media (prefers-reduced-motion)` must reduce to a 200ms opacity fade, no exceptions.
+
+## Reference
+
+- README: `design_handoff_taskdeck_paper/README.md` (canonical spec)
+- Tokens: `design_handoff_taskdeck_paper/paper/tokens.css`
+- Components: `design_handoff_taskdeck_paper/paper/components.jsx`
+- Surfaces: `design_handoff_taskdeck_paper/paper/surface-*.jsx`
+- Prototype entry: open `design_handoff_taskdeck_paper/Taskdeck Paper Edition.html` in a browser
+
+## Definition of done for the whole tracker
+
+- All PAPER-01 .. PAPER-12 closed and merged behind the Paper flag.
+- A `/styleguide?theme=paper` (and `paper-night`) page renders every component primitive + every surface.
+- A workspace toggle promotes Paper to canonical; a follow-up tracker decommissions Obsidian.
+- Adversarial review on the integrated experience signs off on accent discipline and motion accessibility.
+
+---
+
+## Child issues
+
+| Phase | Issue | Title |
+|---|---|---|
+| 1 | #997 | PAPER-01 · Foundation — tokens, theme, fonts, substrate |
+| 1 | #998 | PAPER-02 · Component primitives |
+| 2 | #999 | PAPER-03 · Sidebar + TopBar shell |
+| 3 | #1000 | PAPER-04 · Home / Reset |
+| 3 | #1001 | PAPER-05 · Board / Kanban |
+| 3 | #1002 | PAPER-06 · Review (Deep) |
+| 3 | #1003 | PAPER-07 · Inbox / Capture |
+| 3 | #1004 | PAPER-08 · Today / End-of-day dossier |
+| 3 | #1005 | PAPER-09 · Misc surfaces |
+| 4 | #1006 | PAPER-10 · Ink Bleed motion |
+| 4 | #1007 | PAPER-11 · Narrow companions |
+| 4 | #1008 | PAPER-12 · Paper at Night |

.paper-issues/01-tokens.md

@@ -0,0 +1,64 @@
+# PAPER-01 · Foundation — Paper tokens, theme classes, fonts, substrate
+
+Part of the **Paper & Graphite, Ember Edition** overhaul (master tracker: PAPER-00).
+
+## Goal
+
+Land the foundation that every later slice depends on: Paper tokens, theme scope, type utilities, paper-substrate background, and font loading. **Nothing else can ship before this.**
+
+## Scope
+
+### CSS / tokens
+- Add `frontend/taskdeck-web/src/paper-tokens.css` mirroring `design_handoff_taskdeck_paper/paper/tokens.css` exactly:
+  - `:root, .paper { … }` light defaults
+  - `.paper-night { … }` strict dark mirror
+  - Paper substrate: `repeating-linear-gradient` long-fiber + SVG fleck noise via `background-blend-mode: multiply`
+  - All typography utility classes: `.tk-display`, `.tk-h1`, `.tk-h2`, `.tk-h3`, `.tk-lede`, `.tk-body`, `.tk-meta`, `.tk-eyebrow`, `.tk-num`, `.tk-serial`, `.tk-ink-italic`
+  - `.hr-line`, `.hr-soft`, `.hr-double`, `.rule-ledger`
+  - `.stamp` / `.stamp.ember` / `.stamp.applied` / `.stamp b` / `.stamp .stamp-num`
+  - `.letterpress`, `.tagstamp`
+  - `.card`, `.card-lift`, `.well`, `.surface`, `.halo-ember`
+  - `.btn`, `.btn-primary`, `.btn-ember`, `.btn-ghost`, `.kbd`, `.kbd-light`
+  - `.hl-icon` / `-md` / `-lg`
+  - `.status` family (proposed/applied/overdue/draft/live + pulse keyframes)
+  - `.diff-add`, `.diff-rem`, `.erase-line`
+- Import the new sheet from `main.ts` after `design-tokens.css` so Paper sits parallel, not replacing Obsidian.
+- Self-host Fraunces, Inter, JetBrains Mono via `@font-face` with `font-display: swap`. Critical weights: Fraunces italic 400 + 500, Inter 400/500/600, JetBrains Mono 500.
+
+### Theme scoping
+- Add `frontend/taskdeck-web/src/store/paperThemeStore.ts` Pinia store: `mode: 'paper' | 'paper-night' | 'auto' | 'off'` (default `off`).
+- App root applies `paper`/`paper-night` class to `<body>` when mode is on. Persists to `localStorage` key `td.paper.mode`.
+- Honor `prefers-color-scheme: dark` only when mode is `auto`.
+
+### Style-guide route
+- Add `frontend/taskdeck-web/src/views/PaperStyleGuideView.vue` route at `/styleguide/paper`.
+- Render every type utility, component class, status pill, diff strip, stamp variant, both themes side-by-side.
+
+### Tests
+- vitest: store mode persistence and body-class application.
+- vitest: snapshot `.tk-display em`, `.stamp.ember`, `.tagstamp` for token drift.
+
+## Files to touch / create
+
+- create: `frontend/taskdeck-web/src/paper-tokens.css`
+- create: `frontend/taskdeck-web/src/store/paperThemeStore.ts`
+- create: `frontend/taskdeck-web/src/views/PaperStyleGuideView.vue`
+- create: `frontend/taskdeck-web/public/fonts/*.woff2`
+- modify: `frontend/taskdeck-web/src/main.ts`
+- modify: `frontend/taskdeck-web/src/App.vue`
+- modify: `frontend/taskdeck-web/src/router/index.ts`
+
+## Adversarial review checklist
+
+- [ ] Paper variables scoped under `.paper`/`.paper-night` (no leak when mode is off).
+- [ ] No `--td-*` token renamed or removed.
+- [ ] Fraunces italic loads via `font-display: swap` — no FOUC.
+- [ ] `.tk-display em` renders in `--ember`.
+- [ ] Background substrate respects `prefers-reduced-transparency` and zoom 200%.
+- [ ] `.paper-night` does not require a `data-theme` attribute swap — class only.
+
+## Acceptance
+
+- `npm run dev` shows `/styleguide/paper` with all type, components, both themes.
+- `npm run typecheck` and `npm run lint` clean.
+- Master tracker referenced.

.paper-issues/02-primitives.md

@@ -0,0 +1,36 @@
+# PAPER-02 · Component primitives — Stamp, HLBtn, Tagstamp, Card variants, Kbd, Hairline icons
+
+Part of the Paper overhaul (master tracker: PAPER-00). **Blocked by:** PAPER-01.
+
+## Goal
+
+Provide reusable Vue SFC primitives that every Paper surface composes from. Match the JSX reference behavior pixel-for-pixel within Vue 3 idioms.
+
+## Components (under `frontend/taskdeck-web/src/components/paper/`)
+
+- **`PaperStamp.vue`** — props `kind: 'applied' | 'proposed' | 'captured' | 'overdue' | 'draft'`, `date`, `time`, `num`, `rotate?` (default −7° to −9° randomized once on mount). Embossed inset on `applied`. On undo, crossfade to `proposed` over 240ms.
+- **`PaperHLBtn.vue`** — props `label`, `kbd?`, `icon?` (slot), `variant: 'default' | 'primary' | 'ember' | 'ghost'`. Renders the keyboard hint inline with a 1px vertical divider. `:active` `translateY(1px)`.
+- **`PaperTagstamp.vue`** — slot for label, `tone?: 'ember' | 'applied' | 'overdue' | 'mute'`. Letter-spacing **.22em**.
+- **`PaperCard.vue`** — `variant: 'flat' | 'lift' | 'well'`, `halo?: boolean`. Default slot.
+- **`PaperKbd.vue`** — slot for the key glyph. `light?: boolean`.
+- **`PaperHairlineIcons.vue`** — exporting named icon components mirroring `paper/icons.jsx` (Plus, Search, Stamp, Sparkle, ArrowRight, X, Check, Pages, Pen, Cursor, Tag, Dot, Eye, Bell, ChevronD, ChevronR, Settings, Sun, Moon). 14–16px, `stroke="currentColor"`, no fill.
+- **`PaperStatusPill.vue`** — `kind: 'proposed' | 'applied' | 'overdue' | 'draft' | 'live'`. `live` pulses at 0.6Hz.
+- **`PaperLedgerRow.vue`** — `idx`, `title`, `meta`, `status?`, click-to-open.
+- **`PaperConfidenceDial.vue`** — `value: number 0..1`, 84px SVG, ember stroke-dasharray, serif italic value, mono "CONF" caption.
+- **`PaperUndoTimeline.vue`** — `appliedAt`, `windowMs = 6h`, dashed timeline crossfading dashes left-to-right. `requestAnimationFrame` capped at 1Hz with reduced-motion fallback.
+
+## Tests
+
+- vitest unit tests per component.
+- Storybook stories in `src/stories/paper/` per primitive in both themes.
+- Snapshot test for `PaperConfidenceDial value={0.84}`.
+
+## Adversarial review checklist
+
+- [ ] Stamp rotation computed once on mount.
+- [ ] HLBtn `kbd` slot does not break layout for wide keys (`space`, `⌘K`).
+- [ ] Confidence dial respects `prefers-reduced-motion`.
+- [ ] Undo timeline cleans up rAF on unmount.
+- [ ] No primitive imports a surface or store.
+- [ ] All primitives render correctly inside `.paper-night` without a dark-mode prop.
+- [ ] Hairline icons use `currentColor`.

.paper-issues/03-shell.md

@@ -0,0 +1,48 @@
+# PAPER-03 · Shell — Sidebar + TopBar in Paper
+
+Part of the Paper overhaul (master tracker: PAPER-00). **Blocked by:** PAPER-01, PAPER-02.
+
+## Goal
+
+Reskin the persistent shell (sidebar + top bar) to match the Paper specification, behind the Paper feature flag.
+
+## Spec
+
+### Sidebar (220–232px)
+- Background `--paper-2`, right border `1px solid var(--line)`.
+- Header: serif "Taskdeck" 18px medium + tk-eyebrow ("Precision Mode · active" — "active" word in `--ember`).
+- Workspace switcher: paper-card chip (22px serif italic letter glyph) + workspace name + ChevronD.
+- Section groups (each preceded by `tk-eyebrow` label):
+  - Primary loop: Home, Today, Review (badge), Boards, Inbox (badge)
+  - Workbench tools: Views, Notifications, Chat, Calendar, Metrics, Integrations, Activity, Ops
+  - Meta (no eyebrow, muted): Settings, API Keys, Preferences, Shortcuts, Logout
+- Items: 36px height, 6px 20px padding, mono single-letter glyph + 12.5px Inter label, optional `· N` mono badge.
+- Active: 2px left border `--ember`, gradient background, glyph ember, label weight 600.
+- Footer: live status pill + version mono.
+
+### TopBar (48–56px)
+- Background `--paper`, border-bottom `1px solid var(--line)`.
+- Left: breadcrumb sans 12.5px, `/` separator in `--whisper`.
+- Right: ⌘K trigger (paper-card chip), `SYNCED · LOCAL-FIRST` live pill, vertical hairline, Bell + Settings ghost buttons, 26px circular avatar serif italic.
+
+## Implementation
+
+- Create `PaperSidebar.vue` and `PaperTopBar.vue`.
+- Modify `AppShell.vue` to render Paper variants when `paperThemeStore.mode !== 'off'`.
+- Wire breadcrumb from `route.meta.breadcrumb`.
+- ⌘K trigger emits to existing palette composable.
+- Theme toggle (☼ / ☾) in sidebar footer.
+
+## Tests
+- vitest: sidebar groups; active item ember class; badge.
+- vitest: topbar emits `palette:open` on ⌘K.
+- Playwright: smoke load under both themes.
+
+## Adversarial review
+
+- [ ] No double sidebar when toggling.
+- [ ] Active route detection survives nested routes.
+- [ ] Theme toggle persists across reload.
+- [ ] Sidebar collapses cleanly to icon-only at narrow viewports (soft contract for PAPER-11).
+- [ ] No hard-coded color literals in SFC `<style>`.
+- [ ] Breadcrumb truncates with ellipsis at narrow widths.

.paper-issues/04-home.md

@@ -0,0 +1,30 @@
+# PAPER-04 · Home / Reset surface
+
+Part of the Paper overhaul (master tracker: PAPER-00). **Blocked by:** PAPER-01, PAPER-02, PAPER-03.
+
+## Goal
+
+Re-skin `HomeView` as the morning-reset surface — serif italic greeting, queued items, quick capture.
+
+## Spec
+- Greeting in serif italic 36–44px ("Good morning, Daniel."), period auto-derived from local clock.
+- `tk-lede` subtitle summarizing today's queue count + focus block reminder.
+- Three "queued for you" cards (proposals + carry-overs) styled as Paper cards with serial, serif title, mono metadata.
+- Quick capture single-line at the bottom: serif italic placeholder, hairline border, ⌘; hint.
+
+## Implementation
+- Create `frontend/taskdeck-web/src/views/paper/PaperHomeView.vue`.
+- Modify `HomeView.vue` to delegate when paper mode is on (lazy-loaded).
+- Reuse existing home-queue composable; do not refetch.
+- Quick capture wires through existing capture store.
+
+## Tests
+- vitest: greeting picks correct period from a fixed clock.
+- vitest: empty queue shows the empty state primitive.
+- Playwright: smoke load with seeded user.
+
+## Adversarial review
+- [ ] Greeting reads naturally with no first name (fallback "Hello").
+- [ ] Quick capture doesn't dispatch on empty Enter.
+- [ ] Cards keep ember accent only on the proposal subset.
+- [ ] No layout shift when queue resolves.

.paper-issues/05-board.md

@@ -0,0 +1,36 @@
+# PAPER-05 · Board / Kanban surface in Paper
+
+Part of the Paper overhaul (master tracker: PAPER-00). **Blocked by:** PAPER-01, PAPER-02, PAPER-03.
+
+## Goal
+
+Re-skin `BoardView` as the Paper kanban — 4 columns, index card variant, hairline density.
+
+## Spec
+- Columns: 280px wide, `--paper-2` background, `1px var(--line-soft)` border, 16px gap.
+- Header: mono serial (`§ 04`) + serif name + count badge.
+- Card variant A — Index card (default):
+  - Top: mono serial number (`C-090`).
+  - Title serif 14.5px medium.
+  - Optional 1-line body.
+  - 11px mono metadata bottom strip.
+- Card variant B — Tag ribbon: 4px colored ribbon left edge keyed to label.
+- Column footer: hairline `+ capture` button.
+- WIP-limit warning surfaces as overdue tagstamp on column header.
+
+## Implementation
+- Create `views/paper/PaperBoardView.vue`, `PaperBoardColumn.vue`, `PaperBoardCard.vue`.
+- Reuse existing drag-drop composable + `boardStore` actions.
+- Hover lifts card 1px via `box-shadow` (no scale).
+- Card max-width 248px inside column; body line-clamp 1.
+
+## Tests
+- vitest: variant A by default; variant B with prop.
+- Playwright: drag a card across columns; assert audit-log entry.
+- Accessibility: 2px ember focus ring with 1px gap.
+
+## Adversarial review
+- [ ] No re-render storm on drag.
+- [ ] 200-card columns scroll smoothly (60fps).
+- [ ] Empty column shows hairline placeholder.
+- [ ] Done column heuristic still applies for metrics.

.paper-issues/06-review-deep.md

@@ -0,0 +1,61 @@
+# PAPER-06 · Review (Deep) — central surface
+
+Part of the Paper overhaul (master tracker: PAPER-00). **Blocked by:** PAPER-01, PAPER-02, PAPER-03. **Recommended:** PAPER-10.
+
+## Goal
+
+Replace `ReviewView` with the Paper deep-Review surface — the most important screen.
+
+## Spec (paper/surface-review-deep.jsx + README §3)
+
+3-column grid `280px | flex | 320px`:
+
+### Queue rail
+- Eyebrow `Queue · N awaiting · M stale` + filter pills.
+- `Q` rows with serial, age, serif title, author + confidence + reach.
+- Active item: 2px ember left border + ember-bloom gradient.
+- "Recently applied · undoable" with `↶ time-left`.
+- "This week" mini cadence (7 bars) + apply/undo rates.
+
+### Main
+- Header: PROPOSED tagstamp, serial, serif italic 36–44px title with `<em>` highlights, lede, 200px confidence dial card right-aligned.
+- Sticky decision rail: tagstamp DECISION + summary mono + Reject/Edit/Defer/Apply (ember).
+- §I The change: 2-col before/after card. Field diff strip below.
+- §II Provenance: 5 rows (primary/contextual/excluded/inferred), 32px icon + 200px italic key + value.
+- §III Side effects: 7-row table + Reversibility card with `PaperUndoTimeline`.
+- §IV Conflicts & warnings (warn rust / info mute / ok sage).
+- §V History: ledger table, serial + event + age + status pill.
+
+### Right rail
+- Author card with proposed Stamp absolutely positioned top-right rotated −9°; confidence breakdown bars.
+- Why-now card.
+- Similar past decisions (3) with verdict tagstamps.
+- Decide-with-keys card in ember tint.
+
+## Keyboard
+⏎ Apply · ⌫ Reject · E Edit · D Defer 1h · P Provenance · Space Preview
+
+## Implementation
+- Create `views/paper/PaperReviewView.vue` orchestrator.
+- Decompose into `ReviewQueueRail.vue`, `ReviewMain.vue`, `ReviewRightRail.vue`, plus subcomponents.
+- Reuse `useReviewProposals`; extend with provenance/sideEffects/confidenceBreakdown/conflicts/history/similarPast selectors.
+- If backend lacks fields, ship feature-flagged stubs with mock data and open follow-up issues per gap.
+- `useReviewKeymap` composable scoped to route.
+
+## Backend gaps to file as sub-issues
+- Provenance fullReadSet link target.
+- SimilarPastDecisions query (apply rate windowed).
+- ConfidenceBreakdown 4-component.
+- Reversibility per-proposal (defaults to 6h).
+
+## Tests
+- vitest: confidence dial; status pill mapping; keyboard map dispatches.
+- Playwright: open Review; press ⏎; assert applied stamp + undo timer.
+
+## Adversarial review
+- [ ] Decision rail stays sticky without overlap (z-index 2).
+- [ ] Apply remains atomic — single ledger entry post-apply.
+- [ ] ⏎ inside text inputs (defer reason, edit composer) does NOT apply.
+- [ ] Erase-line on Reversibility animates linearly over configured window.
+- [ ] No ember leak into conflicts table (warn = `--overdue`).
+- [ ] Stamp on author card doesn't intercept clicks.