Rework docs around fingerprint lifecycle

.changeset/fingerprint-metadata.md

@@ -0,0 +1,5 @@
+---
+"@anarchitecture/ghost": minor
+---
+
+Align package metadata around portable product-experience fingerprints.

apps/docs/src/App.tsx

@@ -3,9 +3,10 @@ import { useEffect } from "react";
 import { Navigate, Route, Routes, useLocation, useParams } from "react-router";
 import DocsIndex from "@/app/docs/page";
 import HomePage from "@/app/page";
-import GhostDriftLanding from "@/app/tools/drift/page";
+import GhostEmitLanding from "@/app/tools/emit/page";
 import GhostFleetLanding from "@/app/tools/fleet/page";
 import ToolsIndex from "@/app/tools/page";
+import GhostReviewLanding from "@/app/tools/review/page";
 import GhostScanLanding from "@/app/tools/scan/page";
 import GhostUiLanding from "@/app/tools/ui/page";
 import ComponentPage from "@/app/ui/components/[name]/page";
@@ -51,24 +52,27 @@ export function App() {
         <Routes>
           <Route index element={<HomePage />} />
 
-          {/* Tools — four-card index plus per-tool landings */}
+          {/* Tools - command-specific references */}
           <Route path="tools" element={<ToolsIndex />} />
           <Route
             path="tools/map"
             element={<Navigate to="/tools/scan" replace />}
           />
           <Route path="tools/scan" element={<GhostScanLanding />} />
-          <Route path="tools/drift" element={<GhostDriftLanding />} />
+          <Route path="tools/emit" element={<GhostEmitLanding />} />
+          <Route path="tools/review" element={<GhostReviewLanding />} />
+          <Route
+            path="tools/drift"
+            element={<Navigate to="/tools/review" replace />}
+          />
           <Route path="tools/fleet" element={<GhostFleetLanding />} />
           <Route path="tools/ui" element={<GhostUiLanding />} />
 
           {/* Cross-tool docs hub */}
           <Route path="docs" element={<DocsIndex />} />
           <Route
             path="docs/workflow"
-            element={
-              <Navigate to="/docs/getting-started#how-ghost-works" replace />
-            }
+            element={<Navigate to="/docs/generation" replace />}
           />
 
           {/* MDX-authored doc pages under /docs/* */}
@@ -96,15 +100,15 @@ export function App() {
           />
           <Route
             path="tools/drift/concepts"
-            element={
-              <Navigate to="/docs/getting-started#how-ghost-works" replace />
-            }
+            element={<Navigate to="/docs/governance" replace />}
           />
           <Route
             path="tools/drift/workflow"
-            element={
-              <Navigate to="/docs/getting-started#how-ghost-works" replace />
-            }
+            element={<Navigate to="/docs/governance" replace />}
+          />
+          <Route
+            path="tools/drift/*"
+            element={<Navigate to="/docs/governance" replace />}
           />
 
           {/* Redirects from legacy root /foundations and /components URLs */}

apps/docs/src/app/docs/page.tsx

@@ -1,7 +1,16 @@
 "use client";
 
 import { useStaggerReveal } from "ghost-ui";
-import { BookOpen, Rocket } from "lucide-react";
+import {
+  BookOpen,
+  Boxes,
+  GitCompare,
+  PenLine,
+  RadioTower,
+  Rocket,
+  ShieldCheck,
+  Sparkles,
+} from "lucide-react";
 import type { ReactNode } from "react";
 import { Link } from "react-router";
 import { AnimatedPageHeader } from "@/components/docs/animated-page-header";
@@ -16,54 +25,95 @@ const sections: {
   {
     name: "Getting Started",
     href: "/docs/getting-started",
-    description:
-      "Install Ghost, set up the repo fingerprint, and learn the loop around .ghost.",
+    description: "Install Ghost and run the first fingerprint lifecycle loop.",
     icon: <Rocket className="size-8" strokeWidth={1.5} />,
   },
+  {
+    name: "Fingerprint Package",
+    href: "/docs/fingerprint-package",
+    description:
+      "Understand the portable contract: prose, inventory, composition, checks, memory, and cache.",
+    icon: <Boxes className="size-8" strokeWidth={1.5} />,
+  },
+  {
+    name: "Authoring",
+    href: "/docs/authoring",
+    description:
+      "Create, inspect, gather source material, and validate fingerprint layers.",
+    icon: <PenLine className="size-8" strokeWidth={1.5} />,
+  },
+  {
+    name: "Generation",
+    href: "/docs/generation",
+    description:
+      "Use `ghost emit context-bundle` before an agent writes or revises UI.",
+    icon: <Sparkles className="size-8" strokeWidth={1.5} />,
+  },
+  {
+    name: "Governance",
+    href: "/docs/governance",
+    description:
+      "Run checks and advisory review after generated or changed surfaces land.",
+    icon: <ShieldCheck className="size-8" strokeWidth={1.5} />,
+  },
+  {
+    name: "Comparison",
+    href: "/docs/comparison",
+    description:
+      "Compare packages, inspect stacks, and reason across many systems.",
+    icon: <GitCompare className="size-8" strokeWidth={1.5} />,
+  },
+  {
+    name: "Host Adapters",
+    href: "/docs/adapters",
+    description:
+      "Connect Ghost to agents, CI, and review surfaces without changing the package contract.",
+    icon: <RadioTower className="size-8" strokeWidth={1.5} />,
+  },
   {
     name: "CLI Reference",
     href: "/docs/cli",
     description:
-      "Commands for checks and comparison, plus the skill recipes your agent runs.",
+      "Find exact command flags and generated help for the full lifecycle.",
     icon: <BookOpen className="size-8" strokeWidth={1.5} />,
   },
 ];
 
 export default function DocsIndex() {
   const ref = useStaggerReveal<HTMLDivElement>(".doc-card", {
-    stagger: 0.06,
-    y: 30,
-    duration: 0.7,
+    stagger: 0.05,
+    y: 24,
+    duration: 0.65,
   });
 
   return (
     <SectionWrapper>
       <AnimatedPageHeader
         kicker="Docs"
-        title="Documentation"
-        description="Start with the simple loop, then reach for the command reference when you need exact flags and outputs."
+        title="Fingerprint Lifecycle"
+        description="Start with the portable contract, then move through authoring, generation, governance, comparison, and host integration."
       />
 
       <div
         ref={ref}
-        className="pb-16 pt-8 overflow-visible grid gap-4 md:grid-cols-2"
+        className="grid gap-4 pb-16 pt-8 overflow-visible md:grid-cols-2 xl:grid-cols-4"
       >
         {sections.map((item) => (
           <Link
             key={item.href}
             to={item.href}
-            className="doc-card group rounded-[var(--radius-card-sm)] border border-border-card hover:border-foreground/25 bg-card p-10 transition-colors duration-300"
+            className="doc-card group rounded-[var(--radius-card-sm)] border border-border-card bg-card p-7 transition-colors duration-300 hover:border-foreground/25"
           >
-            <div className="mb-6 text-muted-foreground group-hover:text-foreground transition-colors duration-200">
+            <div className="mb-5 text-muted-foreground transition-colors duration-200 group-hover:text-foreground">
               {item.icon}
             </div>
-            <span className="relative inline-block font-display text-lg font-bold tracking-tight">
+            <span className="relative inline-block font-display text-base font-bold tracking-tight">
               <span className="relative z-10 transition-colors duration-300 group-hover:text-background">
                 {item.name}
               </span>
-              <span className="absolute inset-0 bg-foreground origin-left scale-x-0 group-hover:scale-x-100 transition-transform duration-300 ease-out" />
+              <span className="absolute inset-0 origin-left scale-x-0 bg-foreground transition-transform duration-300 ease-out group-hover:scale-x-100" />
             </span>
-            <p className="mt-2 text-sm text-muted-foreground leading-relaxed">
+            <p className="mt-2 text-sm leading-relaxed text-muted-foreground">
               {item.description}
             </p>
           </Link>

apps/docs/src/app/tools/emit/page.tsx

@@ -0,0 +1,80 @@
+"use client";
+
+import { useStaggerReveal } from "ghost-ui";
+import { BookOpen, Send, Sparkles } from "lucide-react";
+import type { ReactNode } from "react";
+import { Link } from "react-router";
+import { AnimatedPageHeader } from "@/components/docs/animated-page-header";
+import { SectionWrapper } from "@/components/docs/wrappers";
+
+const cards: {
+  name: string;
+  href: string;
+  description: string;
+  icon: ReactNode;
+}[] = [
+  {
+    name: "Generation workflow",
+    href: "/docs/generation",
+    description:
+      "Use the context bundle before a host agent writes or revises UI.",
+    icon: <Sparkles className="size-8" strokeWidth={1.5} />,
+  },
+  {
+    name: "CLI reference",
+    href: "/docs/cli#ghost---generate",
+    description:
+      "See exact flags for `ghost emit review-command` and `ghost emit context-bundle`.",
+    icon: <BookOpen className="size-8" strokeWidth={1.5} />,
+  },
+  {
+    name: "Host adapters",
+    href: "/docs/adapters",
+    description: "Connect emitted packets to agents, CI, and review surfaces.",
+    icon: <Send className="size-8" strokeWidth={1.5} />,
+  },
+];
+
+export default function GhostEmitLanding() {
+  const ref = useStaggerReveal<HTMLDivElement>(".tool-card", {
+    stagger: 0.06,
+    y: 30,
+    duration: 0.7,
+  });
+
+  return (
+    <SectionWrapper>
+      <AnimatedPageHeader
+        kicker="ghost emit"
+        title="Generation Packets"
+        description="Emit deterministic handoff packets from checked-in fingerprint layers so host agents can generate from product-experience context before code changes begin."
+      />
+
+      <div
+        ref={ref}
+        className="grid gap-4 md:grid-cols-3 pb-16 overflow-visible"
+      >
+        {cards.map((item) => (
+          <Link
+            key={item.href}
+            to={item.href}
+            className="tool-card group rounded-[var(--radius-card-sm)] border border-border-card hover:border-foreground/25 bg-card p-10 transition-colors duration-300"
+          >
+            <div className="mb-6 text-muted-foreground group-hover:text-foreground transition-colors duration-200">
+              {item.icon}
+            </div>
+            <span className="relative inline-block font-display text-lg font-bold tracking-tight">
+              <span className="relative z-10 transition-colors duration-300 group-hover:text-background">
+                {item.name}
+              </span>
+              <span className="absolute inset-0 bg-foreground origin-left scale-x-0 group-hover:scale-x-100 transition-transform duration-300 ease-out" />
+            </span>
+            <p className="mt-2 text-sm text-muted-foreground leading-relaxed">
+              {item.description}
+            </p>
+          </Link>
+        ))}
+      </div>
+    </SectionWrapper>
+  );
+}

apps/docs/src/app/tools/fleet/page.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { useStaggerReveal } from "ghost-ui";
-import { BookOpen, Network, Rocket } from "lucide-react";
+import { BookOpen, GitCompare, Network } from "lucide-react";
 import type { ReactNode } from "react";
 import { Link } from "react-router";
 import { AnimatedPageHeader } from "@/components/docs/animated-page-header";
@@ -14,14 +14,14 @@ const cards: {
   icon: ReactNode;
 }[] = [
   {
-    name: "Get started",
-    href: "/docs/getting-started",
+    name: "Comparison workflow",
+    href: "/docs/comparison",
     description: "Compare many projects after each has a fingerprint.",
-    icon: <Rocket className="size-8" strokeWidth={1.5} />,
+    icon: <GitCompare className="size-8" strokeWidth={1.5} />,
   },
   {
     name: "CLI reference",
-    href: "/docs/cli#ghost-fleet--view-across-projects",
+    href: "/docs/cli#ghost---compare-and-adapt",
     description: "List members, compute a view, and emit fleet reports.",
     icon: <BookOpen className="size-8" strokeWidth={1.5} />,
   },

apps/docs/src/app/tools/page.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { useStaggerReveal } from "ghost-ui";
-import { FileText, Network, Orbit, Palette } from "lucide-react";
+import { FileText, Network, Palette, Send, ShieldCheck } from "lucide-react";
 import type { ReactNode } from "react";
 import { Link } from "react-router";
 import { AnimatedPageHeader } from "@/components/docs/animated-page-header";
@@ -19,11 +19,17 @@ const tools: {
     blurb: "Check fingerprint readiness",
     icon: <FileText className="size-5" strokeWidth={1.5} />,
   },
+  {
+    name: "ghost emit",
+    href: "/tools/emit",
+    blurb: "Create generation packets",
+    icon: <Send className="size-5" strokeWidth={1.5} />,
+  },
   {
     name: "ghost review",
-    href: "/tools/drift",
-    blurb: "Review UI drift",
-    icon: <Orbit className="size-5" strokeWidth={1.5} />,
+    href: "/tools/review",
+    blurb: "Govern changed UI",
+    icon: <ShieldCheck className="size-5" strokeWidth={1.5} />,
   },
   {
     name: "ghost-fleet",
@@ -49,7 +55,7 @@ function ToolStrip() {
   return (
     <div
       ref={ref}
-      className="grid gap-3 grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 mb-4 overflow-visible"
+      className="grid gap-3 grid-cols-1 sm:grid-cols-2 lg:grid-cols-5 mb-4 overflow-visible"
     >
       {tools.map((tool) => (
         <Link
@@ -77,8 +83,8 @@ export default function ToolsIndex() {
     <SectionWrapper>
       <AnimatedPageHeader
         kicker="Tools"
-        title="Tool Directory"
-        description="Pick the workflow you need: set up fingerprint layers, review drift, compare projects, or inspect the reference UI system."
+        title="Tool Reference"
+        description="Command-specific references for fingerprint readiness, generation packets, governance, fleet comparison, and the reference UI system."
       />
 
       <ToolStrip />