archgen-mcp 0.1.1 → 0.1.2

package/src/tools/help.mjs

@@ -47,7 +47,8 @@ Validates and analyzes a plan (tasks.yaml + plans/).
 - \`brief\` returns a ready-to-send sub-agent prompt (verifier | review | survey | investigate). It derives the slug from \`tasksYaml\` when you do not pass one, and every path in it is ABSOLUTE — so it works from any working directory. The verifier and review briefs carry the graph, the reference-integrity result and the evidence map rendered, so the sub-agent makes no tool call of its own.
 - The verifier and reviewer return \`VERDICT:\` plus a COVERAGE table (every dimension PASS / FAIL / N-A). A report with findings but no coverage table is INCOMPLETE.
 - **Every error carries the next call.** If one fails, read the \`Next:\` line in the message — it is the exact call to make, and the \`Why:\` clause says why. Do not retry the same call.
-- **Batch calls with \`allSettled\`**, not \`all\`: one bad argument must not discard the results of its siblings.`,
+- **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
 
@@ -82,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
 
@@ -206,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
@@ -228,6 +231,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.
+- \`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.`,
 
@@ -252,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,
 });
 
@@ -59,22 +63,55 @@ export function registerSetupTools(server) {
 
       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',
-            })),
+        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') {

package/src/tools/skills.mjs

@@ -11,6 +11,7 @@ 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 { moreMeta, project, withMeta } from '../envelope.mjs';
 import {
   matchSkills,
   installSkill,
@@ -36,11 +37,16 @@ const schema = z.object({
   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.'),
+  skillId: z.string().optional().describe('Registry skill id or slug (install, load, digest, list).'),
+  section: z
+    .string()
+    .optional()
+    .describe('One section of the skill (load, digest). Omit for the section index.'),
   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.'),
+  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,
 });
 
@@ -60,21 +66,39 @@ export function registerSkillTools(server) {
     idempotent: true,
     handler: (ctx, args) => {
       const registry = loadAsset('skill-registry.json');
+      const bound = args.limit ?? 50;
+      const from = args.offset ?? 0;
 
       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,
-          })),
-        };
+        // ONE row, or the whole registry — but never three copies of a row.
+        const rows = 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.skillId) {
+          const one = rows.find((s) => s.id === args.skillId || s.slug === args.skillId);
+          if (!one) {
+            throw invalidInput(
+              teach(`unknown skill '${args.skillId}'`, 'the registry lists every id and slug', "archgen_skills{action:'list'}"),
+              hint({ action: "archgen_skills{action:'list'}", reason: 'the registry is the vocabulary.' }),
+            );
+          }
+          return { version: registry.version, installer: registry.installer, skill: one, skills: [one] };
+        }
+        const p = project(rows, {
+          limit: args.limit,
+          offset: args.offset,
+          next: `archgen_skills{action:'list',limit:${bound},offset:${from + bound}}`,
+        });
+        return withMeta(
+          { version: registry.version, installer: registry.installer, skills: p.items },
+          moreMeta({ total: p.total, returned: p.returned, next: p.next, available: { skills: p.total } }),
+        );
       }
 
       if (args.action === 'match') {
@@ -83,21 +107,47 @@ export function registerSkillTools(server) {
           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 };
+        // ONE copy of each row: the install state rides ON the row, instead of
+        // the same row being delivered three times under three keys.
+        const rows = matched.map((m) => {
+          const found = findInstalledSkill(ctx.projectRoot, m.slug, { home: ctx.home });
+          return { ...m, installed: found.installed, path: found.path, scope: found.scope };
+        });
+        const p = project(rows, {
+          limit: args.limit,
+          offset: args.offset,
+          next: `archgen_skills{action:'match',title:'${args.title ?? ''}',limit:${bound},offset:${from + bound}}`,
+        });
+        return withMeta(
+          {
+            matched: p.items,
+            // The required ones, by id — the rows are already above.
+            required: p.items.filter((m) => m.policy === 'required').map((m) => m.slug),
+            installed: p.items.filter((m) => m.installed).map((m) => m.slug),
+            note: matched.length
+              ? 'Install every required skill before dispatching the worker.'
+              : 'No capability domain matched — no external skill is needed.',
+          },
+          moreMeta({
+            total: p.total,
+            returned: p.returned,
+            next: p.next,
+            available: { skills: p.total, required: p.items.filter((m) => m.policy === 'required').length },
           }),
-          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 }) };
+        const all = listInstalled({ projectRoot: ctx.projectRoot, registry, home: ctx.home });
+        const p = project(all.installed ?? [], {
+          limit: args.limit,
+          offset: args.offset,
+          next: `archgen_skills{action:'installed',limit:${bound},offset:${from + bound}}`,
+        });
+        return withMeta(
+          { installed: p.items },
+          moreMeta({ total: p.total, returned: p.returned, next: p.next, available: { skills: p.total } }),
+        );
       }
 
       // install | load
