archgen-skill 0.1.0 → 0.1.2

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

@@ -0,0 +1,176 @@
+// plan.mjs — the `archgen_plan` tool: plan validation & graph analysis.
+//
+// One tool, one action enum. The tool catalog is injected into the model's
+// context by every client, so a single well-described tool with a short action
+// enum costs far less context than five thin tools — and it removes the
+// "which one do I call?" confusion the whole MCP exercise exists to fix.
+import { z } from 'zod/v4';
+import { registerTool, projectRootArg } from './_register.mjs';
+import { loadAsset, BRIEFS_DIR, TEMPLATES_DIR, serverVersion } from '../context.mjs';
+import { buildScaffold } from '../core/scaffold.mjs';
+import { loadBrief, remainingPlaceholders, renderBriefContext, BRIEF_KINDS } from '../core/briefs.mjs';
+import { resolveBriefScope, briefVars } from '../core/brief-scope.mjs';
+import { buildBriefContext } from '../core/brief-context.mjs';
+import { validateTasksYaml } from '../core/validator.mjs';
+import { verifyPlan, planCoverage } from '../core/verifier.mjs';
+import { planGraph } from '../core/plan-grapher.mjs';
+import { analyzeImpact } from '../core/impact-analyzer.mjs';
+import { invalidInput } from '../core/errors.mjs';
+
+// The action list lives in archgen_help (one call away). Repeating it here
+// would tax every request's context for no extra information.
+const ACTION_DESC =
+  'validate | verify | graph | impact | coverage | scaffold | brief — see archgen_help.';
+
+const schema = z.object({
+  action: z.enum(['validate', 'verify', 'graph', 'impact', 'coverage', 'scaffold', 'brief']).describe(ACTION_DESC),
+  tasksYaml: z
+    .string()
+    .optional()
+    .describe('Absolute path to tasks.yaml. Required for validate, verify, impact and coverage.'),
+  planDir: z.string().optional().describe('Absolute path to the plans directory (verify, coverage, brief).'),
+  target: z.string().optional().describe('Task id or artifact path (impact).'),
+  node: z.string().optional().describe('Restrict the graph to one task neighborhood (graph).'),
+  format: z.enum(['json', 'mermaid']).optional().describe('Graph output format. Defaults to json.'),
+  status: z.boolean().optional().describe('Include status styling (graph, mermaid only).'),
+  module: z.string().optional().describe('Restrict the graph to one module (graph).'),
+  scope: z.enum(['SMALL', 'MEDIUM', 'LARGE']).optional().describe('Scope class (scaffold).'),
+  slug: z.string().optional().describe('Project slug (scaffold, brief).'),
+  kind: z.enum(BRIEF_KINDS).optional().describe('Which dispatch brief (brief).'),
+  featureRequest: z
+    .string()
+    .optional()
+    .describe('The feature being requested, in one line (brief). Defaults to the slug.'),
+  topic: z.string().optional().describe('Investigation topic (brief).'),
+  round: z.number().int().positive().optional().describe('Investigation round number (brief).'),
+  projectRoot: projectRootArg,
+});
+
+/**
+ * @param {import('@modelcontextprotocol/server').McpServer} server
+ */
+export function registerPlanTools(server) {
+  registerTool(server, 'archgen_plan', {
+    title: 'ArchGen plan',
+    description:
+      'Validate and analyze an archgen plan (tasks.yaml + plans/). Use after generating or editing a plan, ' +
+      'before the verifier gate, and when you need the dependency graph or the blast radius of a change.',
+    inputSchema: schema,
+    readOnly: true,
+    idempotent: true,
+    handler: (ctx, args) => {
+      const action = args.action;
+
+      switch (action) {
+        case 'validate': {
+          const file = requireTasksYaml(args, ctx);
+          return validateTasksYaml(file, { planDir: args.planDir ? ctx.contain(args.planDir) : null });
+        }
+        case 'verify': {
+          const file = requireTasksYaml(args, ctx);
+          if (!args.planDir) throw invalidInput('verify requires planDir', { action });
+          return verifyPlan(file, ctx.contain(args.planDir));
+        }
+        case 'coverage': {
+          const file = requireTasksYaml(args, ctx);
+          if (!args.planDir) throw invalidInput('coverage requires planDir', { action });
+          return planCoverage(file, ctx.contain(args.planDir));
+        }
+        case 'impact': {
+          const file = requireTasksYaml(args, ctx);
+          if (!args.target) throw invalidInput('impact requires target (a task id or an artifact path)', { action });
+          return analyzeImpact(file, args.target);
+        }
+        case 'scaffold': {
+          if (!args.scope) throw invalidInput('scaffold requires scope (SMALL | MEDIUM | LARGE)', { action });
+          return buildScaffold(loadAsset('depth-ladder.json'), args.scope, {
+            slug: args.slug ?? null,
+            templatesDir: TEMPLATES_DIR,
+            // The generator token carries the RUNNING server's version. The
+            // server knows it exactly, so the artifact records the truth
+            // instead of the agent having to guess, copy or type a version —
+            // and no release ever has to update a version written by hand.
+            generator: `archgen v${serverVersion()}`,
+          });
+        }
+        case 'brief': {
+          if (!args.kind) throw invalidInput('brief requires kind', { action });
+          // The artifact space is resolved from whatever the caller named:
+          // the tasks.yaml it already holds, the plans dir, or the slug alone.
+          //
+          // The slug is DERIVED from the path when the path implies it — the
+          // caller must not have to state the same fact twice. And every path
+          // the brief carries is ABSOLUTE, because a brief is read by a
+          // sub-agent whose working directory is not necessarily the
+          // project's: a project-relative path in a brief resolves against
+          // the SERVER's root and silently points at the wrong tree.
+          const scope = resolveBriefScope({
+            tasksYaml: args.tasksYaml ? ctx.contain(args.tasksYaml) : null,
+            planDir: args.planDir ? ctx.contain(args.planDir) : null,
+            slug: args.slug ?? null,
+            projectRoot: ctx.projectRoot,
+          });
+          const vars = briefVars(scope, {
+            featureRequest: args.featureRequest ?? null,
+            topic: args.topic ?? null,
+            round: args.round ?? null,
+          });
+
+          // The context the brief carries: the evidence map, the pre-rendered
+          // graph and the reference-integrity result.
+          //
+          // RENDERING THEM HERE (instead of telling the orchestrator to
+          // "attach" them) saves two tool calls per gate round, and removes a
+          // dependency on a call that used to fail on every plan.
+          const briefContext = buildBriefContext(args.kind, scope, ctx);
+
+          const { kind, brief } = loadBrief(BRIEFS_DIR, args.kind, vars);
+          // A brief with a placeholder still in it is a brief that would
+          // send a worker looking for a directory named "<slug dir>".
+          const missing = remainingPlaceholders(brief);
+          if (missing.length) {
+            const passable = missing.filter((m) => m === 'topic' || m === 'round');
+            throw invalidInput(
+              `brief '${kind}' is missing ${missing.join(', ')} — pass ${passable.length ? passable.join(', ') : 'the missing values'}`,
+              { action, kind, missing },
+            );
+          }
+          return { kind, brief: `${renderBriefContext(briefContext)}\n${brief}`, scope };
+        }
+        case 'graph': {
+          const input = args.tasksYaml ?? args.planDir;
+          if (!input) throw invalidInput('graph requires tasksYaml (a slug directory or a tasks.yaml path)', { action });
+          const format = args.format ?? 'json';
+          if (format === 'mermaid' && args.module) {
+            throw invalidInput('module cannot combine with mermaid output', { action });
+          }
+          if (args.status && format !== 'mermaid') {
+            throw invalidInput('status requires mermaid output', { action });
+          }
+          return planGraph(ctx.contain(input), {
+            node: args.node ?? null,
+            mermaid: format === 'mermaid',
+            status: args.status === true,
+            module: args.module ?? null,
+            projectRoot: ctx.projectRoot,
+          });
+        }
+        default:
+          // The schema rejects unknown actions before this point; the explicit
+          // default guarantees an unknown action can never fall through into
+          // the wrong branch if validation is ever bypassed.
+          throw invalidInput(`unknown action '${action}'`, { action });
+      }
+    },
+  });
+}
+
+/**
+ * Resolve the tasks.yaml argument, defaulting to the project's active slug.
+ * @param {any} args
+ * @param {import('../context.mjs').Context} ctx
+ */
+function requireTasksYaml(args, ctx) {
+  if (!args.tasksYaml) throw invalidInput('tasksYaml is required for this action', { action: args.action });
+  return ctx.contain(args.tasksYaml);
+}

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

