archgen-mcp 0.1.1 → 0.1.2

package/README.md

@@ -62,6 +62,20 @@ Every tool returns the same envelope:
 Call `archgen_help { topic: "<domain>" }` for the full briefing on any tool —
 including when to call it, every action, and its gotchas.
 
+### Fetching, not dumping
+
+Every tool takes `limit` and `offset` (default 50 items) — the bound is the
+caller's, and a bounded answer always reports what it left behind. Every
+collection narrows to **one item**: `taskId`, `skillId`, `file` + `section`,
+`harness`. Each answer's `meta` carries `available` (what else exists),
+`more` (the call that fetches one item) and `next` (the exact call for the
+next slice).
+
+So the agent fetches what it needs instead of taking the whole set: a
+reference topic is fetched **one section** at a time (`section: '*'` asks for
+the whole topic deliberately), and a capability skill is fetched as its
+**normative rules plus an index** — never as the file three times over.
+
 ### The judgment / output split
 
 The archgen **skill** carries the judgment (policy, rules, when-to-use). This

package/assets/briefs/survey.md

@@ -4,7 +4,7 @@ SCOPE: Read-only exploration, writing ONLY `<slug dir>/codebase-map.md`.
 DELIVERABLE: Write `<slug dir>/codebase-map.md` containing EXACTLY these four non-empty sections:
 ## Structure — Top 2 directory levels with 1-line purpose per folder
 ## Modules — Table: `module | responsibility | key entry points`
-## Conventions — Observed file naming, error handling, and test placement patterns
+## Conventions — Observed file naming, error handling, and where the tests live today (the source roots and the test tree)
 ## Affected — Files/modules impacted by the feature, citing exact evidence paths
 
 NAVIGATION & VERIFICATION

package/assets/briefs/verifier.md

@@ -9,7 +9,8 @@ STEP 2 — AUDIT JUDGMENT & CONTRACT COMPLETENESS:
 - Wave boundaries match true dependencies without artificial serialization.
 - Acceptance criteria are objectively verifiable (runnable command or observable output).
 - Edge-case coverage satisfies the scope class (`SMALL` / `MEDIUM` / `LARGE`).
-- Planned structure and naming obey `references/code-standards.md`.
+- Planned structure and naming obey `references/code-standards.md` — including the separate source and test trees: no test tree inside the source tree, and every task that owns source owns the mirrored test path.
+- The repository does not hide archgen artifacts: no `.gitignore` rule covers `.archgen/`, `.agents/skills/archgen`, `.claude/skills/archgen`, `AGENTS.md` or `CLAUDE.md`.
 - **CONTRACT-COMPLETENESS SWEEP** (evaluate every dimension; mark `N/A` only when the system genuinely lacks that surface):
   1. `functional coverage`: Every requirement maps to a task + objective acceptance check.
   2. `security & data protection`: Authn/authz flows, session/credential lifecycle, CSRF/replay defense, encryption/privacy boundaries, boundary input validation.

package/assets/references/artifact-templates.md

@@ -62,6 +62,7 @@ Adding or omitting files outside the scaffold output is a right-sizing defect. A
 - **Runnable verification commands:** Repo-root-relative (no `../` or `--plan .`), specifying exact commands, flags, sample sizes, and thresholds.
 - **Restricted YAML subset:** Block mappings, block sequences, and single-line flow collections (`["a/**", "b.ts"]`, `{id: A}`) ONLY. **BANNED:** block scalars (`|` / `>`), duplicate keys, and multi-line flow collections.
 - **Targeted `tasks.yaml` edits:** Apply small, surgical edits or a clean full regeneration—never large multi-region patches.
+- **Both trees declared:** `architecture.yaml` `structure:` lists the source tree AND its sibling test tree, and a task that owns source owns the mirrored test path (`references/code-standards.md` owns the rule).
 
 ## Agent workspace & artifact location — the two-tier rule
 
@@ -79,6 +80,27 @@ Adding or omitting files outside the scaffold output is a right-sizing defect. A
   - Source code (`src/...`) and shipped user/operator documentation (`README.md`, API docs, runbooks).
   - *Durable ADRs:* Promote repo-wide architectural decisions from `.archgen/<slug>/decisions/` to the project's canonical ADR directory (`docs/adr/`). Supersede rather than deleting/renumbering accepted ADRs.
 
