forgetrail 0.3.0

package/prompts/docs-alignment-audit.md

@@ -0,0 +1,108 @@
+# Docs Alignment Audit
+
+Run this prompt to verify that all project documentation is accurate and internally consistent. It checks each doc against the actual codebase and cross-checks docs against each other.
+
+---
+
+## The Prompt
+
+You are auditing the project documentation suite for accuracy and alignment. The docs to audit are:
+
+- `docs/DEPLOYMENT.md`
+- `docs/TECHNICAL_REFERENCE.md`
+- `docs/CODE_QUALITY.md`
+- `docs/BLACK_HAT_REPORT.md`
+- `docs/BUSINESS_PLAN.md`
+- `docs/BRAND_AND_PRODUCT.md`
+- `docs/BUGS.md`
+- `TODO.md`
+- `CONTEXT_PROMPT.md`
+- `.env.example`
+
+## Audit Procedure
+
+Work through each section below. For each check, report PASS, FAIL (with specifics), or STALE (accurate but outdated context). Use the codebase as the source of truth.
+
+### 1. DEPLOYMENT.md vs. Codebase
+
+Check the "What's Done" and "What's Not Done" sections against what actually exists:
+
+- [ ] **Security claims:** For each security item listed as done, verify the code exists. Search for rate limiting, CSRF protection, security headers, input validation schemas, prompt injection guards, parameterized database queries, and file handling sanitization.
+- [ ] **Payment claims:** Verify all payment-related API routes exist. Verify entitlements enforcement exists. Count how many routes import from the entitlements module.
+- [ ] **OAuth claims:** Verify OAuth routes exist. Check that OAuth env vars are referenced in code.
+- [ ] **"Not Done" accuracy:** For each item listed as not done, confirm it's genuinely missing.
+- [ ] **Infrastructure files:** Verify all files listed in deployment sections exist at the stated paths.
+- [ ] **Cost estimates:** Cross-check resource recommendations against actual resource usage patterns.
+
+### 2. TECHNICAL_REFERENCE.md vs. Codebase
+
+- [ ] **Env vars table:** Compare every row against `.env.example`. Flag missing vars in either direction.
+- [ ] **API routes:** List all actual API route files. Compare against the documented routes. Flag undocumented or documented-but-missing routes.
+- [ ] **Data model:** Compare collection schemas against setup/migration scripts. Flag missing fields or collections.
+- [ ] **Billing section:** Cross-check plan limits against the entitlements module constants. Verify product/price IDs if referenced.
+- [ ] **Feature descriptions:** Spot-check 3-5 feature descriptions against their actual implementations.
+
+### 3. CODE_QUALITY.md vs. Codebase
+
+- [ ] **Remediated items:** For each item listed as fixed, verify the fix exists in code.
+- [ ] **Open findings:** For each open finding, verify it's genuinely still present.
+- [ ] **Severity counts:** Recount Critical/Major/Minor from the open findings and verify the summary table.
+
+### 4. BLACK_HAT_REPORT.md vs. Codebase & TODO
+
+- [ ] **Fixed findings:** For each finding marked as fixed, verify remediation code exists.
+- [ ] **Open findings:** For each open finding, verify the vulnerability still exists.
+- [ ] **TODO integration:** Every actionable finding should have a corresponding entry in TODO.md's Security Audit section.
+- [ ] **Priority alignment:** P0 findings should map to Critical + exploitable High. P1 to defense-in-depth. P2 to remaining.
+
+### 5. Cross-Document Consistency
+
+- [ ] **DEPLOYMENT.md vs. TECHNICAL_REFERENCE.md:** Do they agree on env vars, API routes, schemas, payment details, and security measures?
+- [ ] **DEPLOYMENT.md vs. TODO.md:** Are items marked "done" in DEPLOYMENT also checked off in TODO? Are "not done" items present as unchecked?
+- [ ] **CODE_QUALITY.md vs. TODO.md:** Are remediated findings reflected as checked in the TODO Foundation section?
+- [ ] **BLACK_HAT_REPORT.md vs. TODO.md:** Are finding statuses synchronized between the report and the Security Audit section of TODO?
+- [ ] **BUSINESS_PLAN.md vs. TECHNICAL_REFERENCE.md:** Do pricing tiers and plan limits match?
+- [ ] **BUSINESS_PLAN.md vs. entitlements code:** Do documented plan limits match the constants in code?
+- [ ] **CONTEXT_PROMPT.md vs. everything:** Does the project context prompt accurately describe the current architecture? Spot-check 5-10 claims.
+- [ ] **.env.example vs. DEPLOYMENT.md:** Does .env.example include all vars referenced in the go-live checklist?
+- [ ] **BUGS.md vs. TODO.md:** Are triaged bugs cross-referenced to TODO entries?
+
+### 6. Staleness Indicators
+
+Flag any of these patterns found in any doc:
+
+- [ ] Phrases like "not yet done," "planned," "will be added," "TODO" that describe features which now exist
+- [ ] Checked items (`[x]`) that describe features not in the codebase
+- [ ] Unchecked items (`[ ]`) that describe features already implemented
+- [ ] References to old file names, removed files, or restructured paths
+- [ ] Model strings or version numbers that don't match current defaults
+
+## Output Format
+
+For each section, output:
+
+```
+### [Section Name]
+- PASS: [item] - [brief confirmation]
+- FAIL: [item] - [what's wrong and what the correct state is]
+- STALE: [item] - [what's outdated]
+```
+
+End with a summary:
+
+```
+## Summary
+- Total checks: X
+- Pass: X
+- Fail: X (list file + issue for each)
+- Stale: X (list file + issue for each)
+- Recommended fixes: [prioritized list]
+```
+
+---
+
+## Usage Notes
+
+- Run this audit during Phase 7 (Hardening) and before every release.
+- After running, fix all FAIL items first (incorrect information), then STALE items (outdated but not wrong).
+- This prompt is framework-agnostic — adapt the specific file checks to your project's actual doc structure.

