simt-dev 0.7.0 → 0.7.1

package/src/ledger/index.mjs

@@ -48,7 +48,13 @@ export async function treeId(root) {
     // tree it names. `git add -A` would take it once the file exists, and the
     // line would prove a tree that stopped existing when the line was written
     // (review 0003 Q19).
-    const excludes = TREE_EXCLUDES.map((p) => `:(exclude)${p}`);
+    //
+    // Where .gitignore already keeps a path out of the index, the pathspec
+    // would name an ignored path, and `git add` refuses it ("use -f") - and -f
+    // would force the very state back into the tree. The excludes therefore
+    // carry only the paths git does not already ignore.
+    const ignored = await ignoredSet(root, TREE_EXCLUDES);
+    const excludes = TREE_EXCLUDES.filter((p) => !ignored.has(p)).map((p) => `:(exclude)${p}`);
     await exec('git', ['add', '-A', '--', '.', ...excludes], { cwd: root, env });
     const { stdout } = await exec('git', ['write-tree'], { cwd: root, env });
     return stdout.trim();
@@ -57,6 +63,29 @@ export async function treeId(root) {
   }
 }
 
+/**
+ * The paths git already ignores, so the exclude pathspecs do not name them.
+ * A repository with no .gitignore ignores nothing, and every exclude ships
+ * exactly as before.
+ *
+ * @param {string} root
+ * @param {string[]} paths
+ * @returns {Promise<Set<string>>}
+ */
+async function ignoredSet(root, paths) {
+  try {
+    // Paths as argv, not `--stdin`: `promisify(execFile)` drops the `input`
+    // option, so a stdin-fed `check-ignore` waits for input that never comes
+    // and the promise never settles.
+    const { stdout } = await exec('git', ['check-ignore', ...paths], { cwd: root });
+    return new Set(String(stdout).split('\n').filter(Boolean));
+  } catch {
+    // `check-ignore` exits 1 when nothing is ignored - the common case, not an
+    // error. Failing to the full exclude list is the pre-filter behaviour.
+    return new Set();
+  }
+}
+
 /**
  * Append one run. The output itself is not stored: the digest is enough to notice a
  * change, and a ledger that kept logs would keep whatever the command printed.

package/src/local/client.mjs

@@ -18,14 +18,12 @@ function guardEndpoint(endpoint, { allowRemote = false } = {}) {
   if (!endpoint || typeof endpoint !== 'object') {
     return { ok: false, error: 'local model endpoint is not configured', refusedRemote: false };
   }
+  // `url` and `model` are validated once, where the config is read
+  // (`local/config.mjs`): an endpoint that reaches this function has both. What is left
+  // here is the one rule the config cannot enforce - a loopback-only default - and that
+  // is why this function still exists (review 0003 Q83).
   const rawUrl = typeof endpoint.url === 'string' ? endpoint.url.trim() : '';
-  if (!rawUrl) {
-    return { ok: false, error: 'local model endpoint is missing `url`', refusedRemote: false };
-  }
   const model = typeof endpoint.model === 'string' ? endpoint.model.trim() : '';
-  if (!model) {
-    return { ok: false, error: 'local model endpoint is missing `model`', refusedRemote: false };
-  }
   const apiKey = typeof endpoint.apiKey === 'string' && endpoint.apiKey.length > 0 ? endpoint.apiKey : null;
   const loopback = isLoopbackUrl(rawUrl);
   if (!loopback && !allowRemote) {

package/src/locate.mjs

@@ -35,23 +35,47 @@ export function renderLocator(command, { subject = CLI, remedy = `REMEDY run: np
   const D = '$';
   return `# ${D}${BIN_ENV} must name ONE program: an executable on PATH, or a .mjs entry
 # point to hand to node. It cannot be a command line, because there is no safe way
-# to split one in sh without eval, and a value with a space is refused rather than
-# half-executed - running from a source checkout is normal for anyone working on
-# this project itself, so this path has to work with no install step.
+# to split one in sh without eval, and a value with a space that names no file is
+# refused rather than half-executed - running from a source checkout is normal for
+# anyone working on this project itself, so this path has to work with no install step.
+#
+# Every .mjs entry point goes through run_node, which checks for node first: a GUI
+# client's PATH often carries none (nvm is sourced only in an interactive shell), and
+# exec node there fails with 127 and no explanation of what to install.
+run_node() {
+  if ! command -v node >/dev/null 2>&1; then
+    echo "${CLI}: cannot find node to run ${D}1." >&2
+    echo "  the hook runs a .mjs entry point through node; install Node >= 22.20.0," >&2
+    echo "  or set ${BIN_ENV} to an executable ${CLI}" >&2
+    exit 1
+  fi
+  entry="${D}1"
+  shift
+  exec node "${D}entry" "${D}@"
+}
+
 run_simt_dev() {
   case "${D}1" in
     *' '*)
+      # A space is ambiguous as text and unambiguous as a file: a value that names
+      # something on disk is a path in a directory with a space, and runs as one.
+      if [ -f "${D}1" ]; then
+        case "${D}1" in
+          *.mjs)
+            run_node "${D}@"
+            ;;
+          *)
+            exec "${D}@"
+            ;;
+        esac
+      fi
       echo "${CLI}: ${D}${BIN_ENV} names a command line, not a program." >&2
       echo "  set it to a single executable or a .mjs path, e.g." >&2
       echo "    ${BIN_ENV}=/path/to/checkout/${BIN_REL}" >&2
       exit 1
       ;;
     *.mjs)
-      # shift first: "${D}@" still holds ${D}1, which would pass the program path to
-      # itself as the first argument.
-      program="${D}1"
-      shift
-      exec node "${D}program" "${D}@"
+      run_node "${D}@"
       ;;
     *)
       exec "${D}1" "${D}@"
@@ -64,7 +88,7 @@ if [ -n "${D}{${BIN_ENV}:-}" ]; then
 fi
 
 if [ -f "${D}ROOT/node_modules/${PACKAGE_NAME}/${BIN_REL}" ]; then
-  exec node "${D}ROOT/node_modules/${PACKAGE_NAME}/${BIN_REL}" ${command}
+  run_node "${D}ROOT/node_modules/${PACKAGE_NAME}/${BIN_REL}" ${command}
 fi
 
 # The binary this repository downloaded for itself: the pinned bytes, no node.

package/src/manifest/schema.mjs

@@ -0,0 +1,213 @@
+// The manifest's own schema: one table of the keys this file may carry, and one
+// loader that says what is wrong with the file rather than throwing or guessing.
+//
+// The manifest was read in 29 places, each doing a bare `JSON.parse` and then
+// reaching for the key it wanted. That is three answers to "what is this repo" -
+// the parse, the key access, and whatever default the caller invented - and a
+// manifest with `"mode": "kernal"` reached the projection as a mode it had never
+// heard of. A typo in one key silently changed behaviour, because nothing in the
+// tool had ever said what the keys are (review 0003 Q69).
+//
+// Every shape below was read off the manifest this repository carries, not from
+// memory: the first draft of this table called `limits.fileLines` a positive integer
+// and `surfaces` an object, and both are wrong in the only file the tool has to hand.
+// `test/manifest-schema.test.mjs` holds the table to that file, which is the check
+// that would have caught it.
+//
+// `owner` is the reason a key is in this table at all. A `tool` key is written by
+// this binary and a repository editing it is fighting the writer; a `repo` key is
+// the repository's own declaration and this tool only reads it. The distinction is
+// already load-bearing (`GENERATED_KEYS`, `init` keeping `limits`), and stating it
+// here is what keeps the two from drifting apart.
+
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { MANIFEST_FILE, MANIFEST_LEGACY } from '../name.mjs';
+
+/** Absent means 1: the field arrived after the file did, and every file predates it. */
+const MANIFEST_VERSION = 1;
+
+/**
+ * The manifest a repository has, which is not necessarily the one this tool would write.
+ *
+ * The file was renamed from `simt-dev.json` to `simt.json`. Every read site used to say
+ * `join(root, MANIFEST_FILE)` and would have reported an adopted repository as unadopted the
+ * day the constant moved - and "no manifest" means "never adopted", which is the answer
+ * that offers to re-adopt a repo that is already done. Fourteen repositories carry the
+ * old name on disk.
+ *
+ * So the old name is read as a fallback and the new one is written. `writeManifest`
+ * renames rather than creating a second file, which is how the window closes: the first
+ * `simt init` or `simt sync` in an adopted repo retires the old name by moving it.
+ */
+export async function manifestPath(root) {
+  const next = join(root, MANIFEST_FILE);
+  if (existsSync(next)) return next;
+  const previous = join(root, MANIFEST_LEGACY);
+  return existsSync(previous) ? previous : next;
+}
+
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const isStringList = (value) => Array.isArray(value) && value.every((item) => typeof item === 'string');
+const isPositiveInt = (value) => Number.isInteger(value) && value > 0;
+
+/**
+ * The keys a manifest may carry.
+ *
+ * `check` returns a sentence naming what is wrong, or null. It returns a sentence
+ * rather than a boolean because the reader of a problem is a person looking at a file
+ * they edited by hand, and "invalid" tells them nothing they did not know.
+ */
+export const KEYS = [
+  { key: '$comment', owner: 'tool', generated: true, since: '0.7.0', check: (v) => (typeof v === 'string' || isStringList(v) ? null : '$comment must be a string or a list of strings') },
+  { key: 'id', owner: 'tool', since: '0.7.0', check: (v) => (typeof v === 'string' && v.length > 0 ? null : 'id must be a non-empty string') },
+  { key: 'version', owner: 'tool', since: '0.9.0', check: (v) => (Number.isInteger(v) && v >= 1 ? null : 'version must be an integer of at least 1') },
+  { key: 'stack', owner: 'tool', since: '0.7.0', check: (v) => (isStringList(v) ? null : 'stack must be a list of profile ids') },
+  { key: 'limits', owner: 'repo', since: '0.7.0', check: (v) => (isObject(v) ? null : 'limits must be an object') },
+  // {warn, error, excludeTextFiles, exclude} - ADR-005's two tiers plus the paths a
+  // repository opts out of, all of which the repository owns and `init` keeps.
+  { key: 'limits.fileLines', owner: 'repo', since: '0.7.0', check: (v) => (isObject(v) && isPositiveInt(v.warn) && isPositiveInt(v.error) && v.error >= v.warn ? null : 'limits.fileLines must be {warn, error} with error >= warn') },
+  { key: 'limits.coverage', owner: 'repo', since: '0.7.0', check: (v) => (v === null || (typeof v === 'number' && v >= 0 && v <= 100) ? null : 'limits.coverage must be null or a percentage') },
+  { key: 'gates', owner: 'repo', since: '0.7.0', check: (v) => (isObject(v) ? null : 'gates must be an object of gate name to command') },
+  { key: 'localSkills', owner: 'repo', since: '0.7.0', check: (v) => (isStringList(v) ? null : 'localSkills must be a list of skill ids') },
+  { key: 'profiles', owner: 'repo', since: '0.8.0', check: (v) => (isStringList(v) ? null : 'profiles must be a list of profile ids') },
+  { key: 'substitutions', owner: 'repo', since: '0.8.0', check: (v) => (isObject(v) ? null : 'substitutions must be an object keyed by rule id') },
+  { key: 'packs', owner: 'repo', since: '0.8.0', check: (v) => (Array.isArray(v) ? null : 'packs must be a list') },
+  // A workspace declaration is a path relative to the repository; `workspace.mjs`
+  // refuses to walk one that resolves outside, so the type is the whole check.
+  { key: 'workspace', owner: 'repo', since: '0.7.0', check: (v) => (typeof v === 'string' ? null : 'workspace must be a path string') },
+  { key: 'decisions', owner: 'repo', since: '0.8.0', check: (v) => (isObject(v) ? null : 'decisions must be an object') },
+  { key: 'budget', owner: 'repo', since: '0.8.0', check: (v) => (isObject(v) ? null : 'budget must be an object') },
+  { key: 'budget.bytes', owner: 'repo', since: '0.8.0', check: (v) => (isPositiveInt(v) ? null : 'budget.bytes must be a positive integer') },
+  { key: 'mode', owner: 'repo', since: '0.8.0', check: (v) => (v === 'full' || v === 'kernel' ? null : 'mode must be "full" or "kernel", not ' + JSON.stringify(v)) },
+  { key: 'shared', owner: 'repo', since: '0.8.0', check: (v) => (isObject(v) ? null : 'shared must be an object') },
+  // The overlay `plan/template.mjs` compiles over the default tracker body; an array
+  // would be accepted by an object-typed read and then produce an empty template.
+  { key: 'plans', owner: 'repo', since: '0.7.0', check: (v) => (isObject(v) ? null : 'plans must be an object overlay') },
+  // Null and absent both mean "the global standard applies" (manifestDrift's own
+  // rule), and a list is what `init` writes. An object here is a shape nothing has
+  // ever produced, so accepting it would be the validator blessing a typo.
+  { key: 'surfaces', owner: 'repo', since: '0.8.0', check: (v) => (v === null || isStringList(v) ? null : 'surfaces must be null or a list of surface ids') },
+  { key: 'projection', owner: 'tool', generated: true, since: '0.7.0', check: (v) => (isObject(v) ? null : 'projection must be an object') },
+];
+
+const KNOWABLE = new Set(KEYS.map((entry) => entry.key));
+
+/** The keys this tool writes, derived from the table: the `generated` marks above. */
+export const GENERATED_KEYS_OF = new Set(KEYS.filter((entry) => entry.generated === true).map((entry) => entry.key));
+
+
+/**
+ * Namespaces a consumer registered against this table.
+ *
+ * A namespace is a sub-object of the manifest that another part of the tool owns -
+ * plan 0004's `work` is the first. It registers its keys here rather than editing the
+ * table, so adding one touches two files and no reader has to learn a second shape
+ * (review 0003 Q69).
+ */
+const NAMESPACES = new Map();
+
+/**
+ * Declare the keys of one namespace. Registered keys are checked exactly like top-level
+ * ones; a namespace nobody registered is left alone, because an unknown key has never
+ * been an error in this file.
+ *
+ * @param {string} name the manifest key that carries the namespace
+ * @param {{key: string, since?: string, check: (value: unknown) => string|null}[]} keys
+ * @returns {number} how many keys the namespace declares
+ */
+export function registerNamespace(name, keys) {
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+    throw new Error('namespace "' + name + '" must be lower-case words joined by hyphens');
+  }
+  if (KNOWABLE.has(name)) throw new Error('namespace "' + name + '" is already a manifest key');
+  if (NAMESPACES.has(name)) throw new Error('namespace "' + name + '" is already registered');
+  if (!Array.isArray(keys) || keys.length === 0) {
+    throw new Error('namespace "' + name + '" must register at least one key');
+  }
+  for (const entry of keys) {
+    if (typeof entry?.key !== 'string' || !/^[a-z][a-z0-9]*$/.test(entry.key)) {
+      throw new Error('namespace "' + name + '" keys must be lower-case single words');
+    }
+    if (typeof entry.check !== 'function') {
+      throw new Error('namespace "' + name + '" key "' + entry.key + '" has no check');
+    }
+  }
+  NAMESPACES.set(name, keys.map((entry) => ({ owner: 'repo', since: '0.9.0', ...entry })));
+  return keys.length;
+}
+
+/** The namespaces a consumer declared, for a reader that needs the whole set. */
+export function registeredNamespaces() {
+  return [...NAMESPACES.keys()].sort();
+}
+
+/**
+ * What is wrong with one parsed manifest.
+ *
+ * An unknown key is not a problem. A repository that keeps its own note in this file
+ * is doing the thing the file's own comment invites, and a validator that refused it
+ * would be the tool insisting its schema is the whole of a file it calls the
+ * repository's. Only a KNOWN key with an impossible value is reported.
+ */
+export function manifestProblems(manifest) {
+  const problems = [];
+  for (const { key, check } of KEYS) {
+    const [head, tail] = key.includes('.') ? key.split('.') : [key, null];
+    if (!(head in manifest)) continue;
+    if (tail !== null && (!isObject(manifest[head]) || !(tail in manifest[head]))) continue;
+    const value = tail === null ? manifest[head] : manifest[head][tail];
+    if (value === undefined) continue;
+    const problem = check(value);
+    if (problem !== null) problems.push(problem);
+  }
+  for (const [name, keys] of NAMESPACES) {
+    const value = manifest[name];
+    if (!isObject(value)) continue;
+    for (const entry of keys) {
+      if (!(entry.key in value) || value[entry.key] === undefined) continue;
+      const problem = entry.check(value[entry.key]);
+      if (problem !== null) problems.push(name + '.' + entry.key + ': ' + problem);
+    }
+  }
+  return problems;
+}
+
+/**
+ * The manifest a repository has, with its problems named.
+ *
+ * `manifest` is null when there is no file and when the file does not parse, because
+ * a caller that receives a half-read object cannot tell which it has - and the one
+ * caller that did (`fingerprint`) returned `{error}` in place of a manifest, so a
+ * broken file looked like a declaration of a key called `error` (review 0003 Q69).
+ * `exists` and `problems` are what tell the two apart, and neither is optional.
+ *
+ * @returns {Promise<{manifest: object|null, exists: boolean, version: number, problems: string[], path: string}>}
+ */
+export async function loadManifest(root) {
+  const path = await manifestPath(root);
+  let text;
+  try {
+    text = await readFile(path, 'utf8');
+  } catch {
+    return { manifest: null, exists: false, version: MANIFEST_VERSION, problems: [], path };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    return { manifest: null, exists: true, version: MANIFEST_VERSION, problems: [`unparseable: ${error.message}`], path };
+  }
+  if (!isObject(parsed)) {
+    return { manifest: null, exists: true, version: MANIFEST_VERSION, problems: ['not a JSON object'], path };
+  }
+  return {
+    manifest: parsed,
+    exists: true,
+    version: Number.isInteger(parsed.version) ? parsed.version : MANIFEST_VERSION,
+    problems: manifestProblems(parsed),
+    path,
+  };
+}

