@tangle-network/agent-interface 2.17.0 → 2.19.0

package/README.md

@@ -5,6 +5,20 @@ agents, the sidecar, and provider adapters: capabilities, agent profiles,
 message parts, and harness descriptors. This is the canonical home for those
 shapes; higher-level packages import from here rather than redefining them.
 
+## Profile measurements
+
+`measureAgentProfile(profile)` returns the canonical profile digest and JSON byte size,
+per-prompt and inline resource UTF-8 bytes and logical lines, enabled/disabled tool and
+MCP declarations, and declared subagent counts. Resource rows use JSON Pointers;
+GitHub resource content has `bytes: null` and `lines: null` until independently resolved.
+The summary contains no prompt text, resource text, or server configuration.
+
+Store it with the existing profile record and cache by `profileDigest`. Measure authored
+and effective profiles separately, joined through their execution preparation or
+materialization receipts. The function does not load resources or estimate tokens.
+Its coverage explicitly leaves tokenization, materialization, and observed use unassessed.
+A capability declaration is not evidence that it was delivered, opened, or applied.
+
 ## Agent instances
 
 `AgentProfile` describes behavior. `AgentInstanceSpec` describes one optional managed Agent inside an existing execution environment. The environment remains the computer and security boundary, so it may host zero, one, or many Agent instances.
@@ -180,9 +194,15 @@ These checks do not apply to a replacement environment owned by caller code.
 
 ## Profile knowledge base
 
-`@tangle-network/agent-interface/profile-kb` holds how to get the best from each frontier harness and model this platform runs.
-Every entry cites a vendor source or a command run on a dated check.
-Guidance is specific to one harness or model and never compares models.
+`@tangle-network/agent-interface/profile-kb` holds dated harness and model facts, conditional guidance, and reproduced platform learnings.
+Sources guide investigation; they do not prove that a technique improves this platform's behavior.
+
+Entries can expose optional `claims`, each with `text`, `basis` (`documented`, `vendor-guidance`, `local-observation`, or `hypothesis`), `audience` (`agent` or `operator`), and supporting `sources`.
+A source has a URL and check date, with optional `authority` (`primary`, `secondary`, or `local`) and `locator` for the supporting section or artifact.
+Authority describes the source, independently of the claim's basis.
+The maintained entries derive the legacy `prompt`, `operator`, and `sources` arrays from these claims; hypotheses stay inspectable but contribute no prompt or operator text.
+Only agent guidance enters the profile prompt. An empty `prompt` is legitimate when no supported instruction is needed; do not pad it with generic advice.
+Keep applicability conditions in the claim's text so composition preserves them.
 
 `withProfileKb(profile)` composes harness guidance, then model guidance, then the profile's own text into the profile's prompt:
 