package/prompts/engineering-skill-library.md

@@ -0,0 +1,75 @@
+# Engineering Skill Library (Principal-Engineer Handoff)
+
+Produce a **skill library**: a set of mentoring-style documents that capture the **expert judgment, design rationale, and hard-won lessons** behind a mature codebase, so that a new engineer — or a lower-context / cheaper AI model — can continue the work effectively without re-learning everything the expensive way.
+
+Think of it as the handoff a **retiring principal engineer** would write: not "what the code does" (the code shows that) but **why it's built this way, how to decide when the docs run out, and what goes wrong when the conventions are ignored.**
+
+Use this when a project has matured enough to have real conventions, real scars, and real judgment worth preserving — typically before a beta/launch, before handing the project to someone else (human or agent), or when onboarding keeps costing the same explanations. It complements the reference docs (`TECHNICAL_REFERENCE.md`, `CONTEXT_PROMPT.md`): where those say *what* and *where*, the skill library says *why* and *what breaks*.
+
+> **Companion prompts:** `ux-cohesion-audit.md` and `panel-usability-audit.md` read the *product experience*; `black-hat-audit.md` and the `CODE_QUALITY.md` pass read for *findings to fix*. This prompt reads for *judgment to preserve*. Its output is durable teaching material, not a findings backlog.
+
+---
+
+## How to Use
+
+1. Give this prompt to an AI assistant with **full codebase access**.
+2. Optionally set `[SCOPE]` (default: the whole app) and `[SKILL_COUNT]` (default: 10–16 documents).
+3. The assistant audits the repo, then writes one Markdown file per skill under `[docs/skills/]` (or a location you name), plus a short `README.md` index.
+4. Review, then commit. Keep the library next to the code; when a doc contradicts the code later, the **code is newer** — fix the doc in the same change set.
+
+---
+
+## Instructions
+
+You are a **retiring principal engineer** writing a handoff library so the next person or model can operate with your judgment. Ground **everything** in the actual code — real file paths, real function names, real snippets, real past incidents. Generic advice that could apply to any codebase is worthless here; the value is in *this* system's specific decisions and scars.
+
+### Step 1 — Audit before you write
+
+Do a genuine, broad audit first. Do **not** write from memory or the conversation summary. Read, in parallel where possible:
+
+- **Core shared modules** — the server/lib layer, the cross-cutting helpers (auth, data access, validation, LLM/AI calls, file handling, entitlements/billing). These encode the conventions.
+- **The convention/rules files** — `AGENTS.md` / `CLAUDE.md`, `.cursor/rules/*`, `CONTEXT_PROMPT.md`, contributing docs. Each rule usually exists because of a bug; find the bug.
+- **The failure record** — bug logs, `CODE_QUALITY.md` / security reports, `TODO.md` / `IDEAS.md`, and **`git log`** for fix/regression themes. This is the single richest source of "lessons from costly mistakes."
+- **The specs / decision log** — `specs/` (completed and in-flight) for *why* features are shaped as they are and what tradeoffs were weighed.
+- **Route/component conventions** — pick 2–3 representative examples of each layer and note the repeated shape.
+
+> 🔧 **Guidance:** For a large repo, parallelize the audit across sub-areas (server core, docs/failures, each major pipeline, specs, routes) and reconcile the findings before writing. Verify any code snippet you quote against the current file — stale line numbers and imagined APIs destroy trust in a handoff doc.
+
+### Step 2 — Choose the skill set
+
+Aim for `[SKILL_COUNT]` focused documents. Cover these categories (merge or split to fit the project; not every project needs all of them):
+
+1. **Architecture & key design decisions** — the one-page mental model plus the load-bearing decisions *with rationale* (what was chosen, what was rejected, why).
+2. **One document per hairy subsystem** — the data layer, the AI/LLM integration, any document/format pipeline, any scraping/import pipeline, auth/permissions, billing/entitlements. One per subsystem that has real depth or real footguns.
+3. **Debugging playbooks** — symptom-first guides to the recurring and expensive failures ("works locally, fails in prod" and friends), each with the non-obvious root cause.
+4. **Security / review checklist** — the standing defenses and the open findings, framed as a pre-ship gate.
+5. **Testing & verification** — what's automated, what's *deliberately* manual, known-failing tests and why, the pre-commit gate.
+6. **Process** — spec/workflow lifecycle, git discipline, how work gets planned and finished here.
+7. **Judgment calls & decision frameworks** — the capstone: "how I decide when the docs don't cover it," the prime directive, and the failure patterns that repeat. This is the highest-value document; write it last, after the others surface the throughlines.
+
+### Step 3 — Write in a mentoring voice
+
+- **Lead with the decision and its rationale**, then the mechanics. A handoff doc that only describes mechanics is just slower-to-read source code.
+- **Every convention gets its WHY and its scar.** "Always use `[helper]`" is weak; "Always use `[helper]` — we shipped ~N raw `[unsafe pattern]` before the audit caught it, and here's the exact class of bug it prevents" is a lesson that survives.
+- **Capture anti-patterns and war stories.** The thing someone tried that *didn't* work, and the specific incident, are often more valuable than the positive rule. Name the symptom so a future reader recognizes it.
+- **Include real code references** (path + a short snippet) for the most instructive kernels, and cross-link between skill docs.
+- **Write for less context than you have.** The reader — human or a cheaper model — did not watch the codebase evolve. Spell out the terms; don't rely on shorthand only you know.
+- Keep each doc focused and skimmable (headings, tables, checklists). A skill library people actually re-read beats an exhaustive one they don't.
+
+### Step 4 — Index and verify
+
+- Write a `README.md` for the library: a "read this first" order, a "read X when you're about to do Y" table, and the unchanging ground rules.
+- Re-check quoted snippets against the current code. Fix anything stale.
+- Note where a skill doc reveals that an existing convention doc (`AGENTS.md`, `CONTEXT_PROMPT.md`) is **wrong or out of date** — flag it (or fix it) rather than faithfully repeating stale guidance.
+
+### Step 5 — Report
+
+List the documents you created, one line each, and call out: the biggest design decisions you captured, any convention-doc contradictions you found, and anything you judged too app-specific to generalize.
+
+---
+
+## Notes
+
+- This library is **teaching material, not a spec or a findings report.** Don't turn it into a TODO backlog; link to the backlog instead.
+- It pairs naturally with `propagate-to-forgetrail.md`: once the library exists, the *generalizable* lessons inside it are strong propagation candidates for ForgeTrail templates.
+- Revisit after major architectural shifts. A stale handoff library is worse than none, because it teaches confidently wrong things — treat drift as a bug, same as any doc.