@@ -134,13 +184,40 @@ export function registerSkillTools(server) {
           };
         }
         const content = readFileSync(found.path, 'utf8');
-        return {
-          skill: entry.slug,
-          installed: true,
-          path: found.path,
-          scope: found.scope,
-          sections: skillSections(content),
-        };
+        let sections = skillSections(content);
+        // ONE section, when the caller named one.
+        if (args.section) {
+          const wanted = String(args.section).trim().toLowerCase();
+          const hit = sections.find(
+            (s) =>
+              s.slug === args.section ||
+              s.title.toLowerCase() === wanted ||
+              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),
+            });
+          }
+          sections = [hit];
+        }
+        const p = project(sections, {
+          limit: args.limit,
+          offset: args.offset,
+          next: `archgen_skills{action:'digest',skillId:'${entry.slug}',limit:${bound},offset:${from + bound}}`,
+        });
+        return withMeta(
+          { skill: entry.slug, installed: true, path: found.path, scope: found.scope, sections: p.items },
+          moreMeta({
+            total: p.total,
+            returned: p.returned,
+            next: p.next,
+            available: { sections: p.total },
+            more: `archgen_skills{action:'load',skillId:'${entry.slug}',section:'<the section you need>'}`,
+          }),
+        );
       }
 
       if (args.action === 'load') {
@@ -152,9 +229,14 @@ export function registerSkillTools(server) {
           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.
+          loaded: loaded.loaded,
+          path: loaded.path,
+          scope: loaded.scope,
+          // The RAW CONTENT IS NOT RETURNED. It used to be: the file arrived
+          // three times in one call — as `content`, as the extracted `rules`
+          // and as the section index. The rules are what the agent must obey
+          // and the index is what it may pull; the file itself is one call
+          // away (`section:'<slug>'`), and the agent is told where it is.
           rules: rules.rules,
           ruleCount: rules.count,
           sections: sections.map((s) => ({
@@ -169,6 +251,8 @@ export function registerSkillTools(server) {
             ? null
             : 'not installed — install it first: archgen_skills{action:\'install\',skillId:\'' + entry.slug + '\',approve:true}',
         };
+        // Where the tool looked matters only when it found nothing.
+        if (!loaded.loaded) result.searchedPaths = loaded.searchedPaths ?? [];
 
         // ONE section — the agent's lens, the same way archgen_docs serves
         // one section of an artifact.
@@ -187,7 +271,21 @@ export function registerSkillTools(server) {
           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;
+        const p = project(result.sections, {
+          limit: args.limit,
+          offset: args.offset,
+          next: `archgen_skills{action:'load',skillId:'${entry.slug}',limit:${bound},offset:${from + bound}}`,
+        });
+        return withMeta(
+          { ...result, sections: p.items },
+          moreMeta({
+            total: p.total,
+            returned: p.returned,
+            next: p.next,
+            available: { sections: p.total },
+            more: `archgen_skills{action:'load',skillId:'${entry.slug}',section:'<the section you need>'}`,
+          }),
+        );
       }
 
       return installSkill({