@@ -0,0 +1,62 @@
+// refs.mjs — the `archgen_refs` tool: load archgen's protocol documents.
+//
+// The reference documents are the ORCHESTRATOR's judgment layer: how to
+// interview, what artifacts to write, how to dispatch workers, what this
+// platform can do. They live with the MCP server (so they are always the same
+// version as the tools they describe) and are served HERE, section by section.
+//
+// `code-standards.md` is the exception: it is read by WORKER sub-agents, which
+// may have no MCP tools — so it stays a plain file in the skill directory and
+// the worker contract points at it.
+import { z } from 'zod/v4';
+import { join } from 'node:path';
+import { registerTool, projectRootArg } from './_register.mjs';
+import { ASSETS_DIR } from '../context.mjs';
+import { indexTopic, readTopic, searchTopic, listTopics, REF_TOPICS } from '../core/refs.mjs';
+
+const ACTION_DESC =
+  'list = every reference topic with its section count; ' +
+  'index = the section list of one topic; ' +
+  'read = ONE section (or the whole topic); ' +
+  'search = the sections mentioning a token.';
+
+const schema = z.object({
+  action: z.enum(['list', 'index', 'read', 'search']).describe(ACTION_DESC),
+  topic: z.enum(REF_TOPICS).optional().describe('Which reference (index, read, search).'),
+  section: z.string().optional().describe('Section slug or heading (read). Omit for the whole topic.'),
+  token: z.string().optional().describe('The token to look for (search).'),
+  projectRoot: projectRootArg,
+});
+
+/**
+ * @param {import('@modelcontextprotocol/server').McpServer} server
+ */
+export function registerRefTools(server) {
+  registerTool(server, 'archgen_refs', {
+    title: 'ArchGen references',
+    description:
+      "Load archgen's own protocol documents — the interview playbook, the artifact rules, the dispatch and " +
+      'gate protocols, the platform capability notes and the MCP/skill policies. Pull SECTIONS, never whole ' +
+      'files: call index for a topic, then read the section you need.',
+    inputSchema: schema,
+    readOnly: true,
+    idempotent: true,
+    handler: (ctx, args) => {
+      const roots = { assetsDir: join(ASSETS_DIR, 'references'), skillDir: ctx.skill?.path ?? null };
+
+      if (args.action === 'list') return { topics: listTopics(roots) };
+
+      if (!args.topic) {
+        throw invalidInput(`topic is required for '${args.action}'`, { action: args.action, known: REF_TOPICS });
+      }
+
+      if (args.action === 'index') return indexTopic(args.topic, roots);
+      if (args.action === 'search') {
+        if (!args.token) throw invalidInput('search requires token', { action: args.action });
+        return searchTopic(args.topic, args.token, roots);
+      }
+      // read
+      return readTopic(args.topic, { ...roots, section: args.section ?? null });
+    },
+  });
+}

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