package/prompts/landing-page-rewrite.md

@@ -0,0 +1,63 @@
+# Landing Page Rewrite from Brand Doc
+
+A reusable prompt for rewriting a product landing page so it draws its emotional core, vocabulary, and positioning directly from a `BRAND_AND_PRODUCT.md` (or equivalent) document. Works for any product where you already have a strong brand narrative and want the public-facing page to carry the same conviction.
+
+---
+
+## The Prompt
+
+I'm going to give you two files:
+
+1. **The brand document** — the authoritative source of truth for this product's positioning, voice, audience, and emotional framing.
+2. **The current landing page** — the code or copy that needs to be rewritten.
+
+Rewrite the landing page following these principles:
+
+### Frame: Why → What → Who
+
+The landing page is **not** a feature walkthrough or a tutorial. It answers three questions in this order:
+
+1. **Why does this exist?** Lead with the emotional reality the audience is living. Name the frustration, the invisible work, the thing that's broken — in language the reader would use to describe it to a friend. Pull this directly from the brand doc's problem framing.
+
+2. **What does it do?** Describe the product's value at the _outcome_ level, not the mechanics level. Say what changes for the user, not which buttons they'll click. Organize around a small number of pillars (4–6) rather than a long feature list. Each pillar should be one sentence of what it delivers and one sentence of why that matters.
+
+3. **Who is this for?** Be specific about the audience. State who benefits most and what makes them different from casual users. If the brand doc has a "Who It's For" section, lift the defining characteristics almost verbatim — they've already been refined.
+
+### Voice and Tone
+
+- **Pull signature lines from the brand doc.** If the brand doc has a memorable phrase — a tagline, a manifesto line, a reframe — use it on the landing page. These lines were crafted to land; let them.
+- **Emotional specificity over abstraction.** Don't say "we make things easier." Say what actually changes: the task that used to take hours, the output that sounds like you, the follow-up you stopped forgetting.
+- **Conversational authority.** The tone should feel like a sharp colleague explaining why they built something — not a sales page, not a blog post. Confident but not hype. Direct but not cold.
+- **Avoid these words and patterns:**
+  - "simple", "easy", "seamless" — let the product's description imply simplicity.
+  - "revolutionize", "game-changing", "cutting-edge" — hyperbole undercuts credibility.
+  - "helps you" as a crutch — prefer active constructions where the product _does_ something.
+  - Listing internal technical details (AI model names, architecture choices) unless the audience cares.
+
+### Structure and Density
+
+- **Hero section:** One bold headline (can be aspirational or identity-based), one supporting sentence that names the product by name along with its category and positioning, one credibility or traction line. No more. The product name must appear in the hero copy — not just in the logo or nav. A first-time visitor should read the product name in text, anchored to the category definition (e.g., "[Product] is the [category] for [audience]."). This is for SEO, accessibility, and clarity.
+- **Problem/reality section:** Full-width emotional narrative, not a two-column comparison chart. Describe the world the user is already in. Make them feel seen. This section earns the right to present your product.
+- **Value pillars:** Replace any long feature grid with 4–6 outcome-oriented pillars. Each one: a short label, one sentence of what it delivers, one sentence of _why_ it matters. Use icons or visual markers if the format supports it.
+- **Who it's for:** A dedicated section. Name 3–5 defining characteristics of the ideal user, drawn from the brand doc. This section should make the right person think "that's me" and the wrong person self-select out.
+- **Differentiators / Insight section:** If the brand doc articulates a philosophy or insight that sets the product apart, give it its own section. Frame it as a belief or realization, not a feature comparison.
+- **CTA:** One clear call to action at the end. Use the brand doc's closing line if it has one.
+
+### Process: How to Execute
+
+1. **Read the brand doc fully** before touching the landing page. Note the 3–5 most powerful phrases, the emotional arc, specific vocabulary, and any lines that feel like they were written _for_ the landing page.
+
+2. **Audit the current landing page** for: places where copy explains the _how_ when it should explain the _what_; feature lists that could be compressed into outcome pillars; tone mismatches; missing sections from the Why → What → Who framework; language that doesn't appear in the brand doc.
+
+3. **Rewrite section by section**, pulling language and structure from the brand doc. Open each section with the brand doc's framing, adapt to landing-page density, preserve the brand doc's emotional register.
+
+4. **Final check:** Read top to bottom as a first-time visitor. Does it flow Why → What → Who? Does every section have at least one phrase from the brand doc? Would a person from the target audience feel recognized?
+
+---
+
+## Usage Notes
+
+- This prompt works best when the brand doc is already strong. If the brand doc is thin, strengthen it first (see `brand-copy-edit-pass.md`).
+- The prompt focuses on content strategy and copy, not HTML/CSS structure. Apply to whatever template or framework you're using.
+- Run once for a full rewrite, then use the brand copy edit pass for ongoing refinement.
+- If the landing page has a pricing section, leave it mostly unchanged — pricing copy follows different rules.

