archgen-mcp 0.1.0 → 0.1.2

package/src/tools/codegraph.mjs

@@ -8,6 +8,7 @@ import { z } from 'zod/v4';
 import { registerTool, projectRootArg } from './_register.mjs';
 import { loadAsset } from '../context.mjs';
 import { manageCodegraph, assertLocation } from '../core/codegraph-manager.mjs';
+import { moreMeta, project, withMeta } from '../envelope.mjs';
 
 const ACTION_DESC = 'ensure | status | wire — see archgen_help.';
 
@@ -17,6 +18,8 @@ const schema = z.object({
   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.'),
+  limit: z.number().int().positive().optional().describe('Max items to return. Default 50.'),
+  offset: z.number().int().nonnegative().optional().describe('Skip this many items.'),
   projectRoot: projectRootArg,
 });
 
@@ -37,7 +40,7 @@ export function registerCodegraphTools(server) {
       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({
+      const report = await manageCodegraph({
         mode,
         projectRoot: ctx.projectRoot,
         registry,
@@ -48,6 +51,22 @@ export function registerCodegraphTools(server) {
         home: ctx.home,
         env: ctx.env,
       });
+      // The wiring lists grow with the number of detected harnesses, so they
+      // are bounded — and the agent is told what else it could fetch.
+      const p = project(report.detected ?? [], {
+        limit: args.limit,
+        offset: args.offset,
+        next: `archgen_codegraph{action:'status',limit:${args.limit ?? 50},offset:${(args.offset ?? 0) + (args.limit ?? 50)}}`,
+      });
+      return withMeta(
+        { ...report, detected: p.items },
+        moreMeta({
+          total: p.total,
+          returned: p.returned,
+          next: p.next,
+          available: { harnesses: p.total },
+        }),
+      );
     },
   });
 }

package/src/tools/docs.mjs

@@ -6,6 +6,8 @@ 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';
+import { moreMeta, project, withMeta } from '../envelope.mjs';
 
 const ACTION_DESC = 'index | digest | section | refs | map | validate — see archgen_help.';
 
@@ -18,6 +20,8 @@ const schema = z.object({
   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).'),
+  limit: z.number().int().positive().optional().describe('Max items to return. Default 50.'),
+  offset: z.number().int().nonnegative().optional().describe('Skip this many items.'),
   projectRoot: projectRootArg,
 });
 
@@ -35,22 +39,46 @@ export function registerDocTools(server) {
     idempotent: true,
     handler: (ctx, args) => {
       const slugDir = resolveSlugDir(ctx, args.slugDir);
+      const bound = args.limit ?? 50;
+      const from = args.offset ?? 0;
       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':
+        case 'index': {
+          const overview = docIndex(slugDir, { mode: 'overview', file: args.file ?? null, projectRoot: ctx.projectRoot });
+          return bounded('files', overview.data, args, `archgen_docs{action:'index',slugDir:'${slugDir}',limit:${bound},offset:${from + bound}}`, {
+            files: (overview.data.files ?? []).length,
+            more: `archgen_docs{action:'section',slugDir:'${slugDir}',section:'<the section you need>'}`,
+          });
+        }
+        case 'digest': {
+          const digest = docIndex(slugDir, { mode: 'digest', file: args.file ?? null, projectRoot: ctx.projectRoot });
+          return bounded('files', digest.data, args, `archgen_docs{action:'digest',slugDir:'${slugDir}',limit:${bound},offset:${from + bound}}`, {
+            files: (digest.data.files ?? []).length,
+            more: `archgen_docs{action:'section',slugDir:'${slugDir}',section:'<the section you need>'}`,
+          });
+        }
+        case 'validate': {
           return docIndex(slugDir, { mode: 'validate', file: args.file ?? null, projectRoot: ctx.projectRoot });
-        case 'refs':
+        }
+        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':
+          const refs = docIndex(slugDir, { mode: 'refs', token: args.token, file: args.file ?? null, projectRoot: ctx.projectRoot });
+          return bounded('matches', refs.data, args, `archgen_docs{action:'refs',slugDir:'${slugDir}',token:'${args.token}',limit:${bound},offset:${from + bound}}`, {
+            matches: (refs.data.matches ?? []).length,
+          });
+        }
+        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':
+          const map = docIndex(slugDir, { mode: 'map', token: args.token, file: args.file ?? null, projectRoot: ctx.projectRoot });
+          return bounded('sections', map.data, args, `archgen_docs{action:'map',slugDir:'${slugDir}',token:'${args.token}',limit:${bound},offset:${from + bound}}`, {
+            sections: (map.data.sections ?? []).length,
+            matches: map.data.matchCount ?? undefined,
+            more: `archgen_docs{action:'section',slugDir:'${slugDir}',section:'<the section you need>'}`,
+          });
+        }
+        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 });
       }
