archgen-mcp 0.1.0 → 0.1.1

package/assets/harness-mcp.json

@@ -320,12 +320,21 @@
     "vscode": {
       "label": "VS Code / Copilot",
       "codegraphTarget": null,
-      "detectHome": [],
+      "detectHome": [
+        ".copilot"
+      ],
       "detectProject": [
         ".vscode",
         ".github/copilot-instructions.md"
       ],
       "configs": {
+        "global": {
+          "path": "mcp-config.json",
+          "home": "copilot",
+          "format": "json",
+          "key": "mcpServers",
+          "entry": "stdio"
+        },
         "project": {
           "path": ".vscode/mcp.json",
           "format": "json",

package/assets/platform-capabilities.json

@@ -414,6 +414,17 @@
             "env"
           ],
           "urlField": "url"
+        },
+        "global": {
+          "path": "~/.copilot/mcp-config.json",
+          "key": "mcpServers",
+          "note": "$COPILOT_HOME replaces this location, and VS Code checks only one of them",
+          "stdioFields": [
+            "command",
+            "args",
+            "env"
+          ],
+          "urlField": "url"
         }
       },
       "mcpCli": "copilot mcp add; palette \"MCP: Add Server\"",

package/assets/references/platforms.md

@@ -34,10 +34,18 @@ Never hand-edit the `AGENTS.md` registry table (`| Feature | Status | Updated |`
 Query `archgen_setup{action:'harness_info'}` for exact per-platform MCP schemas:
 - **Top-level keys vary:**
   - `mcpServers`: Claude Code, Cursor, Windsurf, Gemini CLI, Antigravity, Kiro, Trae
-  - `servers`: VS Code / GitHub Copilot
+  - `servers`: VS Code (the `.vscode/mcp.json` workspace format)
   - `mcp.servers.<id>`: OpenCode (nested under `mcp.servers`, never flat `mcp.<id>`)
   - `context_servers`: Zed
   - `[mcp_servers.<id>]`: Codex CLI (TOML)
+- **VS Code reads TWO formats.** The VS Code format is `servers` in
+  `.vscode/mcp.json`; the PORTABLE format is `mcpServers` in the Copilot
+  user's `mcp-config.json` — `$COPILOT_HOME/mcp-config.json`, or
+  `~/.copilot/mcp-config.json`. Copilot harness sessions read the portable
+  format directly, and `COPILOT_HOME` REPLACES the default (VS Code checks
+  only one of the two). The global wiring therefore goes to the Copilot home
+  in the portable format, so VS Code stable, VS Code Insiders, the Copilot
+  CLI and every workspace see the same server.
 - **Remote URL keys vary:** `url` vs `serverUrl` vs `httpUrl` (check `harness_info`).
 - **Automated wiring:** Use `archgen_setup{action:'install_mcp', approve:true}` rather than hand-editing config files.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgen-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "MCP server for archgen \u2014 the single runtime that owns architecture-plan validation, wave execution, artifact navigation, CodeGraph bootstrap and harness MCP wiring for coding agents.",
   "license": "MIT",
   "type": "module",

package/src/cli.mjs

@@ -204,7 +204,7 @@ export async function runCli(argv, io = {}) {
       codegraph: codegraph ? { bin: codegraph.bin, version: codegraph.version } : null,
       mcpBinary: status.binary,
       mcpTargets: status.targets,
-      harnesses: detectHarnesses(registry, ctx.projectRoot, ctx.home).map((d) => d.id),
+      harnesses: detectHarnesses(registry, ctx.projectRoot, ctx.home, ctx.env).map((d) => d.id),
     };
     if (opts.json) {
       out(JSON.stringify(report, null, 2));
@@ -225,7 +225,7 @@ export async function runCli(argv, io = {}) {
       err('uninstall-mcp needs --yes (nothing was removed)');
       return 2;
     }
-    const res = uninstallArchgenMcp(ctx.projectRoot, ctx.home);
+    const res = uninstallArchgenMcp(ctx.projectRoot, ctx.home, 'both', ctx.env);
     if (opts.json) out(JSON.stringify(res, null, 2));
     else {
       out(`removed ${res.removed.length} config(s)`);

package/src/core/codegraph-manager.mjs

@@ -263,7 +263,7 @@ export async function manageCodegraph(opts) {
 
   /** Wire the MCP server into every detected harness (native + fallback). */
   const wireHarnesses = async (cli) => {
-    const detected = detectHarnesses(registry, projectRoot, home);
+    const detected = detectHarnesses(registry, projectRoot, home, env);
     const wanted = targets ?? detected.map((d) => d.id);
     const selected = detected.filter((d) => wanted.includes(d.id));
 
@@ -428,7 +428,7 @@ export async function manageCodegraph(opts) {
       report.cli.latest = m ? m[1] : null;
     }
     report.telemetry.state = telemetryState(cli?.bin ?? null);
-    const detected = detectHarnesses(registry, projectRoot, home);
+    const detected = detectHarnesses(registry, projectRoot, home, env);
     report.detected = detected.map((d) => d.id);
     for (const d of detected) {
       for (const cfg of Object.values(d.spec.configs ?? {})) {

package/src/core/doc-navigator.mjs

@@ -32,6 +32,7 @@ import { buildGraph, GraphError } from './graph.mjs';
 import { resolveSlugInput, ScopeError } from './scope.mjs';
 import { parseMarkdown, buildSections, findSection, anchorExists } from './docs.mjs';
 import { cycle, invalidInput, notFound } from './errors.mjs';
+import { artifactSpaceMissing } from './guidance.mjs';
 
 // Overview emits at most this many files (sorted); above it, truncated:true.
 export const OVERVIEW_MAX_FILES = 100;
@@ -71,7 +72,10 @@ export function resolveDocScope(input, projectRoot = null) {
     scoped = resolveSlugInput(input, projectRoot);
   } catch (e) {
     if (e instanceof ScopeError) throw invalidInput(`doc-index: ${e.message}`, { input });
-    throw invalidInput(`cannot read ${input} (missing or not a directory)`, { input });
+    // The artifact space does not exist yet. Say WHY, and what to do: the
+    // scaffold tool returns CONTENT and writes nothing, so the caller has to
+    // write it before any artifact tool can read it.
+    throw artifactSpaceMissing(null, input);
   }
   return {
     slugDir: scoped.root,

package/src/core/docs.mjs

@@ -129,7 +129,22 @@ export function buildSections(doc) {
   return sections;
 }
 
-/** Resolve a section by slug, title, or tolerant slug variant. */
+/**
+ * Resolve a section by slug, title, tolerant slug variant, or PREFIX.
+ *
+ * The PREFIX form matters: the skill's `§` markers use SHORT names
+ * (`§artifact-templates/plan-depth`) while the headings produce longer
+ * slugs (`plan-depth-by-scope-class`). Every `§` shorthand in the skill is
+ * a prefix of a real slug, so accepting a prefix makes the shorthand the
+ * skill teaches actually RESOLVABLE — an agent can pass exactly what it was
+ * told without a discovery round-trip first.
+ *
+ * A prefix that matches MORE THAN ONE section is refused, never guessed:
+ * two sections sharing a prefix means the caller must use the full slug.
+ *
+ * @param {any} doc
+ * @param {string} ref
+ */
 export function findSection(doc, ref) {
   const sections = buildSections(doc);
   const wanted = String(ref).trim();
@@ -142,7 +157,14 @@ export function findSection(doc, ref) {
   // Case-insensitive + collapsed-hyphen comparison: agents type
   // "FR-Catalog-01" or "fr-catalog-01" for the same heading.
   const lower = wanted.toLowerCase();
-  return sections.find((s) => slugsMatch(s.slug.toLowerCase(), lower)) ?? null;
+  const byLoose = sections.find((s) => slugsMatch(s.slug.toLowerCase(), lower));
+  if (byLoose) return byLoose;
+  // The `§` shorthand: a PREFIX of the slug. Only an UNAMBIGUOUS prefix
+  // resolves — a guess would send the agent to the wrong section.
+  const needle = slugifyHeading(wanted).toLowerCase();
+  if (!needle) return null;
+  const byPrefix = sections.filter((s) => s.slug.toLowerCase().startsWith(needle));
+  return byPrefix.length === 1 ? byPrefix[0] : null;
 }
 
 /** Does `anchor` exist in the target document? */

package/src/core/fs-safety.mjs

@@ -18,7 +18,7 @@
 // skill/scripts/set-status.mjs — the MCP server must not be weaker than the
 // scripts it replaces.
 import { lstatSync, mkdirSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
-import { dirname, resolve, sep } from 'node:path';
+import { basename, dirname, join, resolve, sep } from 'node:path';
 import { conflict, permissionDenied } from './errors.mjs';
 
 /** Canonical refusal message — identical wording to the CLI's. */
@@ -41,20 +41,58 @@ export function assertNotSymlink(absPath) {
   if (st.isSymbolicLink()) throw permissionDenied(refuseSymlinkMessage(absPath), { path: absPath });
 }
 
+/**
+ * The REAL path of a path, climbing to the nearest existing ancestor when
+ * the leaf does not exist yet — so a symlinked PARENT is caught too.
+ *
+ * Returns null when the chain cannot be resolved at all (a broken symlink,
+ * or a component that is not a directory).
+ *
+ * @param {string} abs
+ * @returns {string|null}
+ */
+function realPathWithTail(abs) {
+  const tail = [];
+  let probe = resolve(abs);
+  for (;;) {
+    try {
+      const real = realpathSync(probe);
+      return tail.length ? join(real, ...tail) : real;
+    } catch (e) {
+      if (!e || e.code !== 'ENOENT') return null;
+      const parent = dirname(probe);
+      if (parent === probe) return null;
+      tail.unshift(basename(probe));
+      probe = parent;
+    }
+  }
+}
+
 /**
  * Realpath-escape guard: refuse anything that lands outside `rootAbs`.
  *
- * TWO CHECKS, IN ORDER.
+ * TWO COMPARISONS, AND THE PATH IS ALLOWED IF EITHER SAYS IT IS INSIDE.
+ *
+ *   1. LEXICAL — the caller's spelling against the root's spelling.
+ *   2. REAL — where the path actually LANDS against where the root actually
+ *      IS. This is the one that catches a symlinked PARENT redirecting a
+ *      write elsewhere, and it is the only one that can answer the question
+ *      when the two paths are spelled differently.
  *
- *   1. LEXICAL. After normalization, the path must be inside the root. This
- *      always applies — it is the primary guard, and it cannot be skipped
- *      because a path does not exist yet.
- *   2. REAL. The nearest existing ancestor is resolved and must also be
- *      inside the root's real path. This is what catches a symlinked
- *      PARENT directory that would redirect the write elsewhere.
+ * They can disagree, and they DO whenever the root and the path are spelled
+ * differently — which is the NORMAL case on macOS (`/tmp`, `/var`) and for
+ * any symlinked project: `process.cwd()` is the REAL path while the caller
+ * passes the LOGICAL one.
  *
- * The guard does NOT fail open: if the root cannot be resolved, only the
- * lexical check stands, and the lexical check is always applied.
+ * The old guard compared the LEXICAL path against the REAL root and refused
+ * on that mismatch, so a perfectly valid path inside the project was
+ * reported as "outside the project" — and the two names the SAME place. The
+ * real comparison is the one that can actually answer the question, and it
+ * must be allowed to.
+ *
+ * The guard does NOT fail open: if the real comparison cannot be made, the
+ * lexical one stands on its own, and a path outside the root by every
+ * measure we could make is always refused.
  *
  * @param {string} rootAbs
  * @param {string} absPath
@@ -62,43 +100,24 @@ export function assertNotSymlink(absPath) {
 export function assertWithinRoot(rootAbs, absPath) {
   const root = resolve(rootAbs);
   const abs = resolve(absPath);
-  if (abs !== root && !abs.startsWith(root + sep)) {
-    throw permissionDenied(
-      `refusing a path outside the project: ${absPath} is not inside ${rootAbs}`,
-      { path: absPath, root: rootAbs },
-    );
-  }
 
-  let rootReal;
-  try {
-    rootReal = realpathSync(root);
-  } catch {
-    return; // the root itself does not exist yet — the lexical check stands
-  }
-  let probe = abs;
-  for (;;) {
-    let exists = true;
-    try {
-      lstatSync(probe);
-    } catch {
-      exists = false;
-    }
-    if (exists) {
-      let real;
-      try {
-        real = realpathSync(probe);
-      } catch {
-        return; // broken chain: nothing writable through it
-      }
-      if (real !== rootReal && !real.startsWith(rootReal + sep)) {
-        throw permissionDenied(refuseSymlinkMessage(absPath), { path: absPath, root: rootAbs });
-      }
-      return;
-    }
-    const parent = dirname(probe);
-    if (parent === probe) return;
-    probe = parent;
+  const rootReal = realPathWithTail(root);
+  const pathReal = realPathWithTail(abs);
+
+  const lexicalInside = abs === root || abs.startsWith(root + sep);
+  const realInside =
+    rootReal && pathReal ? pathReal === rootReal || pathReal.startsWith(rootReal + sep) : null;
+
+  if (realInside === true || (realInside === null && lexicalInside)) return;
+
+  if (lexicalInside) {
+    // Lexically inside, but it lands somewhere else: a symlinked parent.
+    throw permissionDenied(refuseSymlinkMessage(absPath), { path: absPath, root: rootAbs });
   }
+  throw permissionDenied(
+    `refusing a path outside the project: ${absPath} is not inside ${rootAbs}`,
+    { path: absPath, root: rootAbs },
+  );
 }
 
 /**

package/src/core/guidance.mjs

@@ -0,0 +1,142 @@
+// guidance.mjs — every failure teaches the agent what to do NEXT, in ONE line.
+//
+// WHY THIS FILE EXISTS.
+//
+// An error that only says WHAT FAILED leaves the agent to guess, and a guess
+// that fails the same way is a loop. An agent that called
+// `archgen_refs{action:'read', section:'plan-depth'}` and got
+// "no section 'plan-depth'" had no way to know the slug it was told to use
+// was a shorthand for a longer one — so it burned a round-trip rediscovering
+// the vocabulary, and did it again for the next section.
+//
+// So every archgen failure is ONE line that carries the cause, the fix, and
+// the exact next call:
+//
+//   <cause> — <the fix in a clause>. Next: <the call, ready to paste>
+//
+// The vocabulary is SHARED, so every tool teaches the same way. And where a
+// failure can be prevented rather than explained, it is: the section
+// resolver accepts the shorthand the skill teaches, so the question never
+// comes up.
+//
+// `hint()` adds machine-readable next-step fields to the error DETAILS, so a
+// client can act on them without parsing prose.
+import { invalidInput, notFound } from './errors.mjs';
+
+/**
+ * Compose a ONE-LINE teaching message.
+ *
+ * @param {string} cause what went wrong, in a few words
+ * @param {string} fix the fix, in one clause
+ * @param {string} action the exact next call, ready to paste
+ * @returns {string}
+ */
+export function teach(cause, fix, action) {
+  return `${cause} — ${fix}. Next: ${action}`;
+}
+
+/**
+ * Machine-readable next-step fields, attached to an error's details.
+ *
+ * @param {{action?: string, reason?: string, alternatives?: string[], available?: unknown[]}} spec
+ * @returns {Record<string, unknown>}
+ */
+export function hint(spec) {
+  const out = {};
+  if (spec.action) out.nextAction = spec.action;
+  if (spec.reason) out.reason = spec.reason;
+  if (spec.alternatives?.length) out.alternatives = spec.alternatives;
+  if (spec.available?.length) out.available = spec.available;
+  return out;
+}
+
+/**
+ * "The artifact space does not exist yet."
+ *
+ * `archgen_plan{action:'scaffold'}` is a GENERATOR: it returns the CONTENT
+ * of the files to create, and writes nothing. An agent that assumes otherwise
+ * gets "missing or not a directory" from every artifact tool, and the
+ * natural reading — "the tool is broken" — sends it hunting for a flag that
+ * does not exist.
+ *
+ * @param {string} slug the slug, when known
+ * @param {string} slugDir the path that was looked for
+ */
+export function artifactSpaceMissing(slug, slugDir) {
+  return invalidInput(
+    teach(
+      `no artifact space at ${slugDir}`,
+      '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.' }),
+  );
+}
+
+/**
+ * "That section does not exist."
+ *
+ * @param {string} topic the reference topic
+ * @param {string} section the section that was asked for
+ * @param {string[]} available the valid slugs
+ */
+export function noSuchSection(topic, section, available) {
+  return notFound(
+    teach(
+      `no section '${section}' in '${topic}'`,
+      'a prefix of the slug works too, if unambiguous',
+      `archgen_refs{action:'index',topic:'${topic}'}`,
+    ),
+    hint({ action: `archgen_refs{action:'index',topic:'${topic}'}`, reason: 'the index lists every exact slug.', available }),
+  );
+}
+
+/**
+ * "That skill is not installed."
+ *
+ * @param {string} slug the skill slug
+ */
+export function skillNotInstalled(slug) {
+  return invalidInput(
+    teach(
+      `the capability skill '${slug}' is not installed`,
+      'install it before dispatching the worker',
+      `archgen_skills{action:'install',skillId:'${slug}',approve:true}`,
+    ),
+    hint({ action: `archgen_skills{action:'install',skillId:'${slug}',approve:true}`, reason: 'a required skill must be on disk before dispatch.' }),
+  );
+}
+
+/**
+ * "That task id is not in the plan."
+ *
+ * @param {string} taskId the id that was asked for
+ * @param {string[]} available the task ids that exist
+ */
+export function noSuchTask(taskId, available) {
+  return notFound(
+    teach(
+      `no task '${taskId}' in the plan`,
+      'task ids are case-sensitive',
+      "archgen_tasks{action:'list',tasksYaml:'<tasks.yaml>'}",
+    ),
+    hint({ action: "archgen_tasks{action:'list',tasksYaml:'<tasks.yaml>'}", reason: 'the list carries every task id.', available }),
+  );
+}
+
+/**
+ * "That path is outside the project."
+ *
+ * @param {string} path the refused path
+ * @param {string} root the anchor the server is bound to
+ */
+export function outsideProject(path, root) {
+  return invalidInput(
+    teach(
+      `the path is outside the project: ${path}`,
+      'the server is anchored to one root and cannot read or write outside it',
+      `use a path under ${root}`,
+    ),
+    hint({ action: `use a path under ${root}`, reason: 'the anchor is the boundary.' }),
+  );
+}

package/src/core/harness-wiring.mjs

@@ -24,23 +24,103 @@ import { assertNotSymlink, assertWithinRoot, withFileLock, writeFileAtomic } fro
 import { mergeEntry, parseJsonc, removeEntry } from './jsonc-config.mjs';
 import { invalidInput } from './errors.mjs';
 
+/**
+ * The Copilot home: `$COPILOT_HOME`, or `~/.copilot`.
+ *
+ * VS Code reads the Copilot CLI's MCP configuration from here, and the
+ * documentation is explicit that `COPILOT_HOME` REPLACES the default:
+ * "VS Code does not check both locations."
+ *
+ * So a user who sets it has their configuration in ONE place and the other
+ * is ignored. Writing to the ignored one is exactly the "the agent cannot
+ * see the MCP" failure — which is why the config location and the detection
+ * must both follow this same home.
+ *
+ * @param {Record<string, string|undefined>} [env]
+ * @param {string} [home]
+ * @returns {string}
+ */
+export function copilotHome(env = process.env, home = homedir()) {
+  const fromEnv = env.COPILOT_HOME;
+  if (typeof fromEnv === 'string' && fromEnv.trim() !== '') return resolve(fromEnv);
+  return join(home, '.copilot');
+}
+
 /**
  * Detect which harnesses are present in this environment.
  * @param {any} registry the harness-mcp.json content
  * @param {string} projectRoot
  * @param {string} [home]
+ * @param {Record<string, string|undefined>} [env]
  * @returns {Array<{id: string, label: string, atHome: boolean, atProject: boolean, spec: any}>}
  */
-export function detectHarnesses(registry, projectRoot, home = homedir()) {
+export function detectHarnesses(registry, projectRoot, home = homedir(), env = process.env) {
   const found = [];
   for (const [id, h] of Object.entries(registry.harnesses ?? {})) {
-    const atHome = (h.detectHome ?? []).some((m) => existsSync(join(home, m)));
+    const atHome =
+      (h.detectHome ?? []).some((m) => existsSync(join(home, m))) ||
+      // A harness whose configuration lives in a NAMED home (the Copilot
+      // home) is present when that home exists. `COPILOT_HOME` replaces the
+      // default, and the client checks only one of them — so detecting the
+      // default alone would miss a user who set the variable, and wiring the
+      // default alone would write a file the client never reads.
+      namedHomeExists(h, env, home);
     const atProject = (h.detectProject ?? []).some((m) => existsSync(join(projectRoot, m)));
     if (atHome || atProject) found.push({ id, label: h.label, atHome, atProject, spec: h });
   }
   return found;
 }
 
+/** True when the home a harness's configuration lives in exists. */
+function namedHomeExists(harness, env, home) {
+  for (const cfg of Object.values(harness.configs ?? {})) {
+    if (cfg.home === 'copilot' && existsSync(copilotHome(env, home))) return true;
+  }
+  return false;
+}
+
+/**
+ * Where a harness's configuration file lives — and the root it must stay
+ * inside.
+ *
+ * THREE BASES:
+ *   - `home: "copilot"` — the Copilot home (`$COPILOT_HOME`, or
+ *     `~/.copilot`), with the path relative to it.
+ *   - a path starting with `~/` — relative to the home directory.
+ *   - anything else — relative to the project root.
+ *
+ * The path and its containment root come from ONE function on purpose: when
+ * they were computed separately, the root said "the home directory" while
+ * the path said "$COPILOT_HOME" — and the write was then refused by the very
+ * guard meant to protect it.
+ *
+ * @param {any} cfg the registry's config entry
+ * @param {{projectRoot: string, home: string, env?: Record<string, string|undefined>}} ctx
+ * @returns {{path: string, root: string}} the absolute path and its root
+ */
+export function configTargetFor(cfg, ctx) {
+  const env = ctx.env ?? process.env;
+  if (cfg.home === 'copilot') {
+    const base = copilotHome(env, ctx.home);
+    return { path: join(base, cfg.path), root: base };
+  }
+  if (cfg.path.startsWith('~/')) {
+    return { path: expandHome(cfg.path, ctx.home), root: ctx.home };
+  }
+  return { path: join(ctx.projectRoot, cfg.path), root: ctx.projectRoot };
+}
+
+/**
+ * Where a harness's configuration file lives.
+ *
+ * @param {any} cfg the registry's config entry
+ * @param {{projectRoot: string, home: string, env?: Record<string, string|undefined>}} ctx
+ * @returns {string} the absolute path
+ */
+export function configPathFor(cfg, ctx) {
+  return configTargetFor(cfg, ctx).path;
+}
+
 /** Expand a leading `~/` to the home directory. */
 export function expandHome(p, home = homedir()) {
   return p.startsWith('~/') ? join(home, p.slice(2)) : p;
@@ -361,9 +441,10 @@ export function wireServer(opts) {
     fallbackCommand = serverId,
     skipHarnesses = [],
     targets = null,
+    env = process.env,
   } = opts;
 
-  const detected = detectHarnesses(registry, projectRoot, home);
+  const detected = detectHarnesses(registry, projectRoot, home, env);
   // A caller that narrowed the set of harnesses must get exactly that set.
   // The native path honoured the filter and this one did not, so a request
   // for two harnesses wired ten.
@@ -383,9 +464,10 @@ export function wireServer(opts) {
       if (!cfg) continue;
       if (loc === 'global' && !d.atHome) continue;
       if (loc === 'project' && !d.atProject) continue;
-      const absPath = cfg.path.startsWith('~') ? expandHome(cfg.path, home) : join(projectRoot, cfg.path);
+      const target = configTargetFor(cfg, { projectRoot, home, env });
+      const absPath = target.path;
       const entry = buildEntry(entries, npxEntries, cfg.entry, binPath, fallbackCommand);
-      const root = loc === 'global' ? home : projectRoot;
+      const root = target.root;
       const res =
         cfg.format === 'toml'
           ? writeTomlConfig(absPath, serverId, entry, { approved, dryRun, root })
@@ -438,7 +520,7 @@ export function recordWiring(projectRoot, serverId, entries) {
  * @param {'project'|'global'|'both'} [location] which scope to remove
  * @returns {{removed: string[], skipped: string[]}}
  */
-export function removeWiring(projectRoot, serverId, home = homedir(), location = 'both') {
+export function removeWiring(projectRoot, serverId, home = homedir(), location = 'both', env = process.env) {
   const p = join(projectRoot, '.archgen', '.mcp-wiring.json');
   let manifest = null;
   try {
@@ -463,9 +545,11 @@ export function removeWiring(projectRoot, serverId, home = homedir(), location =
       // The manifest is a file ON DISK in the project — repository content.
       // Its paths are therefore untrusted: a clone could ship a manifest
       // naming any file on the machine. A recorded path must resolve inside
-      // the project root or the user's home, or it is refused.
-      if (!pathIsWithin(abs, projectRoot) && !pathIsWithin(abs, home)) {
-        skipped.push(`${abs} (outside the project and home directories)`);
+      // the project root, the user's home, or the Copilot home — those are
+      // the three places a harness's own configuration may live.
+      const allowedRoots = [projectRoot, home, copilotHome(env, home)];
+      if (!allowedRoots.some((r) => pathIsWithin(abs, r))) {
+        skipped.push(`${abs} (outside the project, home and Copilot directories)`);
         continue;
       }
       if (!existsSync(abs)) {

package/src/core/mcp-server-manager.mjs

@@ -112,9 +112,11 @@ export function wireArchgenMcp(opts) {
  * Remove the archgen MCP entries this server wrote.
  * @param {string} projectRoot
  * @param {string} [home]
+ * @param {'project'|'global'|'both'} [location]
+ * @param {Record<string, string|undefined>} [env]
  */
-export function uninstallArchgenMcp(projectRoot, home = homedir(), location = 'both') {
-  return removeWiring(projectRoot, 'archgen', home, location);
+export function uninstallArchgenMcp(projectRoot, home = homedir(), location = 'both', env = process.env) {
+  return removeWiring(projectRoot, 'archgen', home, location, env);
 }
 
 /**

package/src/core/plan-grapher.mjs

@@ -19,6 +19,7 @@ import { parseYaml } from './yaml.mjs';
 import { buildGraph, findCycle, computeWaves, dedupeDependencies, computeQualityStats, GraphError } from './graph.mjs';
 import { resolveSlugInput, ScopeError } from './scope.mjs';
 import { cycle, invalidInput, notFound } from './errors.mjs';
+import { noSuchTask } from './guidance.mjs';
 
 // Whole-graph Mermaid above this node count is refused.
 export const MERMAID_WHOLE_MAX_NODES = 250;
@@ -238,7 +239,7 @@ export function planGraph(input, opts = {}) {
 
   if (node !== null) {
     const t = byId.get(node);
-    if (!t) throw notFound(`no task '${node}' in ${tasksFile}`, { node, file: tasksFile });
+    if (!t) throw noSuchTask(node, uniqueTasks.map((x) => x.id));
     if (mermaid) {
       const up = [...bfsDistances(t.id, prerequisites)].filter(([id]) => id !== t.id).map(([id]) => id).sort();
       const down = [...bfsDistances(t.id, dependents)].filter(([id]) => id !== t.id).map(([id]) => id).sort();

package/src/core/refs.mjs

@@ -23,6 +23,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { parseMarkdown, buildSections, findSection } from './docs.mjs';
 import { notFound } from './errors.mjs';
+import { noSuchSection } from './guidance.mjs';
 
 /** The reference documents this server serves. */
 export const REF_TOPICS = [
@@ -104,11 +105,7 @@ export function readTopic(topic, opts) {
   const section = findSection(doc, opts.section);
   if (!section) {
     const available = buildSections(doc).map((s) => s.slug);
-    throw notFound(`no section '${opts.section}' in '${resolved.topic}'`, {
-      topic: resolved.topic,
-      section: opts.section,
-      available,
-    });
+    throw noSuchSection(resolved.topic, opts.section, available);
   }
   return {
     topic: resolved.topic,

package/src/core/scaffold.mjs

@@ -81,6 +81,12 @@ export function buildScaffold(ladder, scopeClass, opts = {}) {
   return {
     scopeClass: key,
     label: spec.label,
+    // THIS TOOL WRITES NOTHING. It returns the CONTENT of every file the
+    // scope class needs, and the caller writes them. An agent that assumes
+    // otherwise gets "missing or not a directory" from every artifact tool
+    // and reads it as a broken tool rather than an unwritten plan.
+    writes: false,
+    writeThese: artifacts.map((a) => a.path),
     intentDefaults: spec.intentDefaults ?? [],
     roundCap: spec.roundCap ?? null,
     artifacts,

package/src/core/worker-contract.mjs

@@ -30,7 +30,8 @@ import { dirname, join } from 'node:path';
 import { parseYaml } from './yaml.mjs';
 import { buildGraph, GraphError } from './graph.mjs';
 import { skillDirective } from './skill-manager.mjs';
-import { invalidInput, notFound } from './errors.mjs';
+import { invalidInput } from './errors.mjs';
+import { noSuchTask } from './guidance.mjs';
 
 /**
  * Assemble the worker prompt for one task.
@@ -64,7 +65,7 @@ export function buildWorkerContract(opts) {
   }
   const tasks = Array.isArray(data?.tasks) ? data.tasks : [];
   const task = tasks.find((t) => t?.id === taskId);
-  if (!task) throw notFound(`task '${taskId}' not found in ${tasksYaml}`, { taskId, file: tasksYaml });
+  if (!task) throw noSuchTask(taskId, tasks.map((t) => t?.id).filter(Boolean));
 
   // The dependency neighbourhood — what must exist BEFORE this task, and what
   // waits on it. Derived from depends_on, never hand-labelled.

package/src/tools/docs.mjs

@@ -6,6 +6,7 @@ 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.';
 
@@ -69,8 +70,15 @@ export function resolveSlugDir(ctx, explicit) {
   const active = activeSlugDir(ctx);
   if (!active) {
     throw invalidInput(
-      `no .archgen/<slug>/ directory found under ${ctx.projectRoot} — generate a plan first, or pass slugDir`,
-      { projectRoot: ctx.projectRoot },
+      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;

package/src/tools/help.mjs

@@ -43,9 +43,11 @@ Validates and analyzes a plan (tasks.yaml + plans/).
 - \`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.
+- \`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.`,
+- 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
 
@@ -100,6 +102,11 @@ you need are usually a few hundred. \`digest\` gives you the section index, \`se
 | \`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.
@@ -221,7 +228,7 @@ Loads archgen's OWN protocol documents — the judgment layer: how to interview,
 
 **Gotchas**
 - Load the SECTION, not the topic: a topic is ~11 KB, a section is ~1-2 KB.
-- Section slugs are GitHub-exact (lowercase, punctuation dropped, whitespace to hyphens). Call \`index\` for the exact slug rather than guessing it.
+- 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

package/src/tools/setup.mjs

@@ -58,7 +58,7 @@ export function registerSetupTools(server) {
       }
 
       if (args.action === 'harnesses') {
-        const detected = detectHarnesses(registry, ctx.projectRoot, ctx.home);
+        const detected = detectHarnesses(registry, ctx.projectRoot, ctx.home, ctx.env);
         return {
           location,
           detected: detected.map((d) => ({
@@ -130,7 +130,7 @@ export function registerSetupTools(server) {
         // project's wiring in place, and vice versa.
         return {
           written: true,
-          ...uninstallArchgenMcp(ctx.projectRoot, ctx.home, location),
+          ...uninstallArchgenMcp(ctx.projectRoot, ctx.home, location, ctx.env),
         };
       }
 

package/src/tools/skills.mjs

@@ -10,6 +10,7 @@ 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,
@@ -108,7 +109,14 @@ export function registerSkillTools(server) {
           ? registry.routing
           : null);
       if (!entry) {
-        throw invalidInput(`unknown skill '${wanted}' — call archgen_skills { action: 'list' }`, { skillId: wanted });
+        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') {
@@ -122,7 +130,7 @@ export function registerSkillTools(server) {
             installed: false,
             sections: [],
             searchedPaths: found.searchedPaths ?? [],
-            hint: 'not installed — call archgen_skills { action: "install" } first',
+            hint: 'not installed — install it first: archgen_skills{action:\'install\',skillId:\'' + entry.slug + '\',approve:true}',
           };
         }
         const content = readFileSync(found.path, 'utf8');
@@ -157,7 +165,9 @@ export function registerSkillTools(server) {
             normative: s.normative,
           })),
           followInstruction: loaded.loaded ? followInstruction({ slug: entry.slug, path: loaded.path, domain: entry.domain }) : null,
-          hint: loaded.loaded ? null : 'not installed — call archgen_skills { action: "install" } first',
+          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