@@ -0,0 +1,35 @@
+// registry.mjs — the `archgen_registry` tool: the AGENTS.md features registry.
+//
+// The registry is machine-maintained. An agent that hand-edits it, or that
+// forgets to refresh it after a wave, leaves every harness reading a stale
+// feature map. This tool is the only sanctioned writer.
+import { z } from 'zod/v4';
+import { registerTool, projectRootArg } from './_register.mjs';
+import { updateRegistry, showRegistry, DISPLAY_STATUSES } from '../core/registry-updater.mjs';
+
+const schema = z.object({
+  action: z.enum(['update', 'show']).describe('update = rewrite the registry from .archgen/; show = read it without writing.'),
+  projectRoot: projectRootArg,
+  slug: z.string().optional().describe('Upsert one feature row (update). Requires status.'),
+  status: z.enum(DISPLAY_STATUSES).optional().describe('Registry status for the upserted row (update).'),
+});
+
+/**
+ * @param {import('@modelcontextprotocol/server').McpServer} server
+ */
+export function registerRegistryTools(server) {
+  registerTool(server, 'archgen_registry', {
+    title: 'ArchGen registry',
+    description:
+      'Keep the AGENTS.md features registry in sync with .archgen/. Call update after every task completes ' +
+      'and after every plan change — the registry is what every harness reads to know what exists.',
+    inputSchema: schema,
+    readOnly: false,
+    destructive: false,
+    idempotent: true,
+    handler: (ctx, args) => {
+      if (args.action === 'show') return showRegistry(ctx.projectRoot);
+      return updateRegistry(ctx.projectRoot, { slug: args.slug ?? null, status: args.status ?? null });
+    },
+  });
+}

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

