archgen-skill 0.1.1 → 0.1.2

package/lib/node_modules/archgen-mcp/src/tools/_register.mjs

@@ -0,0 +1,120 @@
+// _register.mjs — one place where a tool becomes an MCP tool.
+//
+// Every archgen tool follows the same contract:
+//   - a Zod input schema (the only thing the model must get right)
+//   - a handler that returns a plain payload or throws a typed ArchgenError
+//   - the response is ALWAYS the envelope (ok / data / error / meta)
+//
+// Registering through one helper is what keeps the catalog uniform — and the
+// catalog is what every client injects into the model's context, so its shape
+// matters as much as the tool logic.
+import { z } from 'zod/v4';
+import { guard, toToolResult } from '../envelope.mjs';
+import { Context } from '../context.mjs';
+
+/** The envelope, as seen by the client. Loose so `data` can be any shape. */
+export const envelopeSchema = z
+  .object({
+    ok: z.boolean(),
+    data: z.unknown().optional(),
+    error: z
+      .object({
+        code: z.string(),
+        message: z.string(),
+        details: z.record(z.string(), z.unknown()).optional(),
+      })
+      .optional(),
+    meta: z.record(z.string(), z.unknown()),
+  })
+  .loose();
+
+/**
+ * Every registered tool, keyed by name.
+ *
+ * The CLI facade (`archgen-mcp exec <tool> '<json>'`) drives the SAME
+ * handlers the MCP server exposes — there is no second implementation of any
+ * tool, only a second way to reach it.
+ */
+const SPECS = new Map();
+
+/**
+ * Look up a registered tool spec by name.
+ * @param {string} name
+ */
+export function getToolSpec(name) {
+  return SPECS.get(name) ?? null;
+}
+
+/** Every registered tool name. */
+export function registeredToolNames() {
+  return [...SPECS.keys()];
+}
+
+/**
+ * Register one tool on the server.
+ *
+ * @param {import('@modelcontextprotocol/server').McpServer} server
+ * @param {string} name tool name
+ * @param {{
+ *   title: string,
+ *   description: string,
+ *   inputSchema: z.ZodObject<any>,
+ *   handler: (ctx: Context, args: any) => unknown|Promise<unknown>,
+ *   readOnly?: boolean,
+ *   destructive?: boolean,
+ *   idempotent?: boolean,
+ * }} spec
+ */
+export function registerTool(server, name, spec) {
+  SPECS.set(name, spec);
+  server.registerTool(
+    name,
+    {
+      title: spec.title,
+      description: spec.description,
+      inputSchema: spec.inputSchema,
+      outputSchema: envelopeSchema,
+      annotations: {
+        readOnlyHint: spec.readOnly === true,
+        destructiveHint: spec.destructive === true,
+        idempotentHint: spec.idempotent === true,
+        openWorldHint: false,
+      },
+    },
+    async (args, extra) => {
+      // A tool may target a directory inside the project (a monorepo package,
+      // a worktree under it). The projectRoot argument SELECTS one; it does
+      // not define the boundary. The server's anchor does, and a selection
+      // outside it is refused with PERMISSION_DENIED.
+      const base = extra?.archgenContext ?? serverContext();
+      const requested = args?.projectRoot;
+      const ctx =
+        typeof requested === 'string' && requested.trim() !== ''
+          ? base.withProjectRoot(requested)
+          : base;
+      const envelope = await guard(spec.handler, ctx, args ?? {});
+      return toToolResult(envelope);
+    },
+  );
+}
+
+/** The process-wide context (project root = cwd unless overridden). */
+let cachedContext = null;
+export function serverContext() {
+  if (!cachedContext) cachedContext = new Context();
+  return cachedContext;
+}
+
+/** Reset the cached context (tests). */
+export function resetServerContext() {
+  cachedContext = null;
+}
+
+/**
+ * A common argument for every tool that touches the project.
+ * Optional: when omitted the server's own project root (cwd) applies.
+ */
+export const projectRootArg = z
+  .string()
+  .optional()
+  .describe('Absolute path to the project root. Defaults to the server working directory.');

package/lib/node_modules/archgen-mcp/src/tools/codegraph.mjs

