@sableui/react 0.0.0-stage → 0.1.0

package/llms/tasks/designing-a-surface.md

@@ -0,0 +1,115 @@
+# Task: designing a surface with Sable
+
+Tokens make decisions consistent; they do not decide what deserves attention.
+Start with the user's task and content, then choose a visual direction. Sable's
+default Base identity is a starting point. A consumer can be light-first,
+photographic, editorial, playful, or quiet while retaining semantic tokens,
+accessible behavior, and a coherent interaction policy.
+
+## 1. Write a short surface brief
+
+Save the brief in the app, for example `design/<surface>/brief.md`. Record:
+
+| Decision | Make it concrete |
+|---|---|
+| User and outcome | Who is here, what they need to understand or do, and the primary action. |
+| Mode | Persuade, operate, read, or experience. This describes the job, not density. |
+| Register | Page or workspace, with a reason based on scrolling and task behavior. |
+| Content truth | Real or clearly labeled fictional data; required copy; available assets; unverified claims excluded. |
+| Direction | Two or three properties expressed as visible choices: e.g. broad image fields, compact captions, low chroma surfaces. |
+| Story | For each section: the user's question, the evidence or task it supplies, and what follows. |
+| Hierarchy and rhythm | Focal element, type contrast, prose measure, alignment anchors, and section spacing relationships. |
+| Color and material | Surface/ink pairs, where accent carries meaning, imagery treatment, supported color modes. |
+| Interaction | Primary flow plus loading, empty, error, success, disabled, keyboard, and touch behavior. |
+| Motion | Purpose, trigger, driver, timing, interruption, and reduced-motion result; include deliberate static decisions. |
+| Adaptation | What stacks, moves, hides with an equivalent route, or becomes scrollable on narrow screens. |
+| Review | Target routes, states, widths, and the uncertainty the proof build must resolve. |
+
+For small changes, record only decisions that change. When the user requests
+alternatives or competing directions materially affect the brief, compare bounded
+rendered studies using [developing-taste.md](./developing-taste.md).
+Keep a user-pinned identity fixed. Do not create decorative variation just to
+satisfy a checklist.
+
+## 2. Retrieve applicable lessons and contracts
+
+```bash
+npx sable atlas --search "editorial hierarchy" --contrast --limit 3 --json   # the project's atlas, if any
+npx sable prefer --search "hierarchy" --scope project:<project-id> --json
+npx sable learn --search "editorial hierarchy" --json
+npx sable pattern --list
+npx sable pattern LandingPage --skeleton
+npx sable component Button --props
+```
+
+Read each lesson's `appliesWhen`, `avoidWhen`, and provenance. State what transfers
+and what does not. A precedent is evidence for a decision in a context, not an
+instruction to reproduce an entire aesthetic. If no lesson fits, proceed from the
+brief and gather fresh evidence.
+
+Use `sable atlas --show <id> --json` to retrieve full annotations and absolute
+capture paths, then view the images. Retrieve only preferences matching the
+project, brand, person, or task context. Scope and the present brief take priority
+over how often a reference or preference was used in the past.
+
+## 3. Choose composition before components
+
+Patterns are useful starting points when their information architecture matches.
+An original composition is equally valid. Use layout primitives and semantic HTML
+for bespoke pages; record why a shell does or does not fit. The closest pattern's
+similarity score describes reuse and cannot establish quality.
+
+Establish the major regions with real text and assets before decorating details.
+
+Record the ownership boundary: Sable behavior components and semantic tokens,
+app-owned composition and assets, and any native controls or custom behavior.
+Using Sable does not require every element to be a library component. Prefer its
+public component APIs and token hooks for repeated control styling. If repeated
+`!important` rules are necessary to change a control's type, spacing or shape,
+identify the missing hook rather than claiming the app is fully system-driven.
+Keep one-off editorial layout decisions local; propose a shared API only when
+multiple real consumers need the same capability.
+
+Use uniform rows for equivalent records, readable measure for prose, larger space
+for the primary artifact, and deliberate density changes where the story changes.
+A palette swap on a canonical landing page does not test a new composition.
+
+Choose type size, weight, line-height, container width, and copy together. Select
+HTML heading levels by document structure and visual tiers by hierarchy. A large
+heading does not become semantically deeper because it needs smaller type.
+
+When images, illustration, video, or fonts carry the message, use
+[creating-design-assets.md](./creating-design-assets.md). Plan concrete subjects,
+treatments, sources, responsive crops, and delivery budgets, then produce and
+inspect the assets in the layout. A mood label or generation prompt alone is not
+a finished asset; keep unresolved placeholders explicit in the review record.
+
+## 4. Make the intended behavior real
+
+Use Sable for behavior that it already owns. Custom interactive elements need
+clear feedback, accessible names, focus visibility, and a complete action. A
+successful demo must show a real result, such as changed data or a confirmation
+with context. Do not leave visible primary actions inert.
+
+Use motion to explain change or establish a deliberate reading cadence. Keep
+frequent actions quick. Initial content may remain static. Avoid adding a reveal
+to every section by habit. Any bespoke animation must honor reduced motion and
+Sable's policy; core primitives cannot control an unrelated animation driver.
+
+For connected routes, use [reviewing-a-journey.md](./reviewing-a-journey.md) to
+plan carried state, shared visual decisions, and recovery. For meaningful motion,
+use [reviewing-motion.md](./reviewing-motion.md) to define and capture temporal
+behavior. These extend the work when relevant; a small static surface does not
+need a manufactured journey or animation.
+
+## 5. Inspect, repair, and record
+
+Run the consumer's typecheck, tests relevant to behavior, and `sable-lint`. Then
+follow [reviewing-a-design.md](./reviewing-a-design.md): inspect desktop and mobile,
+exercise the primary flow and keyboard behavior, and test reduced motion. Fix
+observed failures and recapture affected states. End only when the agreed work is
+complete or the remaining limitation is explicitly recorded.
+
+Distill a useful discovery through
+[learning-from-builds.md](./learning-from-builds.md). Good builds may teach no new
+rule. Do not claim timelessness or premium quality from a passing lexical score.

