From 12021ea3739a3fcfccbcedc13acecac04246d249 Mon Sep 17 00:00:00 2001
From: Nahiyan Khan <nahiyan@squareup.com>
Date: Tue, 19 May 2026 11:02:17 -0400
Subject: [PATCH] Refresh docs after unified Ghost updates

---
 apps/docs/src/app/docs/page.tsx               |  2 +-
 apps/docs/src/app/page.tsx                    |  4 +-
 apps/docs/src/app/tools/drift/page.tsx        |  9 +--
 apps/docs/src/app/tools/page.tsx              |  4 +-
 apps/docs/src/app/tools/scan/page.tsx         | 12 ++--
 apps/docs/src/content/docs/cli-reference.mdx  |  3 +-
 docs/cli-consolidation-plan.md                | 13 +++-
 docs/fingerprint-format.md                    |  2 +-
 packages/ghost-scan/README.md                 | 66 ++++++++++++-------
 packages/ghost-ui/README.md                   | 11 +++-
 packages/ghost/README.md                      |  2 +-
 .../src/skill-bundle/references/critique.md   |  2 +-
 .../src/skill-bundle/references/review.md     |  2 +-
 13 files changed, 84 insertions(+), 48 deletions(-)

diff --git a/apps/docs/src/app/docs/page.tsx b/apps/docs/src/app/docs/page.tsx
index 8db0a617..e7ad367e 100644
--- a/apps/docs/src/app/docs/page.tsx
+++ b/apps/docs/src/app/docs/page.tsx
@@ -17,7 +17,7 @@ const sections: {
     name: "Getting Started",
     href: "/docs/getting-started",
     description:
-      "Install Ghost, scan a repo, and learn the loop around .ghost/fingerprint.",
+      "Install Ghost, capture a repo fingerprint, and learn the loop around .ghost.",
     icon: <Rocket className="size-8" strokeWidth={1.5} />,
   },
   {
diff --git a/apps/docs/src/app/page.tsx b/apps/docs/src/app/page.tsx
index 8e0f7bf5..274fc092 100644
--- a/apps/docs/src/app/page.tsx
+++ b/apps/docs/src/app/page.tsx
@@ -64,7 +64,7 @@ export default function Home() {
               disappear into chats, reviews, and one-off prompts.
             </p>
             <p className="thesis-item">
-              Ghost builds this fingerprint package from evidence in the
+              Ghost builds this fingerprint bundle from evidence in the
               codebase:
             </p>
             <ul className="thesis-item list-disc space-y-2 pl-6">
@@ -156,7 +156,7 @@ export default function Home() {
               system's boundary becomes visible where composition fails.
             </p>
             <p className="thesis-item">
-              The fingerprint package must live where generation happens: in the
+              The fingerprint bundle must live where generation happens: in the
               repository, versioned alongside the code it governs, evolving
               through the same pull requests that introduce new UI. As the
               product changes, the package updates with it, maintaining
diff --git a/apps/docs/src/app/tools/drift/page.tsx b/apps/docs/src/app/tools/drift/page.tsx
index 0298a5a7..e9074ebc 100644
--- a/apps/docs/src/app/tools/drift/page.tsx
+++ b/apps/docs/src/app/tools/drift/page.tsx
@@ -15,15 +15,16 @@ const cards: {
 }[] = [
   {
     name: "Ghost loop",
-    href: "/docs/getting-started#how-ghost-works",
-    description: "See how scan, fingerprint, review, and intent fit together.",
+    href: "/docs/getting-started#the-simple-model",
+    description:
+      "See how capture, review, comparison, and intent fit together.",
     icon: <Orbit className="size-8" strokeWidth={1.5} />,
   },
   {
     name: "Get started",
     href: "/docs/getting-started",
     description:
-      "Install the skill bundle and review changed UI against .ghost/fingerprint.",
+      "Install the skill bundle and review changed UI against the .ghost bundle.",
     icon: <Rocket className="size-8" strokeWidth={1.5} />,
   },
   {
@@ -47,7 +48,7 @@ export default function GhostDriftLanding() {
       <AnimatedPageHeader
         kicker="ghost review"
         title="Drift"
-        description="Check whether changed or generated UI still matches the fingerprint package. ghost runs deterministic checks, emits advisory review packets, compares fingerprints, and records whether a difference should be fixed, accepted, or tracked as the new direction."
+        description="Check whether changed or generated UI still matches the .ghost bundle. ghost runs deterministic checks, emits advisory review packets, compares fingerprints, and records whether a difference should be fixed, accepted, or tracked as the new direction."
       />
 
       <div
diff --git a/apps/docs/src/app/tools/page.tsx b/apps/docs/src/app/tools/page.tsx
index 1d476e63..c874dbae 100644
--- a/apps/docs/src/app/tools/page.tsx
+++ b/apps/docs/src/app/tools/page.tsx
@@ -16,7 +16,7 @@ const tools: {
   {
     name: "ghost scan",
     href: "/tools/scan",
-    blurb: "Create the fingerprint",
+    blurb: "Capture the fingerprint",
     icon: <FileText className="size-5" strokeWidth={1.5} />,
   },
   {
@@ -78,7 +78,7 @@ export default function ToolsIndex() {
       <AnimatedPageHeader
         kicker="Tools"
         title="Tool Directory"
-        description="Pick the workflow you need: create the fingerprint, review drift, compare projects, or inspect the reference UI system."
+        description="Pick the workflow you need: capture the fingerprint, review drift, compare projects, or inspect the reference UI system."
       />
 
       <ToolStrip />
diff --git a/apps/docs/src/app/tools/scan/page.tsx b/apps/docs/src/app/tools/scan/page.tsx
index 11bdf046..8f99e0ab 100644
--- a/apps/docs/src/app/tools/scan/page.tsx
+++ b/apps/docs/src/app/tools/scan/page.tsx
@@ -17,20 +17,20 @@ const cards: {
     name: "Get started",
     href: "/docs/getting-started",
     description:
-      "Install the skill bundle and ask your agent to create a fingerprint.",
+      "Install the skill bundle and ask your agent to capture a fingerprint.",
     icon: <Rocket className="size-8" strokeWidth={1.5} />,
   },
   {
     name: "CLI reference",
-    href: "/docs/cli#ghost--authoring--validation",
-    description: "Validate, describe, diff, and emit agent-ready context.",
+    href: "/docs/cli#ghost--capture-support-and-bundle-checks",
+    description: "Check capture progress, validate bundles, and emit context.",
     icon: <BookOpen className="size-8" strokeWidth={1.5} />,
   },
   {
     name: "Format spec",
     href: "https://github.com/block/ghost/blob/main/docs/fingerprint-format.md",
     description:
-      "The full package format for map, survey, fingerprint, and optional checks.",
+      "The full bundle format for resources, map, survey, patterns, checks, and optional memory.",
     icon: <FileText className="size-8" strokeWidth={1.5} />,
   },
 ];
@@ -46,8 +46,8 @@ export default function GhostScanLanding() {
     <SectionWrapper>
       <AnimatedPageHeader
         kicker="ghost scan"
-        title="Ghost Scan"
-        description="The authoring tool that creates and maintains the repo-local fingerprint agents read before they generate UI."
+        title="Fingerprint Capture"
+        description="The BYOA workflow that produces the repo-local .ghost bundle agents read before they generate or review UI."
       />
 
       <div
diff --git a/apps/docs/src/content/docs/cli-reference.mdx b/apps/docs/src/content/docs/cli-reference.mdx
index 060d8a8f..2c0b75b7 100644
--- a/apps/docs/src/content/docs/cli-reference.mdx
+++ b/apps/docs/src/content/docs/cli-reference.mdx
@@ -80,8 +80,9 @@ deterministic BYOA handoff.
 
 ```bash
 ghost scan
-ghost scan fleet/members/cash-ios
+ghost scan ../other-repo/.ghost
 ghost scan . --format json
+ghost scan . --include-scopes
 ```
 
 ### Repo map - `inventory`
diff --git a/docs/cli-consolidation-plan.md b/docs/cli-consolidation-plan.md
index 71d85382..cc023266 100644
--- a/docs/cli-consolidation-plan.md
+++ b/docs/cli-consolidation-plan.md
@@ -5,7 +5,18 @@ owner: nahiyan
 branch: refactor/fingerprint (or a follow-up branch)
 ---
 
-> **Historical document.** This plan describes a pre-BYOA consolidation from 18 verbs to ~11. The current BYOA surface is **7 deterministic primitives** (`compare`, `lint`, `describe`, `ack`, `track`, `diverge`, `emit`) and `profile`, `review`, `verify`, `generate`, and `discover` are skill recipes the host agent runs. Kept for history; don't treat the exploratory verb list below as current. See the [README](../README.md) and the [CLI reference](../apps/docs/src/content/docs/cli-reference.mdx) for the current surface.
+> **Historical document.** This plan describes a pre-BYOA consolidation from 18
+> verbs to ~11. The current public surface is the unified
+> `@anarchitecture/ghost` package with the `ghost` CLI (`init`, `scan`,
+> `inventory`, `lint`, `verify`, `describe`, `diff`, `survey`, `check`,
+> `review`, `compare`, `ack`, `track`, `diverge`, `emit`, and `skill install`)
+> plus the private `ghost-fleet` CLI. Capture, map, survey, patterns, recall,
+> brief, critique, propose, promote, 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
+> [README](../README.md) and the
+> [CLI reference](../apps/docs/src/content/docs/cli-reference.mdx) for the
+> current surface.
 
 # Ghost CLI consolidation — 18 verbs → 9
 
diff --git a/docs/fingerprint-format.md b/docs/fingerprint-format.md
index 08e867f9..f6dcb3f0 100644
--- a/docs/fingerprint-format.md
+++ b/docs/fingerprint-format.md
@@ -125,7 +125,7 @@ authoritative until accepted by a human.
 ### `decisions/*.yml`
 
 Accepted or rejected product-experience decisions use `ghost.decision/v1`.
-These are rationale artifacts: they explain why an experience invariant matters
+These are rationale artifacts: they explain why a product-experience decision matters
 and cite evidence, but they do not block CI.
 
 ```yaml
diff --git a/packages/ghost-scan/README.md b/packages/ghost-scan/README.md
index 2663bea0..7cfa9904 100644
--- a/packages/ghost-scan/README.md
+++ b/packages/ghost-scan/README.md
@@ -1,8 +1,14 @@
 # ghost-scan
 
-**Author and validate Ghost's root repo-local fingerprint bundle. No LLM calls in any verb.**
+**Private historical scan package. Use `@anarchitecture/ghost` and the `ghost`
+CLI for current workflows.**
 
-Canonical package:
+The scan runtime and skill recipes needed by the public package are now folded
+into [`packages/ghost`](../ghost). This package remains in the monorepo for
+historical/development context and compatibility while the public npm surface is
+the unified `@anarchitecture/ghost` package.
+
+The current canonical bundle shape is:
 
 ```text
 .ghost/
@@ -34,38 +40,47 @@ product-experience memory without becoming deterministic gates.
 | Decisions | `decisions/*.yml` | `ghost.decision/v1` | Optional accepted/rejected product-experience rationale. |
 | Proposals | `proposals/*.yml` | `ghost.proposal/v1` | Optional candidate memory changes before promotion. |
 
-## Use
+## Current CLI
+
+Install and use the unified package:
+
+```bash
+npm install -D @anarchitecture/ghost
+npx ghost skill install
+```
+
+The current commands are:
 
 ```bash
-ghost-scan init-package --with-intent
+ghost init --with-intent
 
-ghost-scan inventory
-ghost-scan lint                         # defaults to .ghost
-ghost-scan scan-status
+ghost inventory
+ghost scan --format json
+ghost lint .ghost
 
-ghost-scan survey fix-ids .ghost/survey.json -o .ghost/survey.json
-ghost-scan survey summarize .ghost/survey.json
-ghost-scan survey catalog .ghost/survey.json --kind color
-ghost-scan survey patterns .ghost/survey.json -o .ghost/patterns.yml
+ghost survey fix-ids .ghost/survey.json -o .ghost/survey.json
+ghost survey summarize .ghost/survey.json
+ghost survey catalog .ghost/survey.json --kind color
+ghost survey patterns .ghost/survey.json -o .ghost/patterns.yml
 
-ghost-scan verify .ghost --root .
-ghost-scan describe                     # defaults to .ghost/intent.md
-ghost-scan diff a.fingerprint.md b.fingerprint.md
+ghost verify .ghost --root .
+ghost describe
+ghost diff a.fingerprint.md b.fingerprint.md
 
-ghost-scan emit context-bundle
-ghost-scan emit skill
+ghost emit context-bundle
+ghost skill install
 ```
 
 Zero config for every verb. No API key needed.
 
-## As A Library
+## Current Library Imports
 
 ```ts
 import {
   initFingerprintPackage,
   lintFingerprintPackage,
   verifyFingerprintPackage,
-} from "ghost-scan";
+} from "@anarchitecture/ghost/scan";
 
 const paths = await initFingerprintPackage(undefined, process.cwd(), {
   withIntent: true,
@@ -79,18 +94,19 @@ const verify = await verifyFingerprintPackage(undefined, process.cwd(), {
 ## Skill Bundle
 
 ```bash
-ghost-scan emit skill
+ghost skill install
 ```
 
-The bundle ships recipes for scan, map, survey, patterns, schema reference,
-recall, brief, critique, capture, and promote. Ask your agent to "scan this
-design language end-to-end" or "brief this work with Ghost"; it will author or
-activate package artifacts and use the CLI for validation.
+The unified bundle ships recipes for capture, map, survey, patterns, schema
+reference, recall, brief, critique, review, verify, compare, remediate, propose,
+and promote. Ask your agent to "capture a Ghost fingerprint for this repo" or
+"brief this work with Ghost"; it will author or activate `.ghost/` artifacts
+and use the CLI for deterministic validation.
 
 ## Format Docs
 
-See [`docs/fingerprint-format.md`](https://github.com/block/ghost/blob/main/docs/fingerprint-format.md)
-for the full package format.
+See [`docs/fingerprint-format.md`](../../docs/fingerprint-format.md) for the
+full bundle format.
 
 ## License
 
diff --git a/packages/ghost-ui/README.md b/packages/ghost-ui/README.md
index 84bc33cc..5ff5b7d7 100644
--- a/packages/ghost-ui/README.md
+++ b/packages/ghost-ui/README.md
@@ -2,11 +2,18 @@
 
 **Reference design system for the Ghost project. 97 components, shadcn registry, not published to npm.**
 
-`ghost-ui` is the reference component system Ghost uses to exercise registry and agent-integration workflows. It's distributed as a shadcn registry (`registry.json`) for drop-in consumption, not as an npm package. If you're looking for the drift-detection tool, that's [`ghost-drift`](../ghost-drift).
+`ghost-ui` is the reference component system Ghost uses to exercise registry
+and agent-integration workflows. It's distributed as a shadcn registry
+(`registry.json`) for drop-in consumption, not as an npm package. If you're
+looking for the fingerprint capture and drift-review tool, that's
+[`@anarchitecture/ghost`](../ghost).
 
 ## Registry convention
 
-This package intentionally does not carry package-local Ghost scan artifacts (`map.md`, `survey.json`, or `fingerprint.md`). It stays a component registry. Agents should read this README, `registry.json`, `.shadcn/skills.md`, and source files when integrating components.
+This package intentionally does not carry package-local Ghost capture artifacts
+(`resources.yml`, `map.md`, `survey.json`, `patterns.yml`, or `checks.yml`). It
+stays a component registry. Agents should read this README, `registry.json`,
+`.shadcn/skills.md`, and source files when integrating components.
 
 The shadcn `registry.json` can carry opportunistic, namespaced item metadata:
 
diff --git a/packages/ghost/README.md b/packages/ghost/README.md
index f83d6536..355b4250 100644
--- a/packages/ghost/README.md
+++ b/packages/ghost/README.md
@@ -56,7 +56,7 @@ 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 a product fingerprint: map
 the repo, survey evidence, codify patterns, review drift, verify generated UI,
-remediate issues, and propose accepted fingerprint updates.
+remediate issues, and propose candidate fingerprint updates.
 
 ```bash
 ghost skill install
diff --git a/packages/ghost/src/skill-bundle/references/critique.md b/packages/ghost/src/skill-bundle/references/critique.md
index 6378d32e..385485c7 100644
--- a/packages/ghost/src/skill-bundle/references/critique.md
+++ b/packages/ghost/src/skill-bundle/references/critique.md
@@ -17,7 +17,7 @@ checks and advisory packets; the fingerprint supplies role-aware interpretation.
    - design: feel, hierarchy, flow, density, tone
    - engineering: implementation choices that preserve experience
    - pm: product promise and tradeoffs
-   - qa: experience invariants and edge states
+   - qa: experience commitments and edge states
 5. Classify each issue as fix, intentional divergence, or missing fingerprint context.
 
 ## Output
diff --git a/packages/ghost/src/skill-bundle/references/review.md b/packages/ghost/src/skill-bundle/references/review.md
index 18f8e595..e40fbd99 100644
--- a/packages/ghost/src/skill-bundle/references/review.md
+++ b/packages/ghost/src/skill-bundle/references/review.md
@@ -4,7 +4,7 @@ description: Review PR or working-tree changes against the local Ghost fingerpri
 handoffs:
   - label: Suggest minimal fixes
     skill: remediate
-    prompt: Given the drift findings, suggest the minimal code changes that bring the diff back inside the fingerprint package
+    prompt: Given the drift findings, suggest the minimal code changes that bring the diff back inside the .ghost bundle
   - label: Accept the drift
     command: ghost ack
     prompt: Acknowledge that the current fingerprint no longer matches and record the drift