@kungfu-tech/kfd 1.0.0-alpha.19 → 1.0.0-alpha.20

package/scripts/update-kfd-2-claim.mjs

@@ -2,15 +2,61 @@ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import crypto from "node:crypto";
 import path from "node:path";
 
-const outputPath = ".buildchain/kfd-2/public-release-trust.claim.json";
+const releaseClaimPath = ".buildchain/kfd-2/public-release-trust.claim.json";
+const trustClaimsPath = ".buildchain/kfd-2/kfd-foundation.trust-claims.json";
+const trustAssessmentPath = ".buildchain/kfd-2/kfd-foundation.trust-assessment.json";
 
 const readJson = (filePath) => JSON.parse(readFileSync(filePath, "utf8"));
 const sha256File = (filePath) => crypto.createHash("sha256").update(readFileSync(filePath)).digest("hex");
+const digestFile = (filePath) => `sha256:${sha256File(filePath)}`;
 const pointer = (filePath, extra = {}) => ({
   path: filePath,
   sha256: sha256File(filePath),
   ...extra,
 });
+const artifactPointer = (kind, filePath, extra = {}) => ({
+  kind,
+  path: filePath,
+  sha256: sha256File(filePath),
+  ...extra,
+});
+const evidence = (type, filePath, description, extra = {}) => ({
+  type,
+  pointer: artifactPointer(type === "schema" ? "schema" : type === "witness" ? "witness" : "file", filePath),
+  machineProvability: "machine-verifiable",
+  description,
+  ...extra,
+});
+const evidenceResult = (type, filePath, description, extra = {}) => ({
+  type,
+  result: "pass",
+  machineProvability: "machine-verifiable",
+  path: filePath,
+  digest: digestFile(filePath),
+  description,
+  ...extra,
+});
+const responsibility = {
+  owner: "KFD maintainers",
+  sourceOwner: "KFD maintainers",
+  verificationOwner: "KFD package self-verification",
+  decisionOwner: "KFD maintainers",
+};
+const naturalLanguageResidualRisk = {
+  id: "human-language-interpretation",
+  definedBy: "https://kfd.libkungfu.dev/schemas/kfd-2/trust-taxonomy.schema.json#/$defs/residualRisk",
+  riskType: "natural-language-semantic-risk",
+  trustImpact: "downgrade-warning",
+  machineProvability: "not-exhaustively-enumerable",
+  agentAction: "semantic-review-required",
+  reason: "Natural-language standard interpretation is inspectable and reviewable but cannot be exhaustively proved from package bytes.",
+  owner: "KFD maintainers",
+};
+const writeJson = (filePath, value) => {
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+  console.log(`updated ${filePath}`);
+};
 
 const packageJson = readJson("package.json");
 const releaseAnchor = readJson("kfd.release.json");
@@ -30,6 +76,8 @@ const machineEvidence = [
   pointer(".github/workflows/build.yml", { id: "buildchain-build-workflow" }),
   pointer(".github/workflows/buildchain-ref-promotion.yml", { id: "buildchain-promotion-workflow" }),
   pointer("schemas/kfd-2/trust-taxonomy.schema.json", { id: "kfd-2-trust-taxonomy-schema" }),
+  pointer("schemas/kfd-2/trust-claims.schema.json", { id: "kfd-2-trust-claims-schema" }),
+  pointer("schemas/kfd-2/trust-assessment.schema.json", { id: "kfd-2-trust-assessment-schema" }),
   pointer("schemas/kfd-2/release-claims.schema.json", { id: "kfd-2-release-claims-schema" }),
   pointer("schemas/kfd-2/release-trust-passport.schema.json", { id: "kfd-2-release-trust-passport-schema" }),
 ];
@@ -38,7 +86,7 @@ const hashes = Object.fromEntries(
   [...sourceBindings, ...machineEvidence].map((entry) => [entry.id, entry.sha256]),
 );
 
