block · nahiyankhan · May 19, 2026 · May 19, 2026
@@ -0,0 +1,5 @@
+---
+"@anarchitecture/ghost": patch
+---
+
+Reframe the installed skill and docs around agent-led Ghost Fingerprint Capture.
@@ -0,0 +1,5 @@
+---
+"@anarchitecture/ghost": minor
+---
+
+Report scan evidence readiness so agents can distinguish product-observed, component-demo, substrate-only, and unobservable Ghost bundles.
@@ -1,6 +1,6 @@
 # Ghost
 
-**Ghost gives agents repo-local design memory for product experience.**
+**Ghost captures a repo-local product fingerprint for agents.**
 
 Agents can write UI. What they cannot reliably preserve is the thought behind
 the product experience they are changing: hierarchy, density, restraint,
@@ -17,7 +17,7 @@ The bundle is evidence-first:
 - **`.ghost/checks.yml`** optionally stores human-promoted deterministic gates.
 - **`.ghost/intent.md`** optionally records human-authored or human-approved product intent.
 - **`.ghost/decisions/*.yml`** optionally records accepted/rejected product-experience rationale.
-- **`.ghost/proposals/*.yml`** optionally stages candidate memory changes before promotion.
+- **`.ghost/proposals/*.yml`** optionally stages candidate fingerprint updates before promotion.
 
 ## Install
 
@@ -40,64 +40,68 @@ npx ghost skill install --dest ~/.codex/skills/ghost
 After that, ask your agent in plain English:
 
 ```text
-Scan this project with Ghost.
+Capture a Ghost fingerprint for this repo.
 Review this PR for Ghost drift.
 Compare these two Ghost bundles.
-Brief this work from Ghost memory.
+Brief this work from the Ghost fingerprint.
 ```
 
-## Core Workflow
+## Fingerprint Capture
+
+Fingerprint Capture is a BYOA workflow. Your agent reads, interprets, and writes
+the fingerprint artifacts; the CLI supplies deterministic status, validation,
+derivation, and review helpers.
+
+Ask your agent:
+
+```text
+Capture a Ghost fingerprint for this repo.
+```
+
+During capture, the agent checkpoints with commands like:
 
 ```bash
-# 0. Create the bundle skeleton
 ghost init --with-intent
-
-# 1. Ask your agent to map the repo, then validate
+ghost scan --format json
 ghost inventory
 ghost lint .ghost
-
-# 2. Ask your agent to survey values and composition evidence
 ghost survey fix-ids .ghost/survey.json -o .ghost/survey.json
-ghost lint .ghost
-
-# 3. Derive patterns and verify evidence
 ghost survey patterns .ghost/survey.json -o .ghost/patterns.yml
 ghost verify .ghost --root .
 ghost lint .ghost
+```
+
+## Drift Workflow
 
-# 4. Check or review changes
+```bash
 ghost check --base main
 ghost review --base main --include-memory
-
-# 5. Compare fingerprints or bundles
 ghost compare market/.ghost dashboard/.ghost
 ghost compare a.md b.md --semantic
 ghost compare before.md after.md --temporal
 ghost compare */.ghost
-
-# 6. Record intentional drift
 ghost ack --stance aligned --reason "Initial baseline"
 ghost track new-tracked.fingerprint.md
 ghost diverge typography --reason "Editorial product uses a different type scale"
-
-# 7. Emit derived context
 ghost emit review-command
 ghost emit context-bundle
 ```
 
-`ghost scan --format json` emits deterministic BYOA state: which artifacts are
-present, which stage is next, and enough structure for the host agent to choose
-the next recipe. It does not call an LLM.
+`ghost scan --format json` emits deterministic Fingerprint Capture state: which
+artifacts are present, which stage is next, and evidence readiness. Readiness
+distinguishes a product-observed bundle from component-demo, substrate-only, or
+unobservable evidence, so agents know when tokens/components are available but
+product composition has not been earned yet. It does not call an LLM.
 
 ## CLI Commands
 
 | Command | Description |
 | --- | --- |
 | `ghost init` | Create `.ghost/{resources.yml,map.md,survey.json,patterns.yml,checks.yml}`. |
