diff --git a/.changeset/fingerprint-first-docs.md b/.changeset/fingerprint-first-docs.md
new file mode 100644
index 00000000..e9e95611
--- /dev/null
+++ b/.changeset/fingerprint-first-docs.md
@@ -0,0 +1,5 @@
+---
+"@anarchitecture/ghost": minor
+---
+
+Reframe public docs around Ghost's portable product-experience fingerprint.
diff --git a/README.md b/README.md
index 4e2ec2a0..42170e90 100644
--- a/README.md
+++ b/README.md
@@ -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:
@@ -100,7 +100,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.
```
diff --git a/apps/docs/src/content/docs/cli-reference.mdx b/apps/docs/src/content/docs/cli-reference.mdx
index 7d8f0667..dc772e3e 100644
--- a/apps/docs/src/content/docs/cli-reference.mdx
+++ b/apps/docs/src/content/docs/cli-reference.mdx
@@ -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
-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 command index;
@@ -35,7 +35,7 @@ after command or flag changes.
-
+
### 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/`.
@@ -127,7 +127,7 @@ Print optional `.ghost/fingerprint/memory/intent.md` or a markdown section map.
-### 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
@@ -137,7 +137,7 @@ single-file fingerprint.
-
+
### Deterministic gates - `check`
@@ -147,7 +147,7 @@ per group.
-### 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.
@@ -160,9 +160,10 @@ Pairwise distance or composite analysis over root packages.
-### Intent - `ack` / `track` / `diverge`
+### Drift stance - `ack` / `track` / `diverge`
-Record how the repo should treat tracked fingerprint drift.
+Record how the repo should treat tracked fingerprint drift. These compatibility
+governance verbs still operate on tracked direct fingerprint markdown files.
diff --git a/apps/docs/src/content/docs/getting-started.mdx b/apps/docs/src/content/docs/getting-started.mdx
index e3e44e88..17d9a773 100644
--- a/apps/docs/src/content/docs/getting-started.mdx
+++ b/apps/docs/src/content/docs/getting-started.mdx
@@ -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
-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:
@@ -69,8 +69,9 @@ npx ghost skill install
when you want the complete advanced 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.
@@ -126,10 +127,10 @@ Package comparison uses canonical `.ghost/fingerprint/` packages.
-
+
```text
-Review this PR for design drift
+Review this PR against the Ghost fingerprint
```
`ghost check` applies active deterministic gates from the resolved fingerprint
@@ -159,11 +160,14 @@ optional rationale files. Uncommitted or unmerged edits are drafts; checked-in
-Drift without intent is noise; drift with intent is signal. `ack`, `track`, and
-`diverge` record how the repo should treat tracked fingerprint drift:
+Drift is a governance signal over a fingerprint, not Ghost's center. With
+intent, it becomes a useful signal. `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"
+ghost track new-tracked.fingerprint.md
ghost diverge typography --reason "Editorial product uses a different type scale"
```
diff --git a/docs/cli-consolidation-plan.md b/docs/cli-consolidation-plan.md
index e8c5bc83..f34aabbd 100644
--- a/docs/cli-consolidation-plan.md
+++ b/docs/cli-consolidation-plan.md
@@ -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 # derive static artifacts from fingerprint.md
ghost generate # 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
diff --git a/docs/fingerprint-blueprint.md b/docs/fingerprint-blueprint.md
index 8b37ce9c..33c0b22b 100644
--- a/docs/fingerprint-blueprint.md
+++ b/docs/fingerprint-blueprint.md
@@ -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
diff --git a/docs/fingerprint-format.md b/docs/fingerprint-format.md
index d195f2b6..0821eec4 100644
--- a/docs/fingerprint-format.md
+++ b/docs/fingerprint-format.md
@@ -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/
diff --git a/docs/generation-loop.md b/docs/generation-loop.md
index 567120bb..fb97754c 100644
--- a/docs/generation-loop.md
+++ b/docs/generation-loop.md
@@ -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.
diff --git a/docs/host-adapters.md b/docs/host-adapters.md
index e785805f..c1676739 100644
--- a/docs/host-adapters.md
+++ b/docs/host-adapters.md
@@ -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
diff --git a/docs/ideas/README.md b/docs/ideas/README.md
index efb761db..f349d09f 100644
--- a/docs/ideas/README.md
+++ b/docs/ideas/README.md
@@ -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`).
diff --git a/docs/ideas/fingerprint-first-architecture.md b/docs/ideas/fingerprint-first-architecture.md
new file mode 100644
index 00000000..58b100fd
--- /dev/null
+++ b/docs/ideas/fingerprint-first-architecture.md
@@ -0,0 +1,131 @@
+---
+status: settled
+---
+
+# Fingerprint-first architecture
+
+## Thesis
+
+Ghost is fingerprint-first.
+
+The durable Ghost artifact is the checked-in fingerprint package: a portable
+product-experience contract that humans can approve and agents can act from.
+Everything else in Ghost is tooling for that contract or tooling around it.
+Drift remains important, but it is one governance workflow over the fingerprint,
+not the center of the architecture.
+
+This settles the mental model for follow-on work. Existing docs already describe
+`.ghost/fingerprint/` as the portable package and generation context. Older
+idea docs that center `ghost-drift`, package decomposition, or drift comparison
+should be read through this updated hierarchy: the fingerprint owns product
+memory; tools consume, validate, compare, generate from, or govern that memory.
+
+## Decisions
+
+- The fingerprint package is the durable artifact. `.ghost/fingerprint/`
+ remains the portable boundary, anchored by `fingerprint/manifest.yml`.
+- Core generation input is `prose.yml`, `inventory.yml`, and
+ `composition.yml`. Prose explains what matters and why, inventory points to
+ curated material and exemplars, and composition explains how those materials
+ become experience.
+- Supporting material stays subordinate to the core layers:
+ `enforcement/checks.yml` validates deterministic obligations,
+ `memory/intent.md` and `memory/decisions/` preserve optional human-approved
+ rationale, and `sources/cache/` stores refreshable observations.
+- Tools are consumers or authors of the fingerprint. They may capture,
+ validate, apply, govern, or compare the contract, but they do not replace it.
+- Drift is governance. `check`, `review`, `ack`, `track`, and `diverge` answer
+ whether a change remains faithful to the fingerprint, how intentional
+ divergence is recorded, and how references shift over time.
+- Git remains the approval boundary. Uncommitted or unmerged fingerprint edits
+ are draft work; checked-in fingerprint files are canonical Ghost memory.
+
+## Rationale
+
+Agents need product-experience memory before they generate, not only after a
+diff exists. Post-hoc drift review can catch violations, but it cannot be the
+only way Ghost participates in the work. The highest-leverage artifact is the
+structured input that lets a host agent build, revise, or explain a product
+surface while preserving hierarchy, density, restraint, copy, behavior, trust,
+and flow.
+
+That makes the fingerprint more like an upstream contract than a static
+guideline or a downstream inspection report. Review, linting, comparison,
+generation packets, authoring tools, marketing workflows, and vibe-coding
+workflows can all use the same checked-in product memory. Their outputs differ,
+but their source of truth is the fingerprint.
+
+This also keeps Ghost adapter-neutral. Codex, Claude, Cursor, Goose, CI
+wrappers, docs tools, and design-system integrations can bring their own
+display, policy, and execution format. Ghost owns the portable memory, stable
+packets, deterministic validation, and stack resolution.
+
+## Lifecycle taxonomy
+
+Future docs, CLI help, skills, and examples should organize Ghost around the
+fingerprint lifecycle:
+
+| Lifecycle | Commands and consumers | Purpose |
+| --- | --- | --- |
+| Capture | `init`, `inventory`, `scan` | Create the package, gather optional source material, and report layer readiness. |
+| Validate | `lint`, `verify` | Check schema shape, refs, evidence, exemplars, and deterministic package quality. |
+| Generate / apply | `emit context-bundle`, host agents, future generation consumers | Give agents the upstream product-experience contract before they build or revise. |
+| Govern | `check`, `review`, `ack`, `track`, `diverge` | Validate changed surfaces, produce advisory findings, and record stance toward divergence. |
+| Compare | `compare`, fleet-style analysis | Understand distance, cohorts, reference relationships, and change across packages. |
+
+The taxonomy is conceptual. This memo does not rename commands, change schemas,
+or create public API guarantees. It gives follow-on work a shared hierarchy.
+
+## Consequences
+
+- Positioning should lead with the portable product-experience fingerprint, not
+ drift detection. A good default sentence is: Ghost captures a portable
+ product-experience fingerprint that tools use to generate, validate, compare,
+ and govern product surfaces.
+- Docs IA should make the lifecycle visible. Drift/review docs remain useful,
+ but they should live under governance rather than define the product.
+- CLI help should group commands by fingerprint lifecycle where practical.
+ Existing commands can stay stable while descriptions and ordering teach the
+ new mental model.
+- Skill references should lead with recall, briefing, and generation from
+ fingerprint layers before review, verification, and remediation workflows.
+- Schema exploration may investigate richer fingerprint concepts such as
+ signature moves, memorable product gestures, and executable or buildable
+ inventory evidence. Those ideas are follow-on design work, not new schema in
+ this memo.
+- Dogfooding should update Ghost's own fingerprint and examples to express this
+ identity. The repo should be able to describe itself as fingerprint-first
+ before it asks other repos to do the same.
+
+## Follow-on tracks
+
+1. Positioning and docs language: update README, package README, and core docs
+ so new adopters meet Ghost as a fingerprint system.
+2. Docs information architecture: organize docs pages around capture, validate,
+ generate/apply, govern, and compare.
+3. CLI taxonomy: review command help, docs-generated CLI reference, and command
+ ordering for lifecycle clarity without changing behavior.
+4. Skill workflow: revise the installed Ghost skill bundle so agents brief and
+ generate from fingerprints before reviewing drift.
+5. Schema and model exploration: write separate design notes for signature
+ moves and buildable inventory evidence before any schema change.
+6. Dogfood fingerprint: update `.ghost/fingerprint/` for this repo and validate
+ it with `ghost scan`, `ghost lint`, and `ghost verify`.
+
+## Interface stance
+
+This memo implements no public CLI, schema, package, export, or wire-format
+change. Any future interface change should be proposed in its own plan and
+linked back to this memo as rationale.
+
+## Read-back checks
+
+The memo is successful if:
+
+- A new adopter can understand Ghost without assuming it is primarily a drift
+ tool.
+- A contributor can see why drift commands still matter.
+- A follow-on agent can split docs, CLI, skill, schema, and dogfood work without
+ asking what the architectural center is.
+- Nothing here contradicts the current canonical package shape under
+ `.ghost/fingerprint/`.
diff --git a/docs/ideas/ghost-drift.md b/docs/ideas/ghost-drift.md
index 36595131..8f1bdc52 100644
--- a/docs/ideas/ghost-drift.md
+++ b/docs/ideas/ghost-drift.md
@@ -4,9 +4,18 @@ status: exploring
# ghost drift
+> Fingerprint-first context: this note explores drift as a governance workflow
+> over the fingerprint. The durable Ghost artifact is still the portable
+> `.ghost/fingerprint/` package; drift consumes that contract under change.
+
## Why it's interesting
-Drift is where Ghost earns its keep. Authoring fingerprints is upstream work; comparing them under change is what ships. Drift is also the most CI-relevant tool — its dependency surface needs to stay lean (no map, no fingerprint authoring, no fleet) so a CI job can install just `ghost-drift` and get to a verdict fast.
+Drift is where the fingerprint gets governed under change. Authoring
+fingerprints is upstream work; comparing them under change is one way the
+contract keeps shipping surfaces honest. Drift is also the most CI-relevant
+tool — its dependency surface needs to stay lean (no map, no fingerprint
+authoring, no fleet) so a CI job can install just `ghost-drift` and get to a
+verdict fast.
The user's emphasis on **remediation** and **targeting** sharpens the scope. Targeting is `track` — one repo declares another's fingerprint as its reference, and drift becomes "are we drifting from the system we said we follow?" Remediation is the next loop after review: given that drift exists, what's the minimal change that closes the gap?
@@ -106,7 +115,7 @@ After studying the existing implementation, here's what the audit confirmed and
## Out of scope
- Authoring fingerprints (that's fingerprint).
-- World model across many repos (that's fleet).
+- Fleet-level shape across many repos (that's fleet).
- LLM in CLI.
- Auto-update on drift; drift surfaces signals and humans/agents act on them.
- Hardcoded thresholds — drift reports distance; the consumer picks a threshold.
diff --git a/docs/ideas/ghost-fleet.md b/docs/ideas/ghost-fleet.md
index 0a94e7df..02628ba4 100644
--- a/docs/ideas/ghost-fleet.md
+++ b/docs/ideas/ghost-fleet.md
@@ -4,11 +4,20 @@ status: exploring
# ghost fleet
+> Fingerprint-first context: fleet is a comparison and elevation view over many
+> fingerprints. It does not replace the repo-local fingerprint contract each
+> member owns.
+
## Why it's interesting
Per-repo views answer "is *this* repo drifting?" Fleet answers "what does our design world look like?" The existing `~/Development/ghost-fleet` repo proves the value — 50+ Block frontends, distance matrices, cluster reports — but it's a Block-internal orchestration layer with hardcoded targets and bespoke scripts. The decomposition turns that into a generalized verb anyone can run over their own collection.
-The unlock is **two orthogonal axes**: design language (fingerprint) and implementation (map). Drift compare is single-axis (fingerprint). Fleet groups by map — "how do all the SwiftUI repos cluster in fingerprint-space?" "what does the design world look like for shadcn-based registries vs not?" — and that orthogonality is what makes a *world model* rather than a bigger compare.
+The unlock is **two orthogonal axes**: design language (fingerprint) and
+implementation (map). Drift compare is single-axis (fingerprint). Fleet groups
+by map — "how do all the SwiftUI repos cluster in fingerprint-space?" "what
+does the design world look like for shadcn-based registries vs not?" — and that
+orthogonality makes fleet a higher-level shape view rather than a bigger
+compare.
## What it is — and is not
@@ -23,7 +32,7 @@ A read-only **elevation view** over a directory of (map.md, fingerprint.md) memb
| Layer | What it does | Where it lives |
|---|---|---|
-| `ghost fleet` (skill) | LLM-driven recipe: synthesize the world-model narrative for fleet.md | `packages/ghost-fleet/src/skill-bundle/` |
+| `ghost fleet` (skill) | LLM-driven recipe: synthesize the fleet-shape narrative for fleet.md | `packages/ghost-fleet/src/skill-bundle/` |
| `ghost fleet view` (CLI) | Deterministic composite, group-by, tracks-graph, output artifacts | CLI |
The math is deterministic — composite distances, clustering, group-by. The narrative ("Cash family clusters tight; Tidal pulls away on warmth and density; Afterpay sits in its own region") is judgement and lives in the skill. Same split as map/fingerprint.
diff --git a/docs/ideas/ghost-map.md b/docs/ideas/ghost-map.md
index 977c93b6..4d7a5d7b 100644
--- a/docs/ideas/ghost-map.md
+++ b/docs/ideas/ghost-map.md
@@ -4,11 +4,15 @@ status: exploring
# ghost map
+> Fingerprint-first context: map is optional topology/source-material support.
+> It helps agents find the right product surfaces, but the fingerprint remains
+> the portable product-experience contract.
+
## Why it's interesting
The cash-android profile pass is a forcing function. ~1,580 Gradle modules. No agent can discover topology from scratch in that repo — the existing fleet works around it with hand-authored YAML manifests at `ghost-fleet/manifests/cash-android.yaml` (27 feature areas, convention plugin IDs, include/exclude globs). Those manifests are accurate and load-bearing, but they're hardcoded — every new repo means a human pre-curates the navigation map before the profile recipe runs.
-`ghost map` is the verb that generates that map automatically and writes it to disk as `map.md`. Scan and fleet workflows read map.md as their topology cache, so they do not re-derive "where does the design system live" or "which folders are customer UI." Generation and drift use `fingerprint.md` as their action root. The map becomes the narrow waist between any frontend repo (irrespective of language or stack) and the rest of Ghost.
+`ghost map` is the verb that generates that map automatically and writes it to disk as `map.md`. Scan and fleet workflows read map.md as their topology cache, so they do not re-derive "where does the design system live" or "which folders are customer UI." Generation and governance workflows use the fingerprint as their action root. The map becomes the narrow waist between any frontend repo (irrespective of language or stack) and the rest of Ghost.
This is one of five decentralized tools (`map`, `fingerprint`, `drift`, `fleet`, `ui`). Map is upstream of the other four.
diff --git a/docs/ideas/ghost-scan.md b/docs/ideas/ghost-scan.md
index d15df70d..d986df31 100644
--- a/docs/ideas/ghost-scan.md
+++ b/docs/ideas/ghost-scan.md
@@ -7,7 +7,9 @@ status: exploring
> Historical design note: the separate `packages/ghost-scan` package described
> here was removed. The public Ghost CLI and current fingerprint capture
> workflow live in `packages/ghost` and canonical `.ghost/fingerprint/`
-> memory.
+> memory. Read this through the fingerprint-first architecture: the artifact is
+> the portable package, while scan/fingerprint verbs are authoring and
+> validation tools around it.
## Why it's interesting
diff --git a/docs/ideas/ghost-ui.md b/docs/ideas/ghost-ui.md
index 39877511..585e5d25 100644
--- a/docs/ideas/ghost-ui.md
+++ b/docs/ideas/ghost-ui.md
@@ -4,6 +4,10 @@ status: exploring
# ghost ui
+> Fingerprint-first context: ghost-ui is reference inventory and evidence for
+> fingerprints. It can improve generation and governance, but it is not the
+> portable product-experience contract itself.
+
## Why it's interesting
ghost-ui is the canonical witness. The other four tools must remain stack-agnostic — they need to work on Cash iOS (Bazel, SwiftUI), Cash Android (Gradle, Compose), and arbitrary one-off web repos. ghost-ui's job is the opposite: lean *all the way in* on the convention, and prove the loop end-to-end. When the system works perfectly somewhere, it should work here.
diff --git a/docs/ideas/guided-migration.md b/docs/ideas/guided-migration.md
index cbaf9643..f5e45384 100644
--- a/docs/ideas/guided-migration.md
+++ b/docs/ideas/guided-migration.md
@@ -4,6 +4,10 @@ status: exploring
# Guided migration: drifting a fingerprint toward another
+> Fingerprint-first context: migration treats distance as a governance signal
+> between two fingerprints. The migration target is another approved contract,
+> not drift for its own sake.
+
An agentic loop where repo A consciously migrates toward repo B's visual direction, driven by fingerprint distance + vector as the signal.
## The observation
diff --git a/docs/ideas/phase-0-decisions.md b/docs/ideas/phase-0-decisions.md
index 4be55a96..4365ecd2 100644
--- a/docs/ideas/phase-0-decisions.md
+++ b/docs/ideas/phase-0-decisions.md
@@ -6,7 +6,9 @@ status: settled
> Historical design note: this decomposition plan predates the unified
> `@anarchitecture/ghost` package. The separate `ghost-scan` package mentioned
-> below was removed; current runtime code lives in `packages/ghost`.
+> below was removed; current runtime code lives in `packages/ghost`. Treat the
+> package split vocabulary below as historical and subordinate to the
+> fingerprint-first architecture memo.
Decisions that unblock the five-tool decomposition. Captured here so worktree agents reference one canonical source rather than scrolling open questions across five plan files.
diff --git a/packages/ghost/README.md b/packages/ghost/README.md
index 6563369e..9f990cce 100644
--- a/packages/ghost/README.md
+++ b/packages/ghost/README.md
@@ -1,10 +1,12 @@
# @anarchitecture/ghost
-**Unified Ghost CLI for repo-local product-experience world models.**
+**Unified Ghost CLI for portable product-experience fingerprints.**
-Ghost initializes root `.ghost/fingerprint/` memory, checks diffs against
-deterministic gates, emits advisory review packets, compares packages, and
-records intentional drift. It ships one CLI: `ghost`.
+Ghost captures a portable product-experience fingerprint that tools use to
+generate, validate, compare, and govern product surfaces. It initializes root
+`.ghost/fingerprint/` packages, validates deterministic gates, emits handoff
+and review packets, compares packages, and records intentional divergence. It
+ships one CLI: `ghost`.
## Project Status: Beta
@@ -67,8 +69,9 @@ import { compareFingerprints } from "@anarchitecture/ghost/core";
Ghost is bring-your-own-agent. The CLI performs deterministic work: inventory,
lint, verify, compare, check, and handoff packet generation. The installed
`ghost` skill teaches your host agent how to capture canonical
-`.ghost/fingerprint/` memory, brief work from it, review drift, verify
-generated UI, remediate issues, and suggest memory edits when the user asks.
+`.ghost/fingerprint/` memory, brief and generate work from it, review changes
+against it, verify generated UI, remediate issues, and suggest memory edits
+when the user asks.
```bash
ghost skill install
@@ -77,7 +80,7 @@ ghost skill install
Then ask your agent:
```text
-Set up Ghost memory for this repo.
+Set up the Ghost fingerprint for this repo.
```
## Maintainers