@panaversity/ksor 0.0.12 → 0.0.13

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # @panaversity/ksor
 
+## 0.0.13
+
+### Patch Changes
+
+- 8c5013b: A provider outage is never reported as "the record does not cover this"
+
+  When the embedding provider is down, the vector arm does not run — so an empty
+  result says nothing about coverage. It says we could not look. That distinction
+  was fixed once for records with a calibrated floor, and the condition was the
+  bug: it left the case out that matters most.
+
+  An **uncalibrated** record is the default state of every fresh scaffold. There
+  the emptiness came from the keyword arm, which abstains when it returns no rows
+  — and it returns nothing for almost every natural-language question, because
+  `websearch_to_tsquery` ANDs its terms (measured 12 of 12 on real questions). So
+  during any outage an uncalibrated record answered every question with
+  `abstained: true`, while the tool description instructs the agent to state that
+  as fact and never fall back on its own knowledge.
+
+  It reached this release because the existing test asked a question the keyword
+  arm could answer, so the degraded path served real hits and looked correct. Ask
+  the way a person asks and it did not. That case is now covered.
+
+  Found live against the published 0.0.12 with an invalid key — the same state a
+  rejected CI key had produced that morning, which is how likely this is.
+
+  **`ksor calibrate` also stops blessing a floor on far-domain evidence alone.**
+  The built-in out-of-corpus probes are all far-domain — dinner, taxes, boiling an
+  egg — and a shipped set cannot be scope-adjacent, because adjacency depends on a
+  corpus it has never seen. Far-domain probes score low against anything, so the
+  margin comes out inflated. Measured on one record, changing only the probe set:
+  built-ins reported "separable, margin 0.072" and recommended a floor; eight
+  scope-adjacent near-misses reported "NOT separable, margin -0.030" — and that
+  floor then answered six of the eight live, with citations. The tool already knew
+  to say "widen the probe set", but said it only on the not-separable branch, which
+  is when it is least needed. It now says it whenever the built-ins are used.
+
+- 692d296: `ksor ingest` says how much of the record no search will return
+
+  A chunk shorter than the navigation threshold is stored, embedded and readable —
+  and excluded from every retrieval arm by the serving predicate. That rule exists
+  for a good reason: a "See also: [a] [b] [c]" block should never be a search hit.
+  But it decides by LENGTH ALONE, so a short _substantive_ paragraph is caught by
+  it too — and a policy handbook is made of short substantive statements.
+
+  Measured on a realistic five-document operations handbook with real embeddings:
+  **10 of 16 chunks unsearchable, and one entire document that `outline` lists and
+  `read` returns in full but `search` can never find.** A complete policy
+  statement — "Probation: six months, with a written review at three and six" —
+  is 191 characters, so the record treats it as navigation. The ingest line
+  reported a cheerful `16 chunks; embedded 16` and said nothing.
+
+  It says it now:
+
+  ```
+  ingest: generation 1 — 2 nodes, 4 chunks; embedded 4, carried 0, failed 0
+    not searchable: 3 of 4 chunk(s) (75%) are shorter than the navigation
+      threshold — stored and readable, but no search returns them
+    FOUND ONLY BY NAME: knowledge/onboarding:prose — no searchable chunk at all
+  ```
+
+  This does **not** change the threshold, and nothing that was searchable stops
+  being so. Where that line belongs needs a gold-set measurement, which is issue
+  #55. What is fixed here is the silence — because the silence is what let a
+  record ship most of itself unfindable, and told its owner everything was fine.
+
+  The count is computed with the serving predicate's own admission test, and a db
+  test compares it against what the SQL actually admits: a report the database
+  disagrees with would be worse than none.
+
+- c4976dd: Two defects introduced in 0.0.12, found by verifying the published package live
+
+  **The discovery document became invalid exactly when a record became real.** The
+  MCP registry schema caps `ServerDetail.description` at **100 characters**
+  (2025-12-11). 0.0.12 started generating that description from the record's own
+  prose — a real improvement over the hard-coded sentence it replaced — and capped
+  it at 300. The unfilled placeholder is 88 characters and validates; a described
+  record's title plus scope sentence is routinely 150-350 and does not. So
+  `/.well-known/mcp/server.json` passed validation until the owner did the thing
+  the scaffold asks for, then silently stopped, with nothing in the build to say
+  so. It is now assembled inside the schema's budget and trimmed at a word
+  boundary rather than mid-word.
+
+  **The boot report reassured the operator in the one configuration that needs a
+  warning.** `KSOR_ALLOW_PUBLIC_UNAUTHENTICATED=1` permits an unauthenticated
+  public bind, and the auth line kept printing `DISABLED — 0.0.0.0 only, and a
+public bind will refuse to boot` — false on both counts, at the moment the whole
+  record is being served to anyone who can reach the port. It now says that,
+  naming the variable responsible.
+
+  Both shipped in 0.0.12 and both were mine; the aligned boot report and the
+  self-describing discovery document are otherwise unchanged.
+
 ## 0.0.12
 
 ### Patch Changes

