docs: cover hardcore mode, onboarding, and failed-job self-heal

[cursor]

Summary

Bring engineering docs in line with recent web shortcut/onboarding work and Sync’s durable failed-job self-heal path. Updates existing pages only (no new doc trees).

Docs added/updated

• docs/development/feature-file-map.md — Keyboard Shortcuts + Onboarding Tour sections; fixed stale useGlobalShortcuts path; day-column / all-day tint / account header pointers; failed-job self-heal entry
• docs/acceptance/shortcuts.md — Shift-Shift keyboard-only scenario, spatial arrow focus, palette undo/redo + restart tour, regression checklist
• docs/frontend/frontend-runtime-flow.md — Welcome → onboarding tour + keyboard-only mount contract
• docs/development/common-change-recipes.md — recipe for adding/changing shortcuts safely
• docs/features/google-sync-and-sse-flow.md + docs/self-hosting/monitoring.md — failed-job self-heal / durable auto-clear operator notes
• docs/README.md — discoverability links for shortcuts and onboarding

Codepaths covered

• packages/web/src/shortcuts/** (registry, shift-tap gesture, shift-hint, keyboard-only, global shell shortcuts)
• packages/web/src/components/OnboardingTour/** + Welcome Start Now / command-palette restart
• packages/web/src/grid/shortcuts/focus-adjacent-grid-event.ts (spatial focus)
• packages/sync/src/domain/failed-job-requeue.service.ts + sweep wiring in packages/sync/src/app.ts
• bun run cli manage-failed-jobs operator path (already documented in cli.md)

Key knowledge gaps addressed

• Keyboard-only mode (Shift-Shift) had only a one-line mention; now has acceptance coverage and file map pointers
• Onboarding tour was undocumented after shipping
• Feature file map still pointed at a removed views/Week/.../useGlobalShortcuts path
• Sync durable failed-job auto-clear (fix(sync): clear exhausted jobs blocked by durable read failures #2712) was only in CLI notes; sync flow + monitoring now describe the self-heal loop

Simplicity

Prefer updating existing docs over new pages. No implementation-detail dumps; verified behavior against source before writing.

Automated validation

Docs-only change. Cross-checked paths and behaviors against current source (shortcuts.registry.ts, useKeyboardOnlyMode, onboarding tour steps/store, failed-job-requeue.service.ts, command palette labels).

Independent review

Self-reviewed against recent main commits (#2697–#2722) and existing docs style. Intentionally omitted superseded digit 1–7 weekday focus (replaced by Shift day-prefix jump).

Test plan

• Verified referenced file paths exist on disk
• Spot-checked user-visible labels against CommandPalette / registry source
• No package tests required (documentation-only)

  

---

Note

Low Risk
Markdown-only updates to internal docs; no runtime, API, or deployment behavior changes.

Overview
Documentation-only PR that brings existing guides in line with shipped web shortcut/onboarding behavior and Sync’s failed-job self-heal operator path.

Discoverability & navigation: docs/README.md adds common-change-path links for shortcuts/Hardcore Mode and welcome/showcase/checklist.

Shortcuts acceptance (docs/acceptance/shortcuts.md): Expands scope and reference table (?, global H, redo, four-arrow Day focus, spatial Week focus). Command palette expectations now include undo/redo, Hardcore, practice/welcome rows. Scenario 13 documents Hardcore Mode (H); regression checklist splits jump (S) from Hardcore.

Engineering maps & recipes: feature-file-map.md adds Keyboard Shortcuts and Welcome, Showcase, And Checklist sections, corrects global shortcuts path to useGlobalShortcuts.ts, and points at failed-job requeue + CLI. common-change-recipes.md adds a step-by-step recipe for adding/changing shortcuts (registry, keymap, hooks, app-lock).

Runtime & sync ops: frontend-runtime-flow.md documents Welcome → Shortcut Showcase → checklist and Hardcore Mode mount/escape behavior from RootShell. google-sync-and-sse-flow.md and self-hosting/monitoring.md describe the self-heal sweep (cooldown requeue, exhausted jobs, durable read-failure auto-clear, log lines).

^{Reviewed by Cursor Bugbot for commit a8aaee9. Bugbot is set up for automated code reviews on this repo. Configure here.}