@ghostbyte/agent-docs-kit 5.0.1 → 5.1.0

package/CHANGELOG.md

@@ -4,6 +4,25 @@ Notable user-visible changes are recorded here. Versions follow semantic version
 
 ## Unreleased
 
+## 5.1.0 - 2026-10-14
+
+### Added
+
+- Guided `start new|existing|agent|manual` onboarding paths for first-time users.
+- A read-only `next` command that derives the current workflow stage from repository state.
+- Terminal continuation instructions after setup, skill installation, documentation audits, and worksheet creation.
+- A website guide explaining how the CLI, repository skill, coding agent, and durable project records work together.
+- A targeted-loading explanation showing how focused references can reduce unnecessary AI context and token usage.
+
+### Changed
+
+- The interactive menu is organized around starting, continuing, focused workflows, and maintenance instead of a flat command list.
+- The unified skill now detects first-use and post-setup requests and ends with one evidence-bounded next action.
+- Local website preview now builds the current source before starting the server.
+- Website builds use the same explicit public-document allowlist as the npm package.
+
+## 5.0.1 - 2026-10-14
+
 ### Fixed
 
 - Local documentation workspaces and generated audit records are excluded from the npm archive by an explicit public-document allowlist.

package/README.md

@@ -35,6 +35,32 @@ The no-argument command opens a guided menu in an interactive terminal. Installa
 
 The canonical library contains seven documentation areas, 12 security phases, and 14 engineering topics under `content/`. The generated skill loads only the selected reference instead of placing all 33 areas in context.
 
+## Choose a starting path
+
+The kit now separates first-time onboarding from the individual tools:
+
+```bash
+# Show all paths without changing files
+npx @ghostbyte/agent-docs-kit@latest start
+
+# Show one complete path
+npx @ghostbyte/agent-docs-kit@latest start new
+npx @ghostbyte/agent-docs-kit@latest start existing
+npx @ghostbyte/agent-docs-kit@latest start agent
+npx @ghostbyte/agent-docs-kit@latest start manual
+
+# Inspect an initialized project and receive its next action
+npx @ghostbyte/agent-docs-kit@latest next
+```
+
+`next` derives progress from the repository: configuration, required documents, scaffold prompts, saved documentation audits, and open security or engineering worksheets. It does not depend on terminal-session memory and does not write files.
+
+For AI-assisted work, install the repository-scoped skill, restart the AI session if needed, then prompt:
+
+> Use `$manage-project-quality`. Inspect this repository, determine the current Agent Docs stage, and guide me through the next safe step. Do not infer facts without evidence.
+
+If a user gives only the npm package or skill to an AI, the agent should inspect before acting, explain proposed writes, distinguish planned behavior from implemented behavior, and request authorization before active security testing. Package installation alone does not initialize files, run reviews, or grant authority.
+
 ## Install the command
 
 Project-local installation:

package/docs/ARCHITECTURE.md

@@ -16,7 +16,7 @@ Agent_Docs_Kit/
 ├─ src/
 │  ├─ api/index.mjs                # programmatic exports
 │  ├─ cli/                         # parsing, help, and routing
-│  ├─ commands/                    # setup, audit, worksheet, template, skill, validation
+│  ├─ commands/                    # onboarding, state detection, setup, audits, templates, skill
 │  └─ core/                        # catalog, config, filesystem, and package paths
 ├─ content/
 │  ├─ catalog.json                 # versioned selectors and review dates
@@ -43,6 +43,8 @@ Agent_Docs_Kit/
 
 `content/` is the single canonical library for all three workflows. `agent-docs setup` creates `.agent-docs/config.json` and a project documentation tree. Reports are written beneath configured directories; the reference library stays in the npm package and installed skill rather than being duplicated into each project.
 
+`agent-docs start` is a read-only onboarding router for new, existing, AI-assisted, and manual use. `agent-docs next` is a read-only state detector: it derives the current stage from configuration, required documents, starter prompts, saved audits, and open worksheets. It intentionally does not maintain a hidden progress file, so terminal sessions, humans, and coding agents see the same repository-backed state.
+
 Generated outputs under `build/`, package archives, dependencies, and the maintainer’s local monthly AI prompt are ignored by Git. Local consumer-style documentation under the configured `docs/` workspace is also ignored in this repository.
 
 Git ignore rules are not treated as a publishing boundary. `package.json` explicitly lists the six public maintainer guides, `docs/.npmignore` excludes local workspace records, and the packed-installation smoke test rejects every unexpected `docs/` path and every missing declared entry point.

package/docs/PURPOSE.md

@@ -2,6 +2,14 @@
 
 Agent Docs & Quality Kit is a library and command-line interface for establishing repeatable project-quality practices. It unifies three related activities without pretending they have the same consequences.
 
+## Agentic coding
+
+The kit provides durable project context and review instructions for humans and compatible coding agents. It does not include an AI model, start a background process, or perform a review merely because the npm package was installed.
+
+The CLI creates and checks the project workspace. The optional repository skill under `.agents/skills/manage-project-quality/` teaches a supported agent how to select focused references, inspect evidence, preserve safety boundaries, and write maintainable results. The user still starts the agent session, supplies the goal, and authorizes any active testing.
+
+Projects that do not use a skill-aware agent can follow the same process manually through `start`, `next`, focused guides, and generated worksheets.
+
 ## Documentation
 
 The documentation workflow preserves project memory. It creates a predictable place for system facts, current scope, decisions, development records, test evidence, operations, future proposals, and superseded material. Its audit detects gaps and drift.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghostbyte/agent-docs-kit",