package/llms/tasks/developing-taste.md

@@ -0,0 +1,157 @@
+# Task: develop taste and range with Sable
+
+Taste is contextual judgment: deciding what deserves emphasis, which relationships
+make a composition coherent, and whether the result serves its audience. The
+accessibility, semantic-token, and behavior contracts are the floor. A consumer's
+type character, density, imagery, spatial rhythm, shape, and motion can vary.
+
+## Read a small, contrasting reference set
+
+```bash
+npx sable atlas --search "editorial image hierarchy" --contrast --limit 3 --json
+npx sable atlas --show <reference-id> --json
+```
+
+Open the returned `evidence[].absolutePath` images with the agent's image viewer.
+Reading the annotations without viewing the captures does not establish visual
+understanding. The atlas is the project's own (`.sable/atlas/atlas.json`) and works offline;
+the package ships none, and an empty result means working from the user's
+references. Images are reference evidence, never assets to copy into a new
+brand's product.
+
+Choose references for the audience and information problem. Retrieve one close
+analogue and at least one useful contrasting approach when the brief is open.
+Search is contextual lexical retrieval with family diversity, not semantic image
+search or an aesthetic ranking. `--mode` and `--family` are hard filters. A result
+can be irrelevant despite matching a word; no result is better than inventing a
+connection. `sable atlas --check` detects changed or missing captures.
+
+For each reference, name one relationship that transfers and one boundary. For
+example, an image can carry the primary claim while navigation recedes. That does
+not make tiny navigation or a long loading sequence suitable for a public service.
+Gallery inclusion is discovery provenance. Read the recorded limitations and
+distinguish a captured state from observed temporal behavior.
+
+## Express a direction as choices
+
+Keep the factual brief fixed. Describe composition, typography, density, imagery,
+story, and motion as relationships that can be seen or operated. Include spacing
+and color decisions in the rationale and consumer-owned theme. State how the
+direction adapts to smaller viewports and how its primary interaction works.
+
+Coherence matters within a design; range matters across the set of designs. A
+strong result can be bright, dense, playful, quiet, expressive, or austere. Avoid
+turning familiar signals such as serif headlines, beige surfaces, dark canvases,
+hairlines, pills, and oversized type into unconditional definitions of quality.
+Avoid prohibiting these choices universally for the same reason.
+
+When the direction depends on assets, continue with
+[creating-design-assets.md](./creating-design-assets.md): specify and realize
+the subject, treatment, crop, font source, and delivery constraints. Carry the
+chosen direction across a full task with
+[reviewing-a-journey.md](./reviewing-a-journey.md), and assess temporal quality
+using [reviewing-motion.md](./reviewing-motion.md). Read these when relevant;
+three first-view studies alone do not establish full-product consistency.
+
+## Compare rendered alternatives
+
+Start alternatives from different answers to the user's problem, rather than
+assigning an editorial, poster, and dashboard look to every brief. For each
+proposal state what the visitor should notice first, how they reach the first
+useful action, and what information remains visible while deciding. Then choose
+type, color, imagery and density that support that answer. Those familiar styles
+remain valid when the brief warrants them; their presence is not evidence of range.
+
+Compare across recent builds as well as within this set. If unrelated briefs keep
+receiving the same headline treatment, section order and card geometry, revisit
+one direction's information structure. Do not introduce novelty that makes the
+task harder merely to increase difference. Record that tradeoff explicitly.
+
+When requested alternatives or a consequential design choice needs comparison,
+build bounded studies: the first
+viewport and one representative interaction, including a mobile adaptation.
+Use the same content and function. Change composition or information rhythm as
+well as another meaningful axis. Palette swaps alone do not explore a direction.
+For a small refinement or a user-pinned identity, keep the existing direction and
+compare only the decision in question. A new build can proceed directly from its
+brief and selected preset. The `explore` tool requires three to six evidence-bound
+directions; smaller comparisons can be delivered directly.
+
+```bash
+npx sable explore --template > design/exploration.json
+npx sable explore --check design/exploration.json --json
+npx sable explore --compare design/exploration.json --json
+```
+
+Fill the template after rendering, with project-relative artifact paths and exact
+SHA-256 hashes. Each direction needs desktop, mobile, and interaction evidence.
+The validator checks declared differences and file integrity. It cannot determine
+whether different prose describes visually identical layouts; inspect the images.
+An interaction screenshot proves a state, not easing, duration, or interruption.
+Observe behavior or retain a recording when temporal quality is being assessed.
+
+Open the generated comparison HTML. It initially hides direction names and
+rationales so the brief and rendered work lead the judgment. Inspect the captures
+at a useful size. A comparison can end in a tie. Develop the selected direction,
+then perform the full rendered review and repair the observed defects.
+
+When work has a time or cost limit, make the bounded studies runnable early and
+reserve time for an actual first-use check. Prioritize the primary flow, loaded
+assets and narrow-screen layout before extra explanatory records. Save a small
+checkpoint after each direction: files produced, states operated, defects found,
+and checks still untested. A timeout with screenshots is still an incomplete run;
+do not silently retry it as though the failed attempt never happened.
+
+## Keep personal judgment separate from craft lessons
+
+The comparison page exports a preference JSON; it does not silently write to a
+project or update a model. Record the exported file from the project root:
+
+```bash
+npx sable prefer --record design/preference.json
+npx sable prefer --search "hierarchy" --scope project:example --json
+npx sable prefer --check --json
+```
+
+Record the chosen option or tie, both accepted and rejected alternatives, the
+reason, the brief, scope, and the actual reviewer. Supported scopes are personal,
+project, brand, and task-type. Search requires a scope so a choice for one context
+does not quietly become a rule everywhere. Human attribution is self-reported;
+the offline CLI cannot authenticate the reviewer. Never author an agent's choice
+as a human preference. Agent observations are excluded from retrieval by default;
+use `--reviewer agent` or `--reviewer all` when explicitly reviewing those records.
+
+Version the `.sable/preferences/` records with their evidence. Bring a record to
+another project deliberately with its linked artifacts and matching scope; there
+is no hidden cross-project collection. A saved record affects the next build only
+when an agent retrieves, inspects, and applies it. Respect explicit current user
+instructions over earlier preference records. Keep counterexamples and changed
+preferences as new records rather than rewriting a past decision.
+
+Use `sable learn` for observed causal lessons, such as a text-control collision
+under zoom. Use `sable prefer` for judgments among viable alternatives. Promote a
+lesson into general guidance only after reviewing its transfer to another domain.
+
+## Test transfer, quality, and range independently
+
+Use the local comparison HTML generated by `sable explore --compare` when
+alternatives need review. Attribute choices to the actual reviewer; agent
+observations do not become human preferences. For a reusable design input,
+follow [creating-a-preset.md](./creating-a-preset.md).
+
+Freeze unfamiliar briefs and their content. Compare the old workflow against the
+new one under the same model, time/effort budget, assets, and task constraints.
+Keep the test briefs out of reference curation. Preserve source and rendered
+artifacts for each run; do not edit a frozen baseline to improve its score.
+
+Review anonymously, with ties allowed, against audience fit, hierarchy, spatial
+rhythm, color/material coherence, interaction clarity, motion, and adaptation.
+Check task completion and accessibility separately. Compare stylistic range
+across the batch; novelty does not excuse poor usability or an incoherent page.
+Independent agent critique is useful evidence, not a substitute for actual human
+preferences. Calibrate any automated ranking against human comparisons before
+claiming that it predicts a person's taste. A few proof builds establish workflow
+feasibility; repeated held-out comparisons are needed to establish a quality lift.
+
+This process improves retrieved context, decisions, and memory. It does not
+fine-tune the agent's underlying model or guarantee universal aesthetic quality.