package/dist/cli.mjs

@@ -16,7 +16,7 @@ import { bodyLimit } from "hono/body-limit";
 import { execFileSync, spawnSync } from "node:child_process";
 import { parseArgs } from "node:util";
 import { readFile, readdir, stat } from "node:fs/promises";
-//#region ../content-gateway/dist/main-CqOtG-q1.mjs
+//#region ../content-gateway/dist/main-B1G1VdMp.mjs
 /**
 * A connection could not be ESTABLISHED in time — retryable.
 *
@@ -1114,11 +1114,24 @@ g AS (
           WHERE tenant_id = $1 AND corpus_id = $2)
     ) AS gen
 )`;
-const ARM_WHERE$1 = `
+/**
+* The arm predicate, built for the parameter numbering of the query that uses
+* it — a FUNCTION, not a string the caller renumbers afterwards.
+*
+* It used to be derived with `ARM_WHERE.replaceAll("$5", "$4")`, which works
+* only while the predicate happens to contain exactly one placeholder and no
+* other text matching it. Adding any second parameter to the predicate breaks
+* every derived query silently — and when it breaks, the failure arrives as a
+* driver error that the serving layer correctly reduces to "content store
+* temporarily unavailable", which tells you nothing about the cause. Found by
+* tripping over it while trying a fix for issue #59; taking the number as an
+* argument makes the coupling visible instead of textual.
+*/
+const armWhere$1 = (kindsParam) => `
         c.tenant_id = $1 AND c.generation = g.gen
           AND c.embedding_status = 'embedded' AND ${SERVABLE$1}
           AND n.status = 'published'
-          AND ($5::text[] IS NULL OR n.kind = ANY($5::text[]))
+          AND (${kindsParam}::text[] IS NULL OR n.kind = ANY(${kindsParam}::text[]))
           AND ${DENY$1}
           AND ${AUDIENCE_ALLOWED$1}`;
 const JOINS$1 = `
@@ -1127,6 +1140,15 @@ const JOINS$1 = `
         JOIN sources s ON s.source_id = c.source_id AND s.tenant_id = c.tenant_id
                       AND s.generation = c.generation
         JOIN content_nodes n ON n.node_id = s.node_id AND n.tenant_id = s.tenant_id`;
+/**
+* Exported ONLY so a test can EXPLAIN the real thing.
+*
+* The index regression this fixes was announced as fixed once before, and came
+* back through a different clause, because nothing ever asserted the RESULT —
+* that the plan opens `idx_chunks_hnsw`. A timing threshold would be flaky and
+* would not have caught it either; the plan shape is the property that matters
+* (issue #59).
+*/
 const HYBRID_SQL$1 = `
 WITH RECURSIVE ${GEN_CTE$1}, ${DENIED_CTE$1},
     -- The top-k is taken by a PLAIN \`ORDER BY <distance> LIMIT\`, and the rank
@@ -1147,7 +1169,7 @@ WITH RECURSIVE ${GEN_CTE$1}, ${DENIED_CTE$1},
         FROM (
             SELECT c.chunk_id, g.gen, (c.embedding <=> $3::vector) AS dist
             ${JOINS$1}
-            WHERE ${ARM_WHERE$1}
+            WHERE ${armWhere$1("$5")}
             ORDER BY c.embedding <=> $3::vector, c.chunk_id
             LIMIT $6
         ) ranked),
@@ -1156,7 +1178,7 @@ WITH RECURSIVE ${GEN_CTE$1}, ${DENIED_CTE$1},
                row_number() OVER (ORDER BY ts_rank_cd(c.search_tsv,
                    websearch_to_tsquery($9::regconfig, $4)) DESC, c.chunk_id) AS r
         ${JOINS$1}
-        WHERE ${ARM_WHERE$1}
+        WHERE ${armWhere$1("$5")}
           AND c.search_tsv @@ websearch_to_tsquery($9::regconfig, $4)
         ORDER BY r LIMIT $6),
     fused AS (
@@ -1179,10 +1201,10 @@ WITH RECURSIVE ${GEN_CTE$1.replace("$8", "$6")}, ${DENIED_CTE$1}
            ts_rank_cd(c.search_tsv, websearch_to_tsquery($7::regconfig, $3)) AS score,
            g.gen, n.permalink
     ${JOINS$1}
-    WHERE ${ARM_WHERE$1.replaceAll("$5", "$4")}
+    WHERE ${armWhere$1("$4")}
       AND c.search_tsv @@ websearch_to_tsquery($7::regconfig, $3)
     ORDER BY score DESC, c.chunk_id LIMIT $5`;