@@ -58,6 +86,24 @@ export function registerDocTools(server) {
   });
 }
 
+/**
+ * Bound a collection-shaped answer, and report what was left.
+ *
+ * The agent is told how many items exist, how many it got, and the exact
+ * call that returns the next slice — so a bound never hides data.
+ *
+ * @param {string} key the payload key the collection sits in
+ * @param {object} data the payload
+ * @param {any} args
+ * @param {string} next the exact next call
+ * @param {object} available what else exists
+ */
+function bounded(key, data, args, next, available) {
+  const items = data?.[key] ?? [];
+  const p = project(items, { limit: args.limit, offset: args.offset, next });
+  return withMeta({ ...data, [key]: p.items }, moreMeta({ total: p.total, returned: p.returned, next: p.next, available }));
+}
+
 /**
  * Resolve the slug directory: explicit argument, else the most recently
  * modified `.archgen/<slug>/` under the project root.
@@ -69,8 +115,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,12 @@ 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.
+- **Narrow before you fetch.** \`coverage\` takes \`taskId\` for one task; \`scaffold\` takes \`file\` for one skeleton; \`limit\`/\`offset\` bound the rest. The whole set is never the default answer.`,
 
   tasks: `# archgen_tasks
 
@@ -80,7 +83,8 @@ Dispatching the next wave while any of those lag is forbidden.
 - \`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.`,
+- MAX 3 parallel workers at a time. A larger wave runs in batches of three.
+- \`list\` and \`next\` narrow to ONE task with \`taskId\`; \`limit\`/\`offset\` bound the rest. \`meta\` says how many tasks exist.`,
 
   docs: `# archgen_docs
 
@@ -100,6 +104,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.
@@ -199,7 +208,8 @@ Matches a task against the capability-skill registry, installs EXACTLY the match
 - 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.
+- \`load\` returns the NORMATIVE RULES (the MUST / SHOULD / NEVER lines) and the section index — NOT the whole file. The rules are what a worker must follow; pull them from here rather than re-reading the file. One section at a time: \`section:'<slug>'\`.
+- \`list\` narrows to ONE registry row with \`skillId\`; \`digest\` narrows to ONE section with \`section\`.
 - 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
@@ -221,7 +231,8 @@ 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.
+- \`read\` with NO section returns the section INDEX — the map. \`section:'*'\` returns the whole topic, deliberately.
+- 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
@@ -245,6 +256,12 @@ structured result. Every result is \`{ ok, data, error, meta }\` — \`ok:false\
 \`INVALID_INPUT\` · \`NOT_FOUND\` · \`CYCLE\` · \`OWNERSHIP_CONFLICT\` · \`CONFLICT\` · \`PERMISSION_DENIED\` ·
 \`UNAVAILABLE\` · \`TIMEOUT\` · \`INTERNAL\`
 
+**Fetching, not dumping**
+- Every tool takes \`limit\` and \`offset\` (default 50 items). Raise \`limit\` when you need more — the bound is yours, not the server's.
+- Every collection narrows to ONE item: \`taskId\` (tasks, plan coverage), \`skillId\` (skills), \`file\` + \`section\` (docs), \`harness\` (setup).
+- Every answer's \`meta\` carries \`available\` (what else exists), \`more\` (the call that fetches one item) and \`next\` (the exact call for the next slice).
+- A bounded answer never hides data: the count is always in \`meta.total\`.
+
 **Call \`archgen_help { topic: "<domain>" }\`** for the full briefing on any one of them.`,
 };
 

package/src/tools/plan.mjs

@@ -16,6 +16,7 @@ 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';
+import { moreMeta, project, withMeta } from '../envelope.mjs';
 
 // The action list lives in archgen_help (one call away). Repeating it here
 // would tax every request's context for no extra information.
@@ -30,12 +31,14 @@ const schema = z.object({
     .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).'),
+  taskId: z.string().optional().describe('ONE task id (coverage).'),
   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).'),
+  file: z.string().optional().describe('ONE artifact file (scaffold) — returns just that skeleton.'),
   kind: z.enum(BRIEF_KINDS).optional().describe('Which dispatch brief (brief).'),
   featureRequest: z
     .string()
@@ -43,6 +46,8 @@ const schema = z.object({
     .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).'),
+  limit: z.number().int().positive().optional().describe('Max items to return. Default 50.'),
+  offset: z.number().int().nonnegative().optional().describe('Skip this many items.'),
   projectRoot: projectRootArg,
 });
 
@@ -74,16 +79,53 @@ export function registerPlanTools(server) {
         case 'coverage': {
           const file = requireTasksYaml(args, ctx);
           if (!args.planDir) throw invalidInput('coverage requires planDir', { action });
-          return planCoverage(file, ctx.contain(args.planDir));
+          const covered = planCoverage(file, ctx.contain(args.planDir));
+          // ONE task, when the caller named one.
+          if (args.taskId) {
+            const isCovered = (covered.covered ?? []).includes(args.taskId);
+            const isUncovered = (covered.uncovered ?? []).includes(args.taskId);
+            if (!isCovered && !isUncovered) {
+              throw invalidInput(`no task '${args.taskId}' in ${file}`, {
+                action,
+                taskId: args.taskId,
+                available: [...(covered.covered ?? []), ...(covered.uncovered ?? [])],
+              });
+            }
+            return { taskId: args.taskId, covered: isCovered, findings: covered.findings ?? [] };
+          }
+          const p = project([...(covered.covered ?? []), ...(covered.uncovered ?? [])], {
+            limit: args.limit,
+            offset: args.offset,
+            next: `archgen_plan{action:'coverage',tasksYaml:'${file}',planDir:'${args.planDir}',limit:${args.limit ?? 50},offset:${(args.offset ?? 0) + (args.limit ?? 50)}}`,
+          });
+          return withMeta(
+            { ...covered, covered: p.items.slice(0, (covered.covered ?? []).length) },
+            moreMeta({
+              total: p.total,
+              returned: p.returned,
+              next: p.next,
+              available: { tasks: p.total, uncovered: (covered.uncovered ?? []).length },
+              more: `archgen_plan{action:'coverage',tasksYaml:'${file}',planDir:'${args.planDir}',taskId:'<one task>'}`,
+            }),
+          );
         }
         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);
+          const blast = analyzeImpact(file, args.target);
+          const p = project([...(blast.direct ?? []), ...(blast.transitive ?? [])], {
+            limit: args.limit,
+            offset: args.offset,
+            next: `archgen_plan{action:'impact',tasksYaml:'${file}',target:'${args.target}',limit:${args.limit ?? 50},offset:${(args.offset ?? 0) + (args.limit ?? 50)}}`,
+          });
+          return withMeta(
+            blast,
+            moreMeta({ total: p.total, returned: p.returned, next: p.next, available: { impacted: p.total } }),
+          );
         }
         case 'scaffold': {
           if (!args.scope) throw invalidInput('scaffold requires scope (SMALL | MEDIUM | LARGE)', { action });
-          return buildScaffold(loadAsset('depth-ladder.json'), args.scope, {
+          const built = buildScaffold(loadAsset('depth-ladder.json'), args.scope, {
             slug: args.slug ?? null,
             templatesDir: TEMPLATES_DIR,
             // The generator token carries the RUNNING server's version. The
@@ -92,6 +134,29 @@ export function registerPlanTools(server) {
             // and no release ever has to update a version written by hand.
             generator: `archgen v${serverVersion()}`,
           });
+          // ONE file's skeleton, when the caller named one. The whole set is
+          // the CONTRACT — truncating it would produce a broken plan — so the
+          // default stays whole and the map to the rest lives in `meta`.
+          if (args.file) {
+            const key = Object.keys(built.skeletons ?? {}).find((k) => k === args.file || k.endsWith(`/${args.file}`));
+            if (!key) {
+              throw invalidInput(`no skeleton '${args.file}' for scope ${args.scope}`, {
+                action,
+                file: args.file,
+                available: Object.keys(built.skeletons ?? {}),
+              });
+            }
+            return { ...built, skeletons: { [key]: built.skeletons[key] }, one: key };
+          }
+          return withMeta(
+            built,
+            moreMeta({
+              total: (built.writeThese ?? []).length,
+              returned: (built.writeThese ?? []).length,
+              available: { files: (built.writeThese ?? []).length },
+              more: `archgen_plan{action:'scaffold',scope:'${args.scope}',slug:'${args.slug ?? '<slug>'}',file:'<one file>'}`,
+            }),
+          );
         }
         case 'brief': {
           if (!args.kind) throw invalidInput('brief requires kind', { action });

package/src/tools/refs.mjs

@@ -13,18 +13,24 @@ 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';
+import { moreMeta, project, withMeta } from '../envelope.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); ' +
+  'read = ONE section (no section = the index; section:"*" = 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.'),
+  section: z
+    .string()
+    .optional()
+    .describe('One section (read, index). "*" = the whole topic. Omit for the section index.'),
   token: z.string().optional().describe('The token to look for (search).'),
+  limit: z.number().int().positive().optional().describe('Max items to return. Default 50.'),
+  offset: z.number().int().nonnegative().optional().describe('Skip this many items.'),
   projectRoot: projectRootArg,
 });
 
@@ -43,20 +49,85 @@ export function registerRefTools(server) {
     idempotent: true,
     handler: (ctx, args) => {
       const roots = { assetsDir: join(ASSETS_DIR, 'references'), skillDir: ctx.skill?.path ?? null };
+      // The caller's bound, echoed into the exact next call so the agent
+      // never has to build the pagination itself.
+      const bound = args.limit ?? 50;
+      const from = args.offset ?? 0;
 
-      if (args.action === 'list') return { topics: listTopics(roots) };
+      if (args.action === 'list') {
+        const p = project(listTopics(roots).topics, {
+          limit: args.limit,
+          offset: args.offset,
+          next: `archgen_refs{action:'list',limit:${bound},offset:${from + bound}}`,
+        });
+        return withMeta(
+          { topics: p.items },
+          moreMeta({ total: p.total, returned: p.returned, next: p.next, available: { topics: p.total } }),
+        );
+      }
 
       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 === 'index') {
+        const indexed = indexTopic(args.topic, { ...roots, section: args.section ?? null });
+        const p = project(indexed.sections, {
+          limit: args.limit,
+          offset: args.offset,
+          next: `archgen_refs{action:'index',topic:'${args.topic}',limit:${bound},offset:${from + bound}}`,
+        });
+        return withMeta(
+          { ...indexed, sections: p.items },
+          moreMeta({
+            total: p.total,
+            returned: p.returned,
+            next: p.next,
+            available: { sections: p.total },
+            more: `archgen_refs{action:'read',topic:'${args.topic}',section:'<the section you need>'}`,
+          }),
+        );
+      }
+
       if (args.action === 'search') {
         if (!args.token) throw invalidInput('search requires token', { action: args.action });
-        return searchTopic(args.topic, args.token, roots);
+        const found = searchTopic(args.topic, args.token, roots);
+        const p = project(found.sections, {
+          limit: args.limit,
+          offset: args.offset,
+          next: `archgen_refs{action:'search',topic:'${args.topic}',token:'${args.token}',limit:${bound},offset:${from + bound}}`,
+        });
+        return withMeta(
+          { ...found, sections: p.items },
+          moreMeta({
+            total: p.total,
+            returned: p.returned,
+            next: p.next,
+            available: { sections: p.total, matches: found.matchCount },
+            more: `archgen_refs{action:'read',topic:'${args.topic}',section:'<the section you need>'}`,
+          }),
+        );
       }
-      // read
-      return readTopic(args.topic, { ...roots, section: args.section ?? null });
+
+      // read — ONE section by default; the index when no section is named;
+      // the whole topic only when the caller says '*'.
+      const read = readTopic(args.topic, { ...roots, section: args.section ?? null });
+      if (read.whole || read.text !== undefined) return read;
+      const p = project(read.sections, {
+        limit: args.limit,
+        offset: args.offset,
+        next: `archgen_refs{action:'read',topic:'${args.topic}',section:'<the section you need>',limit:${bound},offset:${from + bound}}`,
+      });
+      return withMeta(
+        { ...read, sections: p.items },
+        moreMeta({
+          total: p.total,
+          returned: p.returned,
+          next: p.next,
+          available: { sections: p.total },
+          more: `archgen_refs{action:'read',topic:'${args.topic}',section:'<the section you need>'}`,
+        }),
+      );
     },
   });
 }

package/src/tools/registry.mjs

@@ -6,12 +6,15 @@
 import { z } from 'zod/v4';
 import { registerTool, projectRootArg } from './_register.mjs';
 import { updateRegistry, showRegistry, DISPLAY_STATUSES } from '../core/registry-updater.mjs';
+import { moreMeta, project, withMeta } from '../envelope.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).'),
+  limit: z.number().int().positive().optional().describe('Max rows to return (show). Default 50; null for all.'),
+  offset: z.number().int().nonnegative().optional().describe('Skip this many rows (pagination).'),
 });
 
 /**
@@ -28,7 +31,18 @@ export function registerRegistryTools(server) {
     destructive: false,
     idempotent: true,
     handler: (ctx, args) => {
-      if (args.action === 'show') return showRegistry(ctx.projectRoot);
+      if (args.action === 'show') {
+        const shown = showRegistry(ctx.projectRoot);
+        const p = project(shown.rows ?? [], {
+          limit: args.limit,
+          offset: args.offset,
+          next: `archgen_registry{action:'show',limit:${args.limit ?? 50},offset:${(args.offset ?? 0) + (args.limit ?? 50)}}`,
+        });
+        return withMeta(
+          { ...shown, rows: p.items },
+          moreMeta({ total: p.total, returned: p.returned, next: p.next, available: { rows: p.total } }),
+        );
+      }
       return updateRegistry(ctx.projectRoot, { slug: args.slug ?? null, status: args.status ?? null });
     },
   });

package/src/tools/setup.mjs

@@ -7,6 +7,8 @@ import { manageCodegraph, assertLocation, findCodegraph } from '../core/codegrap
 import { detectHarnesses } from '../core/harness-wiring.mjs';
 import { platformCapabilities, detectHarness } from '../core/platform-caps.mjs';
 import { checkCapability } from '../core/compat.mjs';
+import { invalidInput } from '../core/errors.mjs';
+import { moreMeta, project, withMeta } from '../envelope.mjs';
 
 const ACTION_DESC =
   'doctor | bootstrap | install_mcp | uninstall_mcp | harnesses | harness_info — see archgen_help.';
@@ -16,7 +18,9 @@ const schema = z.object({
   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.'),
+  harness: z.string().optional().describe('Harness id (harness_info, harnesses). One harness (harnesses).'),
+  limit: z.number().int().positive().optional().describe('Max items to return. Default 50.'),
+  offset: z.number().int().nonnegative().optional().describe('Skip this many items.'),
   projectRoot: projectRootArg,
 });
 
@@ -58,23 +62,56 @@ export function registerSetupTools(server) {
       }
 
       if (args.action === 'harnesses') {
-        const detected = detectHarnesses(registry, ctx.projectRoot, ctx.home);
-        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',
-            })),
+        const detected = detectHarnesses(registry, ctx.projectRoot, ctx.home, ctx.env);
+        const rows = 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 }),
-        };
+        }));
+        // ONE harness, when the caller named one.
+        if (args.harness) {
+          const one = rows.find((r) => r.id === args.harness);
+          if (!one) {
+            throw invalidInput(`unknown harness '${args.harness}'`, {
+              action: args.action,
+              harness: args.harness,
+              available: rows.map((r) => r.id),
+            });
+          }
+          return {
+            location,
+            detected: [one],
+            binary: resolveMcpBinary({ projectRoot: ctx.projectRoot, home: ctx.home, env: ctx.env }),
+          };
+        }
+        const p = project(rows, {
+          limit: args.limit,
+          offset: args.offset,
+          next: `archgen_setup{action:'harnesses',limit:${args.limit ?? 50},offset:${(args.offset ?? 0) + (args.limit ?? 50)}}`,
+        });
+        return withMeta(
+          {
+            location,
+            // ONE copy of the rows: the same array under two keys was the
+            // payload saying the same thing twice.
+            detected: p.items,
+            binary: resolveMcpBinary({ projectRoot: ctx.projectRoot, home: ctx.home, env: ctx.env }),
+          },
+          moreMeta({
+            total: p.total,
+            returned: p.returned,
+            next: p.next,
+            available: { harnesses: p.total },
+            more: `archgen_setup{action:'harnesses',harness:'<one harness>'}`,
+          }),
+        );
       }
 
       if (args.action === 'doctor') {
@@ -130,7 +167,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),
         };
       }