package/llms/tasks/getting-started.md

@@ -0,0 +1,63 @@
+# Get started with Sable
+
+Sable is on npm as `@sableui/react`. The installed version's `registry.json`
+consume block has the exact recipe. Requirements: React 19, React DOM 19, and
+Tailwind CSS 4 integrated into your build.
+
+## Install
+
+```bash
+pnpm add @sableui/react
+```
+
+## Connect CSS and React
+
+For `src/styles.css` with `node_modules` at the project root:
+
+```css
+@import "tailwindcss";
+@import "@sableui/react/styles.css";
+@source "../node_modules/@sableui/react/dist/**/*.{js,mjs}";
+```
+
+Adjust the relative `@source` path to your stylesheet's location. Import this
+stylesheet from your app entry. For Vite, preserve your plugins and add
+`resolve: { dedupe: ["react", "react-dom"] }` to its configuration. Load Figtree
+and DM Mono through your font setup, or customize the font tokens.
+
+```tsx
+import { Button } from "@sableui/react"
+import "./styles.css"
+
+export default function App() {
+  return <Button>Save changes</Button>
+}
+```
+
+No provider or icon dependency is required for this first component. Optional
+theme, icon, and motion providers are explained in the package README.
+
+## Connect your agent and verify
+
+```bash
+pnpm exec sable setup --agent --dry-run
+pnpm exec sable setup --agent
+pnpm exec sable doctor
+```
+
+After installing Sable, run `pnpm exec sable setup --agent` in the target
+project. It installs discoverable entry files in `.agents/skills/sable` for
+Codex/Cursor and `.claude/skills/sable` for Claude Code; `--target` selects a host.
+Each entry resolves `skills/sable/SKILL.md` from the installed package, so package
+upgrades also update the workflow. Other agents can read that file directly.
+Use `$sable build <idea>`, `inspire <references>`, `audit <target>`, or
+`polish <target>` in Codex; use `/sable` with the same modes in Claude Code or
+Cursor. `create` is a build alias. These are agent modes, not shell commands.
+
+Upgrade with `pnpm update @sableui/react --latest`, then
+`pnpm exec sable setup --agent --update`. Setup only replaces managed files
+that have not been locally edited; `--dry-run` checks without writing. Keep
+project preferences in project instructions. Package installation alone does not
+change agent settings. See [building-with-sable.md](./building-with-sable.md),
+[creating-a-preset.md](./creating-a-preset.md), and
+[using-presets.md](./using-presets.md).