-| `ghost scan` | Report scan state and emit the next BYOA handoff. |
+| `ghost scan` | Report fingerprint capture progress and emit the next BYOA handoff. |
 | `ghost inventory` | Emit raw repo signals as JSON for map authoring. |
 | `ghost lint` | Validate a bundle or individual artifact. |
-| `ghost verify` | Validate resource reachability, pattern evidence, checks, and optional memory. |
+| `ghost verify` | Validate resource reachability, pattern evidence, checks, and optional decisions/proposals. |
 | `ghost describe` | Print optional `intent.md` or direct markdown section ranges + token estimates. |
 | `ghost diff` | Structural prose-level diff between direct fingerprints. |
 | `ghost survey <op>` | Operate on `ghost.survey/v2` files: `merge`, `fix-ids`, `summarize`, `catalog`, `patterns`. |
@@ -117,7 +121,7 @@ workspace packages remain only for historical/development context.
 
 | Path | Role | Published? |
 | ---- | ---- | --- |
-| [`packages/ghost`](./packages/ghost) | Unified public package. Ships the `ghost` CLI, scan/memory authoring, deterministic checks, advisory review packets, comparison, stance tracking, and the unified skill bundle. | yes: `@anarchitecture/ghost` |
+| [`packages/ghost`](./packages/ghost) | Unified public package. Ships the `ghost` CLI, fingerprint capture helpers, deterministic checks, advisory review packets, comparison, stance tracking, and the unified skill bundle. | yes: `@anarchitecture/ghost` |
 | [`packages/ghost-core`](./packages/ghost-core) | Private historical shared library. Runtime code is folded into `packages/ghost` for publishing. | no |
 | [`packages/ghost-scan`](./packages/ghost-scan) | Private historical scan package. Runtime code is folded into `packages/ghost` for publishing. | no |
 | [`packages/ghost-fleet`](./packages/ghost-fleet) | Private fleet view across many members. | no |

@@ -9,11 +9,12 @@ slug: cli
 
 <DocSection title="Overview">
 
-The CLI does the repeatable parts: initialize bundles, validate files, transform
-survey data, compare bundles, check diffs, emit handoff packets, and record
-intent. Your agent does the reading, writing, and reviewing.
+The CLI does the repeatable parts: initialize bundles, report Fingerprint
+Capture progress, validate files, transform survey data, compare bundles, check
+diffs, emit handoff packets, and record intent. Your agent does the reading,
+writing, and reviewing.
 
-A scan follows one path:
+Fingerprint Capture follows one path:
 
 ```text
 resources.yml -> map.md -> survey.json -> patterns.yml
@@ -26,15 +27,21 @@ npm install -D @anarchitecture/ghost
 npx ghost skill install
 ```
 
+Ask your agent to run the workflow:
+
+```text
+Capture a Ghost fingerprint for this repo.
+```
+
 Commands are grouped by job:
 
 - **Create and check the fingerprint bundle**: `init`, `scan`, `inventory`, `lint`, `verify`, `describe`, `diff`, `survey <op>`, `emit`.
 - **Review and compare drift**: `check`, `review`, `compare`, `ack`, `track`, `diverge`.
 - **Install BYOA recipes**: `skill install`.
 - **View many projects**: `ghost-fleet members`, `ghost-fleet view`, `ghost-fleet emit skill`.
 
-Workflows like _scan_, _map_, _survey_, _patterns_, _recall_, _brief_,
-_critique_, _capture_, _promote_, _review_, _verify_, _compare_, and
+Workflows like _capture_, _map_, _survey_, _patterns_, _recall_, _brief_,
+_critique_, _propose_, _promote_, _review_, _verify_, _compare_, and
 _remediate_ are skill recipes your host agent runs. They are installed by
 `ghost skill install`; they are not LLM-running CLI verbs.
 