@@ -0,0 +1,53 @@
+// codegraph.mjs — the `archgen_codegraph` tool: install + wire + index
+// CodeGraph (and CodeGraph's own MCP server).
+//
+// The tool DRIVES the official CodeGraph CLI — it never reimplements it. The
+// MCP-config writing goes through the shared harness-wiring module, so the
+// archgen MCP and the CodeGraph MCP are wired by the same code.
+import { z } from 'zod/v4';
+import { registerTool, projectRootArg } from './_register.mjs';
+import { loadAsset } from '../context.mjs';
+import { manageCodegraph, assertLocation } from '../core/codegraph-manager.mjs';
+
+const ACTION_DESC = 'ensure | status | wire — see archgen_help.';
+
+const schema = z.object({
+  action: z.enum(['ensure', 'status', 'wire']).describe(ACTION_DESC),
+  location: z.enum(['project', 'global', 'both']).optional().describe('Which scope to wire. Defaults to both.'),
+  approve: z.boolean().optional().describe('Required to write any MCP config. Without it you get the plan and nothing is written.'),
+  telemetry: z.enum(['keep', 'off', 'on']).optional().describe('Telemetry preference. Defaults to keep (leave as-is).'),
+  noInstall: z.boolean().optional().describe('Do not install the CLI; use the npx fallback in configs.'),
+  projectRoot: projectRootArg,
+});
+
+/**
+ * @param {import('@modelcontextprotocol/server').McpServer} server
+ */
+export function registerCodegraphTools(server) {
+  registerTool(server, 'archgen_codegraph', {
+    title: 'ArchGen CodeGraph',
+    description:
+      'Install, wire and index CodeGraph — the source-symbol index — and its MCP server. ' +
+      'Run once per project when .codegraph/ is missing; the index stays live afterwards, so never re-index.',
+    inputSchema: schema,
+    readOnly: false,
+    destructive: false,
+    idempotent: true,
+    handler: async (ctx, args) => {
+      const registry = loadAsset('harness-mcp.json');
+      const location = assertLocation(args.location ?? 'both');
+      const mode = args.action === 'status' ? 'status' : args.action === 'wire' ? 'wire' : 'ensure';
+      return manageCodegraph({
+        mode,
+        projectRoot: ctx.projectRoot,
+        registry,
+        location,
+        approved: args.approve === true,
+        telemetry: args.telemetry ?? 'keep',
+        noInstall: args.noInstall === true,
+        home: ctx.home,
+        env: ctx.env,
+      });
+    },
+  });
+}

package/lib/node_modules/archgen-mcp/src/tools/docs.mjs