@@ -0,0 +1,179 @@
+// setup.mjs — the `archgen_setup` tool: install, MCP wiring, health.
+import { z } from 'zod/v4';
+import { registerTool, projectRootArg } from './_register.mjs';
+import { loadAsset } from '../context.mjs';
+import { wireArchgenMcp, archgenMcpStatus, resolveMcpBinary, uninstallArchgenMcp } from '../core/mcp-server-manager.mjs';
+import { manageCodegraph, assertLocation, findCodegraph } from '../core/codegraph-manager.mjs';
+import { detectHarnesses } from '../core/harness-wiring.mjs';
+import { platformCapabilities, detectHarness } from '../core/platform-caps.mjs';
+import { checkCapability } from '../core/compat.mjs';
+
+const ACTION_DESC =
+  'doctor | bootstrap | install_mcp | uninstall_mcp | harnesses | harness_info — see archgen_help.';
+
+const schema = z.object({
+  action: z.enum(['doctor', 'bootstrap', 'install_mcp', 'uninstall_mcp', 'harnesses', 'harness_info']).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('CodeGraph telemetry preference (bootstrap).'),
+  harness: z.string().optional().describe('Harness id (harness_info). Defaults to the detected one.'),
+  projectRoot: projectRootArg,
+});
+
+/**
+ * @param {import('@modelcontextprotocol/server').McpServer} server
+ */
+export function registerSetupTools(server) {
+  registerTool(server, 'archgen_setup', {
+    title: 'ArchGen setup',
+    description:
+      'Install and wire archgen: report the health of an install, wire the archgen MCP server into every detected ' +
+      'harness, bootstrap CodeGraph (CLI + its MCP + the project index), or remove what was wired.',
+    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 approved = args.approve === true;
+
+      if (args.action === 'harness_info') {
+        const caps = loadAsset('platform-capabilities.json');
+        if (args.harness) return platformCapabilities(caps, args.harness);
+        // No explicit harness: report the detected one, and never throw — an
+        // unknown platform is a normal situation (the skill has a procedure
+        // for it), not an error.
+        try {
+          return detectHarness(caps, { projectRoot: ctx.projectRoot, home: ctx.home });
+        } catch (e) {
+          return {
+            detected: null,
+            reason: e instanceof Error ? e.message : String(e),
+            nextStep: 'Unknown platform: web-search the official MCP + skills docs, propose findings, get user approval.',
+            harnesses: Object.entries(caps.harnesses ?? {}).map(([id, h]) => ({ id, label: h.label })),
+            universal: caps.universal ?? null,
+          };
+        }
+      }
+
+      if (args.action === 'harnesses') {
+        const detected = detectHarnesses(registry, ctx.projectRoot, ctx.home, ctx.env);
+        return {
+          location,
+          detected: detected.map((d) => ({
+            id: d.id,
+            label: d.label,
+            atHome: d.atHome,
+            atProject: d.atProject,
+            configs: Object.entries(d.spec.configs ?? {}).map(([loc, cfg]) => ({
+              location: loc,
+              path: cfg.path,
+              key: cfg.key ?? `mcp_servers.archgen`,
+              format: cfg.format ?? 'json',
+            })),
+          })),
+          binary: resolveMcpBinary({ projectRoot: ctx.projectRoot, home: ctx.home, env: ctx.env }),
+        };
+      }
+
+      if (args.action === 'doctor') {
+        const status = archgenMcpStatus({ projectRoot: ctx.projectRoot, registry, home: ctx.home });
+        const codegraph = findCodegraph(ctx.env);
+        const checks = [];
+
+        // THE CAPABILITY CONTRACT — the skill declares the server version it
+        // needs; this is where a mismatch surfaces instead of failing silently
+        // later as "the agent called an action that no longer exists".
+        const compat = checkCapability({ skillDir: ctx.skill?.path ?? null, serverVersion: ctx.serverVersion });
+        checks.push({
+          status: compat.compatible ? 'OK' : 'FAIL',
+          msg: !ctx.skill
+            ? 'capability contract — no skill installed, nothing to check (run `npx archgen-skill init`)'
+            : compat.compatible
+              ? `capability contract satisfied (skill requires archgen-mcp ${compat.required}, server is ${compat.running})`
+              : `CAPABILITY MISMATCH — ${compat.reason}. Update the server: npm i -g archgen-mcp@latest`,
+        });
+
+        checks.push({
+          status: ctx.skill ? 'OK' : 'WARN',
+          msg: ctx.skill
+            ? `skill installed at ${ctx.skill.path} (${ctx.skill.version ?? 'unknown version'})`
+            : 'skill not found — run `npx archgen-skill init` in the project root',
+        });
+        checks.push({
+          status: status.binary.bin ? 'OK' : 'WARN',
+          msg: `archgen-mcp binary: ${status.binary.bin ?? 'not on PATH (npx fallback used)'} (${status.binary.source})`,
+        });
+        checks.push({
+          status: codegraph ? 'OK' : 'WARN',
+          msg: codegraph ? `codegraph ${codegraph.version} at ${codegraph.bin}` : 'codegraph not installed — run archgen_codegraph { action: "ensure" }',
+        });
+        checks.push({
+          status: 'OK',
+          msg: `node ${process.versions.node} · server ${ctx.serverVersion}`,
+        });
+        return {
+          checks,
+          tally: checks.reduce((acc, c) => ({ ...acc, [c.status]: (acc[c.status] ?? 0) + 1 }), {}),
+          versions: { skill: ctx.skill?.version ?? null, server: ctx.serverVersion, codegraph: codegraph?.version ?? null },
+          mcpTargets: status.targets,
+          node: process.versions.node,
+        };
+      }
+
+      if (args.action === 'uninstall_mcp') {
+        if (!approved) {
+          return { written: false, planned: true, detail: 'uninstall_mcp needs approve: true — nothing was removed' };
+        }
+        // The scope is honoured: removing only the global wiring leaves the
+        // project's wiring in place, and vice versa.
+        return {
+          written: true,
+          ...uninstallArchgenMcp(ctx.projectRoot, ctx.home, location, ctx.env),
+        };
+      }
+
+      if (args.action === 'install_mcp') {
+        const res = wireArchgenMcp({
+          projectRoot: ctx.projectRoot,
+          registry,
+          home: ctx.home,
+          location,
+          approved,
+          env: ctx.env,
+        });
+        return res;
+      }
+
+      // bootstrap — wire archgen MCP AND ensure CodeGraph, in one report.
+      // A capability mismatch is reported, never silently ignored: wiring a
+      // skill to an incompatible server is how a broken install is born.
+      const compat = checkCapability({ skillDir: ctx.skill?.path ?? null, serverVersion: ctx.serverVersion });
+      const mcp = wireArchgenMcp({
+        projectRoot: ctx.projectRoot,
+        registry,
+        home: ctx.home,
+        location,
+        approved,
+        env: ctx.env,
+      });
+      const codegraph = await manageCodegraph({
+        mode: 'ensure',
+        projectRoot: ctx.projectRoot,
+        registry,
+        location,
+        approved,
+        telemetry: args.telemetry ?? 'keep',
+        home: ctx.home,
+        env: ctx.env,
+      });
+      return {
+        compat,
+        mcp: { detected: mcp.detected, wired: mcp.wired, planned: mcp.planned, binary: mcp.binary },
+        codegraph,
+        ok: codegraph.ok !== false,
+      };
+    },
+  });
+}

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