package/llms/tasks/learning-from-builds.md

@@ -0,0 +1,74 @@
+# Task: learning from audits and builds
+
+A useful lesson connects a decision to an observed consequence and says where it
+stops applying. "Use bigger type" is not enough. "A display-led section lost its
+hierarchy when the feature title used the compact card tier; matching the tier,
+measure, and surrounding spacing restored emphasis" is a testable lesson.
+
+## Retrieve before inventing
+
+```bash
+npx sable learn --search "motion workspace" --json
+npx sable learn --show motion-needs-a-reason --json
+```
+
+The command reads packaged precedents and the current project's
+`.sable/lessons/*.json`. It works offline at the installed package version and
+does not require a plugin. Entries carry `appliesWhen`, `avoidWhen`, origin,
+confidence, and evidence. A search match is a candidate; inspect the conditions
+before applying it. Curated precedents preserve earlier observed failure mechanisms
+in shipped markdown. They are not fresh tests of the current build.
+
+## Record observed consequences as lessons
+
+After [reviewing-a-design.md](./reviewing-a-design.md), distill zero or one new
+lesson unless several independent discoveries warrant records. Search first to
+avoid duplicates. Record the failed hypothesis too when it explains a boundary.
+
+```bash
+npx sable learn --template > design/lesson.json
+```
+
+Fill the template with a specific id, searchable tags, mode/register, principle,
+conditions for applying and avoiding it, observed before/after change, date,
+reviewer, source build, and Sable version. Evidence paths are relative to the
+project root, unlike review artifacts which are relative to their review JSON.
+Link distinct, existing before and after artifacts and describe what was observed.
+Reference the associated design review in the source description.
+
+```bash
+npx sable learn --record design/lesson.json
+npx sable learn --check
+```
+
+Run from the project root. Recording writes a new `.sable/lessons/<id>.json` with
+exclusive creation; it refuses duplicate ids and never edits the installed package.
+Version those files with the project and retain the linked artifacts. Package
+upgrades preserve this local memory. Missing artifacts are reported as errors, not
+silently ignored. The CLI does not send evidence anywhere.
+
+All local records remain `provisional`, including a human's record. Artifact
+existence validates traceability, not the reviewer's conclusion. Reuse a lesson in
+a different composition or domain before treating it as broad guidance. If it
+fails, preserve that counterexample in a distinct, related lesson rather than
+rewriting history. Maintainers can curate repeated, scoped findings into bundled
+precedents with a source record and explicit transfer boundaries.
+
+## Keep learning portable
+
+Store general decisions in lessons; keep customer data, brand assets, and detailed
+private audit captures in the project evidence. Distributed precedents should be
+neutral and specific. A visual technique should never become a global rule just
+because it worked for one dark technical page. Typography weight, square versus
+round shape, accent restraint, and scroll choreography all depend on the brief.
+
+Use the package CLI to retrieve guidance, build, inspect, and record what you learn.
+
+## Record preferences in their own memory
+
+`sable prefer` stores comparisons between rendered alternatives, a choice or tie,
+the reason, reviewer, and personal/project/brand/task-type scope. It does not turn
+a subjective choice into a correctness rule. `sable explore` creates the local
+comparison interface and export. See [developing-taste.md](./developing-taste.md)
+for the visual atlas, scoped retrieval, comparison workflow, and transfer tests.
+Only label a record human when it reflects an actual human's stated judgment.