package/prompts/microcopy-centralization.md

@@ -0,0 +1,128 @@
+# Microcopy centralization
+
+Run this when a product has **substantial UI copy still inline in `.svelte` files**, or when marketing/help/tour strings drift from a single source of truth. Complements [User-Facing Content Sync Audit](./user-facing-content-sync-audit.md) (surface completeness) with **implementation discipline** (where strings live and how to verify them).
+
+---
+
+## How to use
+
+Give this prompt to an AI coding assistant with full codebase access:
+
+```
+Run microcopy centralization using [path to this file].
+Mode: [phased clusters / final sweep / audit-only].
+Scope: [optional panel list, or "follow inline audit"].
+```
+
+**Audit-only** — run export + inline + duplication audits; report backlog; no refactors.
+
+**Phased clusters** — migrate high-traffic surfaces in batches (onboarding, primary record tabs, billing, admin). Prefer **clusters over long-tail sweeps** until the inline audit is near zero.
+
+**Final sweep** — after clusters, clear remaining 1-hit files in one pass.
+
+---
+
+## Three-layer architecture
+
+| Layer | Typical module | Owns |
+| --- | --- | --- |
+| **Feature labels** | `[productLabels].ts` | Canonical feature names for landing, help, tours, nav, tabs |
+| **Cross-cutting UI** | `[microcopy].ts` | Save failures, quota errors, shared toasts, Foreman/network banners |
+| **Surface modules** | `[panelName]Copy.ts` under `$lib/content/` (or equivalent) | Panel intros, modals, section blurbs, wizard steps |
+
+**What stays inline:** dead-obvious chrome (`Cancel`, `Save`, `Close`) unless repeated 3+ times; CSS classes; paths; MIME constants may live in admin/dev copy modules **omitted from user-facing export**.
+
+**Legal pages:** one **markdown file per page** (`terms.md`, `privacy.md`) — do **not** shard into microcopy constants. Inline audit treats legal as document sections.
+
+---
+
+## Duplication policy
+
+| Pattern | Action |
+| --- | --- |
+| Same feature title on landing + help + tour | Import `[FEATURE_LABELS].*` |
+| Feature group on About cards | Import `[FEATURE_GROUP_LABELS].*` |
+| Help tip body | Import from tips module; **never duplicate prose** |
+| Elevator pitch variants | **Keep separate** — intentional messaging options |
+| Landing FAQ vs feature summary | FAQ may shorten; don't force identical text |
+| Short tooltip vs long feature summary | **Derive** tip from summary or shared excerpt constant |
+| Terms / Privacy | **Markdown** per page, not `*Copy.ts` shards |
+| Plan tier names / limits | Structured catalog; separate landing vs billing depth where needed |
+
+---
+
+## Three audits (different jobs)
+
+| Command / prompt | Answers |
+| --- | --- |
+| **`user-facing-content-sync-audit.md`** | Is every **shipped feature mentioned** on landing, help, tours, onboarding? |
+| **`export:copy`** (app script) | Regenerate **prose + terms** catalogs for writers/review |
+| **`audit:copy`** (app script) | Exact **duplicate prose** inside the export inventory |
+| **`audit:inline-copy`** (app script) | AST scan of `.svelte`; backlog metric = **UI prose not in export** |
+
+**Acceptance:** inline audit reaches **0 UI prose not in export** (terms/noise/CSS may remain). Sync audit passes for feature parity.
+
+> 🔧 **Guidance:** Apps adopt these scripts when copy volume justifies them (typically Phase 6–7 or after 10+ panels with product copy). ForgeTrail templates describe the **pattern**; copy script implementations from a reference app or build minimal stubs that call your `$lib/content/exportUserFacingCopy` module.
+
+---
+
+## Phased migration checklist
+
+### Phase 1 — Foundation
+
+- [ ] `[productLabels].ts` — wire into marketing About, help section titles, tours
+- [ ] `[microcopy].ts` — save failures, network errors, shared toasts
+- [ ] Document Help ← tips **aliases** in export (no double prose)
+- [ ] `audit:copy` duplication report
+
+### Phase 2+ — Clusters (repeat until audit clean)
+
+For each cluster:
+
+1. Create or extend `*Copy.ts` for the surface
+2. Wire Svelte components to import constants (no string literals for product copy)
+3. Register strings in **export aggregator** (prose + terms groups)
+4. Run `export:copy` + `audit:inline-copy`
+5. Update delivery spec / TODO backlog count
+
+**Cluster examples (rename for your product):**
+
+- Onboarding wizard + start page
+- Primary entity detail tabs
+- Settings / profile / work preferences
+- Billing + export panels
+- Admin / internal tools (may omit dev-only strings from user export)
+
+### Final sweep
+
+- [ ] Remaining 1-hit files from inline audit
+- [ ] Move spec to **completed**; mark TODO done
+- [ ] Propagate lessons to ForgeTrail (`propagate-to-forgetrail.md`)
+
+---
+
+## Export structure
+
+Split **prose** (paragraphs, intros, help bodies) from **terms** (labels, tooltips, errors, button-adjacent strings). Use helper functions for parameterized copy (`saveFailedWithLabel(name)`) and register **sample invocations** in export so audit can match dynamic strings.
+
+**User-facing content rule:** Help, onboarding, tours, toasts, and empty states must **not** mention internal spec paths or engineering jargon (see `.cursor/rules/user-facing-content.mdc`).
+
+**Locale:** Default **US English** for product copy and LLM prompts that generate user-visible text (see `.cursor/rules/us-english.mdc`).
+
+---
+
+## When to run
+
+| Trigger | Action |
+| --- | --- |
+| After 3+ features ship in a week | Sync audit + spot-check inline audit |
+| Before launch / marketing push | Full sync audit + inline audit at 0 prose backlog |
+| After landing/help rebrand | Reconcile `FEATURE_LABELS` + sync audit |
+| New high-traffic panel | Add `*Copy.ts` in same PR; don't defer |
+| Periodic (monthly) | `export:copy` + `audit:inline-copy` in CI or pre-release checklist |
+
+---
+
+## Propagate to ForgeTrail
+
+When your app completes a centralization pass, run **`prompts/propagate-to-forgetrail.md`** so templates, `TECHNICAL_REFERENCE`, and `CODE_QUALITY` stay aligned — generalize patterns only, not app-specific strings.