@@ -44,11 +51,12 @@ reference.
 
 </DocSection>
 
-<DocSection title="ghost - scan and bundle">
+<DocSection title="ghost - capture support and bundle checks">
 
-`ghost` owns the root bundle scan. It inventories the repo, validates each file,
-verifies cross-artifact fidelity, describes markdown, diffs direct fingerprint
-files, runs survey ops, and emits agent-ready outputs.
+`ghost` supports Fingerprint Capture. It inventories the repo, reports capture
+progress, validates each file, verifies cross-artifact fidelity, describes
+markdown, diffs direct fingerprint files, runs survey ops, and emits
+agent-ready outputs.
 
 ### Initialize - `init`
 
@@ -62,10 +70,11 @@ ghost init
 ghost init --with-intent
 ```
 
-### Pipeline progress - `scan`
+### Capture progress - `scan`
 
-Report which scan stages already exist in a directory and which stage the
-agent should run next. `--format json` is the deterministic BYOA handoff.
+Report which fingerprint capture stages already exist in a directory, evidence
+readiness, and which stage the agent should run next. `--format json` is the
+deterministic BYOA handoff.
 
 <CliHelp tool="ghost" command="scan" hideDescription />
 
@@ -195,8 +204,8 @@ ghost check --diff patch.diff --format json
 ### Advisory packet - `review`
 
 Emit an evidence-routed advisory review packet grounded in `.ghost/patterns.yml`,
-`.ghost/survey.json`, optional `.ghost/intent.md`, optional memory, checks, and
-the diff.
+`.ghost/survey.json`, optional `.ghost/intent.md`, accepted decisions, checks,
+and the diff.
 
 <CliHelp tool="ghost" command="review" hideDescription />
 
@@ -248,9 +257,9 @@ ghost diverge palette --reason "Dark-mode-first palette for this product"
 
 ### Skill bundle - `skill install`
 
-Install the unified `ghost` skill bundle into a host agent. It contains scan,
-map, survey, patterns, schema, recall, brief, critique, capture, promote,
-review, verify, compare, and remediate recipes.
+Install the unified `ghost` skill bundle into a host agent. It contains
+Fingerprint Capture, map, survey, patterns, schema, recall, brief, critique,
+propose, promote, review, verify, compare, and remediate recipes.
 
 <CliHelp tool="ghost" command="skill" hideDescription />
 
@@ -297,11 +306,11 @@ then ask your agent in plain English.
 
 | Recipe | Bundle | Trigger |
 | --- | --- | --- |
-| `scan` | `ghost` | "scan this project" / "go end-to-end" |
+| `capture` | `ghost` | "Capture a Ghost fingerprint for this repo" |
 | `map` | `ghost` | "map this repo" / "write map.md" |
 | `survey` | `ghost` | "survey design values" / "extract tokens" |
 | `patterns` | `ghost` | "write patterns.yml" / "codify composition patterns" |
-| `recall` / `brief` / `critique` / `capture` / `promote` | `ghost` | "what does Ghost remember?" / "brief this work" / "capture this decision" |
+| `recall` / `brief` / `critique` / `propose` / `promote` | `ghost` | "brief this work" / "propose this decision" / "promote this proposal" |
 | `review` | `ghost` | "review this PR for drift" |
 | `verify` | `ghost` | "verify generated UI against the bundle" |
 | `compare` | `ghost` | "why did these two fingerprints drift?" |

@@ -1,6 +1,6 @@
 ---
 title: Getting Started
-description: Install Ghost, scan a repo, and review generated UI against a root fingerprint bundle.
+description: Install Ghost, capture a repo fingerprint, and review generated UI against it.
 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 memory in the repo, where your agent
-can use it. The public package is `@anarchitecture/ghost`, and it installs one
-CLI: `ghost`.
+Ghost captures a project's product identity in the repo, where your agent can
+use it. The public package is `@anarchitecture/ghost`, and it installs one CLI:
+`ghost`.
 
 The fingerprint is the root `.ghost/` bundle:
 
@@ -22,7 +22,7 @@ what to read     where UI lives  what exists   composition grammar
 
 `checks.yml` is optional deterministic enforcement. `intent.md`,
 `decisions/*.yml`, and `proposals/*.yml` are optional human-approved or
-human-staged product-experience memory.
+human-staged context around the fingerprint.
 
 | Surface | Job | Verbs |
 | --- | --- | --- |
@@ -40,19 +40,19 @@ npx ghost --help
 npx ghost skill install
 ```
 
-Once the skill is installed, ask your agent in plain English: "scan this
-project with Ghost" or "review this PR for drift". The recipe tells the agent
-what to read, what to write, and which CLI checks to run.
+Once the skill is installed, ask your agent in plain English: "Capture a 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.
 
 </DocSection>
 
-<DocSection title="Scan Your First System">
+<DocSection title="Capture Your First Fingerprint">
 
 ```text
-Scan this project with Ghost
+Capture a Ghost fingerprint for this repo.
 ```
 
-The `scan` recipe checkpoints between stages:
+Fingerprint Capture checkpoints between stages:
 
 1. **Resources (`resources.yml`)** - declare the primary target, design-system
    references, canonical surfaces, screenshots, docs, resolvers, and path
@@ -105,18 +105,18 @@ advisory packet.
 
 </DocSection>
 
-<DocSection title="Capture Product-Experience Memory">
+<DocSection title="Propose Fingerprint Updates">
 
 Use the installed `ghost` skill when work reveals a decision Ghost should
-remember:
+consider adding to the fingerprint:
 
 ```text
-Brief this work with Ghost memory
-Capture this product-experience decision as a proposal
+Brief this work from the Ghost fingerprint
+Propose this product-experience decision as a fingerprint update
 Promote this accepted proposal
 ```
 
-The recipes write proposals first. Humans promote durable memory into accepted
+The recipes write proposals first. Humans promote durable context into accepted
 decisions, `patterns.yml`, `checks.yml`, or `intent.md`.
 
 </DocSection>

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-05-18T18:58:16.311Z",
+  "generatedAt": "2026-05-19T14:36:11.941Z",
   "tools": [
     {
       "tool": "ghost",
@@ -72,7 +72,7 @@
           "tool": "ghost",
           "name": "scan",
           "rawName": "scan [dir]",
-          "description": "Report which root fingerprint bundle stages have produced artifacts: resources.yml, map.md, survey.json, patterns.yml, and optional checks.yml/intent.md.",
+          "description": "Report fingerprint capture progress: produced artifacts, evidence readiness, and the next BYOA step.",
           "options": [
             {
               "rawName": "--include-scopes",

@@ -12,14 +12,15 @@ not a single prose file. The canonical on-disk shape is:
   checks.yml
   intent.md        # optional
   decisions/       # optional ghost.decision/v1 product-experience rationale
-  proposals/       # optional ghost.proposal/v1 candidate memory changes
+  proposals/       # optional ghost.proposal/v1 candidate fingerprint updates
 ```
 
 `survey.json` is the evidence ledger. `patterns.yml` is the operational
 composition grammar. `checks.yml` is the deterministic gate layer. `intent.md`
 is optional human-authored or human-approved intent. `decisions/` and
-`proposals/` are optional product-experience memory: accepted/rejected rationale
-and candidate changes that may later be promoted.
+`proposals/` are optional product-experience context: accepted/rejected
+rationale and candidate changes that may later be promoted into the
+fingerprint.
 
 ## Package Artifacts
 
@@ -150,8 +151,9 @@ decided_at: "2026-05-17T00:00:00.000Z"
 
 ### `proposals/*.yml`
 
-Candidate memory changes use `ghost.proposal/v1`. They are working memory until
-a human promotes them into decisions, patterns, checks, or intent.
+Candidate fingerprint updates use `ghost.proposal/v1`. They remain unresolved
+proposals until a human promotes them into decisions, patterns, checks, or
+intent.
 
 ```yaml
 schema: ghost.proposal/v1