block · nahiyankhan · Jun 5, 2026
@@ -0,0 +1,5 @@
+---
+"@anarchitecture/ghost": minor
+---
+
+Reframe public docs around Ghost's portable product-experience fingerprint.
@@ -1,13 +1,13 @@
 # Ghost
 
-**Ghost is a product-experience world model for AI agents.**
+**Ghost captures a portable product-experience fingerprint for AI agents.**
 
-Agents can write UI. What they cannot reliably preserve is the
-product-experience world that UI belongs to: hierarchy, density, restraint,
-behavior, copy, accessibility, trust, and flow. Traditional design systems give
-humans parts, rules, and examples. Ghost stores the upstream product judgment
-agents need around those parts in a versioned `.ghost/` bundle they can read
-before generation and validate after changes.
+Agents can write UI. What they cannot reliably preserve is the product
+experience that UI belongs to: hierarchy, density, restraint, behavior, copy,
+accessibility, trust, and flow. Traditional design systems give humans parts,
+rules, and examples. Ghost stores the upstream product judgment agents need
+around those parts in a versioned `.ghost/` bundle they can read before
+generation and validate after changes.
 
 The MVP rule is intentionally small:
 
@@ -35,10 +35,10 @@ Add only the sections that contain real layer content. Ghost normalizes omitted
 layer files or sections internally, so agents and checks still receive the full
 assembled `ghost.fingerprint/v1` shape they expect.
 
-Ghost is not a design-system generator, design-system registry, fingerprint lifecycle
-manager, proposal system, or screenshot archive. It is a small repo-local
-contract agents can read before work and deterministic tooling can validate
-after work.
+Ghost captures a portable product-experience fingerprint that tools use to
+generate, validate, compare, and govern product surfaces. It is not a
+design-system generator, design-system registry, fingerprint lifecycle manager,
+proposal system, or screenshot archive.
 
 Optional material can sit beside the core files:
 
@@ -88,7 +88,7 @@ Then ask your agent in plain English:
 ```text
 Set up the Ghost fingerprint for this repo.
 Brief this work from the Ghost fingerprint.
-Review this PR for Ghost drift.
+Review this PR against the Ghost fingerprint.
 Compare these two Ghost bundles.
 ```
 

@@ -1,6 +1,6 @@
 ---
 title: CLI Reference
-description: Commands for repeatable checks and comparison. Your agent handles the judgment work.
+description: Commands around the portable fingerprint lifecycle. Your agent handles the judgment work.
 kicker: Docs
 section: guide
 order: 30
@@ -9,10 +9,10 @@ slug: cli
 
 <DocSection title="Overview">
 
-The CLI does the repeatable parts: initialize fingerprint packages, report
-fingerprint readiness, validate files, emit raw inventory, compare packages,
-check diffs, emit handoff packets, and record intent. Your agent does the
-reading, writing, and reviewing.
+The CLI does the repeatable parts around the fingerprint lifecycle: capture
+packages, report readiness, validate files, gather optional source material,
+emit handoff packets, govern diffs, compare packages, and record intent. Your
+agent does the reading, writing, and reviewing.
 
 `ghost --help` intentionally shows the short core workflow for new adopters.
 Run `ghost --help --all` for the complete advanced and legacy command index;
@@ -35,7 +35,7 @@ after command or flag changes.
 
 </DocSection>
 
-<DocSection title="ghost - fingerprint layers and package checks">
+<DocSection title="ghost - capture, validate, and generate">
 
 ### Initialize - `init`
 