@@ -203,7 +223,24 @@ The knowledge base owns the block sources `harness`, `model`, and `learning` (`P
 Give each layer its own source name and pass it as `replaceSources`: the composition then replaces only those sources and keeps every other block in place. Without `replaceSources`, it replaces every block.
 The block marker is reserved for composers: a hand-written `<profile-guidance source="model" ...>` block counts as a knowledge-base block and is replaced.
 
-The module also exports the data (`profileKbHarnesses`, `profileKbModels`), operator notes for launching each harness and model, platform learnings (admitted only after an agent-eval check reproduced them), and `profileKbDiscrepancies`, which records where a vendor source states a requested name differently.
+The module also exports the data (`profileKbHarnesses`, `profileKbModels`), operator notes, platform learnings (admitted only after an agent-eval check reproduced them), and `profileKbDiscrepancies`, which preserves dated naming and availability checks.
+The source audit is retained in [Anthropic and OpenAI](src/profile-kb/research/anthropic-openai.md), [open harnesses and model APIs](src/profile-kb/research/open-harnesses.md), and the [distillation and consumer review](src/profile-kb/research/distillation-review.md).
+
+### Applicability and evidence
+
+Read vendor guidance within its documented, dated scope. Papers and social posts propose hypotheses to evaluate; they do not establish universal agent constraints. A measured conclusion applies to the configuration, tasks, environment, and evidence that supported it.
+
+Keep that scope with the existing evaluation record and link it from the learning's evidence source:
+
+- Requested model and observed served identity, provider route and adapter revision, harness and CLI version, and the authored and effective `AgentProfile` revisions or digests.
+- Reasoning settings, tool, MCP server and hook versions or definitions, permissions, and the loaded skill and instruction revisions. Distinguish declared configuration from observed delivery and use.
+- Task and acceptance-check revisions, environment and relevant resource limits, sampling and budget, measured outcome, errors and counterexamples, and source traces or artifacts.
+
+Unknown identity, usage, or cost stays unknown. A requested model name does not prove which model served the run; partial accounting supports a floor, not a complete total or zero spend.
+
+Before reusing a conclusion after a material change to any of these conditions, review its applicability against the retained evidence. State what still transfers and what needs a new check; use the existing registration and resource authorization for any experiment. Preserve the original record and append the changed scope or new evidence.
+
+The current [learning selector](src/profile-kb/index.ts) matches only harness and model; it does not validate the other conditions above. Keep narrower limits explicit in the learning text, or retain the finding in its evaluation record until it is suitable for composed guidance. The [learning records](src/profile-kb/records.ts) remain the single admission surface. Claim provenance does not automatically revalidate a run or authorize an experiment.
 
 ## Failed execution accounting
 

package/dist/agent-profile-measurements.d.ts

@@ -0,0 +1,57 @@
+import type { Sha256Digest } from "./agent-candidate.js";
+import type { AgentProfile } from "./agent-profile.js";
+/** UTF-8 source bytes and logical lines, without normalizing the supplied text. */
+export interface AgentProfileTextMeasurement {
+    /** RFC 6901 pointer into the measured profile. */
+    readonly path: string;
+    readonly bytes: number;
+    /** Empty text has zero lines; a final line terminator adds no empty line. */
+    readonly lines: number;
+}
+/** A resource declaration; external content has no measured size until resolved. */
+export interface AgentProfileResourceMeasurement {
+    /** RFC 6901 pointer to the resource or string instruction declaration. */
+    readonly path: string;
+    readonly kind: "inline" | "github";
+    readonly name?: string;
+    readonly bytes: number | null;
+    readonly lines: number | null;
+}
+/** Explicit capability declarations, independent of what a harness actually serves. */
+export interface AgentProfileCapabilityCounts {
+    readonly declared: number;
+    readonly enabled: number;
+    readonly disabled: number;
+}
+/**
+ * Content-free measurements of one exact AgentProfile value. Apply separately
+ * to authored and effective profiles, linked by their existing receipt digests.
+ * This declaration neither proves materialization nor observes capability use.
+ */
+export interface AgentProfileMeasurements {
+    readonly version: 1;
+    readonly basis: "profile-declaration";
+    readonly profileDigest: Sha256Digest;
+    /** Bytes of canonical profile JSON, not mounted context or billed input tokens. */
+    readonly canonicalBytes: number;
+    readonly prompt: readonly AgentProfileTextMeasurement[];
+    readonly tools: AgentProfileCapabilityCounts;
+    readonly mcp: AgentProfileCapabilityCounts;
+    readonly subagents: {
+        readonly declared: number;
+    };
+    readonly resources: readonly AgentProfileResourceMeasurement[];
+    readonly coverage: {
+        readonly tokens: "not-measured";
+        readonly materialization: "not-assessed";
+        readonly usage: "not-assessed";
+    };
+}
+/**
+ * Measure a canonical profile without resolving resources, reading files, or
+ * estimating tokens. Validates the same public profile contract used for
+ * identity. Cache by profileDigest; requesting another summary needs no scan.
+ * Results preserve declaration order and contain no prompt/resource content,
+ * server configuration, permission values, or secret references.
+ */
+export declare function measureAgentProfile(profile: AgentProfile): AgentProfileMeasurements;

package/dist/agent-profile-measurements.js

@@ -0,0 +1,80 @@
+import { canonicalAgentProfileDigest } from "./agent-execution-preparation.js";
+import { canonicalAgentProfileJson } from "./agent-profile-canonical.js";
+import { agentProfileSchema } from "./profile-schema.js";
+const utf8 = new TextEncoder();
+function textMeasurement(path, text) {
+    const breaks = text.match(/\r\n|\r|\n/g)?.length ?? 0;
+    return {
+        path,
+        bytes: utf8.encode(text).byteLength,
+        lines: text.length === 0 ? 0 : breaks + (/[\r\n]$/.test(text) ? 0 : 1),
+    };
+}
+function resourceMeasurement(path, resource) {
+    const text = resource.kind === "inline"
+        ? textMeasurement(path, resource.content)
+        : undefined;
+    return {
+        path,
+        kind: resource.kind,
+        ...(resource.name === undefined ? {} : { name: resource.name }),
+        bytes: text?.bytes ?? null,
+        lines: text?.lines ?? null,
+    };
+}
+function capabilityCounts(enabled) {
+    const count = enabled.filter(Boolean).length;
+    return { declared: enabled.length, enabled: count, disabled: enabled.length - count };
+}
+/**
+ * Measure a canonical profile without resolving resources, reading files, or
+ * estimating tokens. Validates the same public profile contract used for
+ * identity. Cache by profileDigest; requesting another summary needs no scan.
+ * Results preserve declaration order and contain no prompt/resource content,
+ * server configuration, permission values, or secret references.
+ */
+export function measureAgentProfile(profile) {
+    const value = agentProfileSchema.parse(profile);
+    const profileDigest = canonicalAgentProfileDigest(value);
+    const canonical = canonicalAgentProfileJson(value);
+    const prompt = [];
+    for (const key of ["systemPrompt", "appendSystemPrompt"]) {
+        const text = value.prompt?.[key];
+        if (text !== undefined)
+            prompt.push(textMeasurement(`/prompt/${key}`, text));
+    }
+    value.prompt?.instructions?.forEach((text, index) => {
+        prompt.push(textMeasurement(`/prompt/instructions/${index}`, text));
+    });
+    const resources = [];
+    value.resources?.files?.forEach((file, index) => {
+        resources.push(resourceMeasurement(`/resources/files/${index}/resource`, file.resource));
+    });
+    for (const group of ["tools", "skills", "agents", "commands"]) {
+        value.resources?.[group]?.forEach((resource, index) => {
+            resources.push(resourceMeasurement(`/resources/${group}/${index}`, resource));
+        });
+    }
+    const instructions = value.resources?.instructions;
+    if (instructions !== undefined) {
+        resources.push(typeof instructions === "string"
+            ? { kind: "inline", ...textMeasurement("/resources/instructions", instructions) }
+            : resourceMeasurement("/resources/instructions", instructions));
+    }
+    return {
+        version: 1,
+        basis: "profile-declaration",
+        profileDigest,
+        canonicalBytes: utf8.encode(canonical).byteLength,
+        prompt,
+        tools: capabilityCounts(Object.values(value.tools ?? {})),
+        mcp: capabilityCounts(Object.values(value.mcp ?? {}).map((server) => server.enabled !== false)),
+        subagents: { declared: Object.keys(value.subagents ?? {}).length },
+        resources,
+        coverage: {
+            tokens: "not-measured",
+            materialization: "not-assessed",
+            usage: "not-assessed",
+        },
+    };
+}

package/dist/index.d.ts

@@ -31,6 +31,7 @@ export * from "./agent-instance.js";
 export * from "./agent-profile-snapshot.js";
 export * from "./agent-profile-activation.js";
 export * from "./agent-profile-materialization.js";
+export * from "./agent-profile-measurements.js";
 export * from "./agent-execution-preparation.js";
 export * from "./agent-workspace-lease.js";
 export * from "./certified-context.js";

package/dist/index.js

@@ -29,6 +29,7 @@ export * from "./agent-instance.js";
 export * from "./agent-profile-snapshot.js";
 export * from "./agent-profile-activation.js";
 export * from "./agent-profile-materialization.js";
+export * from "./agent-profile-measurements.js";
 export * from "./agent-execution-preparation.js";
 export * from "./agent-workspace-lease.js";
 export * from "./certified-context.js";

package/dist/profile-kb/entry.d.ts

@@ -0,0 +1,12 @@
+import type { ProfileKbClaim, ProfileKbSource, ProfileKbSurface } from "./types.js";
+export declare function claim(text: string, source: ProfileKbSource, basis?: ProfileKbClaim["basis"], audience?: ProfileKbClaim["audience"]): ProfileKbClaim;
+/** Keep public string arrays and entry citations derived from the same claim records. */
+export declare function kbEntry<const T extends {
+    claims: ProfileKbClaim[];
+    surfaces?: ProfileKbSurface[];
+    aliases?: string[];
+}>(entry: T): T & {
+    sources: ProfileKbSource[];
+    prompt: string[];
+    operator: string[];
+};

package/dist/profile-kb/entry.js

@@ -0,0 +1,20 @@
+export function claim(text, source, basis = "documented", audience = "operator") {
+    return { text, basis, audience, sources: [source] };
+}
+/** Keep public string arrays and entry citations derived from the same claim records. */
+export function kbEntry(entry) {
+    const sources = new Map();
+    for (const claim of entry.claims) {
+        for (const source of claim.sources)
+            sources.set(JSON.stringify(source), source);
+    }
+    const textFor = (audience) => entry.claims
+        .filter((claim) => claim.audience === audience && claim.basis !== "hypothesis")
+        .map((claim) => claim.text);
+    return {
+        ...entry,
+        sources: [...sources.values()],
+        prompt: textFor("agent"),
+        operator: textFor("operator"),
+    };
+}

package/dist/profile-kb/harnesses.d.ts

@@ -1,9 +1,3 @@
 import type { ProfileKbHarness } from "./types.js";
-/**
- * The frontier coding harnesses this platform runs, checked against the
- * installed CLI on 2026-09-22.
- *
- * `prompt` lines go into the agent's prompt; `operator` lines are launch
- * facts. Each harness is described on its own terms.
- */
+/** Source-qualified launch knowledge; versions describe checked sources, not every host's installation. */
 export declare const profileKbHarnesses: readonly ProfileKbHarness[];

package/dist/profile-kb/harnesses.js

@@ -1,123 +1,84 @@
-const CHECKED = "2026-09-22";
-/**
- * The frontier coding harnesses this platform runs, checked against the
- * installed CLI on 2026-09-22.
- *
- * `prompt` lines go into the agent's prompt; `operator` lines are launch
- * facts. Each harness is described on its own terms.
- */
+import { claim, kbEntry } from "./entry.js";
+const CHECKED = "2026-10-04";
+const source = (url, locator) => ({
+    url,
+    locator,
+    checkedAt: CHECKED,
+    authority: "primary",
+});
+const claudeCli = source("https://code.claude.com/docs/en/cli-reference", "CLI flags: --print, --bg, --bare, system prompt flags");
+const claudeAgents = source("https://code.claude.com/docs/en/sub-agents", "How subagents work; forked subagents");
+const codexConfig = source("https://learn.chatgpt.com/docs/config-file/config-reference", "model_instructions_file; model_reasoning_effort");
+const codexAgents = source("https://learn.chatgpt.com/docs/agent-configuration/subagents", "Availability; approvals and sandbox controls");
+const codexCommands = source("https://learn.chatgpt.com/docs/developer-commands", "Set or view a task goal with /goal");
+const piBase = "https://github.com/earendil-works/pi/blob/200387122ca450d6387f033949423114a270b96c/packages/coding-agent/";
+const piCli = source(`${piBase}docs/cli.md`, "Invocation and output; models; prompts and process");
+const piRpc = source(`${piBase}docs/rpc.md#run-lifecycle`, "Run lifecycle");
+const piCommands = source(`${piBase}docs/rpc-commands.md`, "steer; follow_up; get_available_thinking_levels");
+const opencodeCli = source("https://opencode.ai/docs/cli/", "run; serve; acp");
+const opencodePrompt = source("https://github.com/anomalyco/opencode/blob/907b3bc518fa48e90e8ec24dd327d13eee71c36c/packages/opencode/src/session/llm/request.ts#L51-L70", "LLMRequestPrep.prepare");
+const kimiCli = source("https://moonshotai.github.io/kimi-code/en/reference/kimi-command.html", "Flag conflict rules; non-interactive execution");
+const kimiConfig = source("https://moonshotai.github.io/kimi-code/en/configuration/config-files.html", "Config file location; thinking; complete example");
+/** Source-qualified launch knowledge; versions describe checked sources, not every host's installation. */
 export const profileKbHarnesses = [
-    {
+    kbEntry({
         id: "claude-code",
         name: "Claude Code",
-        version: "2.1.280",
-        sources: [
-            {
-                url: "https://code.claude.com/docs/en/cli-reference",
-                checkedAt: CHECKED,
-            },
-            { url: "cli:claude --help", checkedAt: CHECKED, note: "2.1.280" },
-        ],
-        prompt: [
-            "Delegate independent slices to subagents, several in one turn so they run in parallel, then synthesize their results.",
-            "Use the skills listed in your session for procedures they cover.",
-            "Run long commands in the background and keep working while they finish.",
+        version: "2.1.289",
+        claims: [
+            claim("For a non-forked subagent, supply the context needed for its task; forked subagents inherit the parent conversation.", claudeAgents, "documented", "agent"),
+            claim("Headless: claude -p <prompt> --model <id> --effort <level> --output-format stream-json --verbose. --bg is a separate background-session mode and cannot combine with -p.", claudeCli),
+            claim("--append-system-prompt adds to the default; --system-prompt replaces it. On resume, prompt changes may wait for compaction.", claudeCli),
+            claim("--bare skips automatic discovery; explicitly supplied context can still load. It is not an established speed improvement for this workload.", claudeCli),
+            claim("--max-budget-usd caps the print invocation's spend, excluding restored prior spend; --json-schema constrains output structure, not correctness.", claudeCli),
         ],
-        operator: [
-            "Headless: `claude -p <prompt> --model <id> --effort <level> --output-format stream-json`.",
-            "`--append-system-prompt` adds to the built-in prompt; `--system-prompt` replaces it.",
-            "`--max-budget-usd` caps spend; `--json-schema` validates structured output; `--mcp-config` loads MCP servers.",
-            "`--bg` starts a background session; `--bare` skips hooks, plugins, memory, and CLAUDE.md discovery.",
-        ],
-    },
-    {
+    }),
+    kbEntry({
         id: "codex",
         name: "Codex CLI",
-        version: "0.156.1",
-        sources: [
-            { url: "https://learn.chatgpt.com/docs/models", checkedAt: CHECKED },
-            {
-                url: "cli:codex exec --help; codex features list",
+        version: "0.160.0",
+        claims: [
+            claim("Observed on the Mac: codex exec <prompt> -m <model> -c model_reasoning_effort=<level> --json -o <file>; --output-schema, review, resume and fork are available.", {
+                url: "cli:codex --version; codex exec --help",
                 checkedAt: CHECKED,
-                note: "0.156.1; multi_agent stable and enabled",
-            },
-        ],
-        prompt: [
-            "Split independent work across child agents with spawn_agent, and join them with wait_agent.",
-            "Edit with apply_patch and search with rg.",
-            "Carry the task end to end in this turn: gather context, implement, run the checks, and report the evidence.",
+                authority: "local",
+                locator: "Codex 0.160.0, Mac; research/anthropic-openai.md#local-codex-catalog-evidence",
+            }, "local-observation"),
+            claim("model_instructions_file replaces model instructions. Reasoning support is model/client-specific; a requested effort does not establish the effective effort.", codexConfig),
+            claim("Current local Codex spawns subagents after a direct request or applicable project/skill instruction. Enabled features do not establish tool exposure in another integration.", codexAgents),
+            claim("/goal tracks an interactive objective; it does not establish recovery across host or process restarts.", codexCommands),
         ],
-        operator: [
-            "Headless: `codex exec <prompt> -m <model> -c model_reasoning_effort=<level> --json -o <last-message-file>`.",
-            "`--output-schema <file>` enforces structured output. `codex review` runs a non-interactive review.",
-            "Reasoning levels are per model; read them from `$CODEX_HOME/models_cache.json`.",
-            "System-prompt replacement uses the `model_instructions_file` config key; standing instructions go in AGENTS.md.",
-            "`/goal` runs long unattended work; `resume` and `fork` continue a session.",
-        ],
-    },
-    {
+    }),
+    kbEntry({
         id: "opencode",
         name: "OpenCode",
-        version: "1.18.32",
-        sources: [
-            { url: "https://opencode.ai/docs/cli/", checkedAt: CHECKED },
-            { url: "cli:opencode run --help", checkedAt: CHECKED, note: "1.18.32" },
-        ],
-        prompt: [
-            "Delegate a focused subtask to a named agent when its persona or model fits the subtask.",
-            "Use the mounted MCP tools for external actions.",
-        ],
-        operator: [
-            "Headless: `opencode run <message> -m <provider/model> --agent <name> --variant <effort> --format json`.",
-            "Standing text goes through `instructions` files or appended system text; the built-in prompt stays in place.",
-            "`opencode serve` with `run --attach <url>`, or `opencode acp`, gives a parent live control.",
+        version: "1.18.34",
+        claims: [
+            claim("Headless: opencode run <message> -m <provider/model> --agent <name> --variant <variant> --format json. Variants are provider-specific.", opencodeCli),
+            claim("A configured agent.prompt replaces the provider prompt before system/user additions; plugins can transform it further. Do not assume the provider prompt is retained.", opencodePrompt),
+            claim("serve exposes an HTTP API, run --attach reuses that server, and acp exposes an IDE protocol; these capabilities do not establish a particular parent adapter's support.", opencodeCli),
         ],
-    },
-    {
+    }),
+    kbEntry({
         id: "pi",
         name: "Pi",
-        version: "0.87.1",
-        sources: [
-            {
-                url: "https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/cli.md",
-                checkedAt: CHECKED,
-            },
-            {
-                url: "https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/rpc.md",
-                checkedAt: CHECKED,
-            },
-            { url: "cli:pi --help", checkedAt: CHECKED, note: "0.87.1" },
-        ],
-        prompt: [
-            "Expect steering messages mid-run and fold each one into the current plan.",
-            "Fan out independent work by running `pi -p <task> --mode json` from bash, several at once, and read the results back.",
-        ],
-        operator: [
-            "Headless: `pi -p <prompt> --model <provider/id[:thinking]> --mode json`.",
-            "`--mode rpc` takes JSONL commands on stdin (steer, follow-up, set model, compact, fork) for live control.",
-            "`--thinking` takes off, minimal, low, medium, high, xhigh, or max.",
-            "`--system-prompt` replaces the default; `--append-system-prompt` adds to it.",
+        version: "1.0.2",
+        claims: [
+            claim("Headless: pi -p <prompt> --model <provider/id[:thinking]> --mode json. Model arguments can fuzzy-match; inspect the selected identity. --thinking clamps to model capability.", piCli),
+            claim("--system-prompt replaces the default; --append-system-prompt adds to it. JSON mode exits after supplied prompts; RPC stays alive on stdin/stdout.", piCli),
+            claim("In Pi 1.0.2 RPC, prompt acceptance and agent_end do not prove settlement: wait for agent_settled, except a handled prompt that began no run.", piRpc),
+            claim("RPC steering arrives after current tool calls, before the next model call; follow-ups wait for tool calls and steering to drain. Query get_available_thinking_levels for the selected model.", piCommands),
         ],
-    },
-    {
+    }),
+    kbEntry({
         id: "kimi-code",
         name: "Kimi Code CLI",
-        version: "2.0.2",
-        sources: [
-            { url: "https://moonshotai.github.io/kimi-code/", checkedAt: CHECKED },
-            {
-                url: "cli:kimi --help; ~/.kimi-code/config.toml",
-                checkedAt: CHECKED,
-                note: "2.0.2",
-            },
-        ],
-        prompt: [
-            "Plan the change first, then edit and verify each step against tests and runtime output.",
-        ],
-        operator: [
-            "Headless: `kimi -p <prompt> -m kimi-code/k3 --output-format stream-json`.",
-            "`--auto` runs fully autonomous; `--agent-file <path>` loads an agent definition; `--plan` starts in plan mode.",
-            "Effort is the `[thinking] effort` key in `~/.kimi-code/config.toml`: low, high, or max.",
+        version: "2.1.1",
+        claims: [
+            claim("Headless: kimi -p <prompt> -m <configured-alias> --output-format stream-json. Print mode already uses auto policy with static deny rules; it rejects --auto, --yolo and --plan.", kimiCli),
+            claim("--agent-file selects a new session's custom agent and cannot combine with resume/continue.", kimiCli),
+            claim("kimi-code/k3 is a configured coding-provider alias, not Moonshot's public API ID kimi-k3. Configuration lives under KIMI_CODE_HOME or ~/.kimi-code.", kimiConfig),
+            claim("[thinking].effort is model-dependent; unsupported settings fall back to the model default. The documented K3 configuration supports low, high and max.", kimiConfig),
         ],
-    },
+    }),
 ];

package/dist/profile-kb/index.d.ts

@@ -20,8 +20,8 @@ export { composeAgentProfileGuidance, profileKbDiscrepancies, profileKbHarnesses
  * replaces blocks from these sources and keeps blocks any other layer added.
  */
 export declare const PROFILE_KB_SOURCES: readonly ["harness", "model", "learning"];
-/** Date the knowledge base was last checked against its sources. */
-export declare const PROFILE_KB_CHECKED_AT = "2026-09-22";
+/** Date of the latest source audit; individual historical observations retain their own dates. */
+export declare const PROFILE_KB_CHECKED_AT = "2026-10-04";
 /** Find a harness entry by its {@link HarnessType}. */
 export declare function findProfileKbHarness(harness: HarnessType | string | undefined): ProfileKbHarness | undefined;
 /**

package/dist/profile-kb/index.js

@@ -18,8 +18,8 @@ export { composeAgentProfileGuidance, profileKbDiscrepancies, profileKbHarnesses
  * replaces blocks from these sources and keeps blocks any other layer added.
  */
 export const PROFILE_KB_SOURCES = ["harness", "model", "learning"];
-/** Date the knowledge base was last checked against its sources. */
-export const PROFILE_KB_CHECKED_AT = "2026-09-22";
+/** Date of the latest source audit; individual historical observations retain their own dates. */
+export const PROFILE_KB_CHECKED_AT = "2026-10-04";
 /** Find a harness entry by its {@link HarnessType}. */
 export function findProfileKbHarness(harness) {
     if (!harness)
@@ -118,14 +118,14 @@ export function profileKbGuidance(selection) {
         blocks.push({
             source: "harness",
             id: harness.id,
-            text: `You are running in ${harness.name}.\n${bullets(harness.prompt)}`,
+            text: `Harness guidance: ${harness.name}.\n${bullets(harness.prompt)}`,
         });
     }
     if (model && model.prompt.length > 0) {
         blocks.push({
             source: "model",
             id: model.id,
-            text: `You are ${model.name}.\n${bullets(model.prompt)}`,
+            text: `Model guidance: ${model.name}.\n${bullets(model.prompt)}`,
         });
     }
     const learnings = learningsFor(harness, model);

package/dist/profile-kb/models.d.ts

@@ -1,9 +1,3 @@
 import type { ProfileKbModel } from "./types.js";
-/**
- * Current frontier models, from vendor sources read on 2026-09-22.
- *
- * `prompt` lines go into the model's prompt; `operator` lines configure the
- * run. Vendor facts carry their source. Nothing here compares one model with
- * another.
- */
+/** Source-backed facts and conditional advice. API controls never become agent instructions. */
 export declare const profileKbModels: readonly ProfileKbModel[];

package/dist/profile-kb/models.js

@@ -1,118 +1,106 @@
-const CHECKED = "2026-09-22";
+import { claim, kbEntry } from "./entry.js";
+const CHECKED = "2026-10-04";
+const source = (url, locator) => ({
+    url,
+    locator,
+    checkedAt: CHECKED,
+    authority: "primary",
+});
 const claudeDocs = "https://platform.claude.com/docs/en";
-const openaiDocs = "https://developers.openai.com/api/docs";
-/** A router surface is listed only with a dated check that the router served the id. */
-function routerCheck(note) {
-    return {
+const opusGuide = source(`${claudeDocs}/build-with-claude/prompt-engineering/prompting-claude-opus-5-5`, "Tools for complex visual inputs; unattended agentic runs; time signals for multiagent harnesses");
+const fableGuide = source(`${claudeDocs}/build-with-claude/prompt-engineering/prompting-claude-fable-5-1`, "Finish the whole task; batch independent tool calls; keep the conversation history append-only");
+const sonnetGuide = source(`${claudeDocs}/build-with-claude/prompt-engineering/prompting-claude-sonnet-5`, "Code review harnesses; tone and writing style");
+const deepseekModel = source("https://api-docs.deepseek.com/quick_start/pricing/#model-details", "Model details; footnote 1");
+const deepseekThinking = source("https://api-docs.deepseek.com/guides/thinking_mode/", "Thinking mode toggle and effort control; tool calls");
+const glmModel = source("https://docs.z.ai/guides/llm/glm-5.3#feature-changes", "Feature changes");
+const kimiModel = source("https://platform.kimi.ai/docs/guide/kimi-k3-quickstart", "Reasoning effort; vision input; important limits");
+/** Historical acceptance records, not a current serving or quality check. */
+function routerClaim(note) {
+    return claim(`The 2026-09-22 record reports ${note}; this audit recovered no attached trace and made no new router request.`, {
         url: "https://router.tangle.tools/v1/chat/completions",
+        checkedAt: "2026-09-22",
+        authority: "local",
+        locator: "models.ts at d949682; historical routerCheck note",
+    }, "local-observation");
+}
+/** Each row refers to the dated catalog in the retained source audit. */
+function codexCatalogClaim(id, defaultEffort, ultra) {
+    return claim(`Codex cache observed at 2026-10-04T05:31:58Z (client 0.160.0): 272000 context, default ${defaultEffort}, efforts low through max${ultra ? " plus ultra" : ""}. This account/client catalog is not a serving receipt; a later cache written by 0.155.0 lacked GPT-6.1 Sol.`, {
+        url: "file://~/.codex/models_cache.json",
         checkedAt: CHECKED,
+        authority: "local",
+        locator: `research/anthropic-openai.md#local-codex-catalog-evidence; slug ${id}`,
+    }, "local-observation");
+}
+function historicalCodexClaim(id, catalogSource) {
+    const note = catalogSource
+        ? `codex-cli 0.156.1 served list; \`codex exec -m ${id}\` returned OK`
+        : "codex-cli 0.156.1 on a ChatGPT account returned OK";
+    return claim(`The 2026-09-22 record reports ${note}; no attached trace was recovered in this audit.`, {
+        url: catalogSource
+            ? "file://~/.codex/models_cache.json"
+            : `cli:codex exec -m ${id} 'Reply with exactly: OK'`,
+        checkedAt: "2026-09-22",
         note,
-    };
+        authority: "local",
+        locator: "models.ts at d949682; historical CLI check",
+    }, "local-observation");
 }
-/**
- * Current frontier models, from vendor sources read on 2026-09-22.
- *
- * `prompt` lines go into the model's prompt; `operator` lines configure the
- * run. Vendor facts carry their source. Nothing here compares one model with
- * another.
- */
+/** Source-backed facts and conditional advice. API controls never become agent instructions. */
 export const profileKbModels = [
-    {
+    kbEntry({
         id: "claude-opus-5-5",
         name: "Claude Opus 5.5",
         vendor: "Anthropic",
         surfaces: ["api"],
         aliases: ["anthropic/claude-opus-5-5", "anthropic.claude-opus-5-5"],
         defaultEffort: "medium",
-        sources: [
-            { url: `${claudeDocs}/models/opus-5-5/overview`, checkedAt: CHECKED },
-            {
-                url: `${claudeDocs}/build-with-claude/prompt-engineering/prompting-claude-opus-5-5`,
-                checkedAt: CHECKED,
-            },
-            {
-                url: "https://www.anthropic.com/claude-opus-5-5-system-card",
-                checkedAt: CHECKED,
-                note: "system card, linked from the model overview",
-            },
-        ],
-        prompt: [
-            "Keep the task's parts in a checklist you update, and keep working until every item is done or blocked.",
-            "Put status notes and recommendations in the same message as your next tool call; end the turn only when the work is complete or nothing can move without the user.",
-            "Before acting on a loosely specified task, explore the relevant files, records, and sources, including ones the task does not name, and use what you find.",
-            "When a lead agent can delegate, run independent slices in parallel subagents and pace the work to finish early.",
-            "For dense charts, diagrams, or screenshots, crop and zoom with the available image tools before reading values.",
-        ],
-        operator: [
-            "Model id claude-opus-5-5; 1M context, 128K max output; released 2026-09-22.",
-            "Adaptive thinking is always on. Start at effort medium, measure low for cost, and reserve xhigh and max for measured gains.",
-            "Set max_tokens to 128000 for long agentic turns: thinking counts toward it.",
-            "Keep history append-only and pass thinking blocks back unchanged; change instructions with mid-conversation system messages.",
-            "Set thinking display to updates to receive progress notes between tool calls.",
-            "For unattended loops, treat a text-only end of turn as a report: name the open items in a short user message, at most two or three times.",
-            "For multi-agent runs, append elapsed time against a budget (for example `elapsed 340s / 1200s`) to each message.",
-        ],
-    },
-    {
+        claims: [
+            claim("Claude API: 1M context, 128K ordinary output; adaptive thinking is always enabled, default effort medium. Preserve returned thinking and its conversation prefix.", source("https://platform.claude.com/docs/en/models/opus-5-5/overview", "Overview; capabilities; good to know")),
+            claim("For dense charts or screenshots, inspect small details using available crop or zoom tools.", opusGuide, "vendor-guidance", "agent"),
+            claim("For unattended runs that stop with unfinished work, explicit completion tracking and bounded continuation are vendor tuning candidates; interactive confirmations still apply.", opusGuide, "vendor-guidance"),
+            claim("For an already-authorized agent team, elapsed-time and budget signals are a tuning candidate; hard timeouts need enforcement outside the prompt, and time pressure can reduce verification.", opusGuide, "vendor-guidance"),
+        ],
+    }),
+    kbEntry({
         id: "claude-fable-5-1",
         name: "Claude Fable 5.1",
         vendor: "Anthropic",
         surfaces: ["api"],
         aliases: ["anthropic/claude-fable-5-1", "anthropic.claude-fable-5-1"],
         defaultEffort: "high",
-        sources: [
-            { url: `${claudeDocs}/models/fable-5-1/overview`, checkedAt: CHECKED },
-            {
-                url: `${claudeDocs}/build-with-claude/prompt-engineering/prompting-claude-fable-5-1`,
-                checkedAt: CHECKED,
-            },
-        ],
-        prompt: [
-            "You are operating autonomously: for reversible actions that follow from the request, proceed without asking; stop only for destructive actions or scope changes the user must decide.",
-            "Before ending your turn, check your last paragraph: if it is a plan, a list of next steps, or a promise, do that work now with tool calls.",
-            "The request sets the scope: deliver all of it, keep changes to what it needs, and report other findings as follow-ups.",
-            "First privately list what you need next; then request every item that does not depend on another's result in one response.",
-            "Say in a line what you are about to do, give brief updates while you work, and close with a recap that stands on its own.",
-            "Edit files surgically when a targeted edit gives the same result.",
-            "Write plainly: when a literal phrase is available, use it.",
+        claims: [
+            claim("Claude API: 1M context, 128K ordinary output; always-on adaptive thinking, default effort high.", source("https://platform.claude.com/docs/en/models/fable-5-1/overview", "Overview; capabilities")),
+            claim("The vendor offers optional remedies for demonstrated early stopping, serial independent calls, overediting and writing problems. Apply the matching remedy within the task scope and authorization.", fableGuide, "vendor-guidance"),
+            claim("Keep history append-only; supported turn-scoped reminders remain appended. When subagents are already used, nonblocking spawn and later results let the lead continue, but do not guarantee useful overlap.", fableGuide, "vendor-guidance"),
         ],
-        operator: [
-            "Model id claude-fable-5-1; 1M context, 128K max output; released 2026-09-01. For demanding reasoning and long-horizon agentic work.",
-            "Adaptive thinking only. Start at effort high and sweep low, medium, xhigh, and max against your evals.",
-            "Keep history append-only; send per-turn reminders as turn-scoped system messages (clear_at next_user_message).",
-            "Let the lead agent keep working while subagents run: return from the spawn tool immediately and deliver results in a later user message.",
-            "At xhigh and max, leave max_tokens room for thinking plus the deliverable.",
-        ],
-    },
-    {
+    }),
+    kbEntry({
         id: "claude-sonnet-5",
         name: "Claude Sonnet 5",
         vendor: "Anthropic",
         surfaces: ["api", "router"],
         aliases: ["anthropic/claude-sonnet-5", "anthropic.claude-sonnet-5"],
         defaultEffort: "high",
-        sources: [
-            { url: `${claudeDocs}/models/overview`, checkedAt: CHECKED },
-            {
-                url: `${claudeDocs}/build-with-claude/prompt-engineering/prompting-claude-sonnet-5`,
-                checkedAt: CHECKED,
-            },
-            routerCheck("claude-sonnet-5 returned HTTP 200"),
-        ],
-        prompt: [
-            "Apply each instruction to every case it names; where an instruction should apply broadly, the prompt says so.",
-            "For review work, report every issue you find with a confidence and severity; a later step filters them.",
-            "Give regular, short progress updates through long agentic work.",
-        ],
-        operator: [
-            "Model id claude-sonnet-5; 1M context, 128K max output.",
-            "Adaptive thinking is on by default. Effort defaults to high; use xhigh for the hardest coding and agentic tasks.",
-            "Instructions are followed literally, especially at low effort: state scope explicitly.",
-            "Give the task, intent, and constraints up front in the first turn.",
-            "Temperature, top_p, and top_k stay at defaults; steer tone and variety in the prompt.",
+        claims: [
+            claim("Claude API: active legacy model; 1M context, 128K output. Adaptive thinking defaults on with effort high; disabled thinking is also supported.", source("https://platform.claude.com/docs/en/models/sonnet-5/overview", "Capabilities; availability")),
+            claim("For review, specify the desired precision/recall and name any actual downstream filter; do not invent one to justify broad reporting.", sonnetGuide, "vendor-guidance"),
+            claim("Nondefault temperature, top_p and top_k are rejected.", sonnetGuide),
+            routerClaim("claude-sonnet-5 returned HTTP 200"),
+        ],
+    }),
+    kbEntry({
+        id: "claude-sonnet-5-5",
+        name: "Claude Sonnet 5.5",
+        vendor: "Anthropic",
+        surfaces: ["api"],
+        aliases: ["anthropic/claude-sonnet-5-5", "anthropic.claude-sonnet-5-5"],
+        defaultEffort: "high",
+        claims: [
+            claim("Claude API: released 2026-09-28; 1M context, 128K output; adaptive thinking with default effort high. between_tools is the lowest thinking setting and requires effort high or below; do not reuse Sonnet 5 disabled-thinking assumptions.", source("https://platform.claude.com/docs/en/models/sonnet-5-5/overview", "Overview; capabilities; good to know")),
         ],
-    },
-    {
+    }),
+    kbEntry({
         id: "claude-haiku-4-5",
         name: "Claude Haiku 4.5",
         vendor: "Anthropic",
@@ -122,291 +110,153 @@ export const profileKbModels = [
             "anthropic/claude-haiku-4-5",
             "anthropic.claude-haiku-4-5",
         ],
-        sources: [
-            { url: `${claudeDocs}/models/haiku-4-5/overview`, checkedAt: CHECKED },
-        ],
-        prompt: [
-            "Answer directly and keep each step scoped to the task in hand.",
-        ],
-        operator: [
-            "Model id claude-haiku-4-5-20251001 (alias claude-haiku-4-5); 200K context, 64K max output.",
-            "Uses manual extended thinking (thinking.type enabled with budget_tokens); it takes no effort parameter.",
-            "Retirement date: 2026-10-15 at the earliest.",
+        claims: [
+            claim("Claude API alias claude-haiku-4-5 resolves to claude-haiku-4-5-20251001; 200K context, 64K output. Manual extended thinking uses budget_tokens and accepts no effort parameter. Retirement is not before 2026-10-15, not scheduled on that date.", source("https://platform.claude.com/docs/en/models/haiku-4-5/overview", "Model IDs; capabilities; availability")),
         ],
-    },
-    {
+    }),
+    kbEntry({
         id: "gpt-6-pro",
         name: "GPT-6 Pro",
         vendor: "OpenAI",
         surfaces: ["chatgpt"],
         aliases: ["GPT-6 Pro"],
-        sources: [
-            {
-                url: "https://help.openai.com/en/articles/20001354-gpt-56-and-gpt-6-pro-in-chatgpt",
-                checkedAt: CHECKED,
-                note: "read through search results; direct fetch returned HTTP 403",
-            },
-            { url: "https://learn.chatgpt.com/docs/prompting", checkedAt: CHECKED },
+        claims: [
+            claim("GPT-6 Pro is a ChatGPT product mode powered by Astra, with plan/workspace-dependent access and allowances. This entry establishes no API model ID.", source("https://help.openai.com/en/articles/20001354-gpt-56-and-gpt-6-pro-in-chatgpt", "GPT-6 Pro availability; usage limits")),
         ],
-        prompt: [
-            "Start with the result you want, then give the goal, the context that helps, the output format, and what must stay unchanged.",
-            "Describe a process only when the process itself matters; otherwise leave room to search, compare, and adjust.",
-            "End with a final check: confirm each deliverable and flag anything you could not verify.",
-        ],
-        operator: [
-            "A ChatGPT model mode powered by GPT-6 Astra, on Pro, Business, and Enterprise plans. It has a weekly usage limit.",
-            "No API model id; reach it through ChatGPT (chatgpt-fleet).",
+    }),
+    kbEntry({
+        id: "gpt-6.1-sol",
+        name: "GPT-6.1 Sol",
+        vendor: "OpenAI",
+        surfaces: ["codex", "api"],
+        aliases: ["openai/gpt-6.1-sol"],
+        defaultEffort: "medium",
+        claims: [
+            claim("OpenAI API: 1,050,000-token context, 128K output; efforts low, medium, high, xhigh and max. API default is medium. Tool calling requires Responses.", source("https://developers.openai.com/api/docs/models/gpt-6.1-sol", "Model description; reasoning effort; context/output limits; supported endpoints")),
+            codexCatalogClaim("gpt-6.1-sol", "low", true),
         ],
-    },
-    {
+    }),
+    kbEntry({
         id: "gpt-6-astra",
         name: "GPT-6 Astra",
         vendor: "OpenAI",
         surfaces: ["codex", "api"],
         aliases: ["openai/gpt-6-astra"],
         defaultEffort: "medium",
-        sources: [
-            { url: `${openaiDocs}/models/gpt-6-astra`, checkedAt: CHECKED },
-            {
-                url: `${openaiDocs}/guides/latest-model?model=gpt-6-astra`,
-                checkedAt: CHECKED,
-                note: "Using GPT-6: prompting guidance",
-            },
-            { url: "https://learn.chatgpt.com/docs/models", checkedAt: CHECKED },
-            {
-                url: "cli:codex exec -m gpt-6-astra 'Reply with exactly: OK'",
-                checkedAt: CHECKED,
-                note: "codex-cli 0.156.1 on a ChatGPT account returned OK",
-            },
-        ],
-        prompt: [
-            "Infer the user's intent and task scope from the instructions and prior context, bias toward action, and carry the intended task to completion.",
-            "When you can parallelize work by delegating tasks to another agent, do so with the collaboration tools.",
-            "Write clear, concise paragraphs that each develop one idea; use lists only for parallel or sequential items.",
-        ],
-        operator: [
-            "Built for end-to-end work with sustained reasoning across many tools: coding, computer use, research, and documents.",
-            "API: 1,050,000-token context, 128K max output; efforts low, medium, high, xhigh, max.",
-            "Codex: 272K context; efforts low to max plus ultra, which delegates tasks automatically; default medium.",
-        ],
-    },
-    {
+        claims: [
+            claim("OpenAI API: 1,050,000-token context, 128K output; efforts low, medium, high, xhigh and max. Tool calling requires Responses.", source("https://developers.openai.com/api/docs/models/gpt-6-astra", "Model description; reasoning effort; context/output limits; supported endpoints")),
+            codexCatalogClaim("gpt-6-astra", "medium", true),
+            claim("The GPT-6 guide describes Astra prompting patterns; delegation, autonomy and testing examples remain conditional on tools, authorization and workload. Other family members need their own evaluation.", source("https://developers.openai.com/api/docs/guides/latest-model?model=gpt-6-astra", "Prompting best practices; subagent delegation; testing and verification"), "vendor-guidance"),
+            historicalCodexClaim("gpt-6-astra", false),
+        ],
+    }),
+    kbEntry({
         id: "gpt-6-sol",
         name: "GPT-6 Sol",
         vendor: "OpenAI",
         surfaces: ["codex", "api"],
         aliases: ["openai/gpt-6-sol"],
         defaultEffort: "medium",
-        sources: [
-            { url: `${openaiDocs}/models/gpt-6-sol`, checkedAt: CHECKED },
-            {
-                url: `${openaiDocs}/guides/latest-model?model=gpt-6-sol`,
-                checkedAt: CHECKED,
-                note: "Using GPT-6: prompting guidance",
-            },
-            {
-                url: "cli:codex exec -m gpt-6-sol 'Reply with exactly: OK'",
-                checkedAt: CHECKED,
-                note: "codex-cli 0.156.1 on a ChatGPT account returned OK",
-            },
+        claims: [
+            claim("OpenAI API: 1,050,000-token context, 128K output; efforts none, low, medium, high, xhigh and max. API default is medium. Responses supports tools; Chat Completions function calling requires effort none.", source("https://developers.openai.com/api/docs/models/gpt-6-sol", "Model description; reasoning effort; context/output limits; supported endpoints")),
+            codexCatalogClaim("gpt-6-sol", "medium", true),
+            historicalCodexClaim("gpt-6-sol", false),
         ],
-        prompt: [
-            "Treat a request such as 'can you', 'I want to', or 'help me' as an instruction to do the work.",
-            "The user's explicit instructions take precedence over a skill's instructions; if a skill makes you pause or ask, name the SKILL.md file.",
-            "Carry the task to completion and report the checks you ran.",
-        ],
-        operator: [
-            "Built for complex coding and agentic workflows, and for ambiguous or high-value tasks that need analysis and polish.",
-            "API: 1,050,000-token context, 128K max output; efforts none, low, medium (default), high, xhigh, max. Inputs over 272K tokens bill at 2x input and 1.5x output.",
-            "Codex: 272K context; efforts low to max plus ultra; default medium.",
-            "Use the Responses API for built-in tools; Chat Completions supports function calling only at effort none.",
-        ],
-    },
-    {
+    }),
+    kbEntry({
         id: "gpt-6-luna",
         name: "GPT-6 Luna",
         vendor: "OpenAI",
         surfaces: ["codex", "api"],
         aliases: ["openai/gpt-6-luna"],
         defaultEffort: "medium",
-        sources: [
-            { url: `${openaiDocs}/models/gpt-6-luna`, checkedAt: CHECKED },
-            { url: "https://learn.chatgpt.com/docs/models", checkedAt: CHECKED },
-            {
-                url: "cli:codex exec -m gpt-6-luna 'Reply with exactly: OK'",
-                checkedAt: CHECKED,
-                note: "codex-cli 0.156.1 on a ChatGPT account returned OK",
-            },
-        ],
-        prompt: [
-            "Work to the stated success criteria and output format for each item.",
-            "Scale testing to the change: once the targeted checks pass, test further only when new changes or failures justify it.",
+        claims: [
+            claim("OpenAI API: 1,050,000-token context, 128K output; efforts none, low, medium, high, xhigh and max. API default is medium. Responses supports tools; Chat Completions function calling requires effort none.", source("https://developers.openai.com/api/docs/models/gpt-6-luna", "Model description; reasoning effort; context/output limits; supported endpoints")),
+            codexCatalogClaim("gpt-6-luna", "medium", false),
+            historicalCodexClaim("gpt-6-luna", false),
         ],
-        operator: [
-            "Built for focused, high-volume tasks with known success criteria: summarization, extraction, and focused coding.",
-            "API: 1,050,000-token context, 128K max output; efforts none, low, medium (default), high, xhigh, max.",
-            "Codex: 272K context; efforts low to max; default medium.",
-        ],
-    },
-    {
+    }),
+    kbEntry({
         id: "gpt-5.6-sol",
         name: "GPT-5.6 Sol",
         vendor: "OpenAI",
         surfaces: ["codex", "api", "router"],
         aliases: ["openai/gpt-5.6-sol"],
         defaultEffort: "medium",
-        sources: [
-            {
-                url: "https://developers.openai.com/api/docs/models/gpt-5.6-sol",
-                checkedAt: CHECKED,
-            },
-            {
-                url: "https://openai.com/index/builders-guide-to-gpt-5-6/",
-                checkedAt: CHECKED,
-                note: "read through search results; direct fetch returned HTTP 403",
-            },
-            {
-                url: "file://~/.codex/models_cache.json",
-                checkedAt: CHECKED,
-                note: "codex-cli 0.156.1 served list; `codex exec -m gpt-5.6-sol` returned OK",
-            },
-            routerCheck("gpt-5.6-sol returned HTTP 200"),
-        ],
-        prompt: [
-            "Work from the outcome: know what good looks like and the stopping condition, then choose the method yourself.",
-            "Carry the task to completion: gather context, plan, implement, verify, and report the evidence.",
-            "Run independent reads and checks in parallel.",
-        ],
-        operator: [
-            "Flagship GPT-5.6 tier for complex professional work: architecture, security review, repo-wide debugging.",
-            "Keep the system prompt lean: objective, context, hard constraints, approval boundaries, success criteria, required evidence, and output format.",
-            "Efforts: none, low, medium (API default), high, xhigh, max; Codex adds ultra, which runs parallel agents. Codex lists low as its default for this model.",
-            "1,050,000-token context, 128K max output.",
-        ],
-    },
-    {
+        claims: [
+            claim("OpenAI API: 1,050,000-token context, 128K output; efforts none, low, medium, high, xhigh and max. API default is medium.", source("https://developers.openai.com/api/docs/models/gpt-5.6-sol", "Model description; reasoning effort; context/output limits; supported endpoints")),
+            claim("OpenAI API name gpt-5.6 aliases to gpt-5.6-sol.", source("https://developers.openai.com/api/docs/models/gpt-5.6-sol", "Model description; reasoning effort; context/output limits; supported endpoints")),
+            codexCatalogClaim("gpt-5.6-sol", "low", true),
+            historicalCodexClaim("gpt-5.6-sol", true),
+            routerClaim("gpt-5.6-sol returned HTTP 200"),
+        ],
+    }),
+    kbEntry({
         id: "gpt-5.6-terra",
         name: "GPT-5.6 Terra",
         vendor: "OpenAI",
         surfaces: ["codex", "api", "router"],
         aliases: ["openai/gpt-5.6-terra"],
         defaultEffort: "medium",
-        sources: [
-            {
-                url: "https://developers.openai.com/api/docs/models/gpt-5.6-terra",
-                checkedAt: CHECKED,
-            },
-            {
-                url: "file://~/.codex/models_cache.json",
-                checkedAt: CHECKED,
-                note: "codex-cli 0.156.1 served list; `codex exec -m gpt-5.6-terra` returned OK",
-            },
-            routerCheck("gpt-5.6-terra returned HTTP 200"),
-        ],
-        prompt: [
-            "Work from the outcome and the stopping condition; choose the method yourself and verify before you report.",
-        ],
-        operator: [
-            "Balanced GPT-5.6 tier for everyday professional coding.",
-            "Efforts: none, low, medium (default), high, xhigh, max; Codex adds ultra.",
-            "1,050,000-token context, 128K max output.",
-        ],
-    },
-    {
+        claims: [
+            claim("OpenAI API: 1,050,000-token context, 128K output; efforts none, low, medium, high, xhigh and max. API default is medium.", source("https://developers.openai.com/api/docs/models/gpt-5.6-terra", "Model description; reasoning effort; context/output limits; supported endpoints")),
+            codexCatalogClaim("gpt-5.6-terra", "medium", true),
+            historicalCodexClaim("gpt-5.6-terra", true),
+            routerClaim("gpt-5.6-terra returned HTTP 200"),
+        ],
+    }),
+    kbEntry({
         id: "gpt-5.6-luna",
         name: "GPT-5.6 Luna",
         vendor: "OpenAI",
         surfaces: ["codex", "api", "router"],
         aliases: ["openai/gpt-5.6-luna"],
         defaultEffort: "medium",
-        sources: [
-            {
-                url: "https://developers.openai.com/api/docs/models/gpt-5.6-luna",
-                checkedAt: CHECKED,
-            },
-            {
-                url: "file://~/.codex/models_cache.json",
-                checkedAt: CHECKED,
-                note: "codex-cli 0.156.1 served list; `codex exec -m gpt-5.6-luna` returned OK",
-            },
-            routerCheck("gpt-5.6-luna returned HTTP 200"),
-        ],
-        prompt: [
-            "Follow the stated format exactly and finish each item before moving to the next.",
-        ],
-        operator: [
-            "GPT-5.6 tier for cost-sensitive, high-volume work: summarizing, labeling, extraction, scaffolds.",
-            "Efforts: none, low, medium (default), high, xhigh, max. Raise effort for harder items.",
-            "1,050,000-token context, 128K max output.",
-        ],
-    },
-    {
+        claims: [
+            claim("OpenAI API: 1,050,000-token context, 128K output; efforts none, low, medium, high, xhigh and max. API default is medium.", source("https://developers.openai.com/api/docs/models/gpt-5.6-luna", "Model description; reasoning effort; context/output limits; supported endpoints")),
+            codexCatalogClaim("gpt-5.6-luna", "medium", false),
+            historicalCodexClaim("gpt-5.6-luna", true),
+            routerClaim("gpt-5.6-luna returned HTTP 200"),
+        ],
+    }),
+    kbEntry({
         id: "deepseek-v4.1-flash",
         name: "DeepSeek V4.1 Flash",
         vendor: "DeepSeek",
         surfaces: ["api", "router"],
         aliases: ["deepseek-flash", "deepseek/deepseek-v4.1-flash"],
-        sources: [
-            {
-                url: "https://api-docs.deepseek.com/news/news260910/",
-                checkedAt: CHECKED,
-            },
-            {
-                url: "https://api-docs.deepseek.com/quick_start/pricing",
-                checkedAt: CHECKED,
-            },
-            routerCheck("deepseek/deepseek-v4.1-flash returned HTTP 200 and served that id"),
-        ],
-        prompt: [
-            "State the goal and the finished result up front, and use the tools you are given to check your work.",
-        ],
-        operator: [
-            "Vendor API id deepseek-flash (released 2026-09-10); on the Tangle router, deepseek/deepseek-v4.1-flash.",
-            "1M context, 384K max output; thinking mode is the default and non-thinking is available. Native vision.",
-            "OpenCode supports it as an official partner harness.",
+        claims: [
+            claim("DeepSeek API ID deepseek-flash denotes V4.1-Flash: 1M context, 384K output, vision and tools; non-thinking mode is available. Router naming is a separate contract.", deepseekModel),
+            claim("Thinking defaults on at high. Native efforts are low, high and max; minimal maps to low, medium/xhigh to high, and ultra to max. With tools, preserve all previous reasoning_content, including turns without tool calls.", deepseekThinking),
+            routerClaim("deepseek/deepseek-v4.1-flash returned HTTP 200 and served that id"),
         ],
-    },
-    {
+    }),
+    kbEntry({
         id: "glm-5.3",
         name: "GLM-5.3",
         vendor: "Z.ai",
         surfaces: ["api", "router"],
         aliases: ["z-ai/glm-5.3", "zai-coding-plan/glm-5.3"],
         defaultEffort: "ultracode",
-        sources: [
-            { url: "https://docs.z.ai/guides/llm/glm-5.3", checkedAt: CHECKED },
-            routerCheck("glm-5.3 returned HTTP 200, served as z-ai/glm-5.3"),
-        ],
-        prompt: [
-            "Work the task through to a verified result, using the tools to run and check each change.",
-        ],
-        operator: [
-            "Model id glm-5.3; text only; 1M context, 128K max output. Built for long-horizon software engineering.",
-            "Reasoning is always on: thinking.type enabled with reasoning_effort low, high, or max (default). Use max for coding.",
-        ],
-    },
-    {
+        claims: [
+            claim("Z.ai direct API: text-only, 1M context, 128K output; thinking cannot be disabled. reasoning_effort accepts only low, high or max, default max.", glmModel),
+            claim("Coding Plan maps none/minimal/low to low, medium/high to high, and xhigh/max to max; this mapping does not apply to direct GLM-5.3 API requests.", source("https://docs.z.ai/guides/capabilities/thinking#core-parameters", "Core parameters; Coding Plan mappings")),
+            claim("Z.ai recommends max for complex coding; no local effort sweep establishes its value for this workload.", glmModel, "vendor-guidance"),
+            routerClaim("glm-5.3 returned HTTP 200, served as z-ai/glm-5.3"),
+        ],
+    }),
+    kbEntry({
         id: "kimi-k3",
         name: "Kimi K3",
         vendor: "Moonshot AI",
         surfaces: ["api", "router"],
         aliases: ["moonshotai/kimi-k3", "kimi-code/k3"],
         defaultEffort: "ultracode",
-        sources: [
-            {
-                url: "https://platform.kimi.ai/docs/guide/kimi-k3-quickstart",
-                checkedAt: CHECKED,
-            },
-            routerCheck("kimi-k3 returned HTTP 200, served as moonshotai/kimi-k3"),
-        ],
-        prompt: [
-            "Navigate the repository, run the code, and iterate against tests, logs, and runtime output until the result holds.",
-        ],
-        operator: [
-            "Model id kimi-k3; 1M context; native vision. For long-horizon coding, knowledge work, and reasoning.",
-            "Thinking is always on: reasoning_effort low, high, or max (default).",
-            "Sampling is fixed (temperature 1.0, top_p 0.95); omit sampling parameters.",
-            "Return the complete assistant message unchanged in multi-turn and tool-call histories.",
+        claims: [
+            claim("Moonshot API ID kimi-k3: 1M context, native vision, always-on thinking; reasoning_effort low, high or max, default max. The CLI alias kimi-code/k3 belongs to a different configuration surface.", kimiModel),
+            claim("Omit fixed sampling fields. Replay complete assistant messages unchanged, including reasoning and tool calls. Vision uses structured base64 or uploaded-file content, not public image URLs.", kimiModel),
+            claim("For large tool catalogs, tool search followed by dynamic declarations is vendor guidance; the backend must implement retrieval and the K3-specific declaration protocol.", source("https://platform.kimi.ai/docs/guide/kimi-k3-tool-calling-best-practice", "Declare a search tool; use tool_choice; inject tool definitions"), "vendor-guidance"),
+            routerClaim("kimi-k3 returned HTTP 200, served as moonshotai/kimi-k3"),
         ],
-    },
+    }),
 ];

package/dist/profile-kb/records.d.ts

@@ -6,7 +6,7 @@ import type { ProfileKbDiscrepancy, ProfileKbLearning } from "./types.js";
  */
 export declare const profileKbLearnings: readonly ProfileKbLearning[];
 /**
- * Names the platform asked for that vendor sources state differently, as read
- * on 2026-09-22. Recorded instead of guessed.
+ * Historical naming and availability checks from 2026-09-22. Their dates and
+ * observations are retained; they do not establish current service or identity.
  */
 export declare const profileKbDiscrepancies: readonly ProfileKbDiscrepancy[];

package/dist/profile-kb/records.js

@@ -6,16 +6,16 @@ const CHECKED = "2026-09-22";
  */
 export const profileKbLearnings = [];
 /**
- * Names the platform asked for that vendor sources state differently, as read
- * on 2026-09-22. Recorded instead of guessed.
+ * Historical naming and availability checks from 2026-09-22. Their dates and
+ * observations are retained; they do not establish current service or identity.
  */
 export const profileKbDiscrepancies = [
     {
         subject: "OpenAI Codex models",
         requested: "gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna as the current Codex models",
-        observed: "OpenAI's Codex model page lists GPT-6 Astra, GPT-6 Sol, and GPT-6 Luna as the current models. " +
-            "codex-cli 0.156.1 on a ChatGPT account serves all three (each returned OK) and labels the gpt-5.6 tiers 'Older'. " +
-            "The knowledge base carries the GPT-6 tiers as the current Codex models and keeps the requested gpt-5.6 tiers, which Codex and the API still serve.",
+        observed: "On 2026-09-22, OpenAI's Codex model page listed GPT-6 Astra, GPT-6 Sol, and GPT-6 Luna as current. " +
+            "The check notes recorded OK replies for all three with codex-cli 0.156.1 on a ChatGPT account, and labelled the gpt-5.6 tiers 'Older'. " +
+            "Those response checks did not establish served identity, task quality, or availability today.",
         sources: [
             { url: "https://learn.chatgpt.com/docs/models", checkedAt: CHECKED },
             {
@@ -28,9 +28,9 @@ export const profileKbDiscrepancies = [
     {
         subject: "DeepSeek V4.1 Pro",
         requested: "DeepSeek V4.1 Pro",
-        observed: "DeepSeek has released V4.1 Flash only (2026-09-10). Its changelog says the V4 Pro API continues, its pricing page maps " +
-            "deepseek-v4-pro to DeepSeek-V4-Pro-0813, and its V4.1 Flash announcement says deepseek-v4-pro routes to V4.1 Flash from 2026-09-14. " +
-            "On the Tangle router, deepseek-v4-pro returned HTTP 503 (provider quota exhausted). No V4.1 Pro entry exists until DeepSeek ships it.",
+        observed: "The sources checked on 2026-09-22 documented V4.1 Flash, released 2026-09-10, but did not establish a V4.1 Pro model. " +
+            "The changelog said the V4 Pro API continued; pricing mapped deepseek-v4-pro to DeepSeek-V4-Pro-0813, while the Flash announcement said it routed to V4.1 Flash from 2026-09-14. " +
+            "The router check recorded HTTP 503 (provider quota exhausted) for deepseek-v4-pro; it did not resolve that source disagreement.",
         sources: [
             { url: "https://api-docs.deepseek.com/updates/", checkedAt: CHECKED },
             { url: "https://api-docs.deepseek.com/quick_start/pricing", checkedAt: CHECKED },
@@ -40,7 +40,8 @@ export const profileKbDiscrepancies = [
     {
         subject: "DeepSeek V4.1 Flash router id",
         requested: "deepseek-flash (the vendor id)",
-        observed: "On the Tangle router, deepseek-flash returned HTTP 503 (provider_pricing_unavailable); deepseek/deepseek-v4.1-flash returned HTTP 200.",
+        observed: "The 2026-09-22 Tangle router check recorded HTTP 503 (provider_pricing_unavailable) for deepseek-flash and HTTP 200 for deepseek/deepseek-v4.1-flash. " +
+            "These statuses did not establish served identity or current availability.",
         sources: [
             {
                 url: "https://router.tangle.tools/v1/chat/completions",
@@ -51,7 +52,8 @@ export const profileKbDiscrepancies = [
     {
         subject: "GPT-6 Pro",
         requested: "GPT-6 Pro in ChatGPT",
-        observed: "OpenAI's help center names GPT-6 Pro as a ChatGPT mode powered by GPT-6 Astra; it has no API model id.",
+        observed: "The 2026-09-22 check recorded OpenAI's description of GPT-6 Pro as a ChatGPT mode powered by GPT-6 Astra. " +
+            "That check did not establish a separate API model id for the ChatGPT mode.",
         sources: [
             {
                 url: "https://help.openai.com/en/articles/20001354-gpt-56-and-gpt-6-pro-in-chatgpt",

package/dist/profile-kb/types.d.ts

@@ -7,6 +7,17 @@ export interface ProfileKbSource {
     checkedAt: string;
     /** What the source is, when the URL alone does not say. */
     note?: string;
+    /** Authority of the source, independent of whether its claim is advice or a measured result. */
+    authority?: "primary" | "secondary" | "local";
+    /** Section, source lines, or retained artifact locator supporting the claim. */
+    locator?: string;
+}
+/** A short claim with its qualifications in text, so composition cannot strip them. */
+export interface ProfileKbClaim {
+    text: string;
+    basis: "documented" | "vendor-guidance" | "local-observation" | "hypothesis";
+    audience: "agent" | "operator";
+    sources: [ProfileKbSource, ...ProfileKbSource[]];
 }
 /**
  * How to get the best from one harness.
@@ -18,20 +29,21 @@ export interface ProfileKbSource {
 export interface ProfileKbHarness {
     id: HarnessType;
     name: string;
-    /** Installed version the guidance was checked against. */
+    /** Version of the checked CLI or upstream source; claim citations distinguish installation from documentation. */
     version: string;
     sources: ProfileKbSource[];
     prompt: string[];
     operator: string[];
+    /** Canonical claims; prompt/operator are projections retained for existing consumers. */
+    claims?: ProfileKbClaim[];
 }
 /** Where a model is reached. A model id means different things on each surface. */
 export type ProfileKbSurface = "api" | "codex" | "chatgpt" | "router";
 /**
  * How to get the best from one model.
  *
- * Vendor guidance only, each entry citing its source and date. The guidance is
- * positive and specific to this model; it never ranks the model against
- * another.
+ * API facts, dated observations, and conditional vendor guidance. Sources
+ * establish their stated surface, not current availability or task quality.
  */
 export interface ProfileKbModel {
     /** Canonical vendor id. */
@@ -41,11 +53,12 @@ export interface ProfileKbModel {
     surfaces: ProfileKbSurface[];
     /** Other spellings that resolve to this model: router ids, harness aliases. */
     aliases: string[];
-    /** Vendor default reasoning effort, mapped onto the portable scale. */
+    /** Documented API default mapped onto the portable scale (ultracode means max); harness defaults can differ. */
     defaultEffort?: ReasoningEffort;
     sources: ProfileKbSource[];
     prompt: string[];
     operator: string[];
+    claims?: ProfileKbClaim[];
 }
 /**
  * A lesson this platform learned itself. It enters the knowledge base only

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "2.17.0",
+  "version": "2.19.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",