package/llms/tasks/reviewing-a-design.md

@@ -0,0 +1,114 @@
+# Task: reviewing a rendered design
+
+Review has two separate results: code conformance and observed design quality.
+`sable grade` checks source; it cannot see a screen, operate a flow, or judge taste.
+Its pattern similarity is descriptive. Original composition is not a defect.
+
+## Capture a reviewable build
+
+Save the surface brief, then capture the rendered route at a desktop width of at
+least 1024px and a mobile width of at most 480px. Record the actual viewport,
+route/state, supported color mode, and motion setting with each artifact. Inspect
+the whole route as well as its first viewport. Ensure fonts and media have loaded.
+Use a recording or an observed interaction report for behavior that a still cannot
+show. Include reduced motion and every color mode the surface promises to support.
+
+For connected routes, extend this review with
+[reviewing-a-journey.md](./reviewing-a-journey.md), following the complete task and
+recovery rather than judging isolated screens. For temporal behavior, use
+[reviewing-motion.md](./reviewing-motion.md) to retain and inspect playable
+evidence or a timestamped frame sequence with its limits. For identity-bearing
+media and fonts, verify the actual assets, responsive crops, and fallbacks using
+[creating-design-assets.md](./creating-design-assets.md).
+
+```bash
+npx sable grade src --json
+npx sable grade --template > design/review.json
+```
+
+The first command reports `sourceHash`. Copy it into `build.sourceHash` in the
+review template for the source you captured. Source changes invalidate that record;
+re-capture affected states and update the hash after a repair. Artifact paths are
+relative to the review JSON. The fingerprint covers all non-test files in the
+supplied targets and Sable's runtime implementation, registry, and lint contract.
+Use `sable grade src public --json` when images or fonts live in `public`; remote
+resources are outside its coverage. Keep review JSON and captures outside those
+targets so the review does not fingerprint itself. On shells with non-UTF-8
+redirection defaults, save the template as UTF-8 JSON.
+
+Source fingerprints normalize CRLF to LF in known text formats so the same
+checkout remains identifiable on Windows and Linux. Binary assets and artifact
+hashes retain their exact bytes. Before/after iteration records must reference
+distinct capture files; assigning a second artifact ID to one file is insufficient.
+
+Each artifact also requires a `sha256` hash of its inspected bytes. Running the
+grader with `--review` reports `review.artifactHashes` for the current files. Copy
+those values into artifact records only after inspecting the corresponding files;
+replacing a capture at the same path then makes the review incomplete. Neither
+the source fingerprint nor an artifact hash proves someone inspected the screen.
+
+## Review these eight dimensions
+
+| Dimension id | Look for concrete evidence |
+|---|---|
+| `purpose-story` | The user's task is clear, copy is specific, evidence precedes a request to act, and sections advance the story or workflow. |
+| `hierarchy-type` | A clear focal point, meaningful contrast, intentional wrapping, legible real fonts, and a valid heading outline. |
+| `layout-rhythm` | Shared anchors, coherent spacing relationships, useful density, and appropriate grouping rather than repeated default boxes. |
+| `color-material` | Surface and ink pairs remain legible, accent has a job, imagery fits the direction, and all interactive states work. |
+| `interaction` | The primary flow completes; hover, focus, loading, errors, empty states, and success communicate what happened. |
+| `motion` | Transitions explain a change, timing suits use frequency, interruption behaves, and reduced motion keeps content available. |
+| `responsive` | Content priority survives narrow widths, controls remain operable, text and media fit, and intended scroll regions are discoverable. |
+| `accessibility` | Keyboard order, visible focus, names/roles, contrast, announcements, and touch targets work in the rendered context. |
+
+For dense catalogues, inspect actual item names and values at phone width. A
+table that fits the viewport can still crush its identifying column into a few
+characters per line. Choose a readable row/card adaptation or a clearly
+discoverable scroll region, preserving labels and access to the required fields.
+Check long names, not only short placeholders. Inspect edge fades over the first
+and last items too: a scroll hint must not wash out their text or actions.
+
+For each dimension use `pass`, `revise`, or `untested`, with a specific observation
+and supporting artifact IDs. Record the required behavioral checks separately:
+`primary-flow`, `keyboard`, `overflow`, and `reduced-motion`. Do not mark a check
+passed just because a component's underlying primitive supports it.
+
+Before polishing, operate the first useful action from a fresh opening state at
+both widths. A desktop sidebar often lands after a long introduction on mobile.
+Check whether that order serves this task. When explanation genuinely comes
+first, provide and test a clear route to the action; do not universally force a
+button above the fold. Record what the visitor can understand and do before
+scrolling, and what the next scroll reveals.
+
+Inspect section boundaries and layered imagery at normal size and increased text
+size. Negative margins, fixed-height heroes and positioned decoration can clip
+labels or obscure live controls even when there is no horizontal overflow and
+the heading outline is valid. Check that every control's visible area is also
+clickable. Prefer a separate space for decoration when overlap has no purpose;
+keep intentional overlaps only after verifying text, hit targets and narrow
+layouts. An accessibility scan alone cannot settle this visual check.
+
+Use opaque `focus-visible:ring-ring` or `ring-sidebar-ring`; reducing the ring to
+`/40` or `/50` alpha can erase its contrast against the surface. The shared
+`faded-focus-ring` rule catches those classes. A token contrast report establishes
+the tested pairs, not the entire rendered product's accessibility.
+
+Describe a defect as a visible or behavioral consequence: "The heading wraps to
+six lines at 390px and pushes the action below the intended first decision point."
+Then record the repair and before/after artifact IDs in `iterations`. Avoid vague
+scores such as "feels 9/10 premium." Mark unsupported or uninspected claims untested.
+
+```bash
+npx sable grade src --review design/review.json --json --strict
+```
+
+The evidence validator checks the record's completeness, artifact existence, and
+source identity. `review-recorded` means the stated review is complete; it is not
+an independent visual judgment. `evidence-incomplete` and `revision-needed` must
+not be presented as approved work. Keep remaining issues explicit in `openIssues`.
+
+For system changes, prove transfer with distinct original surfaces whose
+information architecture differs: for example, a reading or persuasion page and
+an operating tool. Keep the same content truth across iterations. Compare the
+results against each brief, rather than against how closely they resemble Sable's
+existing reference pages. Then capture a conditional lesson using
+[learning-from-builds.md](./learning-from-builds.md).