+Every path under `.archgen/<slug>/` is committed — the `.agent/` run state included, because it is the audit trail of how the work went (`§artifact-tracking`).
+
+## Artifact tracking — every archgen artifact is committed
+
+The plan of record belongs in the repository and in the history, next to the code it plans: `git log` must show what was decided, when it changed, and what shipped.
+
+**Committed — the whole archgen footprint:**
+- `.archgen/<slug>/` — the plan of record: `tasks.yaml`, `plans/`, `docs/`, `architecture.yaml`, `decisions/`, and the `.agent/` run state.
+- `.agents/skills/archgen/` — the canonical installed skill, one copy for the team.
+- `.claude/skills/archgen` — the harness bridge into that store.
+- `AGENTS.md` and `CLAUDE.md` — the registry hub and its pointer.
+- The project MCP config (`.mcp.json`, `.cursor/mcp.json`, `opencode.json`, `.vscode/mcp.json`, …) — the wiring that gives the team the tools.
+
+**Never committed — machine-local state:** `.codegraph/` (the local symbol index), `.archgen/.runtime/` (the legacy heartbeat), the `.archgen-version` deploy stamp.
+
+**Rules:**
+1. **NEVER gitignore an archgen artifact.** A rule covering `.archgen/`, `.agents/`, `.claude/` or `AGENTS.md` is a defect — remove it.
+2. **Commit the plan before the first wave**, then each wave's artifact state (statuses, notes, decisions, reports, snapshot) with that wave's commits.
+3. **Fix the ignore rule before force-adding** — a forced add hides the rule from the next person; if you must force-add, say so in the completion report.
+4. **Never rewrite published history** to hide an artifact — the plan of record is append-only, like the code it plans.
+
 ## architecture.yaml (LARGE scope)
 
 Generated via `archgen_plan{action:'scaffold', scope:'LARGE'}`. Authoring rules for the four anti-hallucination contract blocks:

package/assets/references/mcp-and-skills.md

@@ -4,6 +4,8 @@
 
 `npx archgen-skill init` (or `install`) automatically wires `archgen-mcp` and CodeGraph into every detected harness. Never configure them manually. If `archgen_*` tools are missing, run `npx archgen-skill init` at the repo root and ask the user to reload the harness (`§platforms/mcp-configuration`).
 
+The install writes into the repository — the skill store, the harness bridge, `AGENTS.md`. Those files are **committed to git** (one copy, shared by the team), never gitignored (`§artifact-templates/artifact-tracking`).
+
 The procedures below govern **external** MCP servers (e.g., `context7`) and capability skills.
 
 ## INSTALL-MCP procedure (approval-gated)