package/prompts/panel-usability-audit.md

@@ -0,0 +1,197 @@
+# Panel Usability Audit
+
+Deep usability audit of a single panel or feature surface. Produces a detailed spec with numbered, categorized findings, severity/effort ratings, concrete recommendations, and a phased implementation plan. Use before a beta, launch, or whenever a surface has accumulated enough features to warrant a fresh-eyes review.
+
+---
+
+## How to Use
+
+1. Give this prompt to an AI coding assistant with **full codebase access**.
+2. Specify which **panel or surface** to audit (the `[TARGET]` placeholder below).
+3. The assistant reads every file involved — component, sub-components, API routes, help content, related specs — then produces a spec under `specs/`.
+4. Save the spec at `specs/<surface>-usability-audit.md`.
+5. Add a backlog entry linking the spec (e.g., `TODO.md` or your tracking system).
+
+---
+
+## Instructions
+
+You are a product-minded UX engineer auditing a feature surface in this codebase. The user will specify which panel, page, or component to audit.
+
+### Step 1 — Inventory (read-only)
+
+Before writing anything, read **every file** that participates in the target surface:
+
+- **Primary component** — the main component file (all state, derived values, async functions, event handlers, lifecycle hooks, template branches, buttons, error displays, conditional text, transitions).
+- **Sub-components** — every child imported by the primary component (e.g., result cards, progress bars, previews, modals, form editors). Note their props, user-visible elements, actions, and accessibility attributes.
+- **API routes** — every server endpoint the surface calls. Note request/response shapes, error handling, entitlement checks, side effects.
+- **Help content** — any help panel, tooltip copy, onboarding tours, or guided flows that describe the surface to users.
+- **Related specs** — completed and open specs that shaped or plan changes to this surface.
+- **Test plan** — any manual or automated test scenarios covering this surface.
+- **Brand / design docs** — target user, design system conventions, copy tone.
+
+Build a complete mental model of: every user path, every state transition, every button and when it appears, every error and how it is displayed, every piece of information shown and when.
+
+### Step 2 — Analyze across six dimensions
+
+Evaluate the surface through each lens below. For each, ask the guiding questions and look for specific anti-patterns.
+
+#### A. Flow and orientation
+
+- Can a new user figure out what to do and in what order without external help?
+- Do visual cues (numbers, arrows, labels) match the actual flexibility of the flow?
+- Is state preserved across navigation (close/reopen, tab switch, browser refresh)?
+- When an operation fails, does the user know what failed and how to recover?
+- After a long operation succeeds, does the UI guide the user to a natural next action?
+
+*Anti-patterns:* strict-looking sequences that are actually optional; state that resets on panel close; error recovery that discards user progress; success screens with no next step.
+
+#### B. Information hierarchy and density
+
+- Is the most important element (primary CTA, key result) visible without scrolling at each state?
+- Does long content (AI output, lists, markdown) push primary actions below the fold?
+- Is the same information rendered in multiple places with slightly different styling?
+- Do secondary surfaces (history, logs, metadata) compete for visual weight with primary workflows?
+
+*Anti-patterns:* CTA buried under 3+ scroll heights of output; duplicated rendering with drift; "always visible" sections that are rarely needed.
+
+#### C. Error handling and recovery
+
+- Does the error state tell the user what went wrong, whether retrying makes sense, and what action to take?
+- Are errors categorized (transient, parse/model, permanent/user) with different recovery paths?
+- Are secondary failures (background saves, list loads, deletes) surfaced or silently swallowed?
+- Does error recovery preserve user context or reset everything?
+
+*Anti-patterns:* generic "Try Again" that resets all state; silent failures that look like empty results; identical error display for all error types.
+
+#### D. Missing affordances
+
+- At each state, what does the user want to do that no button or link offers?
+- Can the user preview results, compare before/after, or undo a destructive action?
+- Is plan usage / cost communicated before an action that consumes a limited resource?
+- Are there actions the user has to perform outside the surface that could be brought in-line?
+
+*Anti-patterns:* no preview after a transformation; no undo or revert; cost/usage hidden until the limit is hit; recovery requires download + re-upload instead of a single action.
+
+#### E. Consistency and patterns
+
+- Do similar actions use the same confirmation pattern (all inline, or all dialog, or all none)?
+- Is button visual weight (primary, secondary, text link) proportional to importance in every state?
+- Are shared UI patterns (upload, progress, preview, error) rendered from shared code or duplicated?
+- Do labels, icons, and placement follow the same vocabulary across states?
+
+*Anti-patterns:* mix of native `confirm()` and inline confirmations; primary-weight buttons for secondary actions; duplicated markup for the same pattern in different branches.
+
+#### F. Accessibility
+
+- Do progress indicators have ARIA roles and live-region attributes?
+- Do icon-only buttons have accessible labels (`aria-label` or visually hidden text)?
+- Are modals/panels keyboard-navigable (Escape to close, focus trap, tab order)?
+- Are decorative vs interactive elements correctly marked?
+
+*Anti-patterns:* `<div>` with `onclick` but no keyboard handler or role; icon buttons with no label; progress bars with no `role="progressbar"`.
+
+### Step 3 — Write the spec
+
+Produce a spec with this structure:
+
+```
+# [Surface Name] — Usability Audit
+
+**Status:** Proposed
+**Audience:** Product and engineering
+**Related:** [links to prior specs, design docs]
+
+---
+
+## 1. Problem
+[1-2 paragraphs: what this surface does, why an audit is warranted, and a bullet summary of the issue categories found.]
+
+## 2. Goals
+[Numbered list: what "good" looks like after fixes are applied.]
+
+## 3. Non-goals
+[Bullet list: what is explicitly out of scope.]
+
+---
+
+## 4. Findings
+
+[Rating key:]
+> Severity: **High** = blocks or confuses most users; **Medium** = friction for some users or edge cases; **Low** = polish or minor annoyance.
+> Effort: **S** = < 1 hour, localized change; **M** = 1–4 hours, touches multiple places; **L** = half-day+, new component or significant restructure.
+
+### A. Flow and orientation
+#### A1. [Finding title]
+**Severity:** X | **Effort:** X
+[Description: what is wrong, why it matters, who it affects.]
+**Recommendation:** [Concrete fix. Name the function, component, or UI element to change. Offer alternatives if relevant.]
+
+[... repeat for each finding across all six categories A–F ...]
+
+---
+
+## 5. Implementation phases
+
+### Phase 0: Quick wins (S effort, high impact) — target before [milestone]
+| # | Finding | Change |
+|---|---------|--------|
+[table rows]
+
+### Phase 1: [Theme] (M effort, high impact) — target for [milestone]
+[table]
+
+### Phase 2: [Theme] (M effort, medium impact) — [timeline]
+[table]
+
+### Phase 3: [Theme] (L effort) — [timeline]
+[table]
+
+---
+
+## 6. Files affected (Phase 0–1 scope)
+| File | Changes |
+|------|---------|
+[table rows with specific file paths and one-line change descriptions]
+
+---
+
+## 7. Open questions
+[Numbered list of decisions that need product/design input before implementation.]
+```
+
+### Rules
+
+- **Ground every finding in code.** Name the specific state variable, template branch, function, or component. Do not write vague "the UX could be better" observations.
+- **Be concrete in recommendations.** Say "add a button that calls `togglePreview('resume')`" not "consider adding a preview."
+- **Include severity AND effort.** Readers use these to prioritize; omitting either makes the spec less actionable.
+- **Phase the work.** Group by effort and impact so the team can ship quick wins before larger restructures.
+- **List affected files.** For at least Phase 0–1, enumerate every file that needs a change.
+- **Flag open questions.** If a recommendation has meaningful alternatives or needs product input, say so — do not bury ambiguity in the recommendation text.
+- **Do not conflate audit with redesign.** The spec identifies and recommends fixes; it does not propose a full UI overhaul unless the findings demand one.
+- **Stay honest.** If something works well, do not manufacture a finding. If the surface is in good shape, say so and keep the spec short.
+
+---
+
+## Input
+
+```
+[TARGET]: The panel or surface to audit. Examples:
+  - "ProfilePanel.svelte (Settings tab)"
+  - "JobDetailPanel.svelte (all tabs)"
+  - "The onboarding flow (signup + first import)"
+
+Audit [TARGET] using the methodology above. Save the spec at specs/<target>-usability-audit.md
+and add a backlog entry linking to it.
+```
+
+---
+
+## Run Logging
+
+After completing the audit, add a backlog entry (e.g., `TODO.md`) under the most relevant section with:
+
+- `[ ]` checkbox (open — the audit is proposed, not implemented)
+- Title: **`[Surface] usability audit`**
+- One-line summary of finding count and key themes
+- Link to the spec