@@ -77,7 +77,7 @@ Inspect the root-to-leaf fingerprint stack for one or more paths.
 ghost stack apps/checkout/review/page.tsx --format json
 ```
 
-### Generated cache - `inventory`
+### Capture source material - `inventory`
 
 Emit raw signals about a frontend repo as JSON. Use this as optional source
 material under `.ghost/fingerprint/sources/cache/`.
@@ -128,7 +128,7 @@ direct fingerprint markdown file.
 
 <CliHelp tool="ghost" command="describe" hideDescription />
 
-### Derived outputs - `emit`
+### Generate handoff packets - `emit`
 
 Emit `review-command` or the `context-bundle` generation packet from split
 fingerprint layers. Context bundles emit split files, not an assembled
@@ -138,7 +138,7 @@ fingerprint layers. Context bundles emit split files, not an assembled
 
 </DocSection>
 
-<DocSection title="ghost - review and compare">
+<DocSection title="ghost - govern and compare">
 
 ### Deterministic gates - `check`
 
@@ -148,7 +148,7 @@ per group.
 
 <CliHelp tool="ghost" command="check" hideDescription />
 
-### Advisory packet - `review`
+### Advisory governance packet - `review`
 
 Emit an evidence-routed advisory review packet grounded in split fingerprint
 layers, optional memory, checks, and the diff.
@@ -162,9 +162,9 @@ fingerprint markdown.
 
 <CliHelp tool="ghost" command="compare" hideDescription />
 
-### Intent - `ack` / `track` / `diverge`
+### Drift stance - `ack` / `track` / `diverge`
 
-Compatibility verbs for tracked direct fingerprint markdown files.
+Compatibility governance verbs for tracked direct fingerprint markdown files.
 
 <CliHelp tool="ghost" command="ack" hideDescription />
 <CliHelp tool="ghost" command="track" hideDescription />

@@ -1,6 +1,6 @@
 ---
 title: Getting Started
-description: Install Ghost, author a repo-local product-experience world model, and review generated UI against it.
+description: Install Ghost, author a portable product-experience fingerprint, and use it to generate, validate, compare, and govern product surfaces.
 kicker: Docs
 section: guide
 order: 10
@@ -9,9 +9,9 @@ slug: getting-started
 
 <DocSection title="The Simple Model">
 
-Ghost keeps a project's product-experience world model in the repo, where your
-agent can use it. The public package is `@anarchitecture/ghost`, and it installs
-one CLI: `ghost`.
+Ghost keeps a project's portable product-experience fingerprint in the repo,
+where your agent can use it. The public package is `@anarchitecture/ghost`,
+and it installs one CLI: `ghost`.
 
 The canonical portable fingerprint is a folder:
 
@@ -52,8 +52,9 @@ npx ghost skill install
 when you want the complete advanced and legacy command index.
 
 Once the skill is installed, ask your agent in plain English: "Set up the Ghost
-fingerprint for this repo" or "review this PR for drift". The recipe tells the
-agent what to read, what to write, and which CLI checks to run.
+fingerprint for this repo" or "review this PR against the Ghost fingerprint".
+The recipe tells the agent what to read, what to write, and which CLI checks to
+run.
 
 </DocSection>
 
@@ -115,10 +116,10 @@ ghost compare a.fingerprint.md b.fingerprint.md --semantic
 
 </DocSection>
 
-<DocSection title="Review Drift in a PR">
+<DocSection title="Govern Changes in a PR">
 
 ```text
-Review this PR for design drift
+Review this PR against the Ghost fingerprint
 ```
 
 `ghost check` applies active deterministic gates from the resolved fingerprint
@@ -148,9 +149,9 @@ optional rationale files. Uncommitted or unmerged edits are drafts; checked-in
 
 <DocSection title="Track Intent Toward Legacy Direct Markdown">
 
-Drift without intent is noise; drift with intent is signal. `ack`, `track`, and
-`diverge` still operate on tracked direct fingerprint markdown files for
-compatibility with older workflows:
+Drift is a governance signal over a fingerprint, not Ghost's center. `ack`,
+`track`, and `diverge` still operate on tracked direct fingerprint markdown
+files for compatibility with older workflows:
 
 ```bash
 ghost ack --stance aligned --reason "Initial baseline"

@@ -13,7 +13,9 @@ branch: refactor/fingerprint (or a follow-up branch)
 > plus the private `ghost-fleet` CLI. Capture, map, survey, patterns, recall,
 > brief, critique, review, verify, compare, and remediate are host-agent skill
 > recipes installed by `ghost skill install`. Kept for history; don't treat the
-> exploratory verb list below as current. See the
+> exploratory verb list below as current. The current architecture is
+> fingerprint-first: the durable artifact is `.ghost/fingerprint/`, and drift
+> is one governance workflow over it. See the
 > [README](../README.md) and the
 > [CLI reference](../apps/docs/src/content/docs/cli-reference.mdx) for the
 > current surface.