@@ -0,0 +1,207 @@
+// skills.mjs — the `archgen_skills` tool: capability-skill matching,
+// installation and loading.
+//
+// This tool replaces the skill's FETCH-SKILL PROSE. The agent no longer reads
+// a registry, shells out to an installer, or hand-composes a follow-instruction:
+// it asks this tool which capability skills a task needs, installs exactly
+// those, and gets the file path a worker must follow.
+import { z } from 'zod/v4';
+import { readFileSync } from 'node:fs';
+import { registerTool, projectRootArg } from './_register.mjs';
+import { loadAsset } from '../context.mjs';
+import { invalidInput } from '../core/errors.mjs';
+import { hint, teach } from '../core/guidance.mjs';
+import {
+  matchSkills,
+  installSkill,
+  loadSkill,
+  listInstalled,
+  findInstalledSkill,
+  followInstruction,
+  skillRules,
+  skillSections,
+  HARNESS_AGENT_IDS,
+} from '../core/skill-manager.mjs';
+
+const ACTION_DESC =
+  'match = which capability skills a task needs; ' +
+  'install = install ONE capability skill (needs approve); ' +
+  'installed = what is already installed; ' +
+  'load = read a skill SKILL.md (or ONE section of it) for prompt injection; ' +
+  'digest = the section index of an installed skill; ' +
+  'list = the registry.';
+
+const schema = z.object({
+  action: z.enum(['match', 'install', 'installed', 'load', 'digest', 'list']).describe(ACTION_DESC),
+  title: z.string().optional().describe('Task title (match).'),
+  summary: z.string().optional().describe('Task summary (match).'),
+  fileOwnership: z.array(z.string()).optional().describe('Task file_ownership globs (match).'),
+  skillId: z.string().optional().describe('Registry skill id or slug (install, load, digest).'),
+  section: z.string().optional().describe('One section of the skill (load). Omit for the whole skill.'),
+  harness: z.string().optional().describe('Harness id to install for (install). Defaults to universal.'),
+  global: z.boolean().optional().describe('Install for the user instead of the project (install).'),
+  approve: z.boolean().optional().describe('Required to install. Without it you get the plan and nothing is written.'),
+  projectRoot: projectRootArg,
+});
+
+/**
+ * @param {import('@modelcontextprotocol/server').McpServer} server
+ */
+export function registerSkillTools(server) {
+  registerTool(server, 'archgen_skills', {
+    title: 'ArchGen skills',
+    description:
+      'Match a task against the capability-skill registry, install exactly the matched skill, and load its ' +
+      'SKILL.md for prompt injection. Use before dispatching a worker whose work touches a registered capability ' +
+      'domain (UI, accessibility, motion, design systems…).',
+    inputSchema: schema,
+    readOnly: false,
+    destructive: false,
+    idempotent: true,
+    handler: (ctx, args) => {
+      const registry = loadAsset('skill-registry.json');
+
+      if (args.action === 'list') {
+        return {
+          version: registry.version,
+          installer: registry.installer,
+          skills: registry.skills.map((s) => ({
+            id: s.id,
+            slug: s.slug,
+            family: s.family,
+            repo: s.repo,
+            purpose: s.purpose,
+            policy: s.policy,
+            matches: s.matches,
+          })),
+        };
+      }
+
+      if (args.action === 'match') {
+        const matched = matchSkills(registry, {
+          title: args.title,
+          summary: args.summary,
+          fileOwnership: args.fileOwnership,
+        });
+        return {
+          matched,
+          required: matched.filter((m) => m.policy === 'required'),
+          installed: matched.map((m) => {
+            const found = findInstalledSkill(ctx.projectRoot, m.slug, { home: ctx.home });
+            return { ...m, installed: found.installed, path: found.path, scope: found.scope };
+          }),
+          note: matched.length
+            ? 'Install every required skill before dispatching the worker.'
+            : 'No capability domain matched — no external skill is needed.',
+        };
+      }
+
+      if (args.action === 'installed') {
+        return { installed: listInstalled({ projectRoot: ctx.projectRoot, registry, home: ctx.home }) };
+      }
+
+      // install | load
+      const wanted = args.skillId;
+      if (!wanted) throw invalidInput('skillId is required for this action', { action: args.action });
+      const entry =
+        registry.skills.find((s) => s.id === wanted || s.slug === wanted) ??
+        (registry.routing && (registry.routing.id === wanted || registry.routing.slug === wanted)
+          ? registry.routing
+          : null);
+      if (!entry) {
+        throw invalidInput(
+          teach(
+            `unknown skill '${wanted}'`,
+            'the registry lists every id and slug',
+            "archgen_skills{action:'list'}",
+          ),
+          hint({ action: "archgen_skills{action:'list'}", reason: 'the registry is the vocabulary.' }),
+        );
+      }
+
+      if (args.action === 'digest') {
+        // The LENS: a map of the skill's sections, so the agent can see what
+        // is in there and pull exactly the one it needs. Same shape as
+        // archgen_docs{action:'digest'} — a map, not a copy.
+        const found = findInstalledSkill(ctx.projectRoot, entry.slug, { home: ctx.home });
+        if (!found.installed || !found.path) {
+          return {
+            skill: entry.slug,
+            installed: false,
+            sections: [],
+            searchedPaths: found.searchedPaths ?? [],
+            hint: 'not installed — install it first: archgen_skills{action:\'install\',skillId:\'' + entry.slug + '\',approve:true}',
+          };
+        }
+        const content = readFileSync(found.path, 'utf8');
+        return {
+          skill: entry.slug,
+          installed: true,
+          path: found.path,
+          scope: found.scope,
+          sections: skillSections(content),
+        };
+      }
+
+      if (args.action === 'load') {
+        const found = findInstalledSkill(ctx.projectRoot, entry.slug, { home: ctx.home });
+        const loaded = loadSkill({ projectRoot: ctx.projectRoot, slug: entry.slug, home: ctx.home });
+        const rules = loaded.loaded ? skillRules(loaded.content) : { rules: '', count: 0, headings: [] };
+        const sections = loaded.loaded ? skillSections(loaded.content) : [];
+        const result = {
+          skill: entry.slug,
+          purpose: entry.purpose,
+          domain: entry.domain ?? entry.family ?? 'Capability',
+          ...loaded,
+          // The normative rules, and the section index — the agent decides
+          // what to pull from here.
+          rules: rules.rules,
+          ruleCount: rules.count,
+          sections: sections.map((s) => ({
+            slug: s.slug,
+            title: s.title,
+            line: s.line,
+            endLine: s.endLine,
+            normative: s.normative,
+          })),
+          followInstruction: loaded.loaded ? followInstruction({ slug: entry.slug, path: loaded.path, domain: entry.domain }) : null,
+          hint: loaded.loaded
+            ? null
+            : 'not installed — install it first: archgen_skills{action:\'install\',skillId:\'' + entry.slug + '\',approve:true}',
+        };
+
+        // ONE section — the agent's lens, the same way archgen_docs serves
+        // one section of an artifact.
+        if (loaded.loaded && args.section) {
+          const wanted = String(args.section).trim();
+          const hit =
+            sections.find((s) => s.slug === wanted) ??
+            sections.find((s) => s.title.toLowerCase() === wanted.toLowerCase()) ??
+            sections.find((s) => s.slug.replace(/-{2,}/g, '-') === wanted.replace(/-{2,}/g, '-'));
+          if (!hit) {
+            throw invalidInput(
+              `no section '${args.section}' in skill '${entry.slug}'`,
+              { skillId: entry.slug, section: args.section, available: sections.map((s) => s.slug) },
+            );
+          }
+          const body = loaded.content.split('\n').slice(hit.line - 1, hit.endLine).join('\n');
+          return { ...result, section: hit.slug, sectionTitle: hit.title, sectionText: body };
+        }
+        return result;
+      }
+
+      return installSkill({
+        registry,
+        entry,
+        projectRoot: ctx.projectRoot,
+        harness: args.harness ?? 'universal',
+        global: args.global === true,
+        approved: args.approve === true,
+        home: ctx.home,
+        env: ctx.env,
+      });
+    },
+  });
+}
+
+export { HARNESS_AGENT_IDS };