-`${GEN_CTE$1.replace("$8", "$5")}${DENIED_CTE$1}${JOINS$1}${ARM_WHERE$1.replaceAll("$5", "$4")}`;
+`${GEN_CTE$1.replace("$8", "$5")}${DENIED_CTE$1}${JOINS$1}${armWhere$1("$4")}`;
 const HIT_COLUMNS = 9;
 /** Serialize a query vector as a pgvector literal. */
 function vectorLiteral$1(vector) {
@@ -2604,7 +2626,7 @@ async function search(ctx, query, k = 10) {
 			const r = await client.query("SELECT active_generation FROM corpora WHERE tenant_id = $1 AND corpus_id = $2", [inst.tenantId, inst.corpusId]);
 			return Number(r.rows[0]?.active_generation ?? 0) === 0;
 		}, audienceScope(ctx));
-		const reason = embedFailed && inst.abstain.vectorFloor !== null ? "unavailable" : unpublished ? "unpublished" : "abstained";
+		const reason = embedFailed ? "unavailable" : unpublished ? "unpublished" : "abstained";
 		return {
 			ok: false,
 			abstained: reason === "abstained",
@@ -3595,9 +3617,10 @@ function withoutSdkResponseModeWarning(body) {
 * it survivable (`buildAuth` refuses a non-loopback bind without auth, so the
 * only way to read this line is on a host that cannot be reached from outside).
 */
-function authPosture(mode, host) {
-	if (mode === "disabled") return `DISABLED — ${host} only, and a public bind will refuse to boot`;
-	return "bearer tokens, verified against the record's authorization server";
+function authPosture(mode, host, publicUnauthenticated) {
+	if (mode !== "disabled") return "bearer tokens, verified against the record's authorization server";
+	if (publicUnauthenticated) return `UNAUTHENTICATED and bound to ${host} — KSOR_ALLOW_PUBLIC_UNAUTHENTICATED=1 is set, so the whole record is served to anyone who can reach this port`;
+	return `DISABLED — ${host} only, and a public bind will refuse to boot`;
 }
 /**
 * What the record will refuse. `null` means no floor is declared and the gate
@@ -4021,7 +4044,7 @@ async function runHttp(composition) {
 		s.once("error", reject);
 	});
 	if (recordIsUndescribed(instance.instructions)) console.error(bootLine("identity", UNDESCRIBED_RECORD));
-	console.error(bootLine("auth", authPosture(auth.mode, bind.host)));
+	console.error(bootLine("auth", authPosture(auth.mode, bind.host, process.env["KSOR_ALLOW_PUBLIC_UNAUTHENTICATED"] === "1" && !loopback)));
 	for (const line of keyLines) console.error(line);
 	console.error(bootLine("abstain", abstainPosture(instance.abstain.vectorFloor)));
 	console.error(bootLine("serving", `http://${bind.host}:${bind.port}/mcp`));
@@ -4431,7 +4454,7 @@ async function withPgRetry(op, options = {}) {
 	throw lastError;
 }
 //#endregion
-//#region ../content/dist/commands-Cysnkk_R.mjs
+//#region ../content/dist/commands-LOfF_iLT.mjs
 /**
 * EVAL-LOCKED constants, quarried verbatim from the oracle
 * (sor-agentfactory @ b554f91, config.py) — changing any of these is a
@@ -5193,11 +5216,24 @@ g AS (
           WHERE tenant_id = $1 AND corpus_id = $2)
     ) AS gen
 )`;
-const ARM_WHERE = `
+/**
+* The arm predicate, built for the parameter numbering of the query that uses
+* it — a FUNCTION, not a string the caller renumbers afterwards.
+*
+* It used to be derived with `ARM_WHERE.replaceAll("$5", "$4")`, which works
+* only while the predicate happens to contain exactly one placeholder and no
+* other text matching it. Adding any second parameter to the predicate breaks
+* every derived query silently — and when it breaks, the failure arrives as a
+* driver error that the serving layer correctly reduces to "content store
+* temporarily unavailable", which tells you nothing about the cause. Found by
+* tripping over it while trying a fix for issue #59; taking the number as an
+* argument makes the coupling visible instead of textual.
+*/
+const armWhere = (kindsParam) => `
         c.tenant_id = $1 AND c.generation = g.gen
           AND c.embedding_status = 'embedded' AND ${SERVABLE}
           AND n.status = 'published'
-          AND ($5::text[] IS NULL OR n.kind = ANY($5::text[]))
+          AND (${kindsParam}::text[] IS NULL OR n.kind = ANY(${kindsParam}::text[]))
           AND ${DENY}
           AND ${AUDIENCE_ALLOWED}`;
 const JOINS = `
@@ -5206,14 +5242,14 @@ const JOINS = `
         JOIN sources s ON s.source_id = c.source_id AND s.tenant_id = c.tenant_id
                       AND s.generation = c.generation
         JOIN content_nodes n ON n.node_id = s.node_id AND n.tenant_id = s.tenant_id`;
-`${GEN_CTE}${DENIED_CTE}${JOINS}${ARM_WHERE}${JOINS}${ARM_WHERE}`;
-`${GEN_CTE.replace("$8", "$6")}${DENIED_CTE}${JOINS}${ARM_WHERE.replaceAll("$5", "$4")}`;
+`${GEN_CTE}${DENIED_CTE}${JOINS}${armWhere("$5")}${JOINS}${armWhere("$5")}`;
+`${GEN_CTE.replace("$8", "$6")}${DENIED_CTE}${JOINS}${armWhere("$4")}`;
 /** The calibrator's standalone top-1 signal (the read path gets it free from HYBRID_SQL). */
 const TOP_ONE_SQL = `
 WITH RECURSIVE ${GEN_CTE.replace("$8", "$5")}, ${DENIED_CTE}
     SELECT 1 - (c.embedding <=> $3::vector) AS score
     ${JOINS}
-    WHERE ${ARM_WHERE.replaceAll("$5", "$4")}
+    WHERE ${armWhere("$4")}
     ORDER BY c.embedding <=> $3::vector, c.chunk_id
     LIMIT 1`;
 /** Serialize a query vector as a pgvector literal. */
@@ -5795,6 +5831,29 @@ const BUILT_IN_OOC = [
 * measurement had an easier question set than production would.
 */
 const SYNTHESIZED_CAVEAT = "CAVEAT: synthesized queries are written FROM the passages they are then scored against, so they share vocabulary a reader's question will not. This door measures an UPPER BOUND on separation — treat the floor below as provisional until it has been checked against questions the corpus did not write (--queries-file), and re-run if real questions score under it.";
+/**
+* What a separability verdict is worth when the probes came from the binary.
+*
+* Every entry in BUILT_IN_OOC is far-domain — dinner, taxes, football, boiling
+* an egg. Those score low against ANY corpus, so max-OOC comes out artificially
+* low and the margin is inflated from that end, exactly as synthesized in-corpus
+* queries inflate it from the other. Measured on one record, changing ONLY the
+* probe set: built-ins reported "separable, margin 0.072" and recommended a
+* floor; eight scope-adjacent near-misses on the same corpus and the same
+* in-corpus questions reported "NOT separable, margin -0.030". The recommended
+* floor then answered six of those eight near-misses live, with citations
+* (2026-08-21).
+*
+* The tool already knows this — the not-separable branch tells the operator to
+* "widen the probe set (scope-adjacent near-misses, not only far-domain
+* questions)". It said so only AFTER weak probes had failed to bless a floor,
+* which is the one case where the advice is least needed.
+*
+* A shipped set cannot be scope-adjacent, because adjacency depends on a corpus
+* the binary has never seen. So this is stated whenever built-ins are used, on
+* BOTH branches, rather than pretending a better default exists.
+*/
+const BUILT_IN_OOC_CAVEAT = "CAVEAT: the out-of-corpus probes are the BUILT-IN set, which is entirely far-domain — a shipped set cannot be scope-adjacent, because adjacency depends on a corpus it has never seen. Far-domain probes score low against anything, so this margin is an OVER-estimate and a floor it blesses may still answer near-misses just outside your scope. Re-run with --ooc-file naming questions a reader might plausibly ask that this record does NOT cover, and trust that verdict over this one.";
 const QUERIES_FILE_CAVEAT = "CAVEAT: --queries-file floors are measured on human/gold-derived queries — section-weighted eval targets, NOT per-node passage samples — so this floor's low tail is a different distribution than the synthesized door's; record 'door: queries-file' beside the number and never compare the two doors' floors as interchangeable.";
 /**
 * The report dict, assembled from every scored query. `in_corpus_queries` /
@@ -5836,6 +5895,7 @@ function buildReport(detail, meta, targetPrecision = .95, now = /* @__PURE__ */
 		paste_why,
 		margin: pythonRound(marginOf(points), 4),
 		separable,
+		ooc_source: meta.oocSource,
 		target: rec.target,
 		measured_at: now.toISOString().slice(0, 10),
 		low_tail,
@@ -5856,6 +5916,7 @@ function renderReport(report) {
 	const gen = report.generation === null ? "unknown (no generation pinned)" : String(report.generation);
 	lines.push(`\nmeasured on generation ${gen} (${how}), model ${report.model}, door: ${report.door}`);
 	lines.push(report.door === "queries-file" ? QUERIES_FILE_CAVEAT : SYNTHESIZED_CAVEAT);
+	if (report.ooc_source === "built-in") lines.push(BUILT_IN_OOC_CAVEAT);
 	lines.push(`AURC = ${pythonFloatRepr(report.aurc)}  (lower = better separation)`);
 	lines.push(`separation margin: ${pythonFormatFixed(report.margin, 3)} (over ${report.in_corpus_queries} in-corpus / ${report.ooc_probes} out-of-corpus probes)`);
 	if (z) lines.push(`zero-FA floor (never refuse a real question): ${pythonFormatFixed(z.floor, 3)} -> coverage ${pythonFormatFixed(z.coverage, 3)}, ooc leak ${pythonFormatFixed(z.risk, 3)}`);
@@ -6110,13 +6171,15 @@ async function runCalibration(pool, options) {
 		}
 		inQueries = normalizeQueries(synthesized);
 	}
+	const oocSource = options.oocProbes === void 0 ? "built-in" : "provided";
 	const ooc = normalizeQueries(options.oocProbes ?? BUILT_IN_OOC);
 	return buildReport([...await scoreQueries(pool, scope, options.provider, inQueries, true), ...await scoreQueries(pool, scope, options.provider, ooc, false)], {
 		generation: counted.measured,
 		pinned: generation !== null,
 		model: options.provider.modelId,
 		dim: options.provider.dim,
-		door
+		door,
+		oocSource
 	}, options.targetPrecision ?? .95);
 }
 /**
@@ -8062,6 +8125,15 @@ async function drain(pending, io) {
 */
 const CHUNK_INSERT_PREFIX = "INSERT INTO chunks (tenant_id, generation, source_id, ordinal, content, chunk_hash, heading_path, heading_path_text, anchor, labels, embedding_status) VALUES ";
 const CHUNK_PARAMS = 10;
+/**
+* Dense character count — whitespace removed, exactly as the serving
+* predicate's `length(regexp_replace(c.content, '\s', '', 'g'))` computes it.
+* Written here rather than approximated so the ingest report and the SQL admit
+* the same chunks.
+*/
+function denseLength(content) {
+	return content.replace(/\s/g, "").length;
+}
 /** 500 rows × 10 params stays far under Postgres's 65535 bind-parameter cap. */
 const CHUNK_ROWS_PER_STATEMENT = 500;
 /**
@@ -8106,6 +8178,8 @@ async function buildStructure(client, opts) {
 	const treeRoot = resolve(opts.treeRoot);
 	let nSources = 0;
 	let nChunks = 0;
+	let nUnsearchable = 0;
+	const unsearchableSources = [];
 	const chunkRows = [];
 	for (const f of manifest.files) {
 		const src = opts.files.get(f.path);
@@ -8129,6 +8203,7 @@ async function buildStructure(client, opts) {
 			manifest.source_commit
 		]);
 		nSources += 1;
+		let sourceServable = 0;
 		for (const chunk of chunkText(body)) {
 			chunkRows.push([
 				tenantId,
@@ -8143,7 +8218,10 @@ async function buildStructure(client, opts) {
 				JSON.stringify({ source_type: chunk.sourceType })
 			]);
 			nChunks += 1;
+			if (chunk.sourceType === "prose" && denseLength(chunk.content) >= 24) sourceServable += 1;
+			else nUnsearchable += 1;
 		}
+		if (sourceServable === 0 && nChunks > 0) unsearchableSources.push(sid);
 	}
 	for (let i = 0; i < chunkRows.length; i += CHUNK_ROWS_PER_STATEMENT) {
 		const slice = chunkRows.slice(i, i + CHUNK_ROWS_PER_STATEMENT);
@@ -8182,7 +8260,9 @@ async function buildStructure(client, opts) {
 		sources: nSources,
 		chunks: nChunks,
 		carried,
-		pending: health.pending
+		pending: health.pending,
+		unsearchable: nUnsearchable,
+		unsearchableSources
 	};
 }
 /**
@@ -8365,6 +8445,8 @@ async function buildGeneration(pool, instance, options) {
 				ready: true,
 				centroids: 0,
 				flipped: false,
+				unsearchable: 0,
+				unsearchableSources: [],
 				refusal: null,
 				health: {
 					ok: true,
@@ -8469,6 +8551,8 @@ async function buildGeneration(pool, instance, options) {
 		ready: fin.ready,
 		centroids: fin.centroids,
 		flipped: fin.flipped,
+		unsearchable: stats.unsearchable,
+		unsearchableSources: stats.unsearchableSources,
 		refusal: fin.refusal,
 		health: fin.health,
 		unchanged: false
@@ -8808,6 +8892,16 @@ async function ingestCommand(args) {
 	}
 	process.stdout.write(sourceCommit === "unspecified" ? "source: unspecified — knowledge/ is not in a git repository, so this generation cannot be traced back to a reviewed commit\n" : `source: ${sourceCommit}\n`);
 	process.stdout.write(`ingest: generation ${report.generation} — ${report.nodes} nodes, ${report.chunks} chunks; embedded ${report.embedded}, carried ${report.carried}, failed ${report.failed}\n`);
+	if (report.unsearchable > 0) {
+		const pct = Math.round(report.unsearchable / Math.max(report.chunks, 1) * 100);
+		process.stdout.write(`  not searchable: ${report.unsearchable} of ${report.chunks} chunk(s) (${pct}%) are shorter than the navigation threshold — stored and readable, but no search returns them\n`);
+		if (report.unsearchableSources.length > 0) {
+			const named = report.unsearchableSources.slice(0, 10).join(", ");
+			const more = report.unsearchableSources.length - Math.min(10, report.unsearchableSources.length);
+			process.stdout.write(`  FOUND ONLY BY NAME: ${named}${more > 0 ? `, and ${more} more` : ""} — no searchable chunk at all; lengthen these sections or read them by slug
+`);
+		}
+	}
 	if (report.refusal !== null) return fail$1(REFUSED, report.refusal);
 	const governance = await withPool(dsn, (pool) => assertGovernanceServable(pool, instance, report.generation).then(() => null, (error) => error instanceof Error ? error.message : String(error)));
 	if (governance !== null) return fail$1(REFUSED, `generation ${report.generation} was built and NOT activated — no surface could serve it\n  ${governance.split("\n").join("\n  ")}\n  note: generation ${report.generation} is left behind, un-activated; \`ksor gc\` reaps it once the grace window passes. The previously active generation still serves.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "description": "Knowledge System of Record — compile governed markdown into a static site for people and an MCP server for AI agents, with citations and measured abstention.",
   "keywords": [
     "abstention",

package/templates/scaffold/system/site/lib/shared.ts

@@ -89,12 +89,38 @@ function readInstanceScope(): string | null {
   for (const para of afterHeading.split(/\n[ \t]*\n/)) {
     const one = para.trim().replace(/\s+/g, " ");
     if (one === "" || one.startsWith("#") || one.startsWith("-") || one.startsWith(">")) continue;
-    const sentence = /^(.+?[.!?])(\s|$)/.exec(one)?.[1] ?? one;
-    return sentence.length > 300 ? `${sentence.slice(0, 297)}...` : sentence;
+    return sentence(one);
   }
   return null;
 }
 
+/**
+ * The MCP registry schema caps `ServerDetail.description` at **100 characters**
+ * (`ServerDetail.description.maxLength`, 2025-12-11). Over it, the document a
+ * validating client reads is invalid — and the failure was shaped exactly
+ * wrong: the unfilled placeholder is 88 characters and validates, so the
+ * document became invalid the moment an owner did the thing the scaffold asks
+ * for and wrote a real scope sentence. Silent, and only for real records.
+ *
+ * A hard truncation would publish a sentence cut mid-word, so this trims at a
+ * word boundary and marks it, and the whole description is assembled inside the
+ * budget rather than clipped after the fact.
+ */
+const DESCRIPTION_MAX = 100;
+
+function sentence(one: string): string {
+  const first = /^(.+?[.!?])(\s|$)/.exec(one)?.[1] ?? one;
+  return first;
+}
+
+/** Fit `text` inside `max`, breaking on a word rather than mid-word. */
+function fit(text: string, max: number): string {
+  if (text.length <= max) return text;
+  const cut = text.slice(0, max - 1);
+  const at = cut.lastIndexOf(" ");
+  return `${(at > max / 2 ? cut.slice(0, at) : cut).replace(/[,;:.\s]+$/, "")}\u2026`;
+}
+
 /** null until the owner has written one — never a guess. */
 export const appScope: string | null = readInstanceScope();
 
@@ -103,9 +129,11 @@ export const appScope: string | null = readInstanceScope();
  * registry document and anything else that needs one cannot drift apart.
  */
 export function recordDescription(): string {
-  return appScope === null
-    ? `${appTitle} — its owner has not yet described what this record covers.`
-    : `${appTitle} — ${appScope}`;
+  const whole =
+    appScope === null
+      ? `${appTitle} — its owner has not yet described what this record covers.`
+      : `${appTitle} — ${appScope}`;
+  return fit(whole, DESCRIPTION_MAX);
 }
 
 /**