@@ -30,7 +32,7 @@ ghost emit <kind>              # derive static artifacts from fingerprint.md
 ghost generate <prompt>        # LLM-produce UI artifact from fingerprint (unchanged)
 
 # Check
-ghost review [scope]           # unified drift detection
+ghost review [scope]           # governance review against the fingerprint
                                #   scopes: files (default), project, suite
 
 # Compare

@@ -1,7 +1,8 @@
 # Ghost Fingerprint Blueprint
 
-A Ghost fingerprint is checked-in product-experience memory for a repo. It is
-the material a host agent reads before generating UI and the deterministic
+A Ghost fingerprint is checked-in product-experience memory for a repo: a
+portable contract humans can approve and agents can act from. It is the
+material a host agent reads before generating UI and the deterministic
 grounding Ghost uses after changes for lint, verify, check, review, compare,
 and context-bundle flows.
 
@@ -274,7 +275,7 @@ Ghost uses typed refs to connect layers without guessing:
 
 Refs are lowercase slug ids after the colon. Use refs when a situation depends
 on a principle, an exemplar demonstrates a pattern, a check derives from prose,
-or a review finding needs to show why a change drifts.
+or a review finding needs to show why a change departs from the fingerprint.
 
 Layer refs without `check:` are used where only fingerprint layer material is
 valid, such as `inventory.exemplars[].refs`.
@@ -451,7 +452,7 @@ ghost lint .ghost
 ghost verify .ghost --root .
 ```
 
-Use the fingerprint before and after generation:
+Use the fingerprint across the lifecycle:
 
 ```bash
 ghost emit context-bundle

@@ -1,7 +1,8 @@
 # The Portable Fingerprint Package Format
 
-A Ghost fingerprint is the checked-in, repo-local product-experience world
-model. The canonical portable package lives under `.ghost/fingerprint/`:
+A Ghost fingerprint is the checked-in, repo-local product-experience contract
+that humans can approve and agents can act from. The canonical portable package
+lives under `.ghost/fingerprint/`:
 
 ```text
 .ghost/

@@ -1,8 +1,8 @@
-# Product-Experience World Model Loop
+# Fingerprint Generation Loop
 
 Ghost gives UI generators and product-development agents a local, auditable
-product-experience world model. Generation starts from checked-in core layers;
-checks validate the result afterward.
+product-experience fingerprint. Generation starts from checked-in core layers;
+checks and review govern the result afterward.
 
 ```text
 fingerprint/prose.yml + fingerprint/inventory.yml + fingerprint/composition.yml
@@ -46,7 +46,7 @@ Cache answers what exists now and does not count toward scan readiness. Prose
 answers what matters and why. Curated inventory points to building blocks and
 exemplars. Composition explains how those blocks become experience.
 
-## Review
+## Govern
 
 `ghost check` is deterministic:
 
@@ -73,7 +73,8 @@ relevant exemplars when useful, and any active check when blocking.
 
 ## Remediation
 
-When review flags drift, the host agent chooses the smallest useful response:
+When review flags drift from the fingerprint, the host agent chooses the
+smallest useful response:
 
 - Fix the generated or changed code.
 - Explain why a divergence is intentional.

@@ -2,7 +2,8 @@
 
 Ghost is adapter-neutral. It owns the portable fingerprint package,
 deterministic validation, stack resolution, and machine-readable packets. Host
-tools own display, severity mapping, and review/check file formats.
+tools consume that fingerprint contract and own display, severity mapping, and
+review/check file formats.
 
 ## Responsibilities
 
@@ -24,6 +25,8 @@ Ghost provides:
 Host adapters provide:
 
 - repo-specific installation workflows
+- policies for when to capture, validate, generate from, govern, or compare a
+  fingerprint
 - generated review/check files in the host's native format
 - severity mapping from Ghost's `critical | serious | nit`
 - policy for when a finding blocks, comments, or remains advisory

@@ -2,6 +2,11 @@
 
 Loose space for concepts that aren't ready to be docs or a changeset but shouldn't be lost to chat history.
 
+Read older decomposition and drift notes through
+`fingerprint-first-architecture.md`: Ghost's durable artifact is the portable
+fingerprint package, and map, drift, fleet, UI, adapters, and generation
+workflows are tools around that contract.
+
 Conventions:
 
 - One file per idea, kebab-case slug (`guided-migration.md`, not `migration-rewrite.md`).