@@ -0,0 +1,113 @@
+// docs.mjs — the `archgen_docs` tool: navigate the markdown artifacts under
+// `.archgen/<slug>/`.
+import { z } from 'zod/v4';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { registerTool, projectRootArg } from './_register.mjs';
+import { docIndex } from '../core/doc-navigator.mjs';
+import { invalidInput } from '../core/errors.mjs';
+import { hint, teach } from '../core/guidance.mjs';
+
+const ACTION_DESC = 'index | digest | section | refs | map | validate — see archgen_help.';
+
+const schema = z.object({
+  action: z.enum(['index', 'digest', 'section', 'refs', 'map', 'validate']).describe(ACTION_DESC),
+  slugDir: z
+    .string()
+    .optional()
+    .describe('Absolute path to the .archgen/<slug>/ directory. Defaults to the active slug under the project root.'),
+  token: z.string().optional().describe('The token to look for (refs, map).'),
+  section: z.string().optional().describe('Section path, optionally path#anchor (section).'),
+  file: z.string().optional().describe('Scope to one document (repo-root-relative or slug-relative).'),
+  projectRoot: projectRootArg,
+});
+
+/**
+ * @param {import('@modelcontextprotocol/server').McpServer} server
+ */
+export function registerDocTools(server) {
+  registerTool(server, 'archgen_docs', {
+    title: 'ArchGen docs',
+    description:
+      'Navigate the markdown artifacts of an archgen plan without pulling whole files into context. ' +
+      'Prefer digest + section over reading a document end to end.',
+    inputSchema: schema,
+    readOnly: true,
+    idempotent: true,
+    handler: (ctx, args) => {
+      const slugDir = resolveSlugDir(ctx, args.slugDir);
+      switch (args.action) {
+        case 'index':
+          return docIndex(slugDir, { mode: 'overview', file: args.file ?? null, projectRoot: ctx.projectRoot });
+        case 'digest':
+          return docIndex(slugDir, { mode: 'digest', file: args.file ?? null, projectRoot: ctx.projectRoot });
+        case 'validate':
+          return docIndex(slugDir, { mode: 'validate', file: args.file ?? null, projectRoot: ctx.projectRoot });
+        case 'refs':
+          if (!args.token) throw invalidInput('refs requires a token', { action: args.action });
+          return docIndex(slugDir, { mode: 'refs', token: args.token, file: args.file ?? null, projectRoot: ctx.projectRoot });
+        case 'map':
+          if (!args.token) throw invalidInput('map requires a token', { action: args.action });
+          return docIndex(slugDir, { mode: 'map', token: args.token, file: args.file ?? null, projectRoot: ctx.projectRoot });
+        case 'section':
+          if (!args.section) throw invalidInput('section requires a section path', { action: args.action });
+          return docIndex(slugDir, { mode: 'section', section: args.section, file: args.file ?? null, projectRoot: ctx.projectRoot });
+        default:
+          throw invalidInput(`unknown action '${args.action}'`, { action: args.action });
+      }
+    },
+  });
+}
+
+/**
+ * Resolve the slug directory: explicit argument, else the most recently
+ * modified `.archgen/<slug>/` under the project root.
+ * @param {import('../context.mjs').Context} ctx
+ * @param {string|undefined} explicit
+ */
+export function resolveSlugDir(ctx, explicit) {
+  if (explicit) return ctx.contain(explicit);
+  const active = activeSlugDir(ctx);
+  if (!active) {
+    throw invalidInput(
+      teach(
+        `no .archgen/<slug>/ directory under ${ctx.projectRoot}`,
+        'scaffold returns file CONTENT and writes nothing, so write it first',
+        "archgen_plan{action:'scaffold',scope:'LARGE',slug:'<slug>'}",
+      ),
+      hint({
+        action: "archgen_plan{action:'scaffold',scope:'LARGE',slug:'<slug>'}",
+        reason: 'scaffold returns content; you write it.',
+      }),
+    );
+  }
+  return active;
+}
+
+/**
+ * Find the active `.archgen/<slug>/` directory (most recently modified).
+ * @param {import('../context.mjs').Context} ctx
+ * @returns {string|null}
+ */
+export function activeSlugDir(ctx) {
+  const archgenDir = join(ctx.projectRoot, '.archgen');
+  if (!existsSync(archgenDir)) return null;
+  let best = null;
+  let bestMtime = -1;
+  for (const ent of readdirSync(archgenDir, { withFileTypes: true })) {
+    if (!ent.isDirectory()) continue;
+    const dir = join(archgenDir, ent.name);
+    if (!existsSync(join(dir, 'tasks.yaml'))) continue;
+    let mtime = 0;
+    try {
+      mtime = statSync(join(dir, 'tasks.yaml')).mtimeMs;
+    } catch {
+      continue;
+    }
+    if (mtime > bestMtime) {
+      bestMtime = mtime;
+      best = dir;
+    }
+  }
+  return best;
+}

package/lib/node_modules/archgen-mcp/src/tools/help.mjs