@@ -33,7 +35,7 @@ Capability-skill loading is **MANDATORY** whenever planned work matches a regist
    ```
    This invokes `npx -y skills add <repo> --skill <slug> --agent <agent> --yes --json` to install the single matched skill non-interactively (never a full repo bundle) and verifies the resulting file path.
 4. **INTEGRATE (inline into worker contract):** Call `archgen_tasks{action:'contract', tasksYaml, taskId}`. It automatically extracts the normative rules (`MUST` / `SHOULD` / `NEVER`), file path, and section index from every matched required skill and embeds them directly into the worker prompt so workers cannot overlook them.
-   - To inspect a skill manually, call `archgen_skills{action:'load', skillId}` (full rules + index), `{action:'digest', skillId}` (index only), or `{action:'load', skillId, section}` (single section).
+   - To inspect a skill manually, call `archgen_skills{action:'load', skillId}` (the normative rules + the section index — never the whole file), `{action:'digest', skillId}` (index only), or `{action:'load', skillId, section}` (single section).
 5. **AUDIT:** Every worker completion report MUST include an explicit compliance line:
    - `Skill compliance: followed <skill-slug> (<path/to/SKILL.md>)`
    - `Skill compliance: NOT followed — <reason>`

package/assets/templates/architecture.yaml

@@ -10,39 +10,33 @@ stack:
   database: postgres
 structure: # planned folder tree defined BEFORE coding
   - path: src/features/<feature>/
-    purpose: feature modules (api, internal, colocated tests)
+    purpose: feature modules (api, internal)
   - path: src/shared/
     purpose: cross-feature utilities; MUST NOT import from features/
   - path: src/config/
     purpose: typed env parsing + constants
+  - path: tests/unit/features/<feature>/
+    purpose: unit tests — the test tree, a SIBLING of src/ that mirrors the source path
 naming_conventions: # referenced by every task step and file_ownership entry
   file_naming: kebab-case files; feature folder matches module name
-  dir_layout: "<module>/{api,internal,tests}; shared utilities in src/shared/ only"
+  dir_layout: "<module>/{api,internal}; shared utilities in src/shared/ only; tests mirror the source path under tests/unit/"
   symbol_casing: PascalCase types, camelCase functions, SCREAMING_SNAKE env vars
-  test_placement: colocated <name>.test.ts beside unit under test
-modules:
+  test_placement: tests/unit/<path under the source root>/<the language's test file> — the test tree is a SIBLING of the source tree, never inside it
+modules: # one entry per module; repeat per module
   - name: catalog
     responsibility: product browsing + search
     owns: ["src/features/catalog/**"]
     depends_on_modules: [] # DAG; drives task depends_on edges
     key_interfaces: # ONLY exports other modules may import
       - CatalogApi (src/features/catalog/api/index.ts)
-  - name: checkout
-    responsibility: cart -> payment orchestration
-    owns: ["src/features/checkout/**"]
-    depends_on_modules: [catalog]
-    key_interfaces:
-      - CheckoutApi (src/features/checkout/api/index.ts)
-data_contracts:
-  orders:
+data_contracts: # one block per entity; repeat per entity
+  order:
     storage: postgres table orders (migrations/NNNN_orders.sql)
     fields:
       - { field: id, type: uuid, required: true, notes: pk }
-      - { field: session_id, type: uuid, required: true, notes: fk sessions }
       - { field: total_cents, type: integer, required: true, notes: ">= 0" }
       - { field: status, type: "enum(pending,paid,failed)", required: true }
-      - { field: created_at, type: timestamptz, required: true, notes: db default now() }
-api_contracts:
+api_contracts: # one block per operation; repeat per operation
   payments:
     - endpoint: /api/checkout/pay
       method: POST
@@ -52,7 +46,6 @@ api_contracts:
       error_shape: { code: string, message: string, retryable: boolean }
 environment_matrix: # unparsed vars fail fast at startup in src/config/
   - { var: DATABASE_URL, dev: local docker postgres, ci: ephemeral service, prod: secret ref, required: true }
-  - { var: PAYMENT_API_KEY, dev: stub key, ci: stub key, prod: secret ref, required: true }
 decisions: # summary index; full records live in decisions/NNNN-title.md
   - id: D1
     title: Postgres over MongoDB

package/assets/templates/tasks.yaml

@@ -7,7 +7,7 @@ tasks:
   - id: C
     title: Scaffold project skeleton + typed config loader
     depends_on: []
-    file_ownership: ["src/config/**", "package.json"] # full repo-root-relative paths ONLY
+    file_ownership: ["src/config/**", "tests/unit/config/**", "package.json"] # full repo-root-relative paths ONLY
     acceptance:
       - "npm run build exits 0"
       - "config loads from env and fails fast on missing required vars"
@@ -37,7 +37,7 @@ tasks:
     parallel_group: wave-payments
     file_ownership:
       - src/features/checkout/internal/capture.ts      # per naming_conventions.dir_layout
-      - src/features/checkout/internal/capture.test.ts # per naming_conventions.test_placement
+      - tests/unit/features/checkout/internal/capture.test.ts # the mirrored test tree
       - docs/payment-retry.md
     artifacts: ["docs/payment-retry.md"]
     acceptance:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgen-mcp",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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/core/doc-navigator.mjs

@@ -576,16 +576,32 @@ export function docIndex(input, opts = {}) {
   if (mode === 'map') {
     if (!token) throw invalidInput('map mode requires a token', {});
     // Section-level retrieval: WHERE is this token mentioned?
+    //
+    // The sections OVERLAP — a parent section's body contains its children's —
+    // so a naive walk reports the same line once per containing section. The
+    // agent then paid for the same sentence three times to learn one fact.
+    // Every hit is reported ONCE, under the DEEPEST section that contains it.
     const re = new RegExp(wholeWordSource(token));
     const hits = [];
     for (const doc of collectDocs().docs) {
-      for (const section of buildSections(doc)) {
+      const sections = buildSections(doc);
+      const ownerOf = (line) => {
+        let owner = null;
+        for (const s of sections) {
+          if (line < s.line || line > s.endLine) continue;
+          if (owner === null || s.level > owner.level) owner = s;
+        }
+        return owner;
+      };
+      for (const section of sections) {
         const bodyLines = doc.lines.slice(section.line - 1, section.endLine);
         const matching = [];
         for (let i = 0; i < bodyLines.length; i++) {
-          if (re.test(bodyLines[i])) {
-            matching.push({ line: section.line + i, text: bodyLines[i].trim().slice(0, 200) });
-          }
+          if (!re.test(bodyLines[i])) continue;
+          const line = section.line + i;
+          const owner = ownerOf(line);
+          if (!owner || owner.slug !== section.slug) continue; // its deepest owner reports it
+          matching.push({ line, text: bodyLines[i].trim().slice(0, 200) });
         }
         if (!matching.length) continue;
         hits.push({
@@ -601,7 +617,10 @@ export function docIndex(input, opts = {}) {
       }
     }
     hits.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : a.line - b.line));
-    return { mode, data: { ref: token, sections: hits, sectionCount: hits.length } };
+    return {
+      mode,
+      data: { ref: token, sections: hits, sectionCount: hits.length, matchCount: hits.reduce((n, h) => n + h.occurrences, 0) },
+    };
   }
 
   // Overview (scale guard): the deduped inventory is always computed in full

package/src/core/refs.mjs

@@ -59,29 +59,61 @@ export function resolveTopic(topic, opts) {
 /**
  * Index one reference topic: its title, purpose and section list.
  *
+ * With `section`, it returns THAT section's entry — the same map, narrowed.
+ * A topic has a dozen sections; an agent that wants one of them should not
+ * have to take the dozen to find it.
+ *
  * @param {string} topic
- * @param {{assetsDir: string, skillDir: string|null}} opts
+ * @param {{assetsDir: string, skillDir: string|null, section?: string|null}} opts
  */
 export function indexTopic(topic, opts) {
   const resolved = resolveTopic(topic, opts);
   if (!resolved) throw notFound(`unknown reference '${topic}'`, { topic, known: REF_TOPICS });
   const doc = parseMarkdown(readFileSync(resolved.path, 'utf8'));
-  return {
-    topic: resolved.topic,
-    root: resolved.root,
-    title: doc.headings.find((h) => h.level === 1)?.text ?? resolved.topic,
-    sections: buildSections(doc).map((s) => ({
+  const sections = buildSections(doc)
+    // The topic's own H1 is not a SECTION — it is the topic. Listing it
+    // would put "the whole document" at index 0 and make every section map
+    // carry an entry that says nothing.
+    .filter((s) => s.level > 1)
+    .map((s) => ({
       slug: s.slug,
       title: s.title,
       level: s.level,
       line: s.line,
       endLine: s.endLine,
-    })),
+    }));
+  if (opts.section) {
+    const hit = findSection(doc, opts.section);
+    if (!hit) throw noSuchSection(resolved.topic, opts.section, sections.map((s) => s.slug));
+    const one = sections.find((s) => s.slug === hit.slug);
+    return {
+      topic: resolved.topic,
+      root: resolved.root,
+      title: doc.headings.find((h) => h.level === 1)?.text ?? resolved.topic,
+      section: one,
+      sections: [one],
+    };
+  }
+  return {
+    topic: resolved.topic,
+    root: resolved.root,
+    title: doc.headings.find((h) => h.level === 1)?.text ?? resolved.topic,
+    sections,
   };
 }
 
 /**
- * Read one section (or the whole topic).
+ * Read one section (or the topic's section INDEX).
+ *
+ * WHY THE DEFAULT IS THE INDEX: a whole topic is ~11 KB of English, and the
+ * whole design of this module is that the agent reads a SECTION. Returning
+ * the entire topic when the caller named no section made the expensive
+ * answer the default — so an agent that forgot the section paid for the
+ * whole protocol instead of getting the map that would have told it which
+ * section it needed.
+ *
+ * So: no section → the INDEX (the map) plus the exact next call. The whole
+ * topic is `section: '*'` — deliberate, never the default.
  *
  * @param {string} topic
  * @param {{assetsDir: string, skillDir: string|null, section?: string|null}} opts
@@ -89,19 +121,32 @@ export function indexTopic(topic, opts) {
 export function readTopic(topic, opts) {
   const resolved = resolveTopic(topic, opts);
   if (!resolved) throw notFound(`unknown reference '${topic}'`, { topic, known: REF_TOPICS });
-  const text = readFileSync(resolved.path, 'utf8');
-  const doc = parseMarkdown(text);
 
-  if (!opts.section) {
+  // The whole topic — asked for explicitly.
+  if (opts.section === '*') {
+    const doc = parseMarkdown(readFileSync(resolved.path, 'utf8'));
     return {
       topic: resolved.topic,
       root: resolved.root,
       section: null,
+      whole: true,
       text: doc.lines.join('\n'),
       lines: doc.lines.length,
     };
   }
 
+  // No section named: the MAP, not the text.
+  if (!opts.section) {
+    const indexed = indexTopic(topic, opts);
+    return {
+      ...indexed,
+      whole: false,
+      next: `archgen_refs{action:'read',topic:'${resolved.topic}',section:'<the section you need>'}`,
+      hint: 'read ONE section — a whole topic is a map plus the text you did not ask for.',
+    };
+  }
+
+  const doc = parseMarkdown(readFileSync(resolved.path, 'utf8'));
   const section = findSection(doc, opts.section);
   if (!section) {
     const available = buildSections(doc).map((s) => s.slug);
@@ -136,14 +181,34 @@ export function searchTopic(topic, token, opts) {
   // Whole-word: a hit must not be glued to word characters on either side.
   const re = new RegExp(`(?<![A-Za-z0-9_])${esc}(?![A-Za-z0-9_])`, 'i');
 
+  // The sections OVERLAP: a parent section's body runs to the next heading at
+  // the same or shallower level, so it CONTAINS its children. Reporting a hit
+  // once per containing section therefore delivered the same line three times
+  // for a three-level nesting — the agent paid for the same sentence three
+  // times to learn one fact.
+  //
+  // So every hit is reported ONCE, under the DEEPEST section that contains
+  // it: the most specific place the line actually lives.
+  const sections = buildSections(doc).filter((s) => s.level > 1);
+  const ownerOf = (line) => {
+    let owner = null;
+    for (const s of sections) {
+      if (line < s.line || line > s.endLine) continue;
+      if (owner === null || s.level > owner.level) owner = s;
+    }
+    return owner;
+  };
+
   const hits = [];
-  for (const section of buildSections(doc)) {
+  for (const section of sections) {
     const bodyLines = doc.lines.slice(section.line - 1, section.endLine);
     const matches = [];
     for (let i = 0; i < bodyLines.length; i++) {
-      if (re.test(bodyLines[i])) {
-        matches.push({ line: section.line + i, text: bodyLines[i].trim().slice(0, 200) });
-      }
+      if (!re.test(bodyLines[i])) continue;
+      const line = section.line + i;
+      const owner = ownerOf(line);
+      if (!owner || owner.slug !== section.slug) continue; // its deepest owner reports it
+      matches.push({ line, text: bodyLines[i].trim().slice(0, 200) });
     }
     if (matches.length) {
       hits.push({
@@ -157,7 +222,15 @@ export function searchTopic(topic, token, opts) {
       });
     }
   }
-  return { topic: resolved.topic, root: resolved.root, token, sections: hits, sectionCount: hits.length };
+  return {
+    topic: resolved.topic,
+    root: resolved.root,
+    token,
+    sections: hits,
+    sectionCount: hits.length,
+    // The distinct lines behind those hits — reported once, counted once.
+    matchCount: hits.reduce((n, h) => n + h.occurrences, 0),
+  };
 }
 
 /**

package/src/envelope.mjs

@@ -42,7 +42,12 @@ export function fail(e, meta = {}) {
 export async function guard(body, ctx, args) {
   try {
     const data = await body(ctx, args);
-    const meta = typeof data === 'object' && data !== null && data.__meta ? data.__meta : ctx.meta();
+    // A tool that carries its own meta (the map to the rest of the data)
+    // EXTENDS the envelope's meta — it never replaces it. The envelope's
+    // meta is the contract (server version, skill version, project root,
+    // warnings); the tool's meta is the map to whatever it did not send.
+    const own = typeof data === 'object' && data !== null && data.__meta ? data.__meta : null;
+    const meta = own ? { ...ctx.meta(), ...own } : ctx.meta();
     const payload = typeof data === 'object' && data !== null && data.__meta ? data.data : data;
     return ok(payload, meta);
   } catch (e) {
@@ -63,3 +68,95 @@ export function toToolResult(envelope) {
     ...(envelope.ok ? {} : { isError: true }),
   };
 }
+
+// ── collection projection ───────────────────────────────────────────────────
+//
+// WHY: a tool that answers "give me everything in this collection" makes the
+// agent pay for the whole collection every time it needs ONE item — and the
+// only way to get one item is to take the whole collection and pick from it.
+// That is the wrong default for both sides: the server sends text nobody
+// asked for, and the agent pays for it in context.
+//
+// The fix is not a smaller cap — a cap silently truncates, and the agent
+// cannot tell what it missed. It is a SELECTOR plus a MAP TO THE REST: every
+// collection-shaped answer can be narrowed to one item, and every answer says
+// what else exists and exactly how to fetch it. The agent fetches; it never
+// receives a dump.
+
+/**
+ * The default bound on a collection.
+ *
+ * It exists so a LARGE project cannot dump itself: a 500-task plan, a
+ * 250-node graph, a 200-file artifact tree. The bound is the CALLER's to
+ * raise (`limit`), and every answer says how many items exist and exactly
+ * which call returns the next slice — so a bound never hides data, it only
+ * makes the agent ask for it.
+ */
+export const DEFAULT_LIMIT = 50;
+
+/**
+ * Narrow a collection to what the caller asked for, and report what is left.
+ *
+ * `limit` is the caller's bound, not the server's: a caller that needs the
+ * whole set asks for it (`limit: null` means no bound). The default is
+ * finite so a huge collection is never dumped — and the report says exactly
+ * how many remain and which call gets the next slice.
+ *
+ * @param {any[]} items
+ * @param {{limit?: number|null, offset?: number|null, next?: string|null}} [opts]
+ * @returns {{items: any[], total: number, returned: number, offset: number, limit: number|null, truncated: boolean, next: string|null}}
+ */
+export function project(items, opts = {}) {
+  const all = Array.isArray(items) ? items : [];
+  const offset = Math.max(0, Number(opts.offset ?? 0) || 0);
+  const rawLimit = opts.limit === undefined ? DEFAULT_LIMIT : opts.limit;
+  const limit = rawLimit === null ? null : Math.max(0, Math.trunc(Number(rawLimit) || 0));
+  const slice = limit === null ? all.slice(offset) : all.slice(offset, offset + limit);
+  const truncated = offset + slice.length < all.length;
+  return {
+    items: slice,
+    total: all.length,
+    returned: slice.length,
+    offset,
+    limit,
+    truncated,
+    // The exact next call — not a hint, not a cursor the agent has to build.
+    next: truncated ? (opts.next ?? null) : null,
+  };
+}
+
+/**
+ * The uniform "what else is there" block.
+ *
+ * Every collection-shaped answer carries it, so the agent always knows that
+ * more exists and exactly how to get it — without the server having sent any
+ * of it.
+ *
+ * @param {{total?: number, returned?: number, available?: object, more?: string|null, next?: string|null}} info
+ * @returns {object}
+ */
+export function moreMeta(info = {}) {
+  const meta = {};
+  if (info.total !== undefined) meta.total = info.total;
+  if (info.returned !== undefined) meta.returned = info.returned;
+  if (info.available && Object.keys(info.available).length) meta.available = info.available;
+  if (info.more) meta.more = info.more;
+  if (info.next) meta.next = info.next;
+  return meta;
+}
+
+/**
+ * Attach meta to a payload.
+ *
+ * The envelope already understands this shape (`__meta` is lifted out of the
+ * data), so a tool can add the map to the rest without knowing anything
+ * about the envelope.
+ *
+ * @param {unknown} data
+ * @param {object} meta
+ * @returns {{data: unknown, __meta: object}}
+ */
+export function withMeta(data, meta) {
+  return { data, __meta: meta };
+}
+

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

@@ -7,6 +7,7 @@ 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.';
 
@@ -19,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,
 });
 
@@ -36,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 });
       }
@@ -59,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.