type: goal

text: Plan A of Zync OS: transform apps/zync-app presentation into a desktop OS shell (windows, taskbar, start menu, tray, notification center, command center, Today app, widgets) powered by one extended module registry, OS mode DEFAULT at login with 'Login to Legacy Site' session fallback, 2 pilot modules (Tasks, Customers) windowed, full 8-layer UI verification program green.


type: methodology

text: Contract-level spec pins seams; design physics live SOLELY in .claude/skills/zc-ui-ux-designer (SKILL.md + references/desktop.md) — every UI task must read it and reviewer/vision-judge reject against it. Same-task-ships-tests law. Wave-1 WindowRouter spike gate blocks all other OS UI work. Gate tiering: slopgate/behavioral/red-proof/KILL per task, baselines+keyframes per surface, vision-judge+fault-injection at wave close. Codex seats implement; vision judge is codex (gpt-5.4-mini/low sweep, gpt-5.5/low re-judge), NEVER Claude self-grading.


type: intent

text: User wants the app to look and feel like an OS that Fable designed — premium physics (respond-first motion, 1:1 drag, ease-settle, depth ladder) executed faithfully by cheaper GPT models. The skill + spec exist precisely so cheap seats cannot improvise the design away.


type: direction

verbatim: make sure that all the physics of the premium feel are actually in the specs, since cheaper models cant think like you and they will mess this up for sure


verbatim: desktop view is default. fallback to regular saas view is possible for now but im not sure we will leave it for launch, for now when logging in, put a checkmark to "Login to Legacy Site" and if not checked, it logs in to desktop mode, by default.


verbatim: I want to design the AI assistant now with you , after we finish designing the UI redesign. and then write the specs and plans for it, but execute it after the redesign lands.


type: deferred

text: Plan B: mobile OS shell + module migration sweep (device_class='mobile', registry mobile presentation, references/mobile.md already written)

reason: user chose 3-plan slicing; desktop first


text: Plan C: virtual desktops, focus mode, lock screen, saved workspaces, taskbar position, always-on-top, portal/staff/admin shells

reason: advanced tier after A+B land


text: Zync AI depth epic: RAG indexing wiring, record-level permission filtering in retrieveContext (SECURITY gap — tenant namespace only today), tool/action system, per-record actions

reason: user: design+spec now (separate brainstorm), execute after redesign lands


type: anchor

what: design-language doctrine (required reading every UI task)


what: desktop surface physics tables (data-fx ids, motion table, drag/snap values)


note: Codex gpt-5.5/high spec review: 13 findings all fixed, re-verify SHIP. Advisor (opus code-reviewer) blocker fixed via osApp:true manifest field; OS-default decision from user replaced classic-default rollout.


type: task

seat: coder

tier: low

desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 1 (Shell token pack) for the full contract. Append shell motion/depth/material/z/radius tokens VERBATIM from .claude/skills/zc-ui-ux-designer/SKILL.md token pack. Acceptance: pnpm typecheck && pnpm --filter zync-app build. Commit only: packages/ui/src/tokens/index.css.


tier: medium

desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 2 (Module registry OS extension) for the full contract. Pure-data ZyncModuleOs + osApp:true identity for today/notifications/settings, routePrefixes from real route table. Acceptance: pnpm --filter @zync/modules test && pnpm typecheck. Commit only: packages/modules/src.


tier: high

desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 3 (WindowRouter SPIKE GATE) for the full contract. Full UNSAFE_LocationContext/UNSAFE_NavigationContext replacement. Follow the .md checklist in order: (1) write the 8 failing hook fixtures first -- this initial run is EXPECTED to fail (TDD red, window-router.tsx does not exist yet) and does NOT stop the run, (2) implement apps/zync-app/src/os/window-router.tsx and window-context.ts per the full Task 3 contract, (3) rerun acceptance. If ANY required fixture still fails after implementing the full Task 3 contract, acceptance is not met: STOP RUN and escalate to user. Acceptance: pnpm --filter zync-app exec vitest run src/os/__tests__/window-router.test.tsx. Commit only: apps/zync-app/src/os.


desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 4 (OS shell store) for the full contract. Zustand store per spec section 3 types verbatim + wm-geometry pure functions. Acceptance: pnpm --filter zync-app exec vitest run src/os/__tests__/os-shell-store.test.ts src/os/__tests__/wm-geometry.test.ts. Commit only: apps/zync-app/src/os.


desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 5 (Backend shell_layouts) for the full contract. Table+migration (zc-dba law), GET/PUT/DELETE /api/shell/layout, ui_shell + force_shell prefs, tenant-guarded. Acceptance: pnpm --filter zync-api test -- shell-layout. Commit only: packages/db apps/zync-api.


desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 6 (Verification scaffold) for the full contract. playwright.os.config 4 projects, fx helpers, slopgate OS pack + fixtures (whitelist fixture paths in edit hooks FIRST), mutation harness. Do NOT touch .github/ (CI wiring is out of scope for this task — human-review follow-up, tracked separately). Acceptance: pnpm --filter zync-app exec playwright test tests/e2e/os-shell/00-scaffold.spec.ts --config playwright.os.config.ts. Commit only: apps/zync-app/playwright.os.config.ts apps/zync-app/tests .slopgate.


desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 7 (Window frame + lifecycle + drag/snap/resize) for the full contract. REQUIRED READING zc-ui-ux-designer SKILL.md + references/desktop.md; implement EVERY lifecycle motion table row with data-fx. Acceptance: pnpm --filter zync-app exec playwright test tests/e2e/os-shell/01-window-frame.spec.ts tests/e2e/os-shell/02-drag-snap.spec.ts --config playwright.os.config.ts. Commit only: apps/zync-app/src/os/window apps/zync-app/tests/e2e/os-shell.


desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 8 (Desktop surface) for the full contract. REQUIRED READING zc-ui-ux-designer desktop.md Desktop surface section. Acceptance: pnpm --filter zync-app exec playwright test tests/e2e/os-shell/03-desktop.spec.ts --config playwright.os.config.ts. Commit only: apps/zync-app/src/os/desktop apps/zync-app/tests/e2e/os-shell.


desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 9 (Taskbar) for the full contract. REQUIRED READING zc-ui-ux-designer desktop.md Taskbar section. Acceptance: pnpm --filter zync-app exec playwright test tests/e2e/os-shell/04-taskbar.spec.ts --config playwright.os.config.ts. Commit only: apps/zync-app/src/os/taskbar apps/zync-app/tests/e2e/os-shell.


desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 10 (Start menu) for the full contract. REQUIRED READING zc-ui-ux-designer desktop.md Start menu section. Acceptance: pnpm --filter zync-app exec playwright test tests/e2e/os-shell/05-start-menu.spec.ts --config playwright.os.config.ts. Commit only: apps/zync-app/src/os/start apps/zync-app/tests/e2e/os-shell.


desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 11 (Tray + notification center + toasts) for the full contract. Reuse use-notifications + useRealtime seams unchanged; presentation-only fork from classic dropdown. Acceptance: pnpm --filter zync-app exec playwright test tests/e2e/os-shell/06-tray-notifications.spec.ts --config playwright.os.config.ts. Commit only: apps/zync-app/src/os/panels apps/zync-app/tests/e2e/os-shell.


desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 12 (App-side registry bindings) for the full contract. Per-module binding files + frozen aggregator + surface selectors + resolveRouteOwner. Acceptance: pnpm --filter zync-app exec vitest run src/os/__tests__/registry-os.test.ts && pnpm typecheck. Commit only: apps/zync-app/src/os.


desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 13 (Command center consolidation) for the full contract. ONE implementation for both shells; enumerate + preserve every legacy palette capability; delete shell/use-search.ts. Acceptance: pnpm --filter zync-app exec playwright test tests/e2e/os-shell/07-command-center.spec.ts --config playwright.os.config.ts plus classic palette regression grep. Commit only: apps/zync-app/src apps/zync-app/tests.


desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 14 (OsShell root + mode resolution + chrome split + login checkbox) for the full contract. Precedence session>tenant>pref>os default; Login to Legacy Site checkbox; AuthenticatedAppChrome; announcer; boot from cache. Acceptance: pnpm --filter zync-app exec playwright test tests/e2e/os-shell/08-shell-mode.spec.ts --config playwright.os.config.ts plus classic shell smoke. Commit only: apps/zync-app/src apps/zync-app/tests.


desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 15 (URL-window engine) for the full contract. history.state.zync identity; popstate precedence instanceId>owner>prefix; spec section 5 verbatim. Acceptance: pnpm --filter zync-app exec vitest run src/os/__tests__/url-sync.test.ts && pnpm --filter zync-app exec playwright test tests/e2e/os-shell/09-url-contract.spec.ts --config playwright.os.config.ts. Commit only: apps/zync-app/src/os apps/zync-app/tests.


desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 16 (Layout persistence client) for the full contract. Commit-point-only writes, zod envelope, per-tab sessionId, deterministic 409 rule, mirror boot. Acceptance: pnpm --filter zync-app exec vitest run src/os/__tests__/layout-persistence.test.ts && pnpm --filter zync-app exec playwright test tests/e2e/os-shell/10-persistence.spec.ts --config playwright.os.config.ts. Commit only: apps/zync-app/src/os apps/zync-app/tests.


desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 17 (Tasks pilot) for the full contract. Normalize location.state.background to full-page in windows (grep count 0); edit ONLY bindings/tasks.ts never registry-os.ts. Acceptance: pnpm --filter zync-app exec playwright test tests/e2e/os-shell/11-tasks-pilot.spec.ts --config playwright.os.config.ts. Commit only: apps/zync-app/src apps/zync-app/tests.


desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 18 (Customers pilot multi-instance) for the full contract. Two windows different records zero cross-bleed; edit ONLY bindings/customers.ts. Acceptance: pnpm --filter zync-app exec playwright test tests/e2e/os-shell/12-customers-pilot.spec.ts --config playwright.os.config.ts. Commit only: apps/zync-app/src apps/zync-app/tests.


desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 19 (Today app) for the full contract. Aggregate todayContribution components from existing queries only, zero new endpoints; first-login auto-open once; one S widget; edit ONLY bindings/today.ts. Acceptance: pnpm --filter zync-app exec playwright test tests/e2e/os-shell/13-today.spec.ts --config playwright.os.config.ts. Commit only: apps/zync-app/src apps/zync-app/tests.


desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 20 (AI window + Settings window) for the full contract. ChatPanel in right-snapped window with optional context prop only (never fork); launcher suppressed in OS; edit ONLY bindings/ai.ts. Acceptance: pnpm --filter zync-app exec playwright test tests/e2e/os-shell/14-ai-settings.spec.ts --config playwright.os.config.ts. Commit only: apps/zync-app/src apps/zync-app/tests.


desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 21 (Onboarding + escape hatches + telemetry) for the full contract. Coach-marks once-only, show-open-windows command, diagnostic copy, 5 telemetry counters. Acceptance: pnpm --filter zync-app exec playwright test tests/e2e/os-shell/15-onboarding-support.spec.ts --config playwright.os.config.ts. Commit only: apps/zync-app/src apps/zync-app/tests.


desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 22 (Visual baselines + perceptual artifacts) for the full contract. 8 surfaces x RTL/LTR x dark/light baselines; keyframes 0/40/80 percent per data-fx; completeness script fails on missing artifact. Acceptance: pnpm --filter zync-app exec playwright test tests/e2e/os-shell/16-baselines.spec.ts tests/e2e/os-shell/17-keyframes.spec.ts --config playwright.os.config.ts && node apps/zync-app/tests/e2e/os-shell/artifact-completeness.ts. Commit only: apps/zync-app/tests.


desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 23 (Accessibility sweep) for the full contract. Runs AFTER t21 within wave (may touch shared src/os files). axe clean, roles per spec Accessibility contract, focus-return matrix, keyboard-only WM session. Acceptance: pnpm --filter zync-app exec playwright test tests/e2e/os-shell/18-a11y.spec.ts --config playwright.os.config.ts. Commit only: apps/zync-app/src apps/zync-app/tests.


desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 24 (Performance budget assertions) for the full contract. CDP 4x throttle: chrome-interactive <=800ms, window-open p95 frame <=24ms, unmount guards, restore <=200ms; fix breaches never relax budgets. Acceptance: pnpm --filter zync-app exec playwright test tests/e2e/os-shell/19-perf.spec.ts --config playwright.os.config.ts. Commit only: apps/zync-app/tests apps/zync-app/src.


desc: Read docs/plans/2026-07-10-zync-os-desktop.md Task 25 (Wave-close program gates) for the full contract. Mutation sweep 100 percent, codex vision-judge verdict table (gpt-5.4-mini/low sweep, gpt-5.5/low re-judge, NEVER Claude), fault injection 7/7 caught, classic regression green; fix-loop until clean. Acceptance: all four gate artifacts attached and clean. Commit only: docs/plans/audit.