package/src/mcp/resources.mjs

@@ -199,15 +199,9 @@ export async function readResource(uri, root = process.cwd()) {
     const [rules, mdc] = await Promise.all([loadRules(null), loadMdcRules()]);
     const rule = [...rules, ...mdc].find((candidate) => candidate.id === parsed.id);
     if (rule === undefined) return null;
-    const text = `${frontmatterOf(rule)}\n${rule.body ?? ''}`.trim();
-    return {
-      uri,
-      mimeType: 'text/markdown',
-      text,
-      // The body a tool returns is redacted for the same reason: a reader outside this
-      // estate is told what the rule says and not which directory here it is filed in.
-      bytes: Buffer.byteLength(text),
-    };
+    // The body a tool returns is redacted for the same reason: a reader outside this
+    // estate is told what the rule says and not which directory here it is filed in.
+    return { uri, mimeType: 'text/markdown', text: `${frontmatterOf(rule)}\n${rule.body ?? ''}`.trim() };
   }
 
   // `loadDecisions` reads the index, not the records: it reports status, currency and
@@ -218,7 +212,10 @@ export async function readResource(uri, root = process.cwd()) {
   if (decision === undefined) return null;
   const raw = await readFile(join(DECISIONS_DIR, decision.file), 'utf8');
   const text = redactInternalPaths(redactEstate(raw)).trim();
-  return { uri, mimeType: 'text/markdown', text, bytes: Buffer.byteLength(text) };
+  // `bytes` is not a `ResourceContents` field: a client validating the result against
+  // the specification sees an unexpected property, and the length is `text.length` away
+  // (Q56).
+  return { uri, mimeType: 'text/markdown', text };
 }
 
 function frontmatterOf(rule) {

package/src/mcp/server.mjs

@@ -24,6 +24,7 @@ import { createInterface } from 'node:readline';
 import { CLI } from '../name.mjs';
 import { getPrompt, PROMPTS } from './prompts.mjs';
 import { RESOURCE_TEMPLATES, listResources, readResource } from './resources.mjs';
+import { check } from './schema.mjs';
 
 /**
  * Every protocol revision this server speaks, newest first.
@@ -49,6 +50,8 @@ export const RPC = {
   PARSE: -32700,
   REQUEST: -32600,
   METHOD: -32601,
+  /** Arguments that do not match the `inputSchema` the client was shown. */
+  INVALID_PARAMS: -32602,
   INTERNAL: -32603,
   /**
    * `UnsupportedProtocolVersionError`, renumbered to -32022 in 2026-07-28. The spec
@@ -86,6 +89,15 @@ const SERVER_INFO = { name: 'simt-dev', title: 'SIMT developer and agent tooling
  */
 const LIST_CACHE = { ttlMs: 3600000, cacheScope: 'private' };
 
+/**
+ * The largest request line this server will answer, in bytes.
+ *
+ * One mebibyte, because the largest honest argument here is a task description or a path
+ * list and both are kilobytes: a line past this is a malformed request or a stream that
+ * lost its newline, and neither should be parsed in full.
+ */
+const MAX_LINE_BYTES = 1 << 20;
+
 /**
  * Handle one parsed request. Pure with respect to the process: returns the response
  * object or null (for a notification), and never writes anywhere. Testable without a
@@ -117,7 +129,17 @@ export async function handle(request, tools, { packageVersion, state, root, sign
   if (request === null || typeof request !== 'object' || Array.isArray(request)) {
     return error(null, RPC.REQUEST, 'request must be a JSON object');
   }
+  // The envelope is checked before anything reads it. `jsonrpc:"2.0"` and an id that is
+  // a string, a number or absent are the three things every revision requires of a
+  // request. An object id used to be echoed back unchanged, which leaves the client
+  // holding an answer it cannot match to anything it sent (Q56).
+  if (request.jsonrpc !== '2.0') {
+    return error(null, RPC.REQUEST, 'request must carry jsonrpc:"2.0"');
+  }
   const { id, method, params } = request;
+  if (id !== undefined && id !== null && typeof id !== 'string' && typeof id !== 'number') {
+    return error(null, RPC.REQUEST, 'id must be a string, a number or absent');
+  }
   // A notification is a request with no id, and the spec's rule is unconditional: it
   // never gets a response, whatever its method. Answering one anyway desynchronises a
   // client that is waiting for the next real answer in the stream.
@@ -200,6 +222,15 @@ export async function handle(request, tools, { packageVersion, state, root, sign
         return error(id, RPC.METHOD, `no tool named "${name}"; call tools/list first`);
       }
       const args = params?.arguments ?? {};
+      // The schema in `tools/list` is the schema this server enforces. A tool that
+      // declares `required:['name']` and runs happily on `{}` answers a question nobody
+      // asked, and the answer looks like a real one - `skills_show` with no name used to
+      // be a lookup for the string "undefined" (Q56). Bad arguments are the client's
+      // mistake, so they are a protocol error and not a tool result.
+      const invalid = check(args, tool.inputSchema);
+      if (invalid !== null) {
+        return error(id, RPC.INVALID_PARAMS, `invalid arguments for ${name}: ${invalid}`);
+      }
       // The one impurity in this file, and scoped to it: progress has to reach
       // the client while the tool runs, not after it returns. Nothing else
       // writes here - diagnostics still go to stderr, never this stream.
@@ -222,17 +253,15 @@ export async function handle(request, tools, { packageVersion, state, root, sign
         // `outputSchema` and what it can index; the text block is what a client that
         // predates structured output reads. Emitting one without the other leaves half
         // the clients guessing, which is the state this release was filed for.
-        return reply({
-          content: [contentOf(payload)],
-          structuredContent: payload,
-          isError: false,
-        });
+        const shaped = bounded(payload);
+        return reply({ content: shaped.content, structuredContent: shaped.structuredContent, isError: false });
       } catch (failure) {
         // An error is a result too, and it carries the same two shapes: the remedy is
         // the part a model needs to act on, and it has to survive in whichever block the
         // client reads.
         const payload = { error: failure.message, remedy: failure.remedy ?? null };
-        return reply({ content: [contentOf(payload)], structuredContent: payload, isError: true });
+        const shaped = bounded(payload);
+        return reply({ content: shaped.content, structuredContent: shaped.structuredContent, isError: true });
       }
     }
 
@@ -280,8 +309,12 @@ export async function handle(request, tools, { packageVersion, state, root, sign
   }
 }
 
+// One entry point, named the way a client names it. This used to spell the CLI command
+// (`simt skills brief`) while the tool description called itself THE entry point and the
+// prompt pointed at `brief` - three answers to "where do I start", and the one a model
+// read first was the only one it could not call (Q56).
 const INSTRUCTIONS =
-  `Read-only. Every answer is JSON. \`${CLI} skills brief\` is the one to call first: it returns the pre-assembled set for a task, plus what it deliberately left out and why.`;
+  'Read-only. Every answer is JSON. Call `skills_brief` first: it returns the pre-assembled skill set for a task, plus what it deliberately left out and why, and it needs no index. Call `brief` for the repository packet once the index exists.';
 
 function serverInfo(packageVersion) {
   return { ...SERVER_INFO, version: packageVersion ?? '0.0.0' };
@@ -369,17 +402,28 @@ function describe(tool, version) {
   return entry;
 }
 
-/** Content is one text block. Bounded, and truncation is announced in the text itself -
- *  the same rule the CLI follows, because a model that cannot tell a truncated answer
- *  from a complete one will guess. */
-function contentOf(payload) {
-  let text = typeof payload === 'string' ? payload : JSON.stringify(payload, null, 2);
+/** Both blocks, bounded together.
+ *
+ * `maxBytes` used to cut the text block alone, so a client reading `structuredContent`
+ * got the whole payload beside a text block that said it had been truncated: two answers
+ * to one question, and the unannounced one was the larger. A truncated payload is not the
+ * payload, so the structured block says so in its own shape - a model validating against
+ * `outputSchema` reads a complete-looking object as complete and the missing part as
+ * absent, which is the one reading truncation must never produce (Q56). */
+function bounded(payload) {
+  const text = typeof payload === 'string' ? payload : JSON.stringify(payload, null, 2);
   const limit = typeof payload === 'object' && payload !== null ? payload.maxBytes : 0;
-  if (Number.isInteger(limit) && limit > 0 && Buffer.byteLength(text) > limit) {
-    const slice = Buffer.from(text).subarray(0, limit).toString('utf8');
-    text = `${slice}\nTRUNCATED ${Buffer.byteLength(text) - limit} bytes omitted; raise maxBytes`;
+  const size = Buffer.byteLength(text);
+  if (!Number.isInteger(limit) || limit <= 0 || size <= limit) {
+    return { content: [{ type: 'text', text }], structuredContent: payload };
   }
-  return { type: 'text', text };
+  const slice = Buffer.from(text).subarray(0, limit).toString('utf8');
+  const omitted = size - limit;
+  const cut = `${slice}\nTRUNCATED ${omitted} bytes omitted; raise maxBytes`;
+  return {
+    content: [{ type: 'text', text: cut }],
+    structuredContent: { truncated: true, omittedBytes: omitted, maxBytes: limit, text: cut },
+  };
 }
 
 function result(id, value) {
@@ -428,6 +472,16 @@ export async function serve(tools, { input = process.stdin, output = process.std
   try {
     for await (const line of rl) {
       if (line.trim() === '') continue;
+      // readline has already buffered this line, so the cap bounds what is parsed and
+      // answered rather than what is read. That is still the difference between a request
+      // the server refuses by name and one it takes apart for minutes: a 40 MB line used
+      // to reach `JSON.parse` and take the process with it (Q56).
+      if (Buffer.byteLength(line) > MAX_LINE_BYTES) {
+        output.write(
+          `${JSON.stringify(error(null, RPC.REQUEST, `request is larger than ${MAX_LINE_BYTES} bytes`))}\n`,
+        );
+        continue;
+      }
 
       // Parse and handling fail differently and must answer differently. A line that is
       // not JSON has no id to answer to, so it is a parse error with `id: null`; a

package/src/mcp/tools.mjs

@@ -248,9 +248,10 @@ const output = {
       workspace: { type: 'string' },
       body: { type: ['string', 'null'] },
       bodyFrom: { type: 'string' },
-      bodyText: { type: 'string' },
+      bodyText: { type: ['string', 'null'] },
+      reason: { type: ['string', 'null'], description: 'why there is no body, when there is none' },
     },
-    required: ['name', 'bytes', 'bodyFrom', 'requires', 'variants'],
+    required: ['name', 'bytes', 'body', 'bodyFrom', 'bodyText', 'reason', 'requires', 'variants'],
   },
   skills_find: {
     type: 'object',
@@ -426,6 +427,7 @@ const output = {
       cut: { type: 'array', items: { type: 'string' } },
       sections: { type: 'object', additionalProperties: { type: 'array', items: { type: 'string' } } },
       text: { type: 'string' },
+      note: { type: ['string', 'null'] },
     },
     required: ['root', 'kind', 'basis', 'task', 'scope', 'budget', 'bytes', 'before', 'floorHeld', 'cut', 'sections', 'text'],
   },
@@ -528,7 +530,7 @@ export const TOOLS = [
     outputSchema: output.doctor,
     name: 'doctor',
     description:
-      'Classify a repository: stack tags, emitted facts with the file that proved each, and manifest presence. Call this first when the repo is unknown.',
+      'Classify a repository: stack tags, the facts with the file that proved each, and manifest presence. Call this first when the repo is unknown. Read-only: `--fix` and `--diff` stay on the command.',
     inputSchema: rootArg,
     async run(args) {
       const root = rootOf(args);
@@ -577,7 +579,7 @@ export const TOOLS = [
     outputSchema: output.skills_brief,
     name: 'skills_brief',
     description:
-      'THE entry point. Resolve the skill set for a task: selected with why, deferred, and not selected with reason - the reasons let you override the resolver instead of guessing at it.',
+      'THE entry point. Resolve the skill set for a task: selected with why, deferred, and not selected with the reason to override.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -627,12 +629,18 @@ export const TOOLS = [
     async run(args) {
       const root = rootOf(args);
       const facts = await skillsShowFacts(root, args?.name, args ?? {});
+      // The schema promises `body: null` when there is no body, and this used to hand the
+      // prose that says so to the field a client tests for null: a caller checking `body`
+      // for null read a paragraph as a body (Q56). The prose moves to `reason`, which is
+      // where a model looks for what to do about it.
+      const missing = typeof facts.bodyText === 'string' && facts.bodyText.startsWith('(body unavailable');
       return {
         ...facts.skill,
         workspace: facts.workspace,
-        body: facts.body,
+        body: missing ? null : facts.body,
         bodyFrom: facts.bodyFrom,
-        bodyText: facts.bodyText,
+        bodyText: missing ? null : facts.bodyText,
+        reason: missing ? facts.bodyText : null,
       };
     },
   },
@@ -905,7 +913,37 @@ export const TOOLS = [
         build: false,
       });
       if (result.error) throw Object.assign(new Error('the index could not be read'), { remedy: `run: ${CLI} index` });
-      if (result.cold) throw Object.assign(new Error('this repository has no index to answer from'), { remedy: `run: ${CLI} index` });
+      // A repository with no index is not a failed call. Every surface points here first,
+      // so the one tool told to be the entry point must answer in a repository that has
+      // never been indexed - it falls back to the skill packet, which is read from the
+      // package rather than the tree, and names the command that unlocks the rest (Q56).
+      if (result.cold) {
+        const task = typeof args?.task === 'string' ? args.task : '';
+        const facts = await skillsBriefFacts(root, { ...(args ?? {}), task });
+        // Through JSON once, so the packet carries exactly what the text block shows: a
+        // property whose value is `undefined` survives `stringify` as nothing at all, and
+        // the two blocks would then describe different objects.
+        const text = JSON.stringify(facts, null, 2);
+        const packet = JSON.parse(text);
+        const size = Buffer.byteLength(text);
+        return {
+          root,
+          kind: 'skills',
+          basis: 'registry',
+          task,
+          scope: [],
+          budget,
+          bytes: size,
+          before: size,
+          // The skill packet is one document and is not cut to fit: saying the floor held
+          // when the answer is over it is the class of claim this review exists to remove.
+          floorHeld: size <= budget,
+          cut: size <= budget ? [] : ['text'],
+          sections: { skills: (packet.resolved ?? []).map((s) => s.name) },
+          text,
+          note: `no index here, so this is the skill packet; run: ${CLI} index for the repository packet`,
+        };
+      }
       return {
         root: result.root,
         kind: result.kind,