package/llms/tasks/reviewing-a-journey.md

@@ -0,0 +1,84 @@
+# Task: review a complete product journey
+
+A polished opening can lead into an incoherent or unfinished product. Use this
+workflow when the request spans connected routes or a meaningful sequence of
+states. It extends [reviewing-a-design.md](./reviewing-a-design.md); a one-control
+refinement does not need a product-wide audit.
+
+## Define the path and what must stay consistent
+
+Write the user's starting situation, intended result, and the shortest meaningful
+path. Include a recovery or reversal that matters to that task. For example:
+discover a workshop → inspect details → choose date and seats → enter attendee
+details → confirm → revisit, change, or cancel the booking. A demo may keep data
+locally, but must communicate that boundary and demonstrate its actual outcome.
+
+Keep a compact journey record beside the brief. Use a table or project-owned JSON;
+this is not a new Sable CLI schema:
+
+| Step | Route/state | User question and action | Carries forward | Review evidence |
+|---|---|---|---|---|
+| Choose | Workshop detail | Is this suitable, and which date works? | Workshop, date, seat count | Actual desktop/mobile state and exercised selection |
+| Commit | Attendee form | What is required, and what happens next? | Selection plus valid entries | Error, correction, pending, and success where implemented |
+| Return | Booking detail | What did I arrange, and how can I change it? | Confirmed result and current status | Re-entry, change, cancellation, or recovery |
+
+Record shared terms, navigation, type roles, color meanings, action hierarchy,
+form treatment, spacing anchors, and motion policy once. Preserve those across
+the path. Allow purposeful differences: discovery can be expressive while entry
+is compact and confirmation is calm. Consistency does not mean identical layouts.
+
+## Review transitions as well as screens
+
+Operate the primary path with real state changes. Check the selected item, count,
+price or other task facts where present; do not silently reset them between pages.
+Inspect forward navigation, browser Back, re-entry, and refresh according to the
+product's promised persistence. Use isolated fixtures for local testing.
+
+A successful storage write is only half of persistence. Confirm a record, reload
+with the same browser storage, and verify that the UI restores the exact saved
+choice. Then change it, cancel it, and reload again. Test invalid stored data or
+denied storage when the app claims to handle them. A confirmation screenshot and
+the presence of a localStorage key do not prove restoration. When an edit is
+abandoned, preserve the last confirmed record unless the user explicitly deleted
+it; describe save and removal failures according to what may survive a reload.
+
+Exercise the relevant failure and recovery cases: unavailable choices, validation,
+slow or failed saves, empty results, duplicates, and cancellation. Select cases
+from the actual behavior rather than adding a checklist of imaginary features.
+User input should survive a recoverable error when appropriate; retry should not
+silently duplicate an action. A success message must describe what really happened.
+
+Follow keyboard focus through each transition and through removal of a focused
+control. Check headings, names, visible focus, and announcements in context.
+Repeat the important path on a narrow viewport using touch-sized controls; a
+stacked layout alone does not prove mobile completion. Review supported color
+modes and reduced motion. Use [reviewing-motion.md](./reviewing-motion.md) for
+behavior whose quality depends on time or interruption.
+
+## Compare the whole path visually
+
+Create a contact sheet or local review page in journey order, with full-size
+captures available. Look for drift that is difficult to notice one page at a time:
+changing content width without a task reason, multiple names for one action,
+inconsistent primary-button hierarchy, unstable selected/error colors, changing
+font character, unrelated empty-state art, or large jumps in density.
+
+Then revisit each transition live. The contact sheet cannot prove preserved
+state, focus destination, completion, or animation quality. Distinguish deliberate
+changes in emphasis from accidental inconsistency; do not flatten every route
+into the same shell to make the sheet look uniform.
+
+## Repair and keep the evidence honest
+
+Fix the smallest shared cause when a defect repeats. Review at least the affected
+routes after changing a shared token or component; a local fix that shifts every
+form is not contained to the screenshot where it was noticed. Preserve the
+selected identity unless the user asks for a new direction.
+
+Retain the journey table, route/state captures, relevant interaction reports or
+recordings, source identity, and unresolved items. Existing `sable grade` review
+records can reference these as screenshot, recording, or report artifacts. Their
+hashes establish identity, not that the journey was correctly exercised. Report
+which path completed, which failures were tested, and which boundaries remain
+simulated or untested. A working isolated journey is evidence of that journey;
+broader product reliability and preference claims need broader evaluation.