@@ -0,0 +1,284 @@
+// help.mjs — the `archgen_help` tool: progressive disclosure.
+//
+// The skill used to carry every procedural detail inline, which meant every
+// agent paid for it in every session whether it needed it or not. The detail
+// lives HERE now and is fetched only when the agent actually needs it.
+//
+// This is the single largest context saving in the whole design: SKILL.md
+// keeps the orchestration rules, and the "how exactly do I do X" knowledge
+// arrives on demand.
+import { z } from 'zod/v4';
+import { registerTool, projectRootArg } from './_register.mjs';
+
+const TOPICS = {
+  plan: `# archgen_plan
+
+Validates and analyzes a plan (tasks.yaml + plans/).
+
+**When to call**
+- After writing or editing tasks.yaml — before anything else.
+- Before the verifier gate (action \`verify\`).
+- When you need the dependency graph (\`graph\`) or the blast radius of a change (\`impact\`).
+
+**Actions**
+| action | what it does | required args |
+|---|---|---|
+| \`validate\` | schema, dependency cycles, dangling refs, ownership, acceptance criteria | tasksYaml, planDir? |
+| \`verify\` | the deterministic verifier gate — returns APPROVE or ISSUES | tasksYaml, planDir |
+| \`coverage\` | which tasks the plans cover and which they miss | tasksYaml, planDir |
+| \`scaffold\` | the REQUIRED artifact set + skeletons for a scope class | scope, slug? |
+| \`brief\` | the dispatch brief for a sub-agent — carries the evidence map, the graph and the docs-validate result already rendered | kind, tasksYaml? |
+| \`graph\` | dependency graph; \`format:'mermaid'\` for a diagram | tasksYaml, node?, module?, format?, status? |
+| \`impact\` | direct + transitive dependents of a task id or artifact path | tasksYaml, target |
+
+**Reading the result**
+- The envelope's \`ok\` says whether the CALL succeeded. The plan's health is \`data.valid\`
+  (and \`data.verdict\` for verify). A call that reports a broken plan is still \`ok:true\`.
+- \`data.valid:false\` with a non-empty \`errors\` array means the plan is broken — fix every
+  error, then re-run. Never proceed past the gate with errors outstanding.
+- \`warnings\` never block. Unknown keys and an unknown root key are warnings, not errors.
+- \`verify\` returning ISSUES is a gate failure: fix and re-verify (max two automatic rounds, then ask the user).
+
+**Gotchas**
+- \`status\` only applies to mermaid output.
+- \`module\` cannot be combined with \`node\` or mermaid.
+- Whole-graph mermaid is refused above 250 nodes — scope it with \`node\` or \`module\`.
+- \`scaffold\` returns the artifact set a scope class MUST have — adding or dropping files is a right-sizing defect. It returns each file's CONTENT and **writes nothing**: you write them under \`.archgen/<slug>/\`, then the artifact tools can read them.
+- \`brief\` returns a ready-to-send sub-agent prompt (verifier | review | survey | investigate). It derives the slug from \`tasksYaml\` when you do not pass one, and every path in it is ABSOLUTE — so it works from any working directory. The verifier and review briefs carry the graph, the reference-integrity result and the evidence map rendered, so the sub-agent makes no tool call of its own.
+- The verifier and reviewer return \`VERDICT:\` plus a COVERAGE table (every dimension PASS / FAIL / N-A). A report with findings but no coverage table is INCOMPLETE.
+- **Every error carries the next call.** If one fails, read the \`Next:\` line in the message — it is the exact call to make, and the \`Why:\` clause says why. Do not retry the same call.
+- **Batch calls with \`allSettled\`**, not \`all\`: one bad argument must not discard the results of its siblings.`,
+
+  tasks: `# archgen_tasks
+
+The wave execution loop.
+
+**When to call**
+- \`next\` at the start of every wave, and after every wave settles.
+- \`set_status\` the moment a task finishes — same turn, never batched.
+- \`snapshot\` after each wave: it writes the compaction-safe resume file.
+
+**Actions**
+| action | what it does | required args |
+|---|---|---|
+| \`next\` | resolves the dependency frontier into waves | tasksYaml |
+| \`set_status\` | atomically sets one task status | tasksYaml, taskId, status, force? |
+| \`list\` | flat task list, filterable | tasksYaml, filterStatus?, module? |
+| \`snapshot\` | writes \`.archgen/<slug>/.agent/resume.md\` | tasksYaml |
+| \`contract\` | assembles the FULL worker prompt for one task | tasksYaml, taskId, slugDir? |
+
+**Status discipline (non-negotiable)**
+After EVERY task completes, in the SAME turn:
+1. \`set_status\` to \`done\` or \`failed\` — and VERIFY it landed.
+2. Mark the tracker/todo item completed.
+3. \`archgen_registry { action: 'update' }\`.
+
+Dispatching the next wave while any of those lag is forbidden.
+
+**Gotchas**
+- Moving a task OUT of \`done\` needs \`force: true\` — reopening completed work requires explicit intent.
+- \`next\` fails with CYCLE or OWNERSHIP_CONFLICT when the plan is broken; fix tasks.yaml, do not work around it.
+- \`blockedByFailure\` lists tasks excluded because an upstream task failed. They are not retried automatically.
+- \`contract\` is the worker prompt — use it instead of assembling one by hand. It carries the acceptance criteria VERBATIM, the owned files, the dependency neighbourhood, the pre-located doc sections, EVERY matched capability skill with its RULES inline, the CodeGraph directive, and the rules the worker must not break.
+- \`contract\` warns when a REQUIRED capability skill is not installed yet — install it before dispatching.
+- \`contract\` returns a \`dispatchKey\`. Keep a ledger of \`dispatchKey → agent session\` so a follow-up CONTINUES that agent instead of starting a fresh one.
+- MAX 3 parallel workers at a time. A larger wave runs in batches of three.`,
+
+  docs: `# archgen_docs
+
+Navigates the markdown artifacts under \`.archgen/<slug>/\`.
+
+**Context economics — read this first.** Pull SECTIONS, not files. A whole plan can be 20k tokens; the sections
+you need are usually a few hundred. \`digest\` gives you the section index, \`section\` fetches exactly one section.
+
+**Actions**
+| action | what it does | required args |
+|---|---|---|
+| \`digest\` | compact section index per document — start here | slugDir? |
+| \`section\` | one section — a bare section slug, a \`path\`, or \`path#anchor\` | section, slugDir? |
+| \`map\` | the SECTIONS mentioning a token — "where is this talked about?" | token, slugDir? |
+| \`refs\` | every LINE mentioning a token | token, slugDir? |
+| \`index\` | full document overview with headings | slugDir? |
+| \`validate\` | reference-integrity gate | slugDir? |
+
+**Gotchas**
+- A section may be named by its exact slug, by its title, or by any unambiguous PREFIX of the slug (\`plan-depth\` finds \`plan-depth-by-scope-class\`).
+- A skill that is not installed reports the install call to make.
+- **Batch calls with \`allSettled\`**, not \`all\`: one bad argument must not discard the results of its siblings.
+
+## Gotchas
+- \`map\` is section-level, \`refs\` is line-level. Use \`map\` to navigate, \`refs\` when you need exact lines.
+- \`section\` takes a BARE SECTION SLUG straight from \`digest\` — e.g. \`section:'non-functional-requirements'\`. It resolves the section across the documents. A slug that matches more than one document comes back as an \`ambiguous\` list, not a guess. \`path\` and \`path#anchor\` also work.
+- Anchors are validated against the target document's real heading slugs — a renamed section is a broken anchor, not a silent pass.
+- \`validate\` reports each broken reference once, at its first occurrence.
+- A section that is not found comes back with the list of available sections — one failed call is enough to recover.
+- \`slugDir\` defaults to the most recently modified \`.archgen/<slug>/\` under the project root.`,
+
+  registry: `# archgen_registry
+
+Keeps the \`AGENTS.md\` features registry in sync with \`.archgen/\`.
+
+**When to call**
+- After every task completes (same turn as \`set_status\`).
+- Right after generating a plan, with the new slug and status.
+- Whenever an artifact changes, so the registry never goes stale.
+
+**Actions**
+| action | what it does | required args |
+|---|---|---|
+| \`update\` | rewrites the registry table from \`.archgen/\` | slug?, status? |
+| \`show\` | reads the current registry without writing | — |
+
+**Gotchas**
+- The registry is machine-maintained. Never hand-edit it — edit the \`.archgen/\` state and call \`update\`.
+- \`slug\` and \`status\` must be passed together.
+- The managed block lives between \`<!-- archgen:features:start -->\` and \`<!-- archgen:features:end -->\`; every byte outside it is preserved.`,
+
+  codegraph: `# archgen_codegraph
+
+Installs, wires and indexes CodeGraph — the source-symbol index — and its own MCP server.
+
+**When to call**
+- Once per project, when \`.codegraph/\` is absent: \`ensure\`.
+- To check what is installed: \`status\`.
+- To wire the CodeGraph MCP into detected harnesses without installing: \`wire\`.
+
+**Actions**
+| action | what it does | required args |
+|---|---|---|
+| \`ensure\` | install the CLI if missing + wire the MCP + build the index | projectRoot?, approve? |
+| \`status\` | what is installed / wired / indexed (read-only) | projectRoot? |
+| \`wire\` | wire the MCP into detected harnesses only | projectRoot?, approve? |
+
+**Gotchas**
+- The index is built ONCE per project; the CodeGraph server's watcher keeps it live. Never re-index by hand.
+- MCP-config writes are approval-gated: without \`approve: true\` the tool prints its plan and writes nothing.
+- Only DETECTED harnesses are touched. A harness that is not installed is never modified.
+- CodeGraph telemetry is ON by default on a fresh install and reports a machine ID. It is disclosed in the
+  result — never claim "100% local".`,
+
+  setup: `# archgen_setup
+
+Installation, MCP wiring and health.
+
+**When to call**
+- When the archgen tools are missing from your tool set: run \`npx archgen-skill init\` in the project root,
+  then ask the user to reload the harness.
+- To install the archgen MCP into other harnesses: \`install_mcp\`.
+- To check the install: \`doctor\`.
+
+**Actions**
+| action | what it does | required args |
+|---|---|---|
+| \`doctor\` | health report: skill, MCP wiring, CodeGraph, node, versions | projectRoot? |
+| \`bootstrap\` | wire the archgen MCP + ensure CodeGraph, in one call | projectRoot?, location?, approve? |
+| \`install_mcp\` | write ONLY the archgen MCP entry into detected harnesses | projectRoot?, location?, approve? |
+| \`uninstall_mcp\` | remove the archgen MCP entries this server wrote | projectRoot?, location?, approve? |
+| \`harnesses\` | detected harnesses + the exact config path/key/diff each would get | projectRoot? |
+
+**Gotchas**
+- Every MCP-config write needs \`approve: true\`. Without it you get the PLAN, and nothing is written.
+- \`location\` is \`project\`, \`global\` or \`both\`. Global writes touch files under \$HOME.
+- The four known top-level config keys are \`mcpServers\` / \`servers\` / \`mcp\` / \`context_servers\` — never assume one.
+- \`harness_info\` with no argument DETECTS the harness and returns its row; with an unknown platform it returns the fallback procedure instead of failing.`,
+
+  skills: `# archgen_skills
+
+Matches a task against the capability-skill registry, installs EXACTLY the matched skill, and loads its SKILL.md.
+
+**When to call**
+- Before dispatching a worker whose work touches a registered capability domain (UI, accessibility, motion, design systems).
+- To install a capability skill that the match reported as missing.
+- To load a skill's SKILL.md so you can point a worker at it.
+
+**Actions**
+| action | what it does | required args |
+|---|---|---|
+| \`match\` | which capability skills a task needs (title + summary + file_ownership) | title?, summary?, fileOwnership? |
+| \`install\` | install ONE capability skill | skillId, harness?, global?, approve? |
+| \`installed\` | what is already installed for this project | — |
+| \`load\` | read a skill's SKILL.md, its RULES, or ONE section of it | skillId, section? |
+| \`digest\` | the section index of an installed skill — the lens | skillId |
+| \`list\` | the registry | — |
+
+**Gotchas**
+- Installing needs \`approve: true\`. Without it you get the PLAN and nothing is written.
+- Exactly ONE skill is installed — never a bundle. A task that mentions "animation" gets the motion skill, not the whole UI family.
+- The installer writes \`<project>/.agents/skills/<slug>/SKILL.md\` — that is the file you point a worker at.
+- \`match\` reports \`required\` vs \`on-demand\`: a \`required\` match MUST be installed before dispatch.
+- \`load\` returns the skill's NORMATIVE RULES (the MUST / SHOULD / NEVER lines) and its section index. The rules are what a worker must follow — pull them from here rather than re-reading the file.
+- A skill that is installed but never named in a worker contract is a skill that is never applied. \`archgen_tasks{action:'contract'}\` names EVERY matched required skill.`,
+
+  refs: `# archgen_refs
+
+Loads archgen's OWN protocol documents — the judgment layer: how to interview, what artifacts to write, how to run the gates, how to dispatch workers, what this platform can do.
+
+**When to call**
+- At the START of a mode: the SKILL's mode table names the sections to load, and every \`§\` mark is an obligation.
+- After a compaction: a compaction drops the loaded section — re-load the current mode's sections as part of re-entry.
+- When you are about to guess a protocol's details. Don't — load it.
+
+**Actions**
+| action | what it does | required args |
+|---|---|---|
+| \`list\` | every reference topic with its section count | — |
+| \`index\` | the section list of one topic | topic |
+| \`read\` | ONE section (or the whole topic when no section is given) | topic, section? |
+| \`search\` | the sections mentioning a token | topic, token |
+
+**Gotchas**
+- Load the SECTION, not the topic: a topic is ~11 KB, a section is ~1-2 KB.
+- A section may be named by its exact slug, by its title, or by any unambiguous PREFIX of the slug. The skill's own \`§\` names are prefixes — \`§artifact-templates/plan-depth\` resolves to \`plan-depth-by-scope-class\` — so pass the \`§\` name straight through. Call \`index\` only when a prefix is ambiguous.
+- \`code-standards.md\` is served too when the skill is installed — but WORKERS read it as a plain file, because they may have no MCP server at all.`,
+
+  all: `# archgen — the complete tool surface
+
+Nine tools, one domain each. Call them by name; the server resolves paths, validates input and returns a
+structured result. Every result is \`{ ok, data, error, meta }\` — \`ok:false\` carries a typed \`error.code\`.
+
+| tool | domain | use it for |
+|---|---|---|
+| \`archgen_plan\` | plan | validate / verify / graph / impact / coverage |
+| \`archgen_tasks\` | execution | next wave / set status / list / resume snapshot |
+| \`archgen_docs\` | artifacts | digest, section, map, refs, index, validate |
+| \`archgen_registry\` | registry | refresh / read the AGENTS.md features table |
+| \`archgen_codegraph\` | code index | install + wire + index CodeGraph and its MCP |
+| \`archgen_setup\` | install | doctor / bootstrap / install_mcp / uninstall_mcp / harnesses |
+| \`archgen_skills\` | capability skills | match / install / installed / load / list |
+| \`archgen_refs\` | archgen's protocols | list / index / read / search |
+| \`archgen_help\` | this | a detailed briefing for one domain |
+
+**Error codes**
+\`INVALID_INPUT\` · \`NOT_FOUND\` · \`CYCLE\` · \`OWNERSHIP_CONFLICT\` · \`CONFLICT\` · \`PERMISSION_DENIED\` ·
+\`UNAVAILABLE\` · \`TIMEOUT\` · \`INTERNAL\`
+
+**Call \`archgen_help { topic: "<domain>" }\`** for the full briefing on any one of them.`,
+};
+
+const schema = z.object({
+  topic: z
+    .enum(['plan', 'tasks', 'docs', 'registry', 'codegraph', 'setup', 'skills', 'refs', 'all'])
+    .describe('Which domain to explain.'),
+  projectRoot: projectRootArg,
+});
+
+/**
+ * @param {import('@modelcontextprotocol/server').McpServer} server
+ */
+export function registerHelpTools(server) {
+  registerTool(server, 'archgen_help', {
+    title: 'ArchGen help',
+    description:
+      'Get the detailed briefing for one archgen tool domain — when to call it, every action, and its gotchas. ' +
+      'Call this instead of guessing an argument shape.',
+    inputSchema: schema,
+    readOnly: true,
+    idempotent: true,
+    handler: (ctx, args) => ({
+      topic: args.topic,
+      briefing: TOPICS[args.topic] ?? TOPICS.all,
+    }),
+  });
+}
+
+export { TOPICS };