-const claim = {
+const releaseClaim = {
   id: "kfd-public-release-trust",
   public: true,
   claim:
@@ -78,6 +126,179 @@ const claim = {
   residualRisk: [],
 };
 
-mkdirSync(path.dirname(outputPath), { recursive: true });
-writeFileSync(outputPath, `${JSON.stringify(claim, null, 2)}\n`);
-console.log(`updated ${outputPath}`);
+writeJson(releaseClaimPath, releaseClaim);
+
+const trustClaims = {
+  schemaVersion: 1,
+  contract: "kfd-2-trust-claims",
+  standard: "kfd-2",
+  projection: {
+    kind: "generic",
+    description: "KFD self-dogfood claims for assessing KFD-1, KFD-3, and KFD-4 from the generic KFD-2 trust model.",
+  },
+  claims: [
+    {
+      id: "kfd-1-contract-world-trust",
+      statement:
+        "KFD-1 is trustable as the KFD package contract-world rule because its surface register, schema, witness, and verification command are inspectable from committed package facts.",
+      subject: {
+        kind: "contract-world",
+        id: "kfd-1-surface-register",
+        standard: "kfd-1",
+        description: "KFD-1 non-drifting fact-source and compatibility-impact surface register.",
+      },
+      facts: [
+        artifactPointer("file", "standards.json"),
+        artifactPointer("schema", "schemas/kfd-1/contract-world.schema.json"),
+      ],
+      evidence: [
+        evidence("schema", "schemas/kfd-1/contract-world.schema.json", "KFD-1 contract-world schema is published as a package surface."),
+        evidence("file", "scripts/check.mjs", "The package check gate validates the KFD-1 schema, surface register, witness, and hashes."),
+      ],
+      verification: {
+        command: "node scripts/check.mjs",
+        expectedResult: "pass",
+      },
+      auditBoundary: {
+        scope: "KFD package KFD-1 surface-register, schema, witness, and self-verification gate",
+        enumerability: "closed-world",
+      },
+      residualRisk: [],
+      responsibility,
+      status: "enforced",
+    },
+    {
+      id: "kfd-3-collaboration-interface-trust",
+      statement:
+        "KFD-3 is trustable as a participant-facing collaboration interface because KFD publishes the declared interface, explicit value evidence, prebuild witness, artifact witness, extension path, and closure check.",
+      subject: {
+        kind: "collaboration-interface",
+        id: "kfd-3-collaboration-interface",
+        standard: "kfd-3",
+        description: "KFD package collaboration interface for humans, agents, maintainers, package consumers, site consumers, and release systems.",
+      },
+      facts: [
+        artifactPointer("file", ".buildchain/kfd-3/collaboration-interface.json"),
+      ],
+      evidence: [
+        evidence("schema", "schemas/kfd-3/collaboration-interface.schema.json", "KFD-3 collaboration interface schema is published."),
+        evidence("file", ".buildchain/kfd-3/collaboration-interface.json", "KFD-3 source collaboration interface declares reachable participant-facing surfaces and value evidence."),
+        evidence("file", "scripts/check.mjs", "The package check gate validates KFD-3 interface closure and witness parity."),
+      ],
+      verification: {
+        command: "node scripts/check.mjs",
+        expectedResult: "warning",
+      },
+      auditBoundary: {
+        scope: "KFD participant-facing collaboration surfaces, extension paths, and shipped witness files",
+        enumerability: "closed-world",
+      },
+      residualRisk: [naturalLanguageResidualRisk],
+      responsibility,
+      status: "enforced",
+    },
+    {
+      id: "kfd-4-observer-perspective-trust",
+      statement:
+        "KFD-4 is trustable as an observer-perspective interface because KFD publishes the schema, standards metadata, decision text, and verification gate for observer-relative timeline views.",
+      subject: {
+        kind: "observer-perspective",
+        id: "kfd-4-observer-perspective",
+        standard: "kfd-4",
+        description: "KFD-4 observer-perspective schema for perspective-bearing timeline views.",
+      },
+      facts: [
+        artifactPointer("file", "decisions/KFD-4.md"),
+        artifactPointer("file", "standards.json"),
+        artifactPointer("schema", "schemas/kfd-4/observer-perspective.schema.json"),
+      ],
+      evidence: [
+        evidence("schema", "schemas/kfd-4/observer-perspective.schema.json", "KFD-4 observer-perspective schema is published."),
+        evidence("file", "standards.json", "Standards metadata exposes the KFD-4 schema ID, path, interface version, and concept names."),
+        evidence("file", "scripts/check.mjs", "The package check gate validates the KFD-4 schema and standards metadata."),
+      ],
+      verification: {
+        command: "node scripts/check.mjs",
+        expectedResult: "pass",
+      },
+      auditBoundary: {
+        scope: "KFD-4 decision text, observer-perspective schema, standards metadata, and self-verification gate",
+        enumerability: "closed-world",
+      },
+      residualRisk: [],
+      responsibility,
+      status: "enforced",
+    },
+  ],
+  schemaEvolution: {
+    compatibilityRule:
+      "Compatible additions may keep schemaVersion 1; semantic, required-field, verification-meaning, or responsibility-boundary changes require a new interface version or contract.",
+  },
+};
+writeJson(trustClaimsPath, trustClaims);
+
+const trustClaimsDigest = digestFile(trustClaimsPath);
+const assessment = {
+  schemaVersion: 1,
+  contract: "kfd-2-trust-assessment",
+  standard: "kfd-2",
+  assessedClaims: {
+    schemaId: "https://kfd.libkungfu.dev/schemas/kfd-2/trust-claims.schema.json",
+    path: trustClaimsPath,
+    digest: trustClaimsDigest,
+  },
+  result: "warning",
+  projection: {
+    kind: "generic",
+    description: "Generic KFD-2 assessment of KFD-owned foundation and practice guideline claims.",
+  },
+  assessments: [
+    {
+      id: "assess-kfd-1-contract-world-trust",
+      claimId: "kfd-1-contract-world-trust",
+      subject: trustClaims.claims[0].subject,
+      result: "pass",
+      facts: trustClaims.claims[0].facts.map((entry) => evidenceResult(entry.kind, entry.path, `Fact ${entry.path} is present and hashable.`)),
+      evidence: trustClaims.claims[0].evidence.map((entry) => evidenceResult(entry.type, entry.pointer.path, entry.description)),
+      auditBoundary: trustClaims.claims[0].auditBoundary,
+      responsibility,
+      residualRisk: [],
+    },
+    {
+      id: "assess-kfd-3-collaboration-interface-trust",
+      claimId: "kfd-3-collaboration-interface-trust",
+      subject: trustClaims.claims[1].subject,
+      result: "warning",
+      facts: trustClaims.claims[1].facts.map((entry) => evidenceResult(entry.kind, entry.path, `Fact ${entry.path} is present and hashable.`)),
+      evidence: trustClaims.claims[1].evidence.map((entry) => evidenceResult(entry.type, entry.pointer.path, entry.description)),
+      auditBoundary: trustClaims.claims[1].auditBoundary,
+      responsibility,
+      residualRisk: [naturalLanguageResidualRisk],
+    },
+    {
+      id: "assess-kfd-4-observer-perspective-trust",
+      claimId: "kfd-4-observer-perspective-trust",
+      subject: trustClaims.claims[2].subject,
+      result: "pass",
+      facts: trustClaims.claims[2].facts.map((entry) => evidenceResult(entry.kind, entry.path, `Fact ${entry.path} is present and hashable.`)),
+      evidence: trustClaims.claims[2].evidence.map((entry) => evidenceResult(entry.type, entry.pointer.path, entry.description)),
+      auditBoundary: trustClaims.claims[2].auditBoundary,
+      responsibility,
+      residualRisk: [],
+    },
+  ],
+  unboundClaims: [],
+  downgradeReasons: [
+    {
+      id: "kfd-3-natural-language-semantics",
+      riskType: "natural-language-semantic-risk",
+      trustImpact: "downgrade-warning",
+      reason: "KFD-3 exposes machine-checkable collaboration surfaces and value evidence, but the human-language meaning of trusted value and non-coercive cooperation remains a reviewable semantic responsibility.",
+      agentAction: "semantic-review-required",
+      source: "kfd-3-collaboration-interface-trust",
+    },
+  ],
+  responsibility,
+  schemaEvolution: trustClaims.schemaEvolution,
+};
+writeJson(trustAssessmentPath, assessment);

package/scripts/update-kfd-3-witness.mjs

@@ -37,6 +37,8 @@ const schemaSurfaces = [
   "schemas/kfd-1/contract-world.schema.json",
   "schemas/kfd-1/witness.schema.json",
   "schemas/kfd-2/trust-taxonomy.schema.json",
+  "schemas/kfd-2/trust-claims.schema.json",
+  "schemas/kfd-2/trust-assessment.schema.json",
   "schemas/kfd-2/release-claims.schema.json",
   "schemas/kfd-2/release-trust-passport.schema.json",
   "schemas/kfd-3/collaboration-interface.schema.json",
@@ -53,8 +55,10 @@ const groupedSurfaces = {
     { id: "doc:readme", sourcePath: "README.md", sha256: sha256File("README.md") },
     { id: "doc:trademarks", sourcePath: "TRADEMARKS.md", sha256: sha256File("TRADEMARKS.md") },
     { id: "doc:docs-map", sourcePath: "docs/MAP.md", sha256: sha256File("docs/MAP.md") },
-    { id: "doc:kfd-2-release-trust", sourcePath: "docs/kfd-2-release-trust.md", sha256: sha256File("docs/kfd-2-release-trust.md") },
-    { id: "doc:kfd-3-collaboration-interface", sourcePath: "docs/kfd-3-collaboration-interface.md", sha256: sha256File("docs/kfd-3-collaboration-interface.md") },
+    { id: "doc:kfd-1-usage", sourcePath: "docs/KFD-1-usage.md", sha256: sha256File("docs/KFD-1-usage.md") },
+    { id: "doc:kfd-2-usage", sourcePath: "docs/KFD-2-usage.md", sha256: sha256File("docs/KFD-2-usage.md") },
+    { id: "doc:kfd-3-usage", sourcePath: "docs/KFD-3-usage.md", sha256: sha256File("docs/KFD-3-usage.md") },
+    { id: "doc:kfd-4-usage", sourcePath: "docs/KFD-4-usage.md", sha256: sha256File("docs/KFD-4-usage.md") },
     ...decisionDocs,
   ],
   schemas: schemaSurfaces,
@@ -65,6 +69,8 @@ const groupedSurfaces = {
     { id: "metadata:release-anchor", sourcePath: "kfd.release.json", sha256: sha256File("kfd.release.json") },
     { id: "metadata:buildchain-contract-lock", sourcePath: "buildchain.contract-lock.json", sha256: sha256File("buildchain.contract-lock.json") },
     { id: "metadata:kfd-2-public-release-trust-claim", sourcePath: ".buildchain/kfd-2/public-release-trust.claim.json", sha256: sha256File(".buildchain/kfd-2/public-release-trust.claim.json") },
+    { id: "metadata:kfd-2-foundation-trust-claims", sourcePath: ".buildchain/kfd-2/kfd-foundation.trust-claims.json", sha256: sha256File(".buildchain/kfd-2/kfd-foundation.trust-claims.json") },
+    { id: "metadata:kfd-2-foundation-trust-assessment", sourcePath: ".buildchain/kfd-2/kfd-foundation.trust-assessment.json", sha256: sha256File(".buildchain/kfd-2/kfd-foundation.trust-assessment.json") },
   ],
   packageExports: [
     { id: "export:package-json", sourcePath: "package.json#exports", sha256: sha256File("package.json") },
@@ -105,6 +111,24 @@ for (const entrypoint of collaborationInterface.minimalEntrypoints) {
   declaredSurfaceIds.add(entrypoint.id);
 }
 
+const valueEvidencePointers = (() => {
+  const entriesByPath = new Map();
+  for (const valueClaim of collaborationInterface.valueEvidence ?? []) {
+    for (const entry of [
+      ...(valueClaim.facts ?? []),
+      ...(valueClaim.evidence ?? []),
+      ...(valueClaim.trustAssessment ? [valueClaim.trustAssessment] : []),
+    ]) {
+      if (!entry?.path || entriesByPath.has(entry.path)) continue;
+      entriesByPath.set(
+        entry.path,
+        pointer(entry.path, `KFD-3 value evidence for ${valueClaim.id}: ${valueClaim.claim}`)
+      );
+    }
+  }
+  return [...entriesByPath.values()];
+})();
+
 const participantProfiles = collaborationInterface.participants.map((entry) => entry.id);
 const responsibility = {
   registryFactsOwner: "KFD maintainers",
@@ -187,9 +211,12 @@ const artifact = {
       pointer("registry.json", "Machine-readable decision index"),
       pointer("standards.json", "Machine-readable standards metadata"),
       pointer(".buildchain/kfd-2/public-release-trust.claim.json", "KFD-2 public release trust claim"),
+      pointer(".buildchain/kfd-2/kfd-foundation.trust-claims.json", "KFD-2 generic trust claims for KFD self-dogfood"),
+      pointer(".buildchain/kfd-2/kfd-foundation.trust-assessment.json", "KFD-2 generic trust assessment for KFD self-dogfood"),
       pointer("package.json", "Package export map"),
       pointer("site/kfd-site.json", "Site content projection"),
     ],
+    valueEvidence: valueEvidencePointers,
     transparentConstraints: [
       pointer("CONTRIBUTING.md", "Append-only decision and contribution constraints"),
       pointer("TRADEMARKS.md", "Trademark and official-status constraints"),
@@ -201,12 +228,17 @@ const artifact = {
       pointer("registry.json", "Agent registry path"),
       pointer("standards.json", "Agent standards metadata path"),
       pointer(".buildchain/kfd-2/public-release-trust.claim.json", "Agent release trust claim path"),
+      pointer(".buildchain/kfd-2/kfd-foundation.trust-claims.json", "Agent generic trust claims path"),
+      pointer(".buildchain/kfd-2/kfd-foundation.trust-assessment.json", "Agent generic trust assessment path"),
       pointer("package.json", "Package consumption path"),
     ],
     manuals: [
       pointer("docs/MAP.md"),
       pointer("TRADEMARKS.md"),
-      pointer("docs/kfd-3-collaboration-interface.md"),
+      pointer("docs/KFD-1-usage.md"),
+      pointer("docs/KFD-2-usage.md"),
+      pointer("docs/KFD-3-usage.md"),
+      pointer("docs/KFD-4-usage.md"),
     ],
   },
   closure: {

package/scripts/update-site-bundle.mjs

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 
 const README_PATH = "README.md";
@@ -105,6 +105,26 @@ const parseProductProofPath = (markdown) => ({
   body: paragraphBlocks(markdown)[0] || "",
 });
 
+const usagePathForEntry = (entry) => `docs/KFD-${entry.number}-usage.md`;
+const usageUrlForEntry = (entry) => `${entry.url}/usage`;
+
+const buildUsagePages = (entries) => entries.map((entry) => {
+  const usagePath = usagePathForEntry(entry);
+  return {
+    id: `${entry.id}-usage`,
+    decisionId: entry.id,
+    decisionNumber: entry.number,
+    parentPath: entry.path,
+    parentUrl: entry.url,
+    path: usagePath,
+    url: usageUrlForEntry(entry),
+    sourcePath: usagePath,
+    sourceExists: existsSync(usagePath),
+    relationship: "usage-child-of-decision",
+    title: `${entry.id} usage`,
+  };
+});
+
 const section = ({ id, sourceHeading, title, markdown, role, priority, presentation, firstScreen = false }) => ({
   id,
   sourcePath: README_PATH,
@@ -206,6 +226,7 @@ export const buildSiteBundle = ({ readmeText, registry }) => {
     routes: {
       home: "/",
       decisionPattern: "/{number}",
+      decisionUsagePattern: "/{number}/usage",
       llms: "/llms.txt",
       manifest: "/manifest.json",
     },
@@ -254,6 +275,13 @@ export const buildSiteBundle = ({ readmeText, registry }) => {
       source: REGISTRY_PATH,
       bodySource: "registry.entries[].path",
       stableUrlField: "url",
+      usagePages: {
+        source: "registry.entries[] + docs/KFD-N-usage.md",
+        bodySource: "docs/KFD-{number}-usage.md",
+        stableUrlPattern: "/{number}/usage",
+        relationship: "usage-child-of-decision",
+        pages: buildUsagePages(entries),
+      },
       metadata: {
         licenseBoundary: {
           license: "Apache-2.0",
@@ -269,7 +297,7 @@ export const buildSiteBundle = ({ readmeText, registry }) => {
           loadBearingCoordinate: "commit-addressed repository contents",
           stableRenderedIndex: "https://kfd.libkungfu.dev",
           canonicalPaths: [
-            "decisions/kfd-N.md",
+            "decisions/KFD-N.md",
             REGISTRY_PATH,
             "standards.json",
           ],
@@ -294,6 +322,8 @@ export const buildSiteBundle = ({ readmeText, registry }) => {
         "decision metadata fact source",
         "license and official-status boundary",
         "decision markdown bodies",
+        "decision usage page mapping",
+        "decision usage markdown bodies",
       ],
       ownedBySite: [
         "HTML structure",

package/site/kfd-site.json

@@ -10,6 +10,7 @@
   "routes": {
     "home": "/",
     "decisionPattern": "/{number}",
+    "decisionUsagePattern": "/{number}/usage",
     "llms": "/llms.txt",
     "manifest": "/manifest.json"
   },
@@ -157,7 +158,7 @@
         "homepagePriority": 40,
         "defaultPresentation": "ordered-steps",
         "includeInFirstScreen": false,
-        "markdown": "Agents consuming this package should start from the same sources as humans:\n\n1. Read this README for the foundation model and package map.\n2. Read `standards.json` for canonical KFD numbers, schema IDs, concept names,\n   and interface contracts.\n3. Use `site/kfd-site.json` decision metadata or the KFD-3 collaboration\n   interface fact-source metadata to identify the public KFD fact source.\n4. Use `schemas/kfd-2/trust-taxonomy.schema.json` for KFD-2 residual-risk and\n   trust-downgrade values. Unknown taxonomy values are invalid.\n5. Use `schemas/kfd-3/collaboration-interface.schema.json` and\n   `schemas/kfd-3/witness.schema.json` to inspect collaboration interfaces.\n6. If a needed KFD-2 taxonomy value is missing, open a KFD GitHub issue rather\n   than inventing a local value:\n   `https://github.com/kungfu-systems/kfd/issues/new?title=KFD-2%20trust%20taxonomy%20extension%20request`.\n\nKFD package semver is only the distribution version. KFD-owned machine\ninterfaces carry their own `schemaVersion` and `contract` fields. Compatible\nadditions may keep the same interface version; semantic changes, required-field\nchanges, verification meaning changes, or responsibility-boundary changes must\nuse a new interface version or contract.\n\nKFD-2 publishes trust-taxonomy, release-claims, and release-trust-passport\nschemas under `schemas/kfd-2/`. These schemas let Buildchain and other release\nsystems audit whether public release claims are bound to source facts,\nevidence, hashes, audit boundaries, residual risk, and responsibility state. See\n[`docs/kfd-2-release-trust.md`](docs/kfd-2-release-trust.md).\n\nKFD-3 also publishes a general collaboration-interface schema and witness\nschema under `schemas/kfd-3/`. These schemas are for participant-facing product\ninterfaces, not only agent APIs. A product such as Kungfu may implement an\nagent-first profile, but that profile remains a product-specific realization of\nKFD-3. The KFD-owned boundary is the standard vocabulary, schema IDs, and\nclosed-world evidence shape. See\n[`docs/kfd-3-collaboration-interface.md`](docs/kfd-3-collaboration-interface.md).\n\nKFD-4 publishes an observer-perspective schema under `schemas/kfd-4/`. It gives\nhumans and agents a standard vocabulary for observer, accepted facts,\nprojection policy, causal constraints, degraded evidence, and verification\nstate when a product shows a perspective-bearing timeline."
+        "markdown": "Agents consuming this package should start from the same sources as humans:\n\n1. Read this README for the foundation model and package map.\n2. Read `standards.json` for canonical KFD numbers, schema IDs, concept names,\n   and interface contracts.\n3. Use `site/kfd-site.json` decision metadata or the KFD-3 collaboration\n   interface fact-source metadata to identify the public KFD fact source.\n4. Use `schemas/kfd-2/trust-taxonomy.schema.json` for KFD-2 residual-risk and\n   trust-downgrade values. Unknown taxonomy values are invalid.\n5. Use `schemas/kfd-2/trust-claims.schema.json` and\n   `schemas/kfd-2/trust-assessment.schema.json` when a claim needs generic\n   KFD-2 assessment instead of a release-specific passport.\n6. Use `schemas/kfd-3/collaboration-interface.schema.json` and\n   `schemas/kfd-3/witness.schema.json` to inspect collaboration interfaces.\n7. If a needed KFD-2 taxonomy value is missing, open a KFD GitHub issue rather\n   than inventing a local value:\n   `https://github.com/kungfu-systems/kfd/issues/new?title=KFD-2%20trust%20taxonomy%20extension%20request`.\n\nKFD package semver is only the distribution version. KFD-owned machine\ninterfaces carry their own `schemaVersion` and `contract` fields. Compatible\nadditions may keep the same interface version; semantic changes, required-field\nchanges, verification meaning changes, or responsibility-boundary changes must\nuse a new interface version or contract.\n\nKFD-2 publishes trust-taxonomy, trust-claims, trust-assessment,\nrelease-claims, and release-trust-passport schemas under `schemas/kfd-2/`.\nThe generic schemas let humans, agents, Buildchain, and other systems assess\nwhether claims about KFD-1, KFD-3, KFD-4, future KFDs, or product surfaces are\nbound to source facts, evidence, hashes, audit boundaries, residual risk, and\nresponsibility state. The release schemas are a release-specific projection of\nthat model. See [`docs/KFD-2-usage.md`](docs/KFD-2-usage.md).\n\nKFD-3 also publishes a general collaboration-interface schema and witness\nschema under `schemas/kfd-3/`. These schemas are for participant-facing product\ninterfaces, not only agent APIs. A product such as Kungfu may implement an\nagent-first profile, but that profile remains a product-specific realization of\nKFD-3. The KFD-owned boundary is the standard vocabulary, schema IDs, and\nclosed-world evidence shape. See\n[`docs/KFD-3-usage.md`](docs/KFD-3-usage.md).\n\nKFD-4 publishes an observer-perspective schema under `schemas/kfd-4/`. It gives\nhumans and agents a standard vocabulary for observer, accepted facts,\nprojection policy, causal constraints, degraded evidence, and verification\nstate when a product shows a perspective-bearing timeline."
       },
       {
         "id": "decision-metadata",
@@ -168,7 +169,7 @@
         "homepagePriority": 50,
         "defaultPresentation": "fact-source",
         "includeInFirstScreen": false,
-        "markdown": "Every rendered decision page should make the KFD fact source explicit. The\npublic KFD fact source is the GitHub-hosted `kungfu-systems/kfd` git\nrepository. GitHub is the current canonical coordination and hosting surface;\nthe load-bearing facts are the commit-addressed repository contents.\n\nDecision metadata should expose:\n\n- Public fact source: `https://github.com/kungfu-systems/kfd`\n- Load-bearing coordinate: commit-addressed repository contents.\n- Canonical paths: `decisions/kfd-N.md`, `registry.json`, `standards.json`.\n- Stable rendered index: `https://kfd.libkungfu.dev`.\n- Rendered URL: `https://kfd.libkungfu.dev/N`.\n\nRendered pages, npm package contents, Buildchain release passports, and\n`kfd.libkungfu.dev` are projections or evidence surfaces. A GitHub issue is an\nextension request path, not a KFD fact by itself; it becomes part of the KFD\nfact source only after the resulting change is committed to the repository."
+        "markdown": "Every rendered decision page should make the KFD fact source explicit. The\npublic KFD fact source is the GitHub-hosted `kungfu-systems/kfd` git\nrepository. GitHub is the current canonical coordination and hosting surface;\nthe load-bearing facts are the commit-addressed repository contents.\n\nDecision metadata should expose:\n\n- Public fact source: `https://github.com/kungfu-systems/kfd`\n- Load-bearing coordinate: commit-addressed repository contents.\n- Canonical paths: `decisions/KFD-N.md`, `registry.json`, `standards.json`.\n- Stable rendered index: `https://kfd.libkungfu.dev`.\n- Rendered URL: `https://kfd.libkungfu.dev/N`.\n\nRendered pages, npm package contents, Buildchain release passports, and\n`kfd.libkungfu.dev` are projections or evidence surfaces. A GitHub issue is an\nextension request path, not a KFD fact by itself; it becomes part of the KFD\nfact source only after the resulting change is committed to the repository."
       }
     ],
     "displayPlan": {
@@ -222,6 +223,66 @@
     "source": "registry.json",
     "bodySource": "registry.entries[].path",
     "stableUrlField": "url",
+    "usagePages": {
+      "source": "registry.entries[] + docs/KFD-N-usage.md",
+      "bodySource": "docs/KFD-{number}-usage.md",
+      "stableUrlPattern": "/{number}/usage",
+      "relationship": "usage-child-of-decision",
+      "pages": [
+        {
+          "id": "KFD-1-usage",
+          "decisionId": "KFD-1",
+          "decisionNumber": 1,
+          "parentPath": "decisions/KFD-1.md",
+          "parentUrl": "https://kfd.libkungfu.dev/1",
+          "path": "docs/KFD-1-usage.md",
+          "url": "https://kfd.libkungfu.dev/1/usage",
+          "sourcePath": "docs/KFD-1-usage.md",
+          "sourceExists": true,
+          "relationship": "usage-child-of-decision",
+          "title": "KFD-1 usage"
+        },
+        {
+          "id": "KFD-2-usage",
+          "decisionId": "KFD-2",
+          "decisionNumber": 2,
+          "parentPath": "decisions/KFD-2.md",
+          "parentUrl": "https://kfd.libkungfu.dev/2",
+          "path": "docs/KFD-2-usage.md",
+          "url": "https://kfd.libkungfu.dev/2/usage",
+          "sourcePath": "docs/KFD-2-usage.md",
+          "sourceExists": true,
+          "relationship": "usage-child-of-decision",
+          "title": "KFD-2 usage"
+        },
+        {
+          "id": "KFD-3-usage",
+          "decisionId": "KFD-3",
+          "decisionNumber": 3,
+          "parentPath": "decisions/KFD-3.md",
+          "parentUrl": "https://kfd.libkungfu.dev/3",
+          "path": "docs/KFD-3-usage.md",
+          "url": "https://kfd.libkungfu.dev/3/usage",
+          "sourcePath": "docs/KFD-3-usage.md",
+          "sourceExists": true,
+          "relationship": "usage-child-of-decision",
+          "title": "KFD-3 usage"
+        },
+        {
+          "id": "KFD-4-usage",
+          "decisionId": "KFD-4",
+          "decisionNumber": 4,
+          "parentPath": "decisions/KFD-4.md",
+          "parentUrl": "https://kfd.libkungfu.dev/4",
+          "path": "docs/KFD-4-usage.md",
+          "url": "https://kfd.libkungfu.dev/4/usage",
+          "sourcePath": "docs/KFD-4-usage.md",
+          "sourceExists": true,
+          "relationship": "usage-child-of-decision",
+          "title": "KFD-4 usage"
+        }
+      ]
+    },
     "metadata": {
       "licenseBoundary": {
         "license": "Apache-2.0",
@@ -237,7 +298,7 @@
         "loadBearingCoordinate": "commit-addressed repository contents",
         "stableRenderedIndex": "https://kfd.libkungfu.dev",
         "canonicalPaths": [
-          "decisions/kfd-N.md",
+          "decisions/KFD-N.md",
           "registry.json",
           "standards.json"
         ],
@@ -261,7 +322,9 @@
       "decision metadata",
       "decision metadata fact source",
       "license and official-status boundary",
-      "decision markdown bodies"
+      "decision markdown bodies",
+      "decision usage page mapping",
+      "decision usage markdown bodies"
     ],
     "ownedBySite": [
       "HTML structure",