-  "version": "5.0.1",
+  "version": "5.1.0",
   "description": "Documentation governance, evidence-based security audits, and engineering-quality reviews for software projects.",
   "type": "module",
   "bin": {
@@ -31,7 +31,7 @@
   ],
   "scripts": {
     "build": "node scripts/build-site.mjs && node scripts/build-skill.mjs",
-    "site:preview": "node scripts/preview-site.mjs",
+    "site:preview": "npm run build && node scripts/preview-site.mjs",
     "doctor": "node bin/agent-docs.mjs doctor",
     "test": "node --test",
     "validate": "node scripts/validate-content.mjs && node scripts/check-links.mjs && node bin/agent-docs.mjs validate",

package/scripts/build-site.mjs

@@ -1,12 +1,14 @@
 import { cp, mkdir, rm, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import { publicDocs } from "./public-docs.mjs";
 
 const root = resolve(import.meta.dirname, "..");
 const output = resolve(root, "build/site");
 await rm(output, { recursive: true, force: true });
 await mkdir(output, { recursive: true });
 await cp(resolve(root, "site"), output, { recursive: true });
-await cp(resolve(root, "docs"), resolve(output, "docs"), { recursive: true });
+await mkdir(resolve(output, "docs"));
+for (const name of publicDocs) await cp(resolve(root, "docs", name), resolve(output, "docs", name));
 await cp(resolve(root, "README.md"), resolve(output, "README.md"));
 await cp(resolve(root, "LICENSE"), resolve(output, "LICENSE"));
 await writeFile(resolve(output, ".nojekyll"), "", "utf8");

package/scripts/public-docs.mjs

@@ -0,0 +1,8 @@
+export const publicDocs = Object.freeze([
+  "ARCHITECTURE.md",
+  "CONTENT_MAINTENANCE.md",
+  "GITHUB_AND_NPM_SETUP.md",
+  "PURPOSE.md",
+  "RELEASE_PROCESS.md",
+  "SECURITY_MODEL.md"
+]);

package/scripts/smoke-package.mjs

@@ -2,6 +2,7 @@ import { execFileSync, spawnSync } from "node:child_process";
 import { access, mkdtemp, mkdir, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { resolve } from "node:path";
+import { publicDocs as publicDocNames } from "./public-docs.mjs";
 
 const root = resolve(import.meta.dirname, "..");
 const scratch = await mkdtemp(resolve(tmpdir(), "agent-docs-kit-smoke-"));
@@ -13,14 +14,7 @@ try {
   const cache = resolve(scratch, "npm-cache");
   const packed = JSON.parse(runNpm(["pack", "--json", "--cache", cache, "--pack-destination", scratch], { cwd: root, encoding: "utf8" }));
   const archivePaths = new Set(packed[0].files.map((entry) => entry.path.replaceAll("\\", "/")));
-  const publicDocs = new Set([
-    "docs/ARCHITECTURE.md",
-    "docs/CONTENT_MAINTENANCE.md",
-    "docs/GITHUB_AND_NPM_SETUP.md",
-    "docs/PURPOSE.md",
-    "docs/RELEASE_PROCESS.md",
-    "docs/SECURITY_MODEL.md"
-  ]);
+  const publicDocs = new Set(publicDocNames.map((name) => `docs/${name}`));
   for (const required of ["scripts/validate-content.mjs", "site/index.html", "tests/cli.test.mjs", "skills/manage-project-quality/references/security-protocol.md", "skills/manage-project-quality/references/engineering-protocol.md", "skills/manage-project-quality/references/documentation-governance.md"]) {
     if (!archivePaths.has(required)) throw new Error(`Packed archive is missing ${required}.`);
   }
@@ -52,9 +46,15 @@ try {
   const cli = resolve(packageRoot, "bin", "agent-docs.mjs");
   const runCli = (...arguments_) => execFileSync(process.execPath, [cli, ...arguments_], { cwd: consumer, encoding: "utf8" });
   const help = execFileSync(process.execPath, [cli, "--help"], { cwd: consumer, encoding: "utf8" });
-  if (!help.includes("documentation guide") || !help.includes("security worksheet") || !help.includes("template create")) throw new Error("Packed CLI help is incomplete.");
+  if (!help.includes("start [new|existing|agent|manual]") || !help.includes("Detect project state") || !help.includes("documentation guide") || !help.includes("security worksheet") || !help.includes("template create")) throw new Error("Packed CLI help is incomplete.");
+  const agentStart = runCli("start", "agent");
+  if (!agentStart.includes("$manage-project-quality") || !agentStart.includes("does not grant authority")) throw new Error("Packed CLI agent onboarding is incomplete.");
+  const emptyNext = runCli("next");
+  if (!emptyNext.includes("Stage 1: Initialize safely")) throw new Error("Packed CLI did not detect an uninitialized project.");
   runCli("setup", "--dry-run");
   runCli("setup");
+  const initializedNext = runCli("next");
+  if (!initializedNext.includes("Stage 3: Build the documentation baseline")) throw new Error("Packed CLI did not detect the generated baseline.");
   runCli("audit", "documentation", "--strict", "--report", "--format", "json");
   const securityOutput = runCli("security", "worksheet", "api-layer");
   const engineeringOutput = runCli("engineering", "worksheet", "testing-types");
@@ -68,7 +68,7 @@ try {
   runCli("skill", "install", "--target", "project");
   runCli("validate");
   await access(resolve(consumer, ".agents/skills/manage-project-quality/SKILL.md"));
-  execFileSync(process.execPath, ["--input-type=module", "--eval", "const api = await import('@ghostbyte/agent-docs-kit'); if (typeof api.auditDocumentation !== 'function' || typeof api.createTemplate !== 'function') process.exit(1);"], { cwd: consumer });
+  execFileSync(process.execPath, ["--input-type=module", "--eval", "const api = await import('@ghostbyte/agent-docs-kit'); if (typeof api.auditDocumentation !== 'function' || typeof api.createTemplate !== 'function' || typeof api.startWorkflow !== 'function' || typeof api.nextWorkflow !== 'function') process.exit(1);"], { cwd: consumer });
   const invalid = spawnSync(process.execPath, [cli, "doctor", "unexpected"], { cwd: consumer, encoding: "utf8" });
   if (invalid.status === 0 || !invalid.stderr.includes("Invalid arguments")) throw new Error("CLI accepted an unexpected positional argument.");
   runNpm(["run", "validate"], { cwd: packageRoot, stdio: "ignore" });

package/site/app.js

@@ -53,7 +53,7 @@ const commandPrefixes = {
 };
 
 const commandExamples = {
-  setup: ["list documentation", "documentation guide system-documentation", "audit documentation --strict"],
+  setup: ["start existing", "", "next", "", "list documentation", "", "documentation guide system-documentation", "", "audit documentation --strict"],
   security: ["list security", "security worksheet api-layer --style learning"],
   engineering: ["list engineering", "engineering worksheet testing-types"],
   skill: ["skill install --target project", "", "# Creates:", "# .agents/skills/manage-project-quality"]

package/site/index.html

@@ -20,8 +20,8 @@
         <span>Agent Docs &amp; Quality</span>
       </a>
       <div class="nav-links">
+        <a href="#getting-started">Start here</a>
         <a href="#workflows">Workflows</a>
-        <a href="#how-it-works">How it works</a>
         <a href="#commands">Commands</a>
         <a class="nav-install" href="#quick-start">Install guide</a>
       </div>
@@ -31,10 +31,10 @@
       <div class="hero-copy">
         <div class="status-pill"><i aria-hidden="true"></i> Quality infrastructure for human + AI teams</div>
         <h1>One project memory.<br><em>Three quality lenses.</em></h1>
-        <p class="hero-lead">Build documentation that stays useful, assess security controls with real evidence, and improve engineering practice—without loading an entire reference library into every session.</p>
+        <p class="hero-lead">Want to review and improve your project’s documentation, security posture, and engineering quality? Try Agent Docs &amp; Quality Kit. You can initialize it in a new project or safely add it to an existing project without overwriting existing files.</p>
         <div class="actions">
           <a class="button primary" href="#quick-start">Start locally <span aria-hidden="true">→</span></a>
-          <a class="button secondary" href="#workflows">Explore the workflows</a>
+          <a class="button secondary" href="#getting-started">Choose your path</a>
         </div>
         <dl class="hero-facts" aria-label="Toolkit facts">
           <div><dt>3</dt><dd>Focused workflows</dd></div>
@@ -49,15 +49,15 @@
           <p><span class="prompt">$</span> <span data-command>npx @ghostbyte/agent-docs-kit@latest</span></p>
           <p class="console-title">Agent Docs &amp; Quality Kit</p>
           <ol>
-            <li><i>01</i> Set up documentation</li>
-            <li><i>02</i> Audit documentation</li>
-            <li class="active"><i>03</i> Start security audit <b>selected</b></li>
-            <li><i>04</i> Start engineering review</li>
-            <li><i>05</i> Install project skill</li>
-            <li><i>06</i> Validate package</li>
-            <li><i>07</i> Open documentation website</li>
+            <li class="active"><i>01</i> Choose a starting path <b>start here</b></li>
+            <li><i>02</i> Continue from project state</li>
+            <li><i>03</i> Documentation workflow</li>
+            <li><i>04</i> Security workflow</li>
+            <li><i>05</i> Engineering workflow</li>
+            <li><i>06</i> Templates and records</li>
+            <li><i>07</i> Validate and maintain</li>
           </ol>
-          <p class="console-result"><span>✓</span> Scope selected: API Layer<br><span>→</span> Report starts as <strong>Unverified</strong></p>
+          <p class="console-result"><span>✓</span> New, existing, AI, and manual paths<br><span>→</span> One clear next action at every stage</p>
         </div>
       </div>
     </div>
@@ -73,6 +73,60 @@
       </div>
     </section>
 
+    <section class="section shell journey-section" id="getting-started">
+      <header class="section-heading split-heading">
+        <div><p class="eyebrow">Start with your situation</p><h2>Choose a path, then let the kit show what comes next.</h2></div>
+        <p>You do not need to memorize the command catalog. Start with one of four paths. After every stage, <code>next</code> inspects the project and gives you one evidence-based continuation.</p>
+      </header>
+
+      <div class="journey-start"><span>First command</span><code data-command="start">npx @ghostbyte/agent-docs-kit@latest start</code><p>Read-only. It explains the paths and does not change the project.</p></div>
+
+      <div class="journey-grid">
+        <article>
+          <span class="journey-number">01</span><p class="journey-label">New or empty</p><h3>Establish the project memory.</h3>
+          <p>Create the structure, document intended behavior as planned, and avoid presenting designs as implemented facts.</p>
+          <code data-command="start new">npx @ghostbyte/agent-docs-kit@latest start new</code>
+        </article>
+        <article>
+          <span class="journey-number">02</span><p class="journey-label">Existing project</p><h3>Reconcile docs with reality.</h3>
+          <p>Preview the safe scaffold, preserve existing files, then use code, configuration, tests, and operations as evidence.</p>
+          <code data-command="start existing">npx @ghostbyte/agent-docs-kit@latest start existing</code>
+        </article>
+        <article>
+          <span class="journey-number">03</span><p class="journey-label">AI-assisted</p><h3>Give the agent a bounded workflow.</h3>
+          <p>Install the repository skill, restart the AI session if needed, and ask it to inspect the project without guessing unavailable facts.</p>
+          <code data-command="start agent">npx @ghostbyte/agent-docs-kit@latest start agent</code>
+        </article>
+        <article>
+          <span class="journey-number">04</span><p class="journey-label">Manual</p><h3>Use the library yourself.</h3>
+          <p>Read one focused guide, complete records by hand, and change Unverified only when your evidence supports it.</p>
+          <code data-command="start manual">npx @ghostbyte/agent-docs-kit@latest start manual</code>
+        </article>
+      </div>
+
+      <div class="journey-continue">
+        <div><p class="eyebrow">Already started?</p><h3>Continue from the real project state.</h3><p>The CLI checks configuration, required documents, starter prompts, saved audits, and open worksheets. It does not rely on memory from the previous terminal session.</p></div>
+        <div><code data-command="next">npx @ghostbyte/agent-docs-kit@latest next</code><ul><li>Stage 1: initialize safely</li><li>Stage 2-3: complete the scaffold and baseline</li><li>Stage 4: verify documentation</li><li>Stage 5-6: review and maintain</li></ul></div>
+      </div>
+
+      <aside class="agent-handoff">
+        <div><span>When another user gives the kit to an AI</span><h3>The package is context, not automatic authority.</h3></div>
+        <p>The AI should inspect the repository, determine the current stage, explain proposed writes, keep unknowns explicit, and ask for authorization before active security testing. Installing the package or skill alone does not initialize files or perform an audit.</p>
+      </aside>
+
+      <div class="agentic-guide" id="agentic-coding">
+        <header><p class="eyebrow">How agentic coding fits</p><h3>The kit supplies project memory and review rules. Your coding agent performs the work you request.</h3><p>Agent Docs &amp; Quality Kit does not bundle an AI model or start a background service. It prepares a durable workspace that humans and compatible coding agents can read, update, and verify together.</p></header>
+        <ol>
+          <li><span>1</span><div><strong>Initialize the workspace</strong><p><code>setup</code> creates the configuration and documentation structure. Existing files are protected by default.</p></div></li>
+          <li><span>2</span><div><strong>Install the project skill</strong><p><code>skill install --target project</code> adds the focused instructions and references under <code>.agents/skills/</code>.</p></div></li>
+          <li><span>3</span><div><strong>Start the coding agent</strong><p>Open or restart a supported agent in the repository, invoke <code>$manage-project-quality</code>, and give it a specific documentation, security, or engineering goal.</p></div></li>
+          <li><span>4</span><div><strong>Keep the result with the project</strong><p>The agent cites repository evidence and writes review records into <code>docs/</code>, where the team can inspect and maintain them.</p></div></li>
+        </ol>
+        <div class="agentic-prompt"><span>Suggested first prompt</span><code>Use $manage-project-quality. Inspect this repository, determine the current Agent Docs stage, and guide me through the next safe step. Do not infer facts without evidence.</code></div>
+        <p class="agentic-note"><strong>Using another AI tool?</strong> If it supports repository skills, point it to <code>.agents/skills/manage-project-quality/SKILL.md</code>. If it does not, the generated <code>docs/README.md</code>, focused CLI guides, and worksheets still provide a complete manual workflow.</p>
+      </div>
+    </section>
+
     <section class="section shell" id="workflows">
       <header class="section-heading split-heading">
         <div><p class="eyebrow">Three jobs, clear boundaries</p><h2>Choose the quality lens that matches the work.</h2></div>
@@ -158,6 +212,10 @@
         <span class="route-arrow" aria-hidden="true">→</span>
         <div class="route-node report"><small>Durable output</small><strong>Evidence-based report</strong><code>docs/04-testing/…</code></div>
       </div>
+      <aside class="token-note">
+        <div><span>Why targeted loading matters</span><strong>Less unrelated context for each review</strong></div>
+        <p>Instead of placing all 33 review areas into every AI session, the skill loads shared evidence rules plus only the selected documentation area, security phase, or engineering topic. This can reduce unnecessary context and token usage while keeping the review focused. Actual token use still depends on the agent, repository, and requested scope.</p>
+      </aside>
     </section>
 
     <section class="section command-section" id="commands">
@@ -165,7 +223,7 @@
         <div>
           <p class="eyebrow">Interactive or automatable</p>
           <h2>Use the menu once. Use direct commands everywhere else.</h2>
-          <p>The no-argument command guides first-time users. Choose how you run the kit and every example on this page will use the right command.</p>
+          <p>Use <code>start</code> once to select a path. Use <code>next</code> whenever you return. Direct commands remain available for scripts and experienced users.</p>
           <div class="command-mode-card" aria-labelledby="command-mode-title">
             <strong id="command-mode-title">How are you running it?</strong>
             <div class="command-mode-switch" role="group" aria-label="Command format">
@@ -187,7 +245,11 @@
             <button id="code-tab-engineering" role="tab" aria-selected="false" aria-controls="code-panel-engineering" tabindex="-1" data-code-tab="engineering">Engineering</button>
             <button id="code-tab-skill" role="tab" aria-selected="false" aria-controls="code-panel-skill" tabindex="-1" data-code-tab="skill">Skill</button>
           </div>
-          <div id="code-panel-setup" class="code-panel" role="tabpanel" aria-labelledby="code-tab-setup" data-code-panel="setup"><pre><code data-command-example="setup">npx @ghostbyte/agent-docs-kit@latest list documentation
+          <div id="code-panel-setup" class="code-panel" role="tabpanel" aria-labelledby="code-tab-setup" data-code-panel="setup"><pre><code data-command-example="setup">npx @ghostbyte/agent-docs-kit@latest start existing
+
+npx @ghostbyte/agent-docs-kit@latest next
+
+npx @ghostbyte/agent-docs-kit@latest list documentation
 
 npx @ghostbyte/agent-docs-kit@latest documentation guide system-documentation
 
@@ -222,7 +284,7 @@ npm --version</code><button class="copy-button light" data-copy="node --version\
             <ol>
               <li><div><strong>Confirm the CLI is available</strong><small>This fetches the current published version and prints its help.</small></div><div class="install-code"><code>npx @ghostbyte/agent-docs-kit@latest --help</code><button class="copy-button light" data-copy="npx @ghostbyte/agent-docs-kit@latest --help">Copy</button></div></li>
               <li><div><strong>Preview the documentation setup</strong><small>The dry run reports intended writes without changing files.</small></div><div class="install-code"><code>npx @ghostbyte/agent-docs-kit@latest setup --dry-run</code><button class="copy-button light" data-copy="npx @ghostbyte/agent-docs-kit@latest setup --dry-run">Copy</button></div></li>
-              <li><div><strong>Open the guided menu</strong><small>Choose documentation, security, engineering, skill installation, or validation.</small></div><div class="install-code"><code>npx @ghostbyte/agent-docs-kit@latest</code><button class="copy-button light" data-copy="npx @ghostbyte/agent-docs-kit@latest">Copy</button></div></li>
+              <li><div><strong>Choose your starting path</strong><small>Get complete instructions for a new project, existing project, AI-assisted workflow, or manual workflow.</small></div><div class="install-code"><code>npx @ghostbyte/agent-docs-kit@latest start</code><button class="copy-button light" data-copy="npx @ghostbyte/agent-docs-kit@latest start">Copy</button></div></li>
             </ol>
           </article>
 
@@ -303,6 +365,8 @@ npx agent-docs --help</code><button class="copy-button light" data-copy="npm ins
 
       <div class="command-reference" role="list">
         <article role="listitem"><div class="command-meta"><span class="read-label">Interactive</span><code data-command>npx @ghostbyte/agent-docs-kit@latest</code></div><div><h3>Open the guided menu</h3><p>Choose documentation setup, documentation audit, security audit, engineering review, project-skill installation, or package validation. In a non-interactive shell, it prints help instead of waiting for input.</p></div></article>
+        <article role="listitem"><div class="command-meta"><span class="read-label">Read-only</span><code data-command="start [new|existing|agent|manual]">npx @ghostbyte/agent-docs-kit@latest start [new|existing|agent|manual]</code></div><div><h3>Show a complete onboarding path</h3><p>Explains the ordered steps, safety boundary, and exact commands for a new project, an existing project, AI-assisted work, or manual work. With no path argument, it shows all four choices.</p></div></article>
+        <article role="listitem"><div class="command-meta"><span class="read-label">Read-only</span><code data-command="next">npx @ghostbyte/agent-docs-kit@latest next</code></div><div><h3>Continue from project state</h3><p>Inspects the configured workspace, starter prompts, saved audits, and open worksheets, then prints the current stage and one concrete set of next actions. It does not write files.</p></div></article>
         <article role="listitem"><div class="command-meta"><span class="write-label">Writes</span><code data-command="setup">npx @ghostbyte/agent-docs-kit@latest setup</code></div><div><h3>Create the documentation workspace</h3><p>Adds `.agent-docs/config.json` and the initial `docs/` hierarchy for system, project, development, testing, operations, future work, and archives. Use `--dry-run` first; existing files are skipped.</p></div></article>
         <article role="listitem"><div class="command-meta"><span class="read-label">Read-only*</span><code data-command="audit documentation">npx @ghostbyte/agent-docs-kit@latest audit documentation</code></div><div><h3>Check documentation health</h3><p>Checks configured required documents, duplicate headings, placeholders, relative links, anchors, and optional metadata. Add <code>--strict</code> for CI, <code>--format</code> for text, Markdown, or JSON, and <code>--report</code> to persist the result.</p></div></article>
         <article role="listitem"><div class="command-meta"><span class="read-label">Read-only</span><code data-command="list documentation">npx @ghostbyte/agent-docs-kit@latest list documentation</code></div><div><h3>List documentation areas</h3><p>Prints the seven canonical documentation area IDs, slugs, and names from the same catalog used by security and engineering.</p></div></article>

package/site/styles.css

@@ -66,6 +66,43 @@ h3 { letter-spacing: -.025em; }
 .principle-strip .shell { display: grid; grid-template-columns: repeat(4, 1fr); }
 .principle-strip p { margin: 0; padding: 1.1rem; border-right: 1px solid var(--line); color: var(--muted); font: 600 .71rem ui-monospace, monospace; text-align: center; text-transform: uppercase; letter-spacing: .08em; }.principle-strip p:first-child { border-left: 1px solid var(--line); }.principle-strip span::before { content: "●"; margin-right: .55rem; color: var(--lime); font-size: .55rem; }
 
+.journey-section { padding-bottom: 0; }
+.journey-start { display: grid; grid-template-columns: auto minmax(280px, 1fr) 1fr; gap: 1.25rem; align-items: center; margin-bottom: 1rem; padding: 1.1rem 1.3rem; border: 1px solid #53653c; border-radius: 12px; background: linear-gradient(90deg, rgba(200,244,107,.1), rgba(200,244,107,.025)); }
+.journey-start span, .journey-label { color: var(--lime); font: 700 .65rem ui-monospace, monospace; text-transform: uppercase; letter-spacing: .09em; }
+.journey-start code, .journey-grid code, .journey-continue code { color: #dfe9e2; font: .74rem/1.55 ui-monospace, monospace; overflow-wrap: anywhere; }
+.journey-start p { margin: 0; color: var(--muted); font-size: .82rem; }
+.journey-grid { display: grid; grid-template-columns: repeat(4, 1fr); border: 1px solid var(--line); border-radius: 14px; overflow: hidden; }
+.journey-grid article { min-height: 330px; padding: 1.4rem; border-right: 1px solid var(--line); background: linear-gradient(160deg, #141916, #0d100f); }
+.journey-grid article:last-child { border-right: 0; }
+.journey-number { display: grid; width: 2rem; height: 2rem; place-items: center; margin-bottom: 3.5rem; border: 1px solid var(--line-strong); border-radius: 50%; color: #89938c; font: .65rem ui-monospace, monospace; }
+.journey-label { margin-bottom: .7rem; }
+.journey-grid h3 { min-height: 2.5em; margin-bottom: .65rem; font-size: 1.15rem; }
+.journey-grid article > p:not(.journey-label) { min-height: 7.8em; color: var(--muted); font-size: .84rem; }
+.journey-grid code { display: block; padding-top: 1rem; border-top: 1px solid var(--line); color: var(--blue); }
+.journey-continue { display: grid; grid-template-columns: 1fr 1fr; gap: 4rem; margin-top: 1rem; padding: clamp(2rem, 5vw, 3.5rem); border: 1px solid var(--line); border-radius: 14px; background: #111512; }
+.journey-continue h3 { margin-bottom: .7rem; font-size: 1.55rem; }
+.journey-continue p:not(.eyebrow), .journey-continue li { color: var(--muted); font-size: .87rem; }
+.journey-continue code { display: block; margin-bottom: 1rem; padding: .9rem; border: 1px solid #355672; border-radius: 8px; background: #090c0a; color: var(--blue); }
+.journey-continue ul { margin: 0; padding-left: 1.2rem; }
+.agent-handoff { display: grid; grid-template-columns: .8fr 1.2fr; gap: 3rem; margin-top: 1rem; padding: 1.5rem; border: 1px solid #725d35; border-radius: 12px; background: rgba(241,197,107,.055); }
+.agent-handoff span { color: var(--amber); font: 700 .65rem ui-monospace, monospace; text-transform: uppercase; letter-spacing: .08em; }
+.agent-handoff h3 { margin: .6rem 0 0; }
+.agent-handoff p { margin: 0; color: var(--muted); font-size: .88rem; }
+.agentic-guide { margin-top: 1rem; padding: clamp(2rem, 5vw, 4rem); border: 1px solid #355672; border-radius: 14px; background: radial-gradient(circle at 85% 5%, rgba(59,118,166,.14), transparent 34%), #101412; }
+.agentic-guide > header { max-width: 810px; margin-bottom: 2.5rem; }
+.agentic-guide > header h3 { font-size: clamp(1.6rem, 3.2vw, 2.65rem); line-height: 1.08; }
+.agentic-guide > header > p:not(.eyebrow) { color: var(--muted); }
+.agentic-guide ol { display: grid; grid-template-columns: 1fr 1fr; gap: 0 2rem; margin: 0; padding: 0; list-style: none; }
+.agentic-guide li { display: grid; grid-template-columns: 34px 1fr; gap: .75rem; padding: 1.2rem 0; border-top: 1px solid var(--line); }
+.agentic-guide li > span { display: grid; width: 27px; height: 27px; place-items: center; border: 1px solid #355672; border-radius: 50%; color: var(--blue); font: .65rem ui-monospace, monospace; }
+.agentic-guide li strong { display: block; margin-bottom: .25rem; }
+.agentic-guide li p { margin: 0; color: var(--muted); font-size: .82rem; }
+.agentic-guide code { color: var(--blue); font: .78rem/1.55 ui-monospace, monospace; overflow-wrap: anywhere; }
+.agentic-prompt { display: grid; grid-template-columns: auto 1fr; gap: 1.2rem; margin-top: 1.5rem; padding: 1.2rem; border: 1px solid #53653c; border-radius: 9px; background: #090c0a; }
+.agentic-prompt span { color: var(--lime); font: 700 .65rem ui-monospace, monospace; text-transform: uppercase; letter-spacing: .08em; }
+.agentic-prompt code { color: #dfe9e2; }
+.agentic-note { margin: 1rem 0 0; padding-top: 1rem; border-top: 1px solid var(--line); color: var(--muted); font-size: .82rem; }
+
 .section { padding-block: clamp(5rem, 10vw, 9rem); }
 .section-heading { max-width: 760px; margin-bottom: 3.5rem; }.section-heading > p:not(.eyebrow) { max-width: 630px; color: var(--muted); font-size: 1.05rem; }
 .split-heading { display: grid; grid-template-columns: 1.3fr .7fr; gap: 4rem; max-width: none; align-items: end; }.split-heading > p { margin-bottom: 1.3rem; }
@@ -80,6 +117,7 @@ h3 { letter-spacing: -.025em; }
 .process-section { border-block: 1px solid var(--line); background: #101412; }.process-list { margin: 0; padding: 0; border-top: 1px solid var(--line); list-style: none; }.process-list li { display: grid; grid-template-columns: 90px 1fr; gap: 1rem; padding: 2rem 0; border-bottom: 1px solid var(--line); }.process-list > li > span { color: var(--lime); font: 700 .74rem ui-monospace, monospace; }.process-list h3 { margin: 0 0 .35rem; font-size: 1.4rem; }.process-list p { max-width: 690px; margin: 0; color: var(--muted); }
 
 .routing-diagram { display: grid; grid-template-columns: 1fr auto 1fr auto 1.15fr auto 1fr; gap: .8rem; align-items: center; }.route-node { min-height: 125px; padding: 1rem; border: 1px solid var(--line); border-radius: 10px; background: var(--panel); }.route-node small { display: block; margin-bottom: .8rem; color: #778179; font: .65rem ui-monospace, monospace; text-transform: uppercase; }.route-node strong { display: block; font-size: .9rem; }.route-node code { display: block; margin-top: .65rem; color: var(--lime); font-size: .65rem; }.route-node.router { border-color: #52633b; }.route-node.selected { min-height: auto; border-color: #405036; background: #151c13; }.route-node.muted { min-height: auto; opacity: .55; }.route-node.report { border-color: #355672; }.route-stack { display: grid; gap: .5rem; }.route-arrow { color: #5c675f; }
+.token-note { display: grid; grid-template-columns: .7fr 1.3fr; gap: 3rem; margin-top: 1rem; padding: 1.35rem; border: 1px solid #52633b; border-radius: 10px; background: rgba(200,244,107,.045); }.token-note span { display: block; margin-bottom: .45rem; color: var(--lime); font: 700 .64rem ui-monospace, monospace; text-transform: uppercase; letter-spacing: .08em; }.token-note strong { font-size: 1.05rem; }.token-note p { margin: 0; color: var(--muted); font-size: .86rem; }
 
 .command-section { background: #e9eddf; color: #10130f; }.command-layout { display: grid; grid-template-columns: .82fr 1.18fr; gap: clamp(3rem, 8vw, 7rem); align-items: center; }.command-section .eyebrow { color: #4c681a; }.command-section p { color: #566057; }.command-notes { margin-top: 2rem; border-top: 1px solid #bdc4b8; }.command-notes p { display: grid; grid-template-columns: 22px 1fr; margin: 0; padding: .8rem 0; border-bottom: 1px solid #c8cec3; }.command-notes span { color: #557817; }.command-notes strong { color: #20251f; }.command-notes small { grid-column: 2; }
 .command-mode-card { margin-top: 1.5rem; padding: 1rem; border: 1px solid #bdc6b9; border-radius: 12px; background: rgba(255,255,255,.5); }.command-mode-card > strong { display: block; margin-bottom: .7rem; font-size: .84rem; }.command-mode-switch { display: grid; grid-template-columns: 1fr 1fr; gap: .45rem; padding: .3rem; border-radius: 9px; background: #d8ddd2; }.command-mode-switch button { display: flex; flex-direction: column; gap: .05rem; padding: .65rem .8rem; border: 1px solid transparent; border-radius: 7px; color: #5a635b; background: transparent; cursor: pointer; text-align: left; }.command-mode-switch button span { color: inherit; font-size: .82rem; font-weight: 760; }.command-mode-switch button small { font-size: .68rem; }.command-mode-switch button[aria-pressed="true"] { border-color: #a7b09f; color: #151a15; background: #fff; box-shadow: 0 3px 12px rgba(28,38,29,.09); }.command-mode-help { min-height: 2.7em; margin: .75rem 0 0 !important; font-size: .76rem; line-height: 1.35; }
@@ -140,14 +178,16 @@ button:focus-visible, a:focus-visible { outline: 2px solid var(--blue); outline-
   .hero-layout { padding-block: 6rem; }.console { max-width: 620px; transform: none; }
   .split-heading { grid-template-columns: 1fr; gap: 1rem; }.workflow-panel { gap: 2.5rem; }
   .routing-diagram { grid-template-columns: 1fr; }.route-arrow { transform: rotate(90deg); text-align: center; }
-  .options-block, .skill-detail { grid-template-columns: 1fr; gap: 2rem; }.package-parts { grid-template-columns: 1fr 1fr; }.package-parts article:nth-child(2) { border-right: 0; }.package-parts article:nth-child(-n+2) { border-bottom: 1px solid var(--line); }.catalog-layout { grid-template-columns: 1fr 1fr; }.documentation-catalog { grid-column: 1 / -1; }
+  .options-block, .skill-detail, .token-note { grid-template-columns: 1fr; gap: 2rem; }.package-parts { grid-template-columns: 1fr 1fr; }.package-parts article:nth-child(2) { border-right: 0; }.package-parts article:nth-child(-n+2) { border-bottom: 1px solid var(--line); }.catalog-layout { grid-template-columns: 1fr 1fr; }.documentation-catalog { grid-column: 1 / -1; }
   .trust-grid { grid-template-columns: 1fr 1fr; }.trust-grid article:nth-child(2) { border-right: 0; }.trust-grid article:nth-child(-n+2) { border-bottom: 1px solid var(--line); }
+  .journey-grid { grid-template-columns: 1fr 1fr; }.journey-grid article:nth-child(2) { border-right: 0; }.journey-grid article:nth-child(-n+2) { border-bottom: 1px solid var(--line); }.journey-continue { gap: 2rem; }
 }
 
 @media (max-width: 700px) {
   .shell { width: min(100% - 2rem, 1160px); }.hero { min-height: auto; }.nav { align-items: flex-start; padding-block: 1rem; }.nav-links a:not(.nav-install) { display: none; }.brand > span:last-child { max-width: 130px; line-height: 1.1; }
   .hero-layout { padding-block: 4.5rem 5rem; }.hero-facts { gap: 1rem; }.hero-facts div { display: block; }.hero-facts dd { max-width: 72px; }
   .principle-strip .shell { grid-template-columns: 1fr 1fr; }.principle-strip p:nth-child(2) { border-right: 1px solid var(--line); }.principle-strip p:nth-child(-n+2) { border-bottom: 1px solid var(--line); }
+  .journey-start, .journey-continue, .agent-handoff, .journey-grid, .agentic-guide ol, .agentic-prompt { grid-template-columns: 1fr; }.journey-start { align-items: start; }.journey-grid article { min-height: auto; border-right: 0; border-bottom: 1px solid var(--line); }.journey-grid article:last-child { border-bottom: 0; }.journey-number { margin-bottom: 1.5rem; }.journey-grid h3, .journey-grid article > p:not(.journey-label) { min-height: 0; }
   .workflow-tabs button { padding: .8rem .4rem; font-size: .72rem; }.workflow-tabs button span { display: block; margin: 0; }.workflow-details { grid-template-columns: 1fr; }.workflow-details .result-card { grid-column: auto; }
   .command-mode-switch { grid-template-columns: 1fr; }
   .command-reference article { grid-template-columns: 1fr; gap: 1rem; }.options-block dl, .package-parts, .catalog-layout, .install-paths, .other-installation { grid-template-columns: 1fr; }.package-parts article { min-height: auto; border-right: 0; border-bottom: 1px solid var(--line); }.package-parts article:last-child { border-bottom: 0; }.package-parts h3 { margin-top: 1.4rem; }.documentation-catalog { grid-column: auto; }

package/skills/manage-project-quality/SKILL.md

@@ -1,12 +1,23 @@
 ---
 name: manage-project-quality
-description: Set up and audit project documentation, perform evidence-based security reviews, or assess engineering practices. Use when asked to create or repair a docs structure, check documentation drift, conduct a security gate or phase audit, review engineering quality, generate audit evidence, or explain Agent Docs & Quality Kit results in standard or learning mode.
+description: Set up and audit project documentation, perform evidence-based security reviews, assess engineering practices, or continue an Agent Docs & Quality Kit workflow. Use when asked to initialize a new or existing repository, decide what to do after setup, create or repair a docs structure, check documentation drift, conduct a security gate or phase audit, review engineering quality, generate audit evidence, or explain kit results in standard or learning mode.
 ---
 
 # Manage Project Quality
 
 Choose exactly one primary workflow for the request: documentation governance, security assurance, or engineering review. Combine workflows only when the user explicitly requests a broader quality pass.
 
+## Start from repository state
+
+When the user hands you this skill, names the npm package, or asks what to do after setup:
+
+1. Inspect the repository before choosing a workflow. Look for `.agent-docs/config.json`, required documents, starter prompts, saved audits, and open `Unverified` worksheets.
+2. If the CLI is available, run or recommend `agent-docs next --cwd <project>` to obtain the current stage. Otherwise apply the same order: initialize, complete the baseline, audit documentation, complete one focused review, then maintain.
+3. Distinguish a new project from an existing implementation. In a new project, record intended behavior as planned. In an existing project, derive statements from code, configuration, tests, workflows, and authorized operational evidence.
+4. Explain proposed writes before making them unless the user has already authorized that exact setup or report action.
+5. If the skill is not installed in the repository, recommend `npx @ghostbyte/agent-docs-kit@latest skill install --target project`. Installation alone does not initialize files, run an audit, or authorize active testing.
+6. End each response with the completed stage, unresolved evidence, and one concrete next action.
+
 ## Establish the operating context
 
 1. Inspect the repository, its local instructions, and the files relevant to the request.

package/skills/manage-project-quality/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Agent Docs & Quality"
-  short_description: "Govern docs and review project quality"
-  default_prompt: "Use $manage-project-quality to set up project documentation or run an evidence-based security or engineering review."
+  short_description: "Guide and review project quality workflows"
+  default_prompt: "Use $manage-project-quality to inspect this repository, determine its current Agent Docs stage, and guide the next safe documentation, security, or engineering step using repository evidence."

package/src/api/index.mjs

@@ -4,5 +4,6 @@ export { installSkill } from "../commands/skill.mjs";
 export { createTemplate, listTemplates, templateTypes } from "../commands/template.mjs";
 export { showDocumentationGuide } from "../commands/guide.mjs";
 export { openWebsite, websiteUrl } from "../commands/website.mjs";
+export { startWorkflow, nextWorkflow, npxCommand } from "../commands/workflow.mjs";
 export { loadCatalog } from "../core/catalog.mjs";
 export { loadProjectConfig, defaultConfig } from "../core/config.mjs";

package/src/cli/help.mjs

@@ -11,6 +11,8 @@ After installing globally:
 
 Commands:
   (no command)                       Open the guided menu (TTY only)
+  start [new|existing|agent|manual]  Show a complete onboarding path
+  next                               Detect project state and show the next step
   setup [--dry-run]                  Create the documentation workspace
   audit documentation [--strict]     Check documentation health
   documentation guide <area>         Print one documentation guidance area
@@ -31,6 +33,8 @@ Commands:
   --version                          Show the package version
 
 Examples:
+  npx @ghostbyte/agent-docs-kit@latest start existing
+  npx @ghostbyte/agent-docs-kit@latest next
   npx @ghostbyte/agent-docs-kit@latest setup --dry-run
   npx @ghostbyte/agent-docs-kit@latest audit documentation --strict --format text
   npx @ghostbyte/agent-docs-kit@latest documentation guide system-documentation
@@ -56,4 +60,8 @@ Options:
   --strict                    Fail when documentation checks fail
   --help                      Show this help
 
-Installing the npm package performs no project setup. Run a command explicitly.`;
+Recommended first run:
+  npx @ghostbyte/agent-docs-kit@latest start
+
+Installing the npm package performs no project setup. Run 'start' for a guided path
+or 'next' to continue an initialized project.`;

package/src/cli/main.mjs

@@ -11,6 +11,7 @@ import { validatePackage } from "../commands/validate.mjs";
 import { openWebsite } from "../commands/website.mjs";
 import { createTemplate, listTemplates } from "../commands/template.mjs";
 import { showDocumentationGuide } from "../commands/guide.mjs";
+import { nextWorkflow, startWorkflow } from "../commands/workflow.mjs";
 import { readFile } from "node:fs/promises";
 import { resolveFromPackage } from "../core/paths.mjs";
 
@@ -27,22 +28,28 @@ function assertInvocation(positionals, flags, { counts, allowedFlags = [], usage
 async function menu() {
   const ui = createInterface({ input: stdin, output: stdout });
   try {
-    console.log(`\nAgent Docs & Quality Kit\n\n1. Set up documentation\n2. Audit documentation\n3. Create security worksheet\n4. Create engineering worksheet\n5. Install project skill\n6. Validate package\n7. Open documentation website\n8. List documentation templates\n0. Exit`);
+    console.log(`\nAgent Docs & Quality Kit\n\nStart and continue\n1. Choose a starting path\n2. Continue from the current project state\n\nFocused workflows\n3. Set up documentation\n4. Audit documentation\n5. Create security worksheet\n6. Create engineering worksheet\n7. Install project skill\n\nReference and maintenance\n8. List documentation templates\n9. Validate package\n10. Open documentation website\n0. Exit`);
     const choice = await ui.question("\nChoose an action: ");
-    if (choice === "1") return setupProject();
-    if (choice === "2") return auditDocumentation();
-    if (choice === "3") {
+    if (choice === "1") {
+      console.log("\n1. New or empty project\n2. Existing project\n3. AI-assisted workflow\n4. Manual workflow");
+      const path = await ui.question("Choose a starting path: ");
+      return startWorkflow({ "1": "new", "2": "existing", "3": "agent", "4": "manual" }[path]);
+    }
+    if (choice === "2") return nextWorkflow();
+    if (choice === "3") return setupProject();
+    if (choice === "4") return auditDocumentation();
+    if (choice === "5") {
       await listCatalog("security");
       return auditSecurity(await ui.question("Phase id or slug: "));
     }
-    if (choice === "4") {
+    if (choice === "6") {
       await listCatalog("engineering");
       return reviewEngineering(await ui.question("Topic id or slug: "));
     }
-    if (choice === "5") return installSkill("project");
-    if (choice === "6") return validatePackage();
-    if (choice === "7") return openWebsite();
+    if (choice === "7") return installSkill("project");
     if (choice === "8") return listTemplates();
+    if (choice === "9") return validatePackage();
+    if (choice === "10") return openWebsite();
     if (choice !== "0") throw new Error("Unknown menu choice.");
   } finally {
     ui.close();
@@ -67,6 +74,14 @@ export async function main(argv) {
     }
     return menu();
   }
+  if (command === "start") {
+    assertInvocation(positionals, flags, { counts: [1, 2], usage: "agent-docs start [new|existing|agent|manual]" });
+    return startWorkflow(subject);
+  }
+  if (command === "next") {
+    assertInvocation(positionals, flags, { counts: [1], allowedFlags: ["cwd"], usage: "agent-docs next [--cwd <path>]" });
+    return nextWorkflow(options);
+  }
   if (command === "setup") {
     assertInvocation(positionals, flags, { counts: [1], allowedFlags: ["cwd", "dry-run", "force"], usage: "agent-docs setup [--cwd <path>] [--dry-run] [--force]" });
     return setupProject(options);

package/src/commands/audit.mjs

@@ -32,6 +32,15 @@ async function reportFor(kind, selector, options = {}) {
   const body = `# ${heading}: ${entry.title}\n\n- Date: ${localDate()}\n- Style: ${options.style ?? config.interactionStyle}\n- Overall status: Unverified\n- Reviewer: _Unassigned_\n\n${context}\n\n## Findings\n\n${columns}\n\n## Reference checklist\n\n${reference.trim()}\n`;
   const result = await writeUnique(output, body, options);
   console.log(`${result.status} ${result.path}`);
+  if (options.dryRun) {
+    console.log("Preview only: no worksheet was created.");
+  } else {
+    console.log("\nNext steps:");
+    console.log(`1. Open ${relative(root, result.path)}. Every finding starts as Unverified.`);
+    console.log("2. Collect evidence, then record status, remediation, owner, and verification. Do not treat worksheet creation as a completed review.");
+    console.log("3. For AI assistance, install the project skill and ask $manage-project-quality to review only this scope.");
+    console.log(`4. Continue: npx @ghostbyte/agent-docs-kit@latest next --cwd "${root}"`);
+  }
   return result;
 }
 
@@ -160,5 +169,9 @@ export async function auditDocumentation(options = {}) {
     console.log(`${written.status} ${written.path}`);
     result.reportPath = written.path;
   }
+  if (options.format === "text") {
+    console.log("\nThis is a structural documentation check; it does not prove that every statement is factually complete or current.");
+    console.log(`Continue: npx @ghostbyte/agent-docs-kit@latest next --cwd "${root}"`);
+  }
   return result;
 }

package/src/commands/setup.mjs

@@ -18,6 +18,17 @@ const files = {
 
 This directory is the maintained project record. Keep decisions and system facts separate from generated audit evidence.
 
+## Start here
+
+1. Replace the starter prompts in \`01-system/overview.md\`, \`02-project/README.md\`, and \`05-operations/README.md\` with verified project facts.
+2. Choose how to complete the baseline:
+   - AI-assisted: install the project skill with \`npx @ghostbyte/agent-docs-kit@latest skill install --target project\`, restart the AI session if needed, then ask it to use \`$manage-project-quality\` and inspect repository evidence.
+   - Manual: run \`npx @ghostbyte/agent-docs-kit@latest list documentation\`, then open one focused area with \`documentation guide <area>\`.
+3. Run \`npx @ghostbyte/agent-docs-kit@latest audit documentation --strict --report --format markdown\`.
+4. Run \`npx @ghostbyte/agent-docs-kit@latest next\` whenever you need the next project-specific action.
+
+Generated structure is not proof of completeness. Keep unknowns explicit, label planned behavior as planned, and never assign a security result without evidence.
+
 - \`01-system/\`: system scope, architecture, data, and security design
 - \`02-project/\`: requirements, roadmap, decisions, and status
 - \`03-development/\`: implementation notes and engineering reviews
@@ -43,5 +54,20 @@ export async function setupProject(options = {}) {
     results.push(await writeSafe(resolve(root, path), contents, options));
   }
   displayResults(root, results);
+  const changed = results.filter((result) => result.status !== "skipped").length;
+  if (options.dryRun) {
+    console.log(`\nPreview complete: ${changed} owned path(s) would be created or replaced.`);
+    console.log(`Apply it: npx @ghostbyte/agent-docs-kit@latest setup --cwd "${root}"`);
+  } else {
+    console.log(`\nWorkspace ready: ${changed} path(s) created or replaced; existing files were skipped unless --force was supplied.`);
+    console.log("Nothing is running in the background, and no AI review has been performed.");
+    console.log("\nTo use this workspace with an AI coding agent:");
+    console.log(`1. npx @ghostbyte/agent-docs-kit@latest skill install --target project --cwd "${root}"`);
+    console.log("2. Open or restart the agent in this repository so it can discover .agents/skills/.");
+    console.log("3. Prompt: Use $manage-project-quality. Inspect this repository, determine the current Agent Docs stage, and guide me through the next safe step. Do not infer facts without evidence.");
+    console.log("\nTo work without an AI:");
+    console.log("npx @ghostbyte/agent-docs-kit@latest start manual");
+    console.log(`\nTo continue later: npx @ghostbyte/agent-docs-kit@latest next --cwd "${root}"`);
+  }
   return results;
 }

package/src/commands/skill.mjs

@@ -11,5 +11,16 @@ export async function installSkill(target = "project", options = {}) {
     : resolve(root, ".agents", "skills", "manage-project-quality");
   const result = await copySafe(resolveFromPackage("skills", "manage-project-quality"), destination, options);
   console.log(`${result.status} ${destination}`);
+  if (options.dryRun) {
+    console.log("\nPreview only: no skill files were copied.");
+  } else if (target === "project") {
+    console.log("\nNext steps:");
+    console.log("1. Open or restart your AI coding session so it can discover .agents/skills/.");
+    console.log("2. Prompt: Use $manage-project-quality. Inspect this repository, determine the current Agent Docs stage, and guide me through the next safe step. Do not infer facts without evidence.");
+    console.log(`3. Check progress: npx @ghostbyte/agent-docs-kit@latest next --cwd "${root}"`);
+  } else {
+    console.log("\nThe skill is now available to supported AI sessions for the current user.");
+    console.log("Open or restart the AI session if it was already running, then invoke $manage-project-quality with a scoped request.");
+  }
   return result;
 }

package/src/commands/workflow.mjs

@@ -0,0 +1,228 @@
+import { readdir, readFile } from "node:fs/promises";
+import { relative, resolve } from "node:path";
+import { loadProjectConfig } from "../core/config.mjs";
+import { exists } from "../core/files.mjs";
+
+export const npxCommand = "npx @ghostbyte/agent-docs-kit@latest";
+
+const startModes = Object.freeze({
+  new: {
+    title: "New or empty project",
+    summary: "Create the documentation structure first, then record plans without presenting them as implemented facts.",
+    steps: [
+      `${npxCommand} doctor`,
+      `${npxCommand} setup --dry-run`,
+      `${npxCommand} setup`,
+      "Describe the intended users, scope, architecture, and operating assumptions in docs/.",
+      `${npxCommand} audit documentation --strict --report --format markdown`,
+      `${npxCommand} next`
+    ],
+    note: "For a new project, label unimplemented behavior as planned or proposed. Do not create security Pass results without evidence."
+  },
+  existing: {
+    title: "Existing project",
+    summary: "Add the scaffold without overwriting existing files, then reconcile it with code, configuration, tests, and deployment evidence.",
+    steps: [
+      `${npxCommand} doctor`,
+      `${npxCommand} setup --dry-run`,
+      `${npxCommand} setup`,
+      "Choose AI-assisted or manual completion below.",
+      `${npxCommand} audit documentation --strict --report --format markdown`,
+      `${npxCommand} next`
+    ],
+    note: "Setup skips existing files by default. Review every generated placeholder before treating the documentation as current."
+  },
+  agent: {
+    title: "AI-assisted workflow",
+    summary: "Install the repository-scoped skill, start a fresh AI session if necessary, and give the agent an evidence-bounded request.",
+    steps: [
+      `${npxCommand} setup --dry-run`,
+      `${npxCommand} setup`,
+      `${npxCommand} skill install --target project`,
+      "Open or restart your AI coding session so it can discover .agents/skills/.",
+      "Prompt: Use $manage-project-quality. Inspect this repository, determine the current Agent Docs stage, and guide me through the next safe step. Do not infer facts without evidence.",
+      `${npxCommand} next`
+    ],
+    note: "Giving an AI only the npm package name does not grant authority or perform an audit. The agent should inspect the repository, explain proposed writes, and request authorization before active security testing."
+  },
+  manual: {
+    title: "Manual workflow",
+    summary: "Use the CLI as a reference and record generator; complete and verify every document or worksheet yourself.",
+    steps: [
+      `${npxCommand} setup --dry-run`,
+      `${npxCommand} setup`,
+      `${npxCommand} list documentation`,
+      `${npxCommand} documentation guide system-documentation`,
+      "Replace scaffold prompts with verified project facts and cite the source of each important claim.",
+      `${npxCommand} audit documentation --strict --report`,
+      `${npxCommand} next`
+    ],
+    note: "For security and engineering work, list the available scopes first, create one worksheet, then replace Unverified only when evidence supports the result."
+  }
+});
+
+function renderStart(path) {
+  return `\n${path.title}\n${"=".repeat(path.title.length)}\n${path.summary}\n\nWorking path\n${path.steps.map((step, index) => `${index + 1}. ${step}`).join("\n")}\n\nImportant\n${path.note}\n\nCommands above use npx. After a global install, replace '${npxCommand}' with 'agent-docs'.`;
+}
+
+export function startWorkflow(mode) {
+  const normalized = mode === "ai" ? "agent" : mode;
+  if (normalized) {
+    const path = startModes[normalized];
+    if (!path) throw new Error(`Unknown start path '${mode}'. Use new, existing, agent, or manual.`);
+    const text = renderStart(path);
+    console.log(text);
+    return { mode: normalized, ...path, text };
+  }
+
+  const text = `\nChoose your starting path\n=========================\n1. New project      ${npxCommand} start new\n2. Existing project ${npxCommand} start existing\n3. Use an AI agent  ${npxCommand} start agent\n4. Work manually    ${npxCommand} start manual\n\nNot sure? Run '${npxCommand} next' to inspect the current project and receive one recommended next step.\n\nInstallation alone changes nothing. Setup creates only the owned scaffold, and existing files are skipped unless --force is explicit.`;
+  console.log(text);
+  return { mode: undefined, paths: Object.keys(startModes), text };
+}
+
+async function markdownFiles(directory) {
+  if (!(await exists(directory))) return [];
+  const found = [];
+  for (const item of await readdir(directory, { withFileTypes: true })) {
+    const path = resolve(directory, item.name);
+    if (item.isDirectory()) found.push(...await markdownFiles(path));
+    else if (item.isFile() && item.name.toLowerCase().endsWith(".md")) found.push(path);
+  }
+  return found;
+}
+
+async function regularFiles(directory) {
+  if (!(await exists(directory))) return [];
+  const found = [];
+  for (const item of await readdir(directory, { withFileTypes: true })) {
+    const path = resolve(directory, item.name);
+    if (item.isDirectory()) found.push(...await regularFiles(path));
+    else if (item.isFile() && item.name !== ".gitkeep") found.push(path);
+  }
+  return found;
+}
+
+async function filesContaining(paths, pattern) {
+  const matching = [];
+  for (const path of paths) {
+    const value = await readFile(path, "utf8");
+    if (pattern.test(value)) matching.push(path);
+  }
+  return matching;
+}
+
+function renderNext(result) {
+  const lines = [
+    `\nStage ${result.stage}: ${result.title}`,
+    "=".repeat(`Stage ${result.stage}: ${result.title}`.length),
+    result.summary,
+    "",
+    "Detected"
+  ];
+  lines.push(...result.detected.map((item) => `- ${item}`), "", "Next actions");
+  lines.push(...result.actions.map((item, index) => `${index + 1}. ${item}`));
+  if (result.note) lines.push("", "Why this stage", result.note);
+  lines.push("", `Re-run '${npxCommand} next' after completing these actions.`);
+  return lines.join("\n");
+}
+
+function nextResult(stage, title, summary, detected, actions, note) {
+  const result = { stage, title, summary, detected, actions, note };
+  result.text = renderNext(result);
+  console.log(result.text);
+  return result;
+}
+
+export async function nextWorkflow(options = {}) {
+  const root = resolve(options.cwd ?? process.cwd());
+  const configPath = resolve(root, ".agent-docs", "config.json");
+  if (!(await exists(configPath))) {
+    return nextResult(1, "Initialize safely", "No Agent Docs workspace was found in this project.", [
+      `Target: ${root}`,
+      "Configuration: not found"
+    ], [
+      `${npxCommand} setup --cwd "${root}" --dry-run`,
+      `${npxCommand} setup --cwd "${root}"`,
+      `Choose a completion path with '${npxCommand} start agent' or '${npxCommand} start manual'.`
+    ], "The preview shows every planned file. The real setup skips existing files by default.");
+  }
+
+  const { config } = await loadProjectConfig(root);
+  const missing = [];
+  for (const path of config.requiredDocuments) if (!(await exists(resolve(root, path)))) missing.push(path);
+  if (missing.length) {
+    return nextResult(2, "Complete the scaffold", "The workspace is configured, but one or more required documents are missing.", [
+      "Configuration: found",
+      `Missing required documents: ${missing.join(", ")}`
+    ], [
+      `${npxCommand} setup --cwd "${root}" --dry-run`,
+      `${npxCommand} setup --cwd "${root}"`
+    ], "Setup restores only missing owned files unless --force is explicitly supplied.");
+  }
+
+  const documentationFiles = await markdownFiles(resolve(root, config.documentationRoot));
+  const placeholders = await filesContaining(documentationFiles, /Status:\s*Needs update|Describe the system boundary|Track requirements|Document setup, deployment/i);
+  const skillInstalled = await exists(resolve(root, ".agents", "skills", "manage-project-quality", "SKILL.md"));
+  if (placeholders.length) {
+    const relativePlaceholders = placeholders.slice(0, 4).map((path) => relative(root, path));
+    return nextResult(3, "Build the documentation baseline", "The scaffold exists, but starter prompts still need verified project information.", [
+      `Starter documents needing work: ${relativePlaceholders.join(", ")}${placeholders.length > 4 ? ` (+${placeholders.length - 4} more)` : ""}`,
+      `Project AI skill: ${skillInstalled ? "installed" : "not installed"}`
+    ], [
+      skillInstalled
+        ? "Ask your AI: Use $manage-project-quality to inspect this repository and update the documentation baseline from repository evidence. Keep unknowns explicit."
+        : `AI-assisted path: ${npxCommand} skill install --target project --cwd "${root}"`,
+      `Manual path: ${npxCommand} list documentation`,
+      `${npxCommand} documentation guide system-documentation`,
+      "Replace generated prompts with evidence-backed facts; label planned behavior as planned."
+    ], "Setup creates a structure, not complete documentation. A structural audit can pass while the content is still incomplete.");
+  }
+
+  const documentationReports = await regularFiles(resolve(root, config.documentationReports));
+  if (!documentationReports.length) {
+    return nextResult(4, "Verify documentation", "The baseline no longer contains starter prompts. Run the structural checks and save the result.", [
+      `Documentation files: ${documentationFiles.length}`,
+      "Saved documentation audit: not found"
+    ], [
+      `${npxCommand} audit documentation --cwd "${root}" --strict --report --format markdown`,
+      "Review every failure and rerun the audit until the result matches the intended release standard."
+    ], "This audit checks structure, metadata, placeholders, and local links. It does not prove that every statement is factually correct.");
+  }
+
+  const securityReports = await markdownFiles(resolve(root, config.securityReports));
+  const engineeringReports = await markdownFiles(resolve(root, config.engineeringReports));
+  const openReports = await filesContaining([...securityReports, ...engineeringReports], /Overall status:\s*Unverified|\|\s*Unverified\s*\|/i);
+  if (openReports.length) {
+    return nextResult(5, "Complete the open review", "A generated worksheet still contains Unverified results and needs evidence or an explicit N/A rationale.", [
+      ...openReports.slice(0, 5).map((path) => `Open: ${relative(root, path)}`)
+    ], [
+      "Inspect the named report and collect code, configuration, test, metric, or authorized environment evidence.",
+      "Assign only the allowed status values; record remediation, owner, and verification for actionable findings.",
+      skillInstalled ? "Ask your AI to use $manage-project-quality for the report's single selected scope." : `${npxCommand} skill install --target project --cwd "${root}" (optional AI assistance)`
+    ], "Creating a worksheet does not perform a review. All findings intentionally begin as Unverified.");
+  }
+
+  if (!securityReports.length && !engineeringReports.length) {
+    return nextResult(5, "Choose a focused quality review", "Documentation is initialized and audited. Security and engineering reviews are optional and should be selected by current risk or project need.", [
+      `Saved documentation audits: ${documentationReports.length}`,
+      "Security worksheets: none",
+      "Engineering worksheets: none"
+    ], [
+      `${npxCommand} list security`,
+      `${npxCommand} security worksheet <phase>`,
+      `${npxCommand} list engineering`,
+      `${npxCommand} engineering worksheet <topic>`
+    ], "Select one narrow scope. Active security testing requires explicit authorization for the exact target.");
+  }
+
+  return nextResult(6, "Maintain the project record", "The workspace has documentation evidence and no open generated worksheet was detected.", [
+    `Documentation audits: ${documentationReports.length}`,
+    `Security worksheets: ${securityReports.length}`,
+    `Engineering worksheets: ${engineeringReports.length}`,
+    `Project AI skill: ${skillInstalled ? "installed" : "not installed"}`
+  ], [
+    `${npxCommand} audit documentation --cwd "${root}" --strict`,
+    "Create ADRs, change records, test evidence, runbooks, or incident reviews when the project changes.",
+    "Revisit focused security and engineering scopes before material releases."
+  ], "Keep the records aligned with code and operations; a previous audit is evidence from a point in time, not a permanent guarantee.");
+}

package/tests/cli.test.mjs

@@ -1,5 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
 import { access, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -14,6 +15,7 @@ import { validateReport } from "../skills/manage-project-quality/scripts/check-r
 import { showDocumentationGuide } from "../src/commands/guide.mjs";
 import { installSkill } from "../src/commands/skill.mjs";
 import { main } from "../src/cli/main.mjs";
+import { nextWorkflow, startWorkflow } from "../src/commands/workflow.mjs";
 
 test("setup is explicit, non-destructive, and repeatable", async () => {
   const root = await mkdtemp(join(tmpdir(), "agent-docs-kit-"));
@@ -29,6 +31,67 @@ test("setup is explicit, non-destructive, and repeatable", async () => {
   }
 });
 
+test("guided starts explain all human and agent onboarding paths", () => {
+  const overview = startWorkflow();
+  assert.deepEqual(overview.paths, ["new", "existing", "agent", "manual"]);
+  const agent = startWorkflow("agent");
+  assert.match(agent.text, /skill install --target project/);
+  assert.match(agent.text, /Do not infer facts without evidence/);
+  assert.throws(() => startWorkflow("unknown"), /Use new, existing, agent, or manual/);
+});
+
+test("next derives progress from project state without writing a progress file", async () => {
+  const root = await mkdtemp(join(tmpdir(), "agent-docs-kit-"));
+  try {
+    const empty = await nextWorkflow({ cwd: root });
+    assert.equal(empty.stage, 1);
+    assert.match(empty.text, /setup --cwd/);
+    await setupProject({ cwd: root });
+    const baseline = await nextWorkflow({ cwd: root });
+    assert.equal(baseline.stage, 3);
+    assert.match(baseline.text, /AI-assisted path/);
+    await assert.rejects(access(join(root, ".agent-docs", "state.json")));
+  } finally { await rm(root, { recursive: true, force: true }); }
+});
+
+test("next recognizes documentation reports in every supported output format", async () => {
+  const root = await mkdtemp(join(tmpdir(), "agent-docs-kit-"));
+  try {
+    await setupProject({ cwd: root });
+    await writeFile(join(root, "docs", "01-system", "overview.md"), "# System overview\n\nVerified system facts.\n");
+    await writeFile(join(root, "docs", "02-project", "README.md"), "# Project\n\nVerified project status.\n");
+    await writeFile(join(root, "docs", "05-operations", "README.md"), "# Operations\n\nVerified operating procedure.\n");
+    await auditDocumentation({ cwd: root, report: true, format: "json" });
+    const result = await nextWorkflow({ cwd: root });
+    assert.equal(result.stage, 5);
+    assert.match(result.text, /Saved documentation audits: 1/);
+  } finally { await rm(root, { recursive: true, force: true }); }
+});
+
+test("next covers the complete repository-backed workflow lifecycle", async () => {
+  const root = await mkdtemp(join(tmpdir(), "agent-docs-kit-"));
+  try {
+    const stages = [];
+    stages.push((await nextWorkflow({ cwd: root })).stage);
+    await setupProject({ cwd: root });
+    await rm(join(root, "docs", "01-system", "overview.md"));
+    stages.push((await nextWorkflow({ cwd: root })).stage);
+    await setupProject({ cwd: root });
+    stages.push((await nextWorkflow({ cwd: root })).stage);
+    await writeFile(join(root, "docs", "01-system", "overview.md"), "# System overview\n\nVerified system facts.\n");
+    await writeFile(join(root, "docs", "02-project", "README.md"), "# Project\n\nVerified project status.\n");
+    await writeFile(join(root, "docs", "05-operations", "README.md"), "# Operations\n\nVerified operating procedures.\n");
+    stages.push((await nextWorkflow({ cwd: root })).stage);
+    await auditDocumentation({ cwd: root, report: true, format: "markdown" });
+    stages.push((await nextWorkflow({ cwd: root })).stage);
+    const report = await auditSecurity("api-layer", { cwd: root });
+    stages.push((await nextWorkflow({ cwd: root })).stage);
+    await writeFile(report.path, (await readFile(report.path, "utf8")).replaceAll("Unverified", "Pass"));
+    stages.push((await nextWorkflow({ cwd: root })).stage);
+    assert.deepEqual(stages, [1, 2, 3, 4, 5, 5, 6]);
+  } finally { await rm(root, { recursive: true, force: true }); }
+});
+
 test("forced setup atomically replaces owned files without leaving staging artifacts", async () => {
   const root = await mkdtemp(join(tmpdir(), "agent-docs-kit-"));
   try {
@@ -216,6 +279,8 @@ test("help distinguishes no-install, local, and global command forms", () => {
   assert.match(helpText, /agent-docs --version/);
   assert.match(helpText, /npm view @ghostbyte\/agent-docs-kit version/);
   assert.match(helpText, /npm install --global @ghostbyte\/agent-docs-kit@latest/);
+  assert.match(helpText, /start \[new\|existing\|agent\|manual\]/);
+  assert.match(helpText, /next\s+Detect project state/);
 });
 
 test("website provides a complete installation guide without a GitHub header button", async () => {
@@ -228,6 +293,13 @@ test("website provides a complete installation guide without a GitHub header but
   assert.match(site, /documentation guide/);
   assert.match(site, /role="tab" aria-selected="true" aria-controls="code-panel-setup"/);
   assert.match(site, /If <code>agent-docs<\/code> is not recognized/);
+  assert.match(site, /Choose a path, then let the kit show what comes next/);
+  assert.match(site, /start \[new\|existing\|agent\|manual\]/);
+  assert.match(site, /The package is context, not automatic authority/);
+  assert.match(site, /The kit supplies project memory and review rules/);
+  assert.match(site, /does not bundle an AI model or start a background service/);
+  assert.match(site, /This can reduce unnecessary context and token usage/);
+  assert.match(site, /Actual token use still depends on the agent, repository, and requested scope/);
   assert.doesNotMatch(site, /View on GitHub/);
   assert.doesNotMatch(site, /git clone https:\/\/github\.com\/ghostbyte1014\/Agent_Docs_Kit\.git/);
   assert.doesNotMatch(site, /Run the repository source/);
@@ -240,3 +312,20 @@ test("website provides a complete installation guide without a GitHub header but
   assert.ok(installationGuide < packageContents, "package details should follow installation");
   assert.ok(packageContents < cliReference, "the complete CLI reference should be the final main section");
 });
+
+test("site preview builds first and the artifact exposes only public documentation", async () => {
+  const projectRoot = join(import.meta.dirname, "..");
+  const metadata = JSON.parse(await readFile(join(projectRoot, "package.json"), "utf8"));
+  assert.match(metadata.scripts["site:preview"], /^npm run build && /);
+  execFileSync(process.execPath, ["scripts/build-site.mjs"], { cwd: projectRoot, stdio: "pipe" });
+  const builtDocs = (await readdir(join(projectRoot, "build", "site", "docs"))).sort();
+  assert.deepEqual(builtDocs, [
+    "ARCHITECTURE.md",
+    "CONTENT_MAINTENANCE.md",
+    "GITHUB_AND_NPM_SETUP.md",
+    "PURPOSE.md",
+    "RELEASE_PROCESS.md",
+    "SECURITY_MODEL.md"
+  ]);
+  await assert.rejects(access(join(projectRoot, "build", "site", "docs", "README.md")));
+});