superbee 0.4.6-pre.2 → 0.4.6-pre.3

package/dist/superbee.mjs

@@ -44,7 +44,7 @@ var __toESM = (mod, isNodeMode, target3) => (target3 = mod != null ? __create(__
 var define_SUPERBEE_BUILD_IDENTITY_default;
 var init_define_SUPERBEE_BUILD_IDENTITY = __esm({
   "<define:__SUPERBEE_BUILD_IDENTITY__>"() {
-    define_SUPERBEE_BUILD_IDENTITY_default = { schema: "superbee.build-identity.v1", package: { name: "superbee", version: "0.4.6-pre.2" }, source: { commit: "2b1d8f3f0c9e2e556e6f7a7343c3a82b559735db", dirty: false }, artifact: { channel: "npm-package" }, compatibility_contracts: { skill: 1, hook: 1, mcp: 1 } };
+    define_SUPERBEE_BUILD_IDENTITY_default = { schema: "superbee.build-identity.v1", package: { name: "superbee", version: "0.4.6-pre.3" }, source: { commit: "1e105cf6a63c34d1d40966ce299ce4087fe7cecd", dirty: false }, artifact: { channel: "npm-package" }, compatibility_contracts: { skill: 1, hook: 1, mcp: 1 } };
   }
 });
 
@@ -82,20 +82,20 @@ var init_errors = __esm({
       suggestedId;
       /** The canonical spelling names a document that already exists, so it is not offered as the fix. */
       existingId;
-      constructor(id, why, suggestion) {
+      constructor(id, why, suggestion2) {
         const explanation = {
           segment_whitespace: "a path segment starts or ends with whitespace",
           format_character: "a path segment holds an invisible format character",
           not_nfc: "it writes a letter as two characters (a base letter and a separate combining mark) instead of one, and some filesystems treat the two spellings as the same name"
         }[why];
         super(
-          `'${visibleId(id)}' cannot be created: ${explanation}. Ids must have one spelling everywhere, so this one would also fail at publish and sync.` + (suggestion === void 0 ? " Choose a different id." : suggestion.exists ? ` '${suggestion.id}' already exists: choose a different id, or edit that document if you meant it.` : ` Use '${suggestion.id}'.`)
+          `'${visibleId(id)}' cannot be created: ${explanation}. Ids must have one spelling everywhere, so this one would also fail at publish and sync.` + (suggestion2 === void 0 ? " Choose a different id." : suggestion2.exists ? ` '${suggestion2.id}' already exists: choose a different id, or edit that document if you meant it.` : ` Use '${suggestion2.id}'.`)
         );
         this.name = "NonCanonicalDocumentIdError";
         this.id = id;
         this.why = why;
-        this.suggestedId = suggestion && !suggestion.exists ? suggestion.id : void 0;
-        this.existingId = suggestion?.exists ? suggestion.id : void 0;
+        this.suggestedId = suggestion2 && !suggestion2.exists ? suggestion2.id : void 0;
+        this.existingId = suggestion2?.exists ? suggestion2.id : void 0;
       }
     };
     FrontmatterRefusedError = class extends InvalidInputError {
@@ -3960,6 +3960,8 @@ function extractMarkdownLinkSpans(source2, options = {}) {
   const body = options.skipCode ? maskMarkdownCode(source2) : source2;
   const out = [];
   let textOpen = -1;
+  let codeOpen = -1;
+  let masked;
   let afterClose;
   let hrefFirst;
   let hrefRest;
@@ -3978,6 +3980,7 @@ function extractMarkdownLinkSpans(source2, options = {}) {
           image
         });
         textOpen = -1;
+        codeOpen = -1;
         afterClose = void 0;
         hrefFirst = void 0;
         hrefRest = void 0;
@@ -3998,10 +4001,22 @@ function extractMarkdownLinkSpans(source2, options = {}) {
       afterClose = void 0;
     }
     if (textOpen >= 0 && char === "]") {
-      afterClose = { open: textOpen, close: cursor };
+      const open7 = codeOpen >= 0 && masked[cursor] !== "]" ? codeOpen : textOpen;
+      afterClose = { open: open7, close: cursor };
       textOpen = -1;
+      codeOpen = -1;
+    }
+    if (char === "[") {
+      if (textOpen >= 0 && !options.skipCode) {
+        masked ??= maskMarkdownCode(source2);
+        if (masked[cursor] !== "[" && masked[textOpen] === "[") {
+          codeOpen = cursor;
+          continue;
+        }
+      }
+      textOpen = cursor;
+      codeOpen = -1;
     }
-    if (char === "[" && textOpen < 0) textOpen = cursor;
   }
   return out;
 }
@@ -6015,10 +6030,10 @@ function positiveOption(value, fallback, name) {
   }
   return resolved;
 }
-function isPrivateFilesystemMutationLockRoot(facts) {
-  const wrongOwner = facts.expectedUid !== void 0 && facts.ownerUid !== facts.expectedUid;
-  const unsafeMode = facts.enforcePrivateMode && (facts.mode & 511) !== 448;
-  return facts.directory && !facts.symbolicLink && !wrongOwner && !unsafeMode;
+function isPrivateFilesystemMutationLockRoot(facts2) {
+  const wrongOwner = facts2.expectedUid !== void 0 && facts2.ownerUid !== facts2.expectedUid;
+  const unsafeMode = facts2.enforcePrivateMode && (facts2.mode & 511) !== 448;
+  return facts2.directory && !facts2.symbolicLink && !wrongOwner && !unsafeMode;
 }
 async function ensurePrivateLockRoot(root, policy) {
   try {
@@ -6364,18 +6379,28 @@ var init_filesystem_lock = __esm({
   }
 });
 
+// ../core/src/path-fold.ts
+function foldPath(path81) {
+  return path81.normalize("NFD").toLowerCase().toUpperCase().toLowerCase().normalize("NFC");
+}
+var init_path_fold = __esm({
+  "../core/src/path-fold.ts"() {
+    "use strict";
+    init_define_SUPERBEE_BUILD_IDENTITY();
+    init_define_SUPERBEE_UPDATE_POLICY();
+  }
+});
+
 // ../core/src/identity-fold.ts
 function foldSegment(segment) {
-  return segment.normalize("NFKD").toLowerCase().toUpperCase().toLowerCase();
-}
-function foldIdentityPath(rel) {
-  return rel.split("/").map(foldSegment).join("/");
+  return foldPath(segment).normalize("NFD");
 }
 var init_identity_fold = __esm({
   "../core/src/identity-fold.ts"() {
     "use strict";
     init_define_SUPERBEE_BUILD_IDENTITY();
     init_define_SUPERBEE_UPDATE_POLICY();
+    init_path_fold();
   }
 });
 
@@ -6442,7 +6467,10 @@ async function existingAnchor(resolved) {
 async function foldedPhysicalRoot(root) {
   const { anchor: anchor2, tail } = await existingAnchor(path2.resolve(root));
   const anchorSegments = anchor2.split(path2.sep).filter((segment, index2) => index2 === 0 || segment !== "");
-  return [...anchorSegments, ...tail].map(foldSegment).join("/");
+  return [...anchorSegments, ...tail].map(foldRootSegment).join("/");
+}
+function foldRootSegment(segment) {
+  return segment.normalize("NFKD").toLowerCase().toUpperCase().toLowerCase();
 }
 async function identityKey(root, rel) {
   const foldedRel = relSegments(rel).map(foldSegment).join("/");
@@ -12320,6 +12348,145 @@ var init_uncertain_write = __esm({
   }
 });
 
+// ../core/src/bundle-health/legacy-page.ts
+function isLegacyPageDoc(frontmatter) {
+  return frontmatter["type"] === LEGACY_PAGE_TYPE_NAME;
+}
+var LEGACY_PAGE_TYPE_NAME, LEGACY_PAGE_MIGRATION_SCRIPT_URL, LEGACY_PAGE_MIGRATION_HELP;
+var init_legacy_page = __esm({
+  "../core/src/bundle-health/legacy-page.ts"() {
+    "use strict";
+    init_define_SUPERBEE_BUILD_IDENTITY();
+    init_define_SUPERBEE_UPDATE_POLICY();
+    LEGACY_PAGE_TYPE_NAME = "Page";
+    LEGACY_PAGE_MIGRATION_SCRIPT_URL = "https://github.com/Holaxis-ai/superbee/blob/v0.4.3/scripts/migrate-legacy-view-names.mjs";
+    LEGACY_PAGE_MIGRATION_HELP = "to migrate existing content in place, check out tag v0.4.3, run `npm ci && npm run build` there, then run `node scripts/migrate-legacy-view-names.mjs --dir <bundle-root>` from that checkout: " + LEGACY_PAGE_MIGRATION_SCRIPT_URL;
+  }
+});
+
+// ../core/src/page.ts
+function resolveBridgeCapability(value) {
+  return value === "bundle-read" || value === "bundle-propose" ? value : "none";
+}
+function declaredAccessValue(frontmatter) {
+  return Object.hasOwn(frontmatter, "access") ? frontmatter.access : void 0;
+}
+function resolveDeclaredAccess(frontmatter) {
+  return resolveBridgeCapability(declaredAccessValue(frontmatter));
+}
+function isPageTypeName(value) {
+  return value === "View";
+}
+function hasSafePageSegments(value, prefix) {
+  if (!value.startsWith(prefix) || value.length === prefix.length) return false;
+  if (value.startsWith("/") || /[\\%?#]/.test(value)) return false;
+  const segments = value.slice(prefix.length).split("/");
+  return segments.every(
+    (segment) => !segment.startsWith(".") && PAGE_SEGMENT.test(segment) && !segment.toLowerCase().endsWith(".md")
+  );
+}
+function isRegistryIdUnder(id, prefix) {
+  if (typeof id !== "string" || !hasSafePageSegments(id, prefix)) {
+    return false;
+  }
+  try {
+    assertSafeConceptId(id);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isEntryKeyUnder(entry, prefix) {
+  if (typeof entry !== "string" || !hasSafePageSegments(entry, prefix)) return false;
+  try {
+    assertSafeBlobKey(entry);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isPageRegistryId(id) {
+  return isRegistryIdUnder(id, PAGE_REGISTRY_PREFIX);
+}
+function isViewRegistryId(id) {
+  return isRegistryIdUnder(id, VIEW_REGISTRY_PREFIX);
+}
+function isAnyRegistryId(id) {
+  return isPageRegistryId(id) || isViewRegistryId(id);
+}
+function isPageEntryKey(entry) {
+  return isEntryKeyUnder(entry, PAGE_ENTRY_PREFIX);
+}
+function isViewEntryKey(entry) {
+  return isEntryKeyUnder(entry, VIEW_ENTRY_PREFIX);
+}
+function isAnyEntryKey(entry) {
+  return isPageEntryKey(entry) || isViewEntryKey(entry);
+}
+function isViewEntryVersion(value) {
+  return isContentVersion(value);
+}
+function parseRegistration(id, frontmatter) {
+  if (!isAnyRegistryId(id) || !isPageTypeName(frontmatter.type) || !isAnyEntryKey(frontmatter.entry)) return null;
+  const rawEntryVersion = Object.hasOwn(frontmatter, "entry_version") ? frontmatter.entry_version : void 0;
+  if (rawEntryVersion !== void 0 && !isViewEntryVersion(rawEntryVersion)) {
+    return null;
+  }
+  return {
+    id,
+    type: frontmatter.type,
+    entry: frontmatter.entry,
+    ...rawEntryVersion ? { entryVersion: rawEntryVersion } : {}
+  };
+}
+var PAGE_REGISTRY_PREFIX, PAGE_ENTRY_PREFIX, VIEW_REGISTRY_PREFIX, VIEW_ENTRY_PREFIX, PAGE_SEGMENT;
+var init_page = __esm({
+  "../core/src/page.ts"() {
+    "use strict";
+    init_define_SUPERBEE_BUILD_IDENTITY();
+    init_define_SUPERBEE_UPDATE_POLICY();
+    init_paths();
+    init_version_transport();
+    PAGE_REGISTRY_PREFIX = "pages-registry/";
+    PAGE_ENTRY_PREFIX = "pages/";
+    VIEW_REGISTRY_PREFIX = "views-registry/";
+    VIEW_ENTRY_PREFIX = "views/";
+    PAGE_SEGMENT = /^[A-Za-z0-9._-]+$/;
+  }
+});
+
+// ../core/src/system-documents.ts
+function typeOf(doc2) {
+  return typeof doc2.frontmatter.type === "string" ? doc2.frontmatter.type : "";
+}
+function isGraphDefinitionDocument(doc2) {
+  const type = typeOf(doc2);
+  return type === CONVENTION_TYPE || isPageTypeName(type) || isLegacyPageDoc(doc2.frontmatter) || type === "Reference" && doc2.id.startsWith("references/") || type === BUNDLE_NAME_DOC_TYPE && doc2.id === BUNDLE_NAME_DOC_ID || type === DEPENDENCIES_DOC_TYPE && doc2.id === DEPENDENCIES_DOC_ID;
+}
+function isSystemDocument(doc2) {
+  return isGraphDefinitionDocument(doc2) || OWNED_INSTANCE_TYPES.has(typeOf(doc2));
+}
+var OWNED_INSTANCE_TYPES, OWNED_INSTANCE_TYPE_NAMES;
+var init_system_documents = __esm({
+  "../core/src/system-documents.ts"() {
+    "use strict";
+    init_define_SUPERBEE_BUILD_IDENTITY();
+    init_define_SUPERBEE_UPDATE_POLICY();
+    init_legacy_page();
+    init_dependencies();
+    init_kinds();
+    init_page();
+    OWNED_INSTANCE_TYPES = /* @__PURE__ */ new Set([
+      "Connector",
+      "Site",
+      "Promotion",
+      // An OKF standard type, validated by `okf-standard-fields.ts`.
+      "Attested Computation"
+    ]);
+    OWNED_INSTANCE_TYPE_NAMES = [...OWNED_INSTANCE_TYPES];
+  }
+});
+
 // ../core/src/kind-undeclared-fields.ts
 function isKindEnvelopeField(key4) {
   return isOkfStandardField(key4) || isManagedDocumentMetadataField(key4) || key4.startsWith("superbee_") && key4 !== SUPERBEE_PROGRESS_STATUS_FIELD;
@@ -12340,9 +12507,51 @@ function undeclaredFieldWarnings(okfVersion, kind2, candidate, existing) {
   const list6 = declared.length > 0 ? declared.join(", ") : "none";
   const progress = progressStatusCoordinate(okfVersion, kind2);
   const message = (key4) => progress && key4 === progress.logicalField && key4 !== progress.storageField ? `'${key4}' is the field name, not its stored key in this bundle; write it in frontmatter as '${progress.storageField}'.` : `'${key4}' is not declared by kind '${kind2.governs}' (declared: ${list6}).`;
-  return undeclaredFrontmatterKeys(okfVersion, kind2, candidate).filter((key4) => !existing || !Object.hasOwn(existing, key4) || !okfValuesEqual(existing[key4], candidate[key4])).sort().map((key4) => ({ code: KIND_FIELD_UNDECLARED, message: message(key4), field: key4, severity: "warning" }));
+  return undeclaredFrontmatterKeys(okfVersion, kind2, candidate).filter((key4) => !existing || !Object.hasOwn(existing, key4) || !okfValuesEqual(existing[key4], candidate[key4])).sort().map((key4) => ({
+    code: KIND_FIELD_UNDECLARED,
+    message: message(key4),
+    field: key4,
+    severity: "warning",
+    details: { kind: kind2.governs, fields: [key4], declared: [...declared] }
+  }));
+}
+function unknownKindFieldNames(okfVersion, kind2, fields2) {
+  return [...fields2].filter((field) => resolveKindFieldCoordinate(okfVersion, kind2, field) === void 0);
+}
+function kindFieldsUndeclaredFinding(okfVersion, kind2, fields2) {
+  if (fields2.length === 0) return void 0;
+  return {
+    code: KIND_FIELD_UNDECLARED,
+    message: "The document's Kind does not declare one or more of the named fields.",
+    ...fields2.length === 1 ? { field: fields2[0] } : {},
+    severity: "warning",
+    details: { kind: kind2.governs, fields: [...fields2], declared: kindDeclaredFieldNames(okfVersion, kind2) }
+  };
+}
+function typeKey(type) {
+  return type.replace(/[\s_-]+/g, "").toLowerCase();
+}
+function undeclaredTypeFinding(registry2, doc2) {
+  const type = doc2.frontmatter.type;
+  if (typeof type !== "string" || type.trim() === "" || registry2.kinds.size === 0) return void 0;
+  if (registry2.kinds.has(type) || isSystemDocument(doc2)) return void 0;
+  const declaredTypes = [...registry2.kinds.keys()].sort();
+  const suggestedType = declaredTypes.find((declared) => typeKey(declared) === typeKey(type));
+  return suggestedType === void 0 ? {
+    code: KIND_TYPE_UNDECLARED,
+    message: "No Kind in this bundle governs this document's type, so the document is not checked against a Kind.",
+    field: "type",
+    severity: "info",
+    details: { type, declaredTypes }
+  } : {
+    code: KIND_TYPE_UNDECLARED,
+    message: "No Kind governs this document's type, but a declared type differs from it only in case or spacing.",
+    field: "type",
+    severity: "warning",
+    details: { type, declaredTypes, suggestedType }
+  };
 }
-var KIND_FIELD_UNDECLARED;
+var KIND_FIELD_UNDECLARED, KIND_TYPE_UNDECLARED;
 var init_kind_undeclared_fields = __esm({
   "../core/src/kind-undeclared-fields.ts"() {
     "use strict";
@@ -12351,8 +12560,10 @@ var init_kind_undeclared_fields = __esm({
     init_managed_document_metadata();
     init_okf_authored_values();
     init_okf_standard_fields();
+    init_system_documents();
     init_kinds();
     KIND_FIELD_UNDECLARED = "KIND_FIELD_UNDECLARED";
+    KIND_TYPE_UNDECLARED = "KIND_TYPE_UNDECLARED";
   }
 });
 
@@ -13203,7 +13414,7 @@ async function readSource(binding2) {
   const docs = new Map(results.map((result3) => [result3.doc.id, result3]));
   const ids = /* @__PURE__ */ new Set([...docs.keys(), ...malformed6.keys()]);
   const dependencies = parseDependencies(docs.get(DEPENDENCIES_DOC_ID)?.doc ?? null, { selfBundleId: binding2.identity });
-  const folds = new Set([...ids].map(foldIdentityPath));
+  const folds = new Set([...ids].map(foldPath));
   return { ids, folds, docs, malformed: malformed6, dependencies, registry: await loadKinds(bundle), bundle };
 }
 async function readTarget(target3) {
@@ -13278,7 +13489,7 @@ function planLink(ctx, sourceId, targetId, span, conflicts) {
   const resolved = resolveConceptId(sourceId, pathPart);
   if (resolved === null) return keep("non_document");
   const present = ctx.source.ids.has(resolved);
-  if (!present && ctx.source.folds.has(foldIdentityPath(resolved))) return keep("case_variant", { source_target: resolved });
+  if (!present && ctx.source.folds.has(foldPath(resolved))) return keep("case_variant", { source_target: resolved });
   const withFragment = fragment === void 0 ? {} : { fragment };
   const mapped = ctx.mapping.get(resolved);
   if (mapped !== void 0) {
@@ -13364,18 +13575,18 @@ function assertImportableTargetId(id, newTarget) {
   assertSafeConceptId(id);
   if (newTarget) assertCanonicalNewDocumentId(id, newTarget.exists);
   if (isReservedFile(pathFromConceptId(id))) throw new InvalidInputError("index.md and log.md are reserved files, not documents");
-  const fold2 = foldIdentityPath(id);
+  const fold2 = foldPath(id);
   if (PROTECTED_TARGET_FOLDS.has(fold2)) throw new InvalidInputError("it is the bundle's own identity or dependency declaration");
   if (fold2.startsWith(CONVENTIONS_FOLD)) throw new InvalidInputError("an import never installs a Kind convention");
 }
 function checkTargetIds(planned, existing, conflicts) {
   const folds = /* @__PURE__ */ new Map();
   const remember = (id) => {
-    const keys2 = [[`${foldIdentityPath(id)}.md`, `${id}.md`]];
+    const keys2 = [[`${foldPath(id)}.md`, `${id}.md`]];
     const segments = id.split("/");
     for (let i = 1; i < segments.length; i++) {
       const dir = segments.slice(0, i).join("/");
-      keys2.push([`${foldIdentityPath(dir)}/`, `${dir}/`]);
+      keys2.push([`${foldPath(dir)}/`, `${dir}/`]);
     }
     return keys2;
   };
@@ -14251,7 +14462,7 @@ var init_document_transfer = __esm({
     init_document_mutation();
     init_engine();
     init_errors();
-    init_identity_fold();
+    init_path_fold();
     init_kinds_load();
     init_kinds();
     init_link_emit();
@@ -14319,8 +14530,8 @@ var init_document_transfer = __esm({
     SOURCE_SELF_DOCS = /* @__PURE__ */ new Set([BUNDLE_NAME_DOC_ID, DEPENDENCIES_DOC_ID]);
     ANY_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
     REFERENCE_DEFINITION = /^ {0,3}\[[^\]\n]+\]:[ \t]*<?([^\s>]+)/gm;
-    PROTECTED_TARGET_FOLDS = new Set([BUNDLE_NAME_DOC_ID, DEPENDENCIES_DOC_ID].map(foldIdentityPath));
-    CONVENTIONS_FOLD = `${foldIdentityPath(CONVENTIONS_PREFIX.replace(/\/$/, ""))}/`;
+    PROTECTED_TARGET_FOLDS = new Set([BUNDLE_NAME_DOC_ID, DEPENDENCIES_DOC_ID].map(foldPath));
+    CONVENTIONS_FOLD = `${foldPath(CONVENTIONS_PREFIX.replace(/\/$/, ""))}/`;
     DOCUMENT_REFRESH_TOKEN_PREFIX = `${DOCUMENT_TRANSFER_CONTRACT}:refresh`;
   }
 });
@@ -14346,6 +14557,13 @@ function localEdgeQualifiedDeclaration(declared, sourceType) {
   const matched = declarationFor(declared, sourceType);
   return parseQualifiedKindTarget(matched.target) === null ? null : matched;
 }
+function localEdgeViolation(declared, sourceType, targetType) {
+  if (!declared || declared.length === 0) return null;
+  const matched = declarationFor(declared, sourceType);
+  const sourceOk = declared.some((d) => d.governs === sourceType);
+  const targetOk = targetType === void 0 || targetType === matched.target;
+  return sourceOk && targetOk ? null : matched;
+}
 function qualifiedEdgeViolation(declared, sourceType, alias, actualTargetType) {
   if (!declared || declared.length === 0) return null;
   const matched = declarationFor(declared, sourceType);
@@ -14363,6 +14581,222 @@ var init_link_types = __esm({
   }
 });
 
+// ../core/src/link-findings.ts
+function docType(doc2) {
+  return typeof doc2?.frontmatter.type === "string" ? doc2.frontmatter.type : "";
+}
+function hrefPath(href) {
+  return (href.split("#")[0] ?? "").split("?")[0]?.trim() ?? "";
+}
+function suggestion(fromId, href) {
+  if (UNREGISTRABLE.test(href)) return {};
+  const suggestedTo = resolveConceptId(fromId, href);
+  if (suggestedTo === null) return {};
+  if (!href.startsWith("/")) {
+    const slash = fromId.lastIndexOf("/");
+    const fromDir = slash >= 0 ? fromId.slice(0, slash) : "";
+    if (normalizeSegments([...fromDir.split("/"), ...hrefPath(href).split("/")])[0] === "..") {
+      return { suggestedHref: `/${suggestedTo}.md`, suggestedTo };
+    }
+  }
+  return { suggestedHref: href, suggestedTo };
+}
+function isBareRelative(path81) {
+  return !path81.startsWith("/") && !path81.startsWith("./") && !path81.startsWith("../");
+}
+function notRecognized(reason, fields2) {
+  return {
+    code: LINK_NOT_RECOGNIZED,
+    message: NOT_RECOGNIZED_MESSAGES[reason],
+    field: "body",
+    severity: "warning",
+    details: { reason, ...fields2 }
+  };
+}
+function classifyUnresolved(fromId, text7, href, at) {
+  if (isQualifiedHref(href)) return void 0;
+  const path81 = hrefPath(href);
+  if (path81 === "" || isExternalHref(path81) || ANY_SCHEME2.test(path81)) return void 0;
+  if (path81.endsWith(".md")) {
+    const resolved = path81.startsWith("/") ? path81.slice(1) : path81;
+    return notRecognized(isReservedFile(resolved.replace(/^(\.\.?\/)+/, "")) ? "reserved-target" : "invalid-target", { text: text7, href, ...at });
+  }
+  const last = path81.slice(path81.lastIndexOf("/") + 1);
+  if (last === "" || last.includes(".")) return void 0;
+  return notRecognized("missing-md-extension", { text: text7, href, ...at, ...suggestion(fromId, `${path81}.md`) });
+}
+function wikilinkFindings(doc2) {
+  const masked = maskMarkdownCode(doc2.body);
+  const out = [];
+  for (const match of masked.matchAll(WIKILINK)) {
+    const start = match.index;
+    const end = start + match[0].length;
+    const inner = doc2.body.slice(start + 2, end - 2);
+    const bar = inner.indexOf("|");
+    const target3 = (bar >= 0 ? inner.slice(0, bar) : inner).trim();
+    const text7 = (bar >= 0 ? inner.slice(bar + 1) : inner).trim();
+    const path81 = hrefPath(target3).replace(/^\/+/, "");
+    out.push(notRecognized("wikilink", {
+      text: text7,
+      href: target3,
+      start,
+      end,
+      ...path81 === "" ? {} : suggestion(doc2.id, `/${path81.endsWith(".md") ? path81 : `${path81}.md`}`)
+    }));
+  }
+  return out;
+}
+function inspectDocumentLinks(doc2) {
+  const links = [];
+  const findings = [];
+  const outsideCode = new Set(extractMarkdownLinkSpans(doc2.body, { skipCode: true }).map((span) => span.start));
+  for (const span of extractMarkdownLinkSpans(doc2.body)) {
+    if (span.image) continue;
+    const to = resolveConceptId(doc2.id, span.href);
+    if (to !== null) {
+      links.push({ from: doc2.id, to, text: span.text, href: span.href });
+      continue;
+    }
+    if (!outsideCode.has(span.start)) continue;
+    const finding = classifyUnresolved(doc2.id, span.text, span.href, { start: span.start, end: span.end });
+    if (finding) findings.push(finding);
+  }
+  findings.push(...wikilinkFindings(doc2));
+  findings.sort((a, b) => (a.details.start ?? 0) - (b.details.start ?? 0));
+  return { links, findings };
+}
+async function linkTargetAbsentFinding(link4, readTarget2) {
+  if (await readTarget2(link4.to) !== void 0) return void 0;
+  return { code: LINK_TARGET_ABSENT, message: TARGET_ABSENT_MESSAGE, field: "body", severity: "warning", details: { ...link4 } };
+}
+async function typeFinding(declarations, link4, readTarget2) {
+  if (declarations.size === 0) return void 0;
+  const { sourceType, ...where } = link4;
+  const exact = declarations.get(link4.text);
+  if (exact && exact.length > 0) {
+    const target3 = await readTarget2(link4.to);
+    const targetType = target3 === void 0 ? null : docType(target3);
+    const qualified = localEdgeQualifiedDeclaration(exact, sourceType);
+    if (qualified) {
+      return {
+        code: LINK_TYPE_VIOLATION,
+        message: TYPE_QUALIFIED_MESSAGE,
+        field: "body",
+        severity: "warning",
+        details: {
+          ...where,
+          declaredBy: qualified.governs,
+          declaredTarget: qualified.target,
+          sourceType,
+          targetType,
+          targetAlias: parseQualifiedKindTarget(qualified.target).alias
+        }
+      };
+    }
+    const violated = localEdgeViolation(exact, sourceType, targetType ?? void 0);
+    if (!violated) return void 0;
+    return {
+      code: LINK_TYPE_VIOLATION,
+      message: TYPE_VIOLATION_MESSAGE,
+      field: "body",
+      severity: "warning",
+      details: { ...where, declaredBy: violated.governs, declaredTarget: violated.target, sourceType, targetType }
+    };
+  }
+  const lower = link4.text.toLowerCase();
+  for (const declaredText of declarations.keys()) {
+    if (declaredText.toLowerCase() === lower) {
+      return {
+        code: LINK_TYPE_CASE_VARIANT,
+        message: TYPE_CASE_VARIANT_MESSAGE,
+        field: "body",
+        severity: "warning",
+        details: { ...where, declaredText }
+      };
+    }
+  }
+  return void 0;
+}
+function linkTypeFinding(registry2, link4, readTarget2) {
+  return typeFinding(collectLinkDeclarations(registry2), link4, readTarget2);
+}
+async function documentLinkReport(doc2, opts) {
+  const { links, findings } = inspectDocumentLinks(doc2);
+  const cache = /* @__PURE__ */ new Map();
+  const read = (id) => {
+    let pending = cache.get(id);
+    if (!pending) {
+      pending = opts.readTarget(id);
+      cache.set(id, pending);
+    }
+    return pending;
+  };
+  const exists3 = async (id) => await read(id) !== void 0;
+  const rootReading = (path81) => isBareRelative(path81) ? resolveConceptId(doc2.id, `/${path81}`) : null;
+  for (const finding of findings) {
+    if (finding.code !== LINK_NOT_RECOGNIZED || finding.details.reason !== "missing-md-extension") continue;
+    const relative2 = finding.details.suggestedTo;
+    if (relative2 !== void 0 && await exists3(relative2)) continue;
+    const path81 = `${hrefPath(finding.details.href)}.md`;
+    const root = rootReading(path81);
+    if (root !== null && root !== relative2 && !UNREGISTRABLE.test(path81) && await exists3(root)) {
+      finding.details.suggestedHref = `/${path81}`;
+      finding.details.suggestedTo = root;
+    }
+  }
+  const declarations = opts.registry ? collectLinkDeclarations(opts.registry) : /* @__PURE__ */ new Map();
+  const sourceType = docType(doc2);
+  const spans = extractMarkdownLinkSpans(doc2.body).filter((span) => !span.image && resolveConceptId(doc2.id, span.href) !== null);
+  for (const [index2, link4] of links.entries()) {
+    if (isQualifiedHref(link4.href)) continue;
+    const span = spans[index2];
+    const where = { start: span.start, end: span.end };
+    const absent = await linkTargetAbsentFinding({ to: link4.to, href: link4.href, text: link4.text, ...where }, read);
+    if (absent) {
+      const path81 = hrefPath(link4.href);
+      const root = rootReading(path81);
+      if (root !== null && root !== link4.to && await exists3(root)) {
+        absent.details.suggestedHref = `/${path81}`;
+        absent.details.suggestedTo = root;
+      }
+      findings.push(absent);
+    }
+    const typed = await typeFinding(declarations, { sourceType, text: link4.text, to: link4.to, ...where }, read);
+    if (typed) findings.push(typed);
+  }
+  findings.sort((a, b) => (a.details.start ?? 0) - (b.details.start ?? 0));
+  return { links, findings };
+}
+var LINK_NOT_RECOGNIZED, LINK_TARGET_ABSENT, LINK_TYPE_VIOLATION, LINK_TYPE_CASE_VARIANT, NOT_RECOGNIZED_MESSAGES, TARGET_ABSENT_MESSAGE, TYPE_VIOLATION_MESSAGE, TYPE_QUALIFIED_MESSAGE, TYPE_CASE_VARIANT_MESSAGE, WIKILINK, ANY_SCHEME2, UNREGISTRABLE;
+var init_link_findings = __esm({
+  "../core/src/link-findings.ts"() {
+    "use strict";
+    init_define_SUPERBEE_BUILD_IDENTITY();
+    init_define_SUPERBEE_UPDATE_POLICY();
+    init_link_types();
+    init_links();
+    init_paths();
+    init_qualified_links();
+    LINK_NOT_RECOGNIZED = "LINK_NOT_RECOGNIZED";
+    LINK_TARGET_ABSENT = "LINK_TARGET_ABSENT";
+    LINK_TYPE_VIOLATION = "LINK_TYPE_VIOLATION";
+    LINK_TYPE_CASE_VARIANT = "LINK_TYPE_CASE_VARIANT";
+    NOT_RECOGNIZED_MESSAGES = {
+      wikilink: "A [[wikilink]] is plain text, not a link; write a markdown link whose target ends in .md.",
+      "missing-md-extension": "This link's target does not end in .md, so it is not a link to a document.",
+      "reserved-target": "This link's target is a reserved file (index.md or log.md), which is never a document.",
+      "invalid-target": "This link's target is not a valid document id, so it is not a link to a document."
+    };
+    TARGET_ABSENT_MESSAGE = "No document exists at this link's target yet; the link is kept as a forward declaration.";
+    TYPE_VIOLATION_MESSAGE = "This link's text is a declared link type, but its source or target is not the declared kind.";
+    TYPE_QUALIFIED_MESSAGE = "This link's text is declared as a link into another bundle, but it points inside this bundle.";
+    TYPE_CASE_VARIANT_MESSAGE = "This link's text differs only in case from a declared link type.";
+    WIKILINK = /\[\[([^[\]\n]+)\]\]/g;
+    ANY_SCHEME2 = /^[a-z][a-z0-9+.-]*:/i;
+    UNREGISTRABLE = /[\s()<>[\]]/;
+  }
+});
+
 // ../core/src/cross-bundle.ts
 function isRecordReason(reason) {
   return RECORD_REASONS.includes(reason);
@@ -14538,18 +14972,6 @@ var init_code_point_order = __esm({
   }
 });
 
-// ../core/src/path-fold.ts
-function foldPath(path81) {
-  return path81.normalize("NFC").toLowerCase().toUpperCase().toLowerCase().normalize("NFC");
-}
-var init_path_fold = __esm({
-  "../core/src/path-fold.ts"() {
-    "use strict";
-    init_define_SUPERBEE_BUILD_IDENTITY();
-    init_define_SUPERBEE_UPDATE_POLICY();
-  }
-});
-
 // ../core/src/governed-body-write.ts
 function fail2(message) {
   throw new Error(`Invalid body delivery: ${message}`);
@@ -15036,8 +15458,13 @@ __export(src_exports, {
   KIND_FIELD_TYPES: () => KIND_FIELD_TYPES,
   KIND_FIELD_TYPE_DESCRIPTIONS: () => KIND_FIELD_TYPE_DESCRIPTIONS,
   KIND_FIELD_UNDECLARED: () => KIND_FIELD_UNDECLARED,
+  KIND_TYPE_UNDECLARED: () => KIND_TYPE_UNDECLARED,
   KindConformanceError: () => KindConformanceError,
   KindFieldMutationConflict: () => KindFieldMutationConflict,
+  LINK_NOT_RECOGNIZED: () => LINK_NOT_RECOGNIZED,
+  LINK_TARGET_ABSENT: () => LINK_TARGET_ABSENT,
+  LINK_TYPE_CASE_VARIANT: () => LINK_TYPE_CASE_VARIANT,
+  LINK_TYPE_VIOLATION: () => LINK_TYPE_VIOLATION,
   MALFORMED_ANSWER: () => MALFORMED_ANSWER,
   MalformedAnswer: () => MalformedAnswer,
   MalformedDocumentError: () => MalformedDocumentError,
@@ -15114,6 +15541,7 @@ __export(src_exports, {
   deleteBlob: () => deleteBlob2,
   deleteDoc: () => deleteDoc2,
   docVersions: () => docVersions2,
+  documentLinkReport: () => documentLinkReport,
   droppedLinks: () => droppedLinks,
   emitLinkHref: () => emitLinkHref,
   escapeHostJson: () => escapeHostJson,
@@ -15134,6 +15562,7 @@ __export(src_exports, {
   inferContentTypeForNewBlob: () => inferContentTypeForNewBlob,
   inferContentTypeFromDocKey: () => inferContentTypeFromDocKey,
   initBundle: () => initBundle,
+  inspectDocumentLinks: () => inspectDocumentLinks,
   inspectKindDeprecatedUsage: () => inspectKindDeprecatedUsage,
   invalidLegacyTimestamp: () => invalidLegacyTimestamp,
   invalidOkfTimestamps: () => invalidOkfTimestamps,
@@ -15142,6 +15571,7 @@ __export(src_exports, {
   isContentVersion: () => isContentVersion,
   isConventionId: () => isConventionId,
   isExternalHref: () => isExternalHref,
+  isGraphDefinitionDocument: () => isGraphDefinitionDocument,
   isHeadsDigest: () => isHeadsDigest,
   isHostedBundleId: () => isHostedBundleId,
   isHumanActor: () => isHumanActor,
@@ -15161,6 +15591,7 @@ __export(src_exports, {
   isRecordReason: () => isRecordReason,
   isReservedFile: () => isReservedFile,
   isStandardDocumentSetField: () => isStandardDocumentSetField,
+  isSystemDocument: () => isSystemDocument,
   isTerminal: () => isTerminal,
   isUsableTimestamp: () => isUsableTimestamp,
   kindConventionDoc: () => kindConventionDoc,
@@ -15171,14 +15602,18 @@ __export(src_exports, {
   kindDeprecationTransition: () => kindDeprecationTransition,
   kindFieldInputValue: () => kindFieldInputValue,
   kindFieldTypeProblem: () => kindFieldTypeProblem,
+  kindFieldsUndeclaredFinding: () => kindFieldsUndeclaredFinding,
   kindInputFieldNames: () => kindInputFieldNames,
   kindValueGuidance: () => kindValueGuidance,
   latestVerifiedAt: () => latestVerifiedAt,
+  linkTargetAbsentFinding: () => linkTargetAbsentFinding,
+  linkTypeFinding: () => linkTypeFinding,
   list: () => list,
   listBlobs: () => listBlobs2,
   loadBoundedYaml: () => loadBoundedYaml,
   loadKinds: () => loadKinds,
   localEdgeQualifiedDeclaration: () => localEdgeQualifiedDeclaration,
+  localEdgeViolation: () => localEdgeViolation,
   matchesFilter: () => matchesFilter,
   matchesSourceIdentity: () => matchesSourceIdentity,
   mutateDocument: () => mutateDocument,
@@ -15252,6 +15687,8 @@ __export(src_exports, {
   trustTierCounts: () => trustTierCounts,
   undeclaredFieldWarnings: () => undeclaredFieldWarnings,
   undeclaredFrontmatterKeys: () => undeclaredFrontmatterKeys,
+  undeclaredTypeFinding: () => undeclaredTypeFinding,
+  unknownKindFieldNames: () => unknownKindFieldNames,
   validateAgainstKind: () => validateAgainstKind,
   validateBodyReceipt: () => validateBodyReceipt,
   validatePreparedBodyDelivery: () => validatePreparedBodyDelivery,
@@ -15302,6 +15739,7 @@ var init_src = __esm({
     init_document_transfer();
     init_qualified_links();
     init_link_types();
+    init_link_findings();
     init_dependencies();
     init_cross_bundle();
     init_freshness();
@@ -15327,6 +15765,7 @@ var init_src = __esm({
     init_managed_document_metadata();
     init_kind_coverage();
     init_kind_undeclared_fields();
+    init_system_documents();
     init_body_pages();
     init_body_replace_guards();
     init_kind_deprecation();
@@ -18448,22 +18887,6 @@ var init_nofollow_read = __esm({
   }
 });
 
-// ../core/src/bundle-health/legacy-page.ts
-function isLegacyPageDoc(frontmatter) {
-  return frontmatter["type"] === LEGACY_PAGE_TYPE_NAME;
-}
-var LEGACY_PAGE_TYPE_NAME, LEGACY_PAGE_MIGRATION_SCRIPT_URL, LEGACY_PAGE_MIGRATION_HELP;
-var init_legacy_page = __esm({
-  "../core/src/bundle-health/legacy-page.ts"() {
-    "use strict";
-    init_define_SUPERBEE_BUILD_IDENTITY();
-    init_define_SUPERBEE_UPDATE_POLICY();
-    LEGACY_PAGE_TYPE_NAME = "Page";
-    LEGACY_PAGE_MIGRATION_SCRIPT_URL = "https://github.com/Holaxis-ai/superbee/blob/v0.4.3/scripts/migrate-legacy-view-names.mjs";
-    LEGACY_PAGE_MIGRATION_HELP = "to migrate existing content in place, check out tag v0.4.3, run `npm ci && npm run build` there, then run `node scripts/migrate-legacy-view-names.mjs --dir <bundle-root>` from that checkout: " + LEGACY_PAGE_MIGRATION_SCRIPT_URL;
-  }
-});
-
 // ../../node_modules/graphql/jsutils/devAssert.mjs
 function devAssert(condition, message) {
   if (!condition) {
@@ -22575,97 +22998,6 @@ var init_connectors = __esm({
   }
 });
 
-// ../core/src/page.ts
-function resolveBridgeCapability(value) {
-  return value === "bundle-read" || value === "bundle-propose" ? value : "none";
-}
-function declaredAccessValue(frontmatter) {
-  return Object.hasOwn(frontmatter, "access") ? frontmatter.access : void 0;
-}
-function resolveDeclaredAccess(frontmatter) {
-  return resolveBridgeCapability(declaredAccessValue(frontmatter));
-}
-function isPageTypeName(value) {
-  return value === "View";
-}
-function hasSafePageSegments(value, prefix) {
-  if (!value.startsWith(prefix) || value.length === prefix.length) return false;
-  if (value.startsWith("/") || /[\\%?#]/.test(value)) return false;
-  const segments = value.slice(prefix.length).split("/");
-  return segments.every(
-    (segment) => !segment.startsWith(".") && PAGE_SEGMENT.test(segment) && !segment.toLowerCase().endsWith(".md")
-  );
-}
-function isRegistryIdUnder(id, prefix) {
-  if (typeof id !== "string" || !hasSafePageSegments(id, prefix)) {
-    return false;
-  }
-  try {
-    assertSafeConceptId(id);
-    return true;
-  } catch {
-    return false;
-  }
-}
-function isEntryKeyUnder(entry, prefix) {
-  if (typeof entry !== "string" || !hasSafePageSegments(entry, prefix)) return false;
-  try {
-    assertSafeBlobKey(entry);
-    return true;
-  } catch {
-    return false;
-  }
-}
-function isPageRegistryId(id) {
-  return isRegistryIdUnder(id, PAGE_REGISTRY_PREFIX);
-}
-function isViewRegistryId(id) {
-  return isRegistryIdUnder(id, VIEW_REGISTRY_PREFIX);
-}
-function isAnyRegistryId(id) {
-  return isPageRegistryId(id) || isViewRegistryId(id);
-}
-function isPageEntryKey(entry) {
-  return isEntryKeyUnder(entry, PAGE_ENTRY_PREFIX);
-}
-function isViewEntryKey(entry) {
-  return isEntryKeyUnder(entry, VIEW_ENTRY_PREFIX);
-}
-function isAnyEntryKey(entry) {
-  return isPageEntryKey(entry) || isViewEntryKey(entry);
-}
-function isViewEntryVersion(value) {
-  return isContentVersion(value);
-}
-function parseRegistration(id, frontmatter) {
-  if (!isAnyRegistryId(id) || !isPageTypeName(frontmatter.type) || !isAnyEntryKey(frontmatter.entry)) return null;
-  const rawEntryVersion = Object.hasOwn(frontmatter, "entry_version") ? frontmatter.entry_version : void 0;
-  if (rawEntryVersion !== void 0 && !isViewEntryVersion(rawEntryVersion)) {
-    return null;
-  }
-  return {
-    id,
-    type: frontmatter.type,
-    entry: frontmatter.entry,
-    ...rawEntryVersion ? { entryVersion: rawEntryVersion } : {}
-  };
-}
-var PAGE_REGISTRY_PREFIX, PAGE_ENTRY_PREFIX, VIEW_REGISTRY_PREFIX, VIEW_ENTRY_PREFIX, PAGE_SEGMENT;
-var init_page = __esm({
-  "../core/src/page.ts"() {
-    "use strict";
-    init_define_SUPERBEE_BUILD_IDENTITY();
-    init_define_SUPERBEE_UPDATE_POLICY();
-    init_paths();
-    init_version_transport();
-    PAGE_REGISTRY_PREFIX = "pages-registry/";
-    PAGE_ENTRY_PREFIX = "pages/";
-    VIEW_REGISTRY_PREFIX = "views-registry/";
-    VIEW_ENTRY_PREFIX = "views/";
-    PAGE_SEGMENT = /^[A-Za-z0-9._-]+$/;
-  }
-});
-
 // ../core/src/recipes.ts
 function nonEmptyString2(v) {
   return typeof v === "string" ? v.trim() : "";
@@ -24258,7 +24590,7 @@ function linkTypeAdditionBlockers(docs, addedTexts, currentRegistry, registry2,
   const declarations = collectLinkDeclarations(registry2);
   const currentDeclarations = collectLinkDeclarations(currentRegistry);
   const docsById = new Map(docs.map((doc2) => [doc2.id, doc2]));
-  const docType3 = (doc2) => typeof doc2.frontmatter.type === "string" ? doc2.frontmatter.type : "";
+  const docType4 = (doc2) => typeof doc2.frontmatter.type === "string" ? doc2.frontmatter.type : "";
   const checked = [];
   for (const doc2 of docs) {
     let carries = false;
@@ -24267,11 +24599,11 @@ function linkTypeAdditionBlockers(docs, addedTexts, currentRegistry, registry2,
       carries = true;
       const target3 = docsById.get(link4.to);
       if (!target3) continue;
-      const sourceType = docType3(doc2);
+      const sourceType = docType4(doc2);
       const violates = (declared) => {
         if (declared.length === 0) return null;
         const matched = declared.find((declaration) => declaration.governs === sourceType);
-        return matched && docType3(target3) === matched.target ? null : matched ?? declared[0];
+        return matched && docType4(target3) === matched.target ? null : matched ?? declared[0];
       };
       const expected = violates(declarations.get(link4.text) ?? []);
       if (!expected) continue;
@@ -24280,7 +24612,7 @@ function linkTypeAdditionBlockers(docs, addedTexts, currentRegistry, registry2,
         blockers,
         "RECIPE_EVOLUTION_INSTANCE_INVALID",
         doc2.id,
-        `declaring link type '${link4.text}' would make the edge to '${link4.to}' a violation (expected ${expected.governs} -> ${expected.target}, found ${sourceType || "untyped"} -> ${docType3(target3) || "untyped"})`,
+        `declaring link type '${link4.text}' would make the edge to '${link4.to}' a violation (expected ${expected.governs} -> ${expected.target}, found ${sourceType || "untyped"} -> ${docType4(target3) || "untyped"})`,
         `links.${link4.text}`
       );
     }
@@ -26063,15 +26395,15 @@ var init_recipe_lifecycle = __esm({
 
 // ../cli/src/actor-guidance.ts
 function actorRefusal(actor, options = {}) {
-  const suggestion = suggestOkfActor(actor);
-  let options_ = [suggestion.primary, ...suggestion.alternatives];
+  const suggestion2 = suggestOkfActor(actor);
+  let options_ = [suggestion2.primary, ...suggestion2.alternatives];
   if (options.preferHuman) {
     const human = options_.find((candidate) => candidate.startsWith("human:"));
     if (human) options_ = [human, ...options_.filter((candidate) => candidate !== human)];
   }
   const spelled = options_.length > 1 ? `${options_.slice(0, -1).join(", ")} or ${options_[options_.length - 1]}` : options_[0];
   const message = `actor '${actor}' is not an OKF actor, so this v0.2 bundle refuses to record it as provenance. Use ${spelled} \u2014 ${OKF_ACTOR_FORMS}.`;
-  if (suggestion.placeholder) {
+  if (suggestion2.placeholder) {
     return {
       message,
       help: `rerun with --actor ${commandLiteral("<actor>")} in one of those forms, or set it once: export SUPERBEE_ACTOR=${commandLiteral("<actor>")}`
@@ -28631,22 +28963,51 @@ function definitionFindingsText(details) {
   }
   return more && text7 !== "" ? `${text7}; and more` : text7;
 }
+function listOf(value, item) {
+  if (!Array.isArray(value)) return void 0;
+  const items = value.flatMap((entry) => {
+    const read = isRecord8(entry) ? item(entry) : void 0;
+    return read === void 0 ? [] : [read];
+  });
+  return items;
+}
+function writeLinks(value) {
+  if (!isRecord8(value) || !Number.isSafeInteger(value.count) || value.count < 0 || !Array.isArray(value.targets) || !value.targets.every(isText)) return void 0;
+  if (value.truncated !== void 0 && typeof value.truncated !== "boolean") return void 0;
+  return { count: value.count, targets: [...value.targets], ...value.truncated !== void 0 ? { truncated: value.truncated } : {} };
+}
+function writeReport(data) {
+  const links = writeLinks(data.links);
+  const warnings = listOf(data.warnings, writeWarning);
+  const guidance = listOf(data.guidance, writeGuidance2);
+  return { ...links ? { links } : {}, ...warnings?.length ? { warnings } : {}, ...guidance?.length ? { guidance } : {} };
+}
 function parseWriteResult(raw, expected) {
   const refuse3 = () => new HostedAnswerError("the write result envelope is not one the client admits");
-  if (!isRecord8(raw) || !onlyKeys2(raw, ["ok", "operationId", "data", "error"]) || typeof raw.operationId !== "string" || !expected.operationIds.includes(raw.operationId)) throw refuse3();
+  if (!isRecord8(raw) || typeof raw.operationId !== "string" || !expected.operationIds.includes(raw.operationId)) throw refuse3();
   const { operationId } = raw;
   if (raw.ok === true) {
     const data = raw.data;
     const deletion = operationId === DELETE_OPERATION_ID;
-    if (raw.error !== void 0 || !isRecord8(data) || !onlyKeys2(data, deletion ? DELETE_DATA_KEYS : DATA_KEYS) || typeof data.bundleId !== "string" || data.bundleId.length === 0 || data.documentId !== expected.documentId || expected.bundleId !== void 0 && data.bundleId !== expected.bundleId || !isContentVersion(data.version) || typeof data.changed !== "boolean" || deletion && (!isContentVersion(data.deletedVersion) || data.deleted !== true)) throw refuse3();
-    const accepted = data;
-    return { ok: true, operationId, data: { ...accepted } };
+    if (raw.error !== void 0 || !isRecord8(data) || typeof data.bundleId !== "string" || data.bundleId.length === 0 || data.documentId !== expected.documentId || expected.bundleId !== void 0 && data.bundleId !== expected.bundleId || !isContentVersion(data.version) || typeof data.changed !== "boolean" || (deletion ? !isContentVersion(data.deletedVersion) || data.deleted !== true : data.deletedVersion !== void 0 || data.deleted !== void 0)) throw refuse3();
+    const accepted = pick(data, deletion ? DELETE_DATA_KEYS : DATA_KEYS);
+    return { ok: true, operationId, data: { ...accepted, ...writeReport(data) } };
   }
   if (raw.ok !== false) throw refuse3();
   const error62 = raw.error;
-  if (raw.data !== void 0 || !isRecord8(error62) || !onlyKeys2(error62, ERROR_KEYS) || !WRITE_ERROR_CODES.includes(error62.code) || typeof error62.message !== "string" || error62.retryable !== false || error62.writeState !== "not_applied" && error62.writeState !== "unknown" || error62.currentVersion !== void 0 && !isContentVersion(error62.currentVersion) || error62.code === "write_outcome_unknown" && error62.writeState !== "unknown" || (error62.code === "request_capacity" ? error62.scope !== "principal" && error62.scope !== "bundle" || error62.writeState !== "not_applied" || error62.resetAt !== void 0 && (typeof error62.resetAt !== "string" || !Number.isFinite(Date.parse(error62.resetAt))) : error62.scope !== void 0 || error62.resetAt !== void 0) || (error62.code === "deletions_held" ? operationId !== DELETE_OPERATION_ID || error62.writeState !== "not_applied" || !count3(error62.deletions) || !count3(error62.baseline) : error62.deletions !== void 0 || error62.baseline !== void 0) || // A model-change refusal says nothing was applied; its findings ride on it alone.
+  if (raw.data !== void 0 || !isRecord8(error62) || !WRITE_ERROR_CODES.includes(error62.code) || typeof error62.message !== "string" || error62.retryable !== false || error62.writeState !== "not_applied" && error62.writeState !== "unknown" || error62.currentVersion !== void 0 && !isContentVersion(error62.currentVersion) || error62.code === "write_outcome_unknown" && error62.writeState !== "unknown" || (error62.code === "request_capacity" ? error62.scope !== "principal" && error62.scope !== "bundle" || error62.writeState !== "not_applied" || error62.resetAt !== void 0 && (typeof error62.resetAt !== "string" || !Number.isFinite(Date.parse(error62.resetAt))) : error62.scope !== void 0 || error62.resetAt !== void 0) || (error62.code === "deletions_held" ? operationId !== DELETE_OPERATION_ID || error62.writeState !== "not_applied" || !count3(error62.deletions) || !count3(error62.baseline) : error62.deletions !== void 0 || error62.baseline !== void 0) || // A model-change refusal says nothing was applied; its findings ride on it alone.
   error62.code === "definition_incompatible" && error62.writeState !== "not_applied" || error62.definitionDetails !== void 0 && error62.code !== "definition_incompatible") throw refuse3();
-  return { ok: false, operationId, error: { ...error62 } };
+  const diagnostics = writeDiagnostics(error62.diagnostics);
+  const inputIssues = listOf(error62.inputIssues, inputIssue);
+  return {
+    ok: false,
+    operationId,
+    error: {
+      ...pick(error62, ERROR_KEYS),
+      ...diagnostics ? { diagnostics } : {},
+      ...inputIssues?.length ? { inputIssues } : {}
+    }
+  };
 }
 function updateRow(answer2) {
   const row5 = rowsByAnswer.get(answer2);
@@ -28772,7 +29133,7 @@ function decodeBlobOutcomeAnswer(value, expected) {
   if (value.status === "refused" && !result3.ok && result3.error.writeState === "not_applied") return { status: "refused", result: result3 };
   throw malformed6();
 }
-var CAPACITY_REFUSAL_CODES, DELETIONS_HELD_REFUSAL_CODE, UPDATE_ANSWER_ROWS, OUTCOME_ANSWER_ROWS, READ_ANSWER_ROWS, WRITE_ERROR_CODES, DELETE_OPERATION_ID, FINDING_IDS_SHOWN, DEFINITION_FINDINGS_TEXT_BYTES, findingText, HostedAnswerError, isRecord8, onlyKeys2, DATA_KEYS, DELETE_DATA_KEYS, ERROR_KEYS, count3, BEFORE_DISPATCH, rowsByAnswer, HostedOutcomeError, OUTCOME_CONTENT_BYTES;
+var CAPACITY_REFUSAL_CODES, DELETIONS_HELD_REFUSAL_CODE, UPDATE_ANSWER_ROWS, OUTCOME_ANSWER_ROWS, READ_ANSWER_ROWS, WRITE_ERROR_CODES, DELETE_OPERATION_ID, FINDING_IDS_SHOWN, DEFINITION_FINDINGS_TEXT_BYTES, findingText, HostedAnswerError, isRecord8, onlyKeys2, DATA_KEYS, DELETE_DATA_KEYS, ERROR_KEYS, count3, pick, isText, writeWarning, writeGuidance2, inputIssue, writeDiagnostics, BEFORE_DISPATCH, rowsByAnswer, HostedOutcomeError, OUTCOME_CONTENT_BYTES;
 var init_answer_rows = __esm({
   "../core/src/hosted-transport/answer-rows.ts"() {
     "use strict";
@@ -28901,8 +29262,18 @@ var init_answer_rows = __esm({
     onlyKeys2 = (value, allowed) => Object.keys(value).every((key4) => allowed.includes(key4));
     DATA_KEYS = ["bundleId", "documentId", "version", "changed", "scope"];
     DELETE_DATA_KEYS = [...DATA_KEYS, "deletedVersion", "deleted"];
-    ERROR_KEYS = ["code", "message", "retryable", "writeState", "currentVersion", "diagnostics", "fieldActionDetails", "definitionDetails", "candidate", "retentionUnavailable", "scope", "resetAt", "deletions", "baseline"];
+    ERROR_KEYS = ["code", "message", "retryable", "writeState", "currentVersion", "fieldActionDetails", "definitionDetails", "candidate", "retentionUnavailable", "scope", "resetAt", "deletions", "baseline"];
     count3 = (value) => Number.isSafeInteger(value) && value >= 1;
+    pick = (value, keys2) => {
+      const picked = {};
+      for (const key4 of keys2) if (Object.hasOwn(value, key4) && value[key4] !== void 0) picked[key4] = value[key4];
+      return picked;
+    };
+    isText = (value) => typeof value === "string";
+    writeWarning = (entry) => isText(entry.code) && (entry.severity === "error" || entry.severity === "warning") && (entry.field === void 0 || isText(entry.field)) ? { code: entry.code, severity: entry.severity, ...entry.field !== void 0 ? { field: entry.field } : {} } : void 0;
+    writeGuidance2 = (entry) => isText(entry.field) && isText(entry.value) && isText(entry.description) ? { field: entry.field, value: entry.value, description: entry.description } : void 0;
+    inputIssue = (entry) => isText(entry.path) && isText(entry.message) ? { path: entry.path, message: entry.message } : void 0;
+    writeDiagnostics = (value) => isRecord8(value) && Number.isSafeInteger(value.version) && Array.isArray(value.items) && value.items.every((item) => isRecord8(item) && isText(item.code)) ? value : void 0;
     BEFORE_DISPATCH = /* @__PURE__ */ new Map([
       [429, { code: "request_capacity", lenient: true }],
       [428, { code: "deletions_held", lenient: false }]
@@ -29956,7 +30327,7 @@ function rootWriteRequest(bundleId2, content3, base) {
 function rootSuccess(body, bundleId2) {
   if (!isRecord10(body) || body.ok !== true || body.operationId !== ROOT_OPERATION_ID || body.error !== void 0) return null;
   const data = body.data;
-  if (!isRecord10(data) || !Object.keys(data).every((key4) => key4 === "bundleId" || key4 === "version" || key4 === "changed")) return null;
+  if (!isRecord10(data)) return null;
   if (data.bundleId !== bundleId2 || !isContentVersion(data.version) || typeof data.changed !== "boolean") return null;
   return { version: data.version, changed: data.changed };
 }
@@ -33736,23 +34107,23 @@ async function inspectBundleHomeAt(canonicalRoot, options = {}) {
   }
 }
 async function unboundLocalCopyAt(canonicalRoot, options = {}) {
-  const facts = await bundleHomeAt(canonicalRoot, options);
-  return facts.home === "local" && facts.copy ? facts.copy : null;
+  const facts2 = await bundleHomeAt(canonicalRoot, options);
+  return facts2.home === "local" && facts2.copy ? facts2.copy : null;
 }
-function unboundCopyOf(facts) {
-  if (facts.home === "hosted" || !facts.copy) return {};
-  return unboundCopyDetail(facts.copy.folder, facts.copy.marker);
+function unboundCopyOf(facts2) {
+  if (facts2.home === "hosted" || !facts2.copy) return {};
+  return unboundCopyDetail(facts2.copy.folder, facts2.copy.marker);
 }
-function homeDetail(facts) {
-  if (facts.home === "hosted") {
-    const { binding: binding2 } = facts;
+function homeDetail(facts2) {
+  if (facts2.home === "hosted") {
+    const { binding: binding2 } = facts2;
     return { hosted: { host: binding2.origin, bundle_id: binding2.bundle_id, workspace: binding2.workspace, principal: binding2.principal_id } };
   }
-  if (facts.home === "git") {
-    const { board } = facts;
-    return { board: { channel: board.channel, branch: board.branch, upstream: board.upstream, shared: board.shared }, ...unboundCopyOf(facts) };
+  if (facts2.home === "git") {
+    const { board } = facts2;
+    return { board: { channel: board.channel, branch: board.branch, upstream: board.upstream, shared: board.shared }, ...unboundCopyOf(facts2) };
   }
-  return unboundCopyOf(facts);
+  return unboundCopyOf(facts2);
 }
 function count5(dir, args) {
   const text7 = gitText(dir, args);
@@ -34204,9 +34575,9 @@ async function entryAvailable(entry) {
 }
 async function entryView(entry, available, home2) {
   if (!available) return { ...entry, available, home: "local" };
-  const facts = await bundleHomeAt(entry.locator.path, { home: home2 });
-  if (facts.home !== "hosted") return { ...entry, available, home: facts.home };
-  const { binding: binding2 } = facts;
+  const facts2 = await bundleHomeAt(entry.locator.path, { home: home2 });
+  if (facts2.home !== "hosted") return { ...entry, available, home: facts2.home };
+  const { binding: binding2 } = facts2;
   return { ...entry, available, home: "hosted", hosted: { host: binding2.origin, bundle_id: binding2.bundle_id, checked_out_at: binding2.created_at } };
 }
 async function listCatalogEntries(home2 = homedir8()) {
@@ -42335,15 +42706,15 @@ function missingMetadataError(target3) {
   const hostname5 = new URL(target3.origin).hostname;
   const parent = parentDomain(hostname5);
   const label = hostname5.split(".")[0];
-  const suggestion = parent !== null && label !== "mcp" && isWorkspaceSlug(label) ? { host: `https://mcp.${parent}`, workspace: label } : null;
+  const suggestion2 = parent !== null && label !== "mcp" && isWorkspaceSlug(label) ? { host: `https://mcp.${parent}`, workspace: label } : null;
   return new CliError("RUNTIME", `protected-resource metadata at ${target3.metadataUrl} returned HTTP 404`, {
     details: {
       status: 404,
       reason: "no_protected_resource_metadata",
       host: target3.origin,
-      ...suggestion ? { suggested_host: suggestion.host, suggested_workspace: suggestion.workspace } : {}
+      ...suggestion2 ? { suggested_host: suggestion2.host, suggested_workspace: suggestion2.workspace } : {}
     },
-    help: suggestion ? `${target3.origin} may be a workspace address rather than the sign-in host; if so, re-run with --host ${commandToken(suggestion.host)} --workspace ${commandToken(suggestion.workspace)} (--workspace only where the command takes it)` : `${target3.origin} publishes no Superbee sign-in metadata; check the URL, or ask the host's operator which Superbee host to use`
+    help: suggestion2 ? `${target3.origin} may be a workspace address rather than the sign-in host; if so, re-run with --host ${commandToken(suggestion2.host)} --workspace ${commandToken(suggestion2.workspace)} (--workspace only where the command takes it)` : `${target3.origin} publishes no Superbee sign-in metadata; check the URL, or ask the host's operator which Superbee host to use`
   });
 }
 async function readWorkspacePointer(fetchImpl, target3) {
@@ -43032,10 +43403,10 @@ function decodeJwtClaims(token) {
 }
 function subjectFrom(tokens, previous3) {
   const claims = decodeJwtClaims(tokens.id_token) ?? decodeJwtClaims(tokens.access_token) ?? {};
-  const pick2 = (key4) => typeof claims[key4] === "string" ? claims[key4] : void 0;
-  const sub = pick2("sub") ?? previous3?.sub;
-  const email3 = pick2("email") ?? previous3?.email;
-  const name = pick2("name") ?? previous3?.name;
+  const pick3 = (key4) => typeof claims[key4] === "string" ? claims[key4] : void 0;
+  const sub = pick3("sub") ?? previous3?.sub;
+  const email3 = pick3("email") ?? previous3?.email;
+  const name = pick3("name") ?? previous3?.name;
   return { ...sub ? { sub } : {}, ...email3 ? { email: email3 } : {}, ...name ? { name } : {} };
 }
 function expiresAt(tokens, now) {
@@ -43902,9 +44273,9 @@ function parseOwnedOrUsage(parse7, command, recovery = {}) {
     if (retiredFlagInParse({ error: err })) throw retiredInputRefusal("--remote");
     const translated = translateParseArgsError(err);
     const raw = err instanceof Error ? err.message : String(err);
-    const suggestion = err?.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION" ? nearestLongOption(QUOTED.exec(raw)?.[1], recovery.optionNames) : void 0;
+    const suggestion2 = err?.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION" ? nearestLongOption(QUOTED.exec(raw)?.[1], recovery.optionNames) : void 0;
     const baseMessage = translated ?? stripAdvisory(raw);
-    const message = suggestion ? `${baseMessage} \u2014 did you mean '${suggestion}'?` : baseMessage;
+    const message = suggestion2 ? `${baseMessage} \u2014 did you mean '${suggestion2}'?` : baseMessage;
     throw new CliError("USAGE", message, { help: `${cliInvocation()} ${commandWords(command)} --help` });
   }
   if (retiredFlagInParse({ values: parsed2.values })) throw retiredInputRefusal("--remote");
@@ -45921,6 +46292,153 @@ var init_kind_write = __esm({
   }
 });
 
+// ../cli/src/write-findings.ts
+function bundleTargetReader(bundle) {
+  return async (id) => {
+    try {
+      return await readDoc2(bundle, id);
+    } catch (err) {
+      if (err?.code === "ENOENT") return void 0;
+      throw err;
+    }
+  };
+}
+function facts(details) {
+  const { start: _start, end: _end, ...rest } = details;
+  return rest;
+}
+function linkWarning(finding, body) {
+  if (finding.code === "LINK_NOT_RECOGNIZED") {
+    const d = finding.details;
+    const written = body.slice(d.start, d.end);
+    const fix = d.suggestedHref !== void 0 ? `; write [${d.text || d.suggestedTo}](${d.suggestedHref})` : "";
+    return {
+      code: finding.code,
+      message: `${written} will not register as a link: ${REASONS[d.reason] ?? "it is not a link to a document"}${fix}.`,
+      field: "body",
+      severity: finding.severity,
+      details: facts(d)
+    };
+  }
+  if (finding.code === "LINK_TARGET_ABSENT") {
+    const d = finding.details;
+    const fix = d.suggestedHref !== void 0 ? `; did you mean ${d.suggestedHref} ('${d.suggestedTo}' exists)?` : ` (kept as a forward declaration); create it with \`${cliInvocation()} doc write ${commandToken(d.to)} --type <t>\`.`;
+    return {
+      code: finding.code,
+      message: `target '${d.to}' has no document yet${fix}`,
+      field: "body",
+      severity: finding.severity,
+      details: facts(d)
+    };
+  }
+  return void 0;
+}
+function findingKey(finding) {
+  const d = finding.details;
+  return JSON.stringify([finding.code, d.reason ?? null, d.href ?? null, d.text ?? null, d.to ?? null]);
+}
+function cachedReader(bundle, failures) {
+  const read = bundleTargetReader(bundle);
+  const cache = /* @__PURE__ */ new Map();
+  return (id) => {
+    const held3 = cache.get(id);
+    if (held3) return held3;
+    const pending = read(id).catch((err) => {
+      failures.set(id, errorText(err));
+      return { id, frontmatter: { type: "" }, body: "" };
+    });
+    cache.set(id, pending);
+    return pending;
+  };
+}
+async function linkFindings(bundle, doc2, prior) {
+  const failures = /* @__PURE__ */ new Map();
+  const readTarget2 = cachedReader(bundle, failures);
+  let findings;
+  let unavailable3;
+  try {
+    ({ findings } = await documentLinkReport(doc2, { readTarget: readTarget2 }));
+  } catch (err) {
+    ({ findings } = inspectDocumentLinks(doc2));
+    unavailable3 = errorText(err);
+  }
+  const linkedBefore = new Set(prior === void 0 ? [] : inspectDocumentLinks({ ...prior, id: doc2.id }).links.map((link4) => link4.to));
+  const unreadable = [...failures].filter(([to]) => !linkedBefore.has(to));
+  const before = /* @__PURE__ */ new Map();
+  if (prior !== void 0 && findings.length > 0) {
+    let old;
+    try {
+      ({ findings: old } = await documentLinkReport({ ...prior, id: doc2.id }, { readTarget: readTarget2 }));
+    } catch {
+      ({ findings: old } = inspectDocumentLinks({ ...prior, id: doc2.id }));
+    }
+    for (const finding of old) before.set(findingKey(finding), (before.get(findingKey(finding)) ?? 0) + 1);
+  }
+  const links = findings.flatMap((finding) => {
+    const key4 = findingKey(finding);
+    const seen = before.get(key4) ?? 0;
+    if (seen > 0) {
+      before.set(key4, seen - 1);
+      return [];
+    }
+    const warning = linkWarning(finding, doc2.body);
+    return warning ? [warning] : [];
+  });
+  const out = links.slice(0, LINK_FINDINGS_SHOWN);
+  if (links.length > LINK_FINDINGS_SHOWN) {
+    const last = out[out.length - 1];
+    out[out.length - 1] = { ...last, message: `${last.message} (${links.length - LINK_FINDINGS_SHOWN} more link findings not shown)` };
+  }
+  for (const [to, reason] of unreadable.slice(0, LINK_FINDINGS_SHOWN)) {
+    out.push({ code: "LINK_LINT_UNAVAILABLE", message: `the link to '${to}' could not be checked: ${reason}`, field: "body", severity: "warning", details: { to } });
+  }
+  if (unavailable3 !== void 0) {
+    out.push({ code: "LINK_LINT_UNAVAILABLE", message: `the document was written, but its links to other documents could not be checked: ${unavailable3}`, field: "body", severity: "warning" });
+  }
+  return out;
+}
+async function writeFindings(bundle, doc2, registry2, prior) {
+  const out = prior === void 0 || prior.body !== doc2.body ? await linkFindings(bundle, doc2, prior) : [];
+  const type = prior === void 0 || prior.frontmatter.type !== doc2.frontmatter.type ? undeclaredTypeFinding(registry2, doc2) : void 0;
+  if (type?.details.suggestedType !== void 0) {
+    const { type: written, suggestedType } = type.details;
+    out.push({
+      code: type.code,
+      message: `no Kind declares type '${written}'; did you mean '${suggestedType}'?`,
+      field: "type",
+      severity: type.severity,
+      details: { type: written, suggestedType }
+    });
+  }
+  return out;
+}
+function writeFindingsHelp(findings) {
+  const help2 = [];
+  if (findings.some((f) => f.code === "LINK_NOT_RECOGNIZED")) help2.push(LINK_FORM_HELP);
+  if (findings.some((f) => f.code === "KIND_TYPE_UNDECLARED")) help2.push(`${cliInvocation()} kinds`);
+  return help2;
+}
+var LINK_FINDINGS_SHOWN, LINK_FORM_HELP, REASONS, errorText;
+var init_write_findings = __esm({
+  "../cli/src/write-findings.ts"() {
+    "use strict";
+    init_define_SUPERBEE_BUILD_IDENTITY();
+    init_define_SUPERBEE_UPDATE_POLICY();
+    init_src();
+    init_invocation();
+    init_command_text();
+    LINK_FINDINGS_SHOWN = 10;
+    LINK_FORM_HELP = "a link registers only as [Text](/folder/id.md) from the bundle root or [Text](./id.md) beside this document";
+    REASONS = {
+      wikilink: "a [[wikilink]] is plain text in OKF",
+      "missing-md-extension": "its target does not end in .md",
+      "reserved-target": "index.md and log.md are never documents",
+      "invalid-target": "its target is not a valid document id"
+    };
+    errorText = (err) => err instanceof Error ? err.message : String(err);
+  }
+});
+
 // ../cli/src/mutate.ts
 async function firePostPersist(hook2) {
   if (!hook2) return;
@@ -46014,7 +46532,7 @@ var init_mutate = __esm({
 });
 
 // ../core/src/bundle-health/report.ts
-function docType(doc2) {
+function docType2(doc2) {
   return typeof doc2.frontmatter.type === "string" ? doc2.frontmatter.type : "";
 }
 function diagnosticValue(value) {
@@ -46024,17 +46542,13 @@ function diagnosticValue(value) {
     return `<non-JSON ${Array.isArray(value) ? "array" : typeof value}: circular or too deeply nested>`;
   }
 }
-function isGraphDefinition(doc2) {
-  const type = docType(doc2);
-  return type === "Convention" || isPageTypeName(type) || isLegacyPageDoc(doc2.frontmatter) || type === "Reference" && doc2.id.startsWith("references/") || type === BUNDLE_NAME_DOC_TYPE && doc2.id === BUNDLE_NAME_DOC_ID || type === DEPENDENCIES_DOC_TYPE && doc2.id === DEPENDENCIES_DOC_ID;
-}
 function okfV02WorkflowStatusCollisions(registry2, docs) {
   const affectedByKind = /* @__PURE__ */ new Map();
   const observedValuesByKind = /* @__PURE__ */ new Map();
   for (const doc2 of docs) {
     const value = doc2.frontmatter.status;
     if (value === void 0 || isOkfLifecycleStatus(value)) continue;
-    const type = docType(doc2);
+    const type = docType2(doc2);
     affectedByKind.set(type, (affectedByKind.get(type) ?? 0) + 1);
     const display = typeof value === "string" ? value : `<${Array.isArray(value) ? "array" : typeof value}>`;
     const observed = observedValuesByKind.get(type) ?? /* @__PURE__ */ new Set();
@@ -46085,13 +46599,13 @@ async function bundleHealth(bundle, options = {}) {
   const deprecatedUsage = [];
   const conformanceDebtDocs = /* @__PURE__ */ new Map();
   for (const doc2 of docs) {
-    const kind2 = registry2.kinds.get(docType(doc2));
+    const kind2 = registry2.kinds.get(docType2(doc2));
     if (!kind2) continue;
     deprecatedUsage.push(...inspectKindDeprecatedUsage(doc2, kind2).map((row5) => ({ id: doc2.id, ...row5 })));
     for (const w of projectKindValidationWarnings(okfVersion, kind2, validateAgainstKind(doc2, kind2))) {
       kindLint.push({ id: doc2.id, field: w.field ?? "", code: w.code });
       if (isKindFieldValidationWarning(w) && !conformanceDebtDocs.has(doc2.id)) {
-        conformanceDebtDocs.set(doc2.id, docType(doc2));
+        conformanceDebtDocs.set(doc2.id, docType2(doc2));
       }
     }
   }
@@ -46105,7 +46619,7 @@ async function bundleHealth(bundle, options = {}) {
   for (const doc2 of docs) {
     for (const l of parseLinksFromDoc(doc2)) {
       if (isQualifiedHref(l.href)) continue;
-      const qualifiedDeclaration = localEdgeQualifiedDeclaration(linkTypeDeclarations.get(l.text), docType(doc2));
+      const qualifiedDeclaration = localEdgeQualifiedDeclaration(linkTypeDeclarations.get(l.text), docType2(doc2));
       if (qualifiedDeclaration) {
         crossLinkTypeViolations.push({
           from: doc2.id,
@@ -46122,24 +46636,17 @@ async function bundleHealth(bundle, options = {}) {
       if (l.to !== doc2.id) {
         inbound.add(l.to);
         const list6 = inboundEdges.get(l.to) ?? [];
-        list6.push({ text: l.text, sourceType: docType(doc2) });
+        list6.push({ text: l.text, sourceType: docType2(doc2) });
         inboundEdges.set(l.to, list6);
       }
-      const declared = linkTypeDeclarations.get(l.text);
-      if (declared && declared.length > 0 && !qualifiedDeclaration) {
-        const sourceType = docType(doc2);
-        const targetType = docType(docsById.get(l.to));
-        const matched = declared.find((d) => d.governs === sourceType) ?? declared[0];
-        const sourceOk = declared.some((d) => d.governs === sourceType);
-        const targetOk = targetType === matched.target;
-        if (!sourceOk || !targetOk) {
-          linkTypeViolations.push({
-            from: doc2.id,
-            to: l.to,
-            text: l.text,
-            expected: `${matched.governs} -> ${matched.target}`
-          });
-        }
+      const matched = qualifiedDeclaration ? null : localEdgeViolation(linkTypeDeclarations.get(l.text), docType2(doc2), docType2(docsById.get(l.to)));
+      if (matched) {
+        linkTypeViolations.push({
+          from: doc2.id,
+          to: l.to,
+          text: l.text,
+          expected: `${matched.governs} -> ${matched.target}`
+        });
       }
     }
   }
@@ -46149,7 +46656,7 @@ async function bundleHealth(bundle, options = {}) {
     for (const q of parseQualifiedLinks(doc2)) {
       qualifiedLinks.push(q);
       if (!q.ref) continue;
-      const violation = qualifiedEdgeViolation(linkTypeDeclarations.get(q.text), docType(doc2), q.ref.alias);
+      const violation = qualifiedEdgeViolation(linkTypeDeclarations.get(q.text), docType2(doc2), q.ref.alias);
       if (violation) {
         metadataViolations.add(q);
         crossLinkTypeViolations.push({
@@ -46193,9 +46700,9 @@ async function bundleHealth(bundle, options = {}) {
         if (!metadataViolations.has(link4)) {
           const violation = qualifiedEdgeViolation(
             linkTypeDeclarations.get(link4.text),
-            docType(docsById.get(link4.from)),
+            docType2(docsById.get(link4.from)),
             resolution.ref.alias,
-            docType(resolution.document)
+            docType2(resolution.document)
           );
           if (violation) crossLinkTypeViolations.push({
             from: link4.from,
@@ -46229,8 +46736,8 @@ async function bundleHealth(bundle, options = {}) {
   const orphans = [];
   if (inbound.size > 0) {
     for (const doc2 of docs) {
-      if (!inbound.has(doc2.id) && !outbound.has(doc2.id) && !isGraphDefinition(doc2)) {
-        orphans.push({ id: doc2.id, type: docType(doc2) });
+      if (!inbound.has(doc2.id) && !outbound.has(doc2.id) && !isGraphDefinitionDocument(doc2)) {
+        orphans.push({ id: doc2.id, type: docType2(doc2) });
       }
     }
   }
@@ -46243,25 +46750,25 @@ async function bundleHealth(bundle, options = {}) {
   for (const doc2 of docs) {
     const invalidLegacy = invalidLegacyTimestamp(doc2.frontmatter, okfVersion);
     if (invalidLegacy) {
-      invalidLegacyTimestamps.push({ id: doc2.id, type: docType(doc2), field: invalidLegacy.field, value: diagnosticValue(invalidLegacy.value) });
+      invalidLegacyTimestamps.push({ id: doc2.id, type: docType2(doc2), field: invalidLegacy.field, value: diagnosticValue(invalidLegacy.value) });
     }
     if (okfVersion === "0.2") {
       for (const { field, value } of invalidOkfTimestamps(doc2.frontmatter)) {
-        invalidTimestamps.push({ id: doc2.id, type: docType(doc2), field, value: diagnosticValue(value) });
+        invalidTimestamps.push({ id: doc2.id, type: docType2(doc2), field, value: diagnosticValue(value) });
       }
     }
-    const kind2 = registry2.kinds.get(docType(doc2));
+    const kind2 = registry2.kinds.get(docType2(doc2));
     const horizonMs = kind2 ? freshnessHorizonMs(kind2) : void 0;
     const hasStaleAfter = okfVersion === "0.2" && Object.hasOwn(doc2.frontmatter, "stale_after");
     const staleAfterIsInvalid = hasStaleAfter && staleAfterInstant(doc2.frontmatter.stale_after) === null;
     if (staleAfterIsInvalid) {
-      invalidStaleAfter.push({ id: doc2.id, type: docType(doc2), value: diagnosticValue(doc2.frontmatter.stale_after) });
+      invalidStaleAfter.push({ id: doc2.id, type: docType2(doc2), value: diagnosticValue(doc2.frontmatter.stale_after) });
     }
     const staleAfter = hasStaleAfter && !staleAfterIsInvalid ? doc2.frontmatter.stale_after : void 0;
     if (horizonMs === void 0 && staleAfter === void 0) continue;
     const result3 = freshness(doc2, { maxAgeMs: horizonMs, now, okfVersion });
     if (result3.verdict === "empty" && horizonMs !== void 0) {
-      noTimestamp.push({ id: doc2.id, type: docType(doc2) });
+      noTimestamp.push({ id: doc2.id, type: docType2(doc2) });
     } else if (result3.verdict === "stale") {
       stale.push({
         id: doc2.id,
@@ -46275,7 +46782,7 @@ async function bundleHealth(bundle, options = {}) {
   const missingExpectedRanked = [];
   let terminalSkipped = 0;
   for (const doc2 of docs) {
-    const kind2 = registry2.kinds.get(docType(doc2));
+    const kind2 = registry2.kinds.get(docType2(doc2));
     if (!kind2?.expectsInbound) continue;
     const terminalDeclared = Object.keys(kind2.fields.terminal).length > 0;
     if (terminalDeclared && isTerminal(kind2, doc2.frontmatter)) {
@@ -46366,7 +46873,7 @@ var init_report = __esm({
     init_page();
     init_qualified_links();
     init_verification();
-    init_legacy_page();
+    init_system_documents();
   }
 });
 
@@ -46706,6 +47213,12 @@ replacement. Kind validation is advisory by default: violations appear as warnin
 no-ops. --strict rejects violations without writing. A changed replacement of a previously conforming
 document cannot be nonconforming, even in advisory mode.
 
+After a changed write, warnings also name what it introduced that will not work as meant: a link
+that will not register (LINK_NOT_RECOGNIZED, with the href that would), a link to a document that
+does not exist yet (LINK_TARGET_ABSENT; still allowed) and a type that misses a declared Kind's
+type only by case, spacing, hyphens or underscores (KIND_TYPE_UNDECLARED, naming the declared
+one). They never refuse the write.
+
 Options:
   --type <t>           OKF concept type (non-empty)                          [required]
   --title <t>          Display title
@@ -46772,6 +47285,7 @@ timestamp) converges to changed:false (no write, no timestamp refresh).
 Standard-field patches use advisory Kind validation by default, returning warnings even on no-ops;
 --strict rejects violations without writing. Dynamic declared fields are always strict: passing a
 --<field> flag requires the whole resulting document to satisfy its Kind, even for a same-value patch.
+A changed body or type also gets the post-write link and type warnings 'doc write' describes.
 
 Options:
   --title <t>            Replace the title
@@ -47201,6 +47715,7 @@ async function docUpdate(argv2, deps2) {
   const mode = resolveMode({ json: p.json });
   const registry2 = await loadKinds(bundle);
   const strict = p.strict || p.kindFields.size > 0;
+  let prior;
   if (route) await assertResolvedLocalRouteIdentity(route);
   const result3 = await mutateDoc({
     bundle,
@@ -47223,6 +47738,7 @@ async function docUpdate(argv2, deps2) {
     input: async (existingDoc, context3) => {
       assertStaleAfterEdition(staleAfter, context3.okfVersion);
       const existing = existingDoc;
+      prior = existing;
       const nextFrontmatter = {};
       if (staleAfter !== void 0) nextFrontmatter.stale_after = staleAfter;
       if (p.title !== void 0) nextFrontmatter.title = p.title;
@@ -47244,21 +47760,24 @@ async function docUpdate(argv2, deps2) {
             { help: `${cliInvocation()} kinds` }
           );
         }
-        const authoringKind = projectKindForAuthoring(context3.okfVersion, kind2);
         const progressCoordinate = progressStatusCoordinate(context3.okfVersion, kind2);
-        const declared = [...authoringKind.fields.required, ...authoringKind.fields.optional];
-        const resolvedFields = /* @__PURE__ */ new Map();
-        for (const field of p.kindFields.keys()) {
-          resolvedFields.set(field, resolveKindFieldCoordinate(context3.okfVersion, kind2, field));
-        }
-        const unknown3 = [...resolvedFields.entries()].filter(([, coordinate]) => coordinate === void 0).map(([field]) => field);
-        if (unknown3.length > 0) {
+        const undeclared = kindFieldsUndeclaredFinding(
+          context3.okfVersion,
+          kind2,
+          unknownKindFieldNames(context3.okfVersion, kind2, p.kindFields.keys())
+        );
+        if (undeclared) {
+          const { kind: governs, fields: unknown3, declared } = undeclared.details;
           throw new CliError(
             "USAGE",
-            `unknown field(s) for kind '${kind2.governs}': ${unknown3.join(", ")} (declared: ${declared.length > 0 ? declared.join(", ") : "none"}; standard patch flags: title, description, type, body, body-file) \u2014 to ADD a field to the '${kind2.governs}' kind: \`${cliInvocation()} kind field ${commandToken(kind2.governs)} add <name>\`. Flags address declared fields only; an undeclared key written in frontmatter follows the kind's undeclared_fields setting (warn by default).`,
+            `unknown field(s) for kind '${governs}': ${unknown3.join(", ")} (declared: ${declared.length > 0 ? declared.join(", ") : "none"}; standard patch flags: title, description, type, body, body-file) \u2014 to ADD a field to the '${governs}' kind: \`${cliInvocation()} kind field ${commandToken(governs)} add <name>\`. Flags address declared fields only; an undeclared key written in frontmatter follows the kind's undeclared_fields setting (warn by default).`,
             { help: `${cliInvocation()} kinds` }
           );
         }
+        const resolvedFields = /* @__PURE__ */ new Map();
+        for (const field of p.kindFields.keys()) {
+          resolvedFields.set(field, resolveKindFieldCoordinate(context3.okfVersion, kind2, field));
+        }
         const suppliedByStorageField = /* @__PURE__ */ new Map();
         if (staleAfter !== void 0) suppliedByStorageField.set("stale_after", "stale-after");
         for (const [field, value] of p.kindFields) {
@@ -47298,10 +47817,12 @@ async function docUpdate(argv2, deps2) {
     // subsequent `--expected-version` compare-and-swap.
     version: result3.version
   };
-  if (result3.warnings.length > 0) receipt5.warnings = result3.warnings;
+  const findings = result3.changed ? await writeFindings(bundle, result3.doc, registry2, prior) : [];
+  const warnings = [...result3.warnings, ...findings];
+  if (warnings.length > 0) receipt5.warnings = warnings;
   if (result3.guidance.length > 0) receipt5.guidance = result3.guidance;
   if (isLegacyPageDoc(result3.doc.frontmatter)) receipt5.hint = LEGACY_PAGE_TYPE_HINT;
-  receipt5.help = [`${cliInvocation()} doc read ${commandToken(result3.doc.id)}`];
+  receipt5.help = [`${cliInvocation()} doc read ${commandToken(result3.doc.id)}`, ...writeFindingsHelp(findings)];
   stdout(render(receipt5, mode));
 }
 var DOC_UPDATE_FIELD_FLAGS, DOC_UPDATE_VALUE_FLAGS, DOC_UPDATE_BOOLEAN_FLAGS;
@@ -47320,6 +47841,7 @@ var init_update2 = __esm({
     init_errors6();
     init_output2();
     init_invocation();
+    init_write_findings();
     init_mutate();
     init_legacy_page2();
     init_board_attribution();
@@ -47451,6 +47973,7 @@ async function docWrite(argv2, deps2) {
   const acceptTruncatedBody = Boolean(values["accept-truncated-body"]);
   const registry2 = await loadKinds(bundle);
   let droppedFields = [];
+  let prior;
   if (route) await assertResolvedLocalRouteIdentity(route);
   const result3 = await mutateDoc({
     bundle,
@@ -47467,6 +47990,7 @@ async function docWrite(argv2, deps2) {
     // refused/failed one — and only for the conventional board bundle (see board-attribution.ts).
     onPersisted: boardPostPersistHook(route ? boardAttributionForRoute(route) : { kind: "none" }, actor),
     buildCandidate: (fresh, context3) => {
+      prior = fresh;
       assertStaleAfterEdition(staleAfter, context3.okfVersion);
       assertAuthoredLegacyTimestamp(values.timestamp?.trim(), context3.okfVersion);
       const legacyTimestamp = values.timestamp?.trim();
@@ -47527,10 +48051,12 @@ async function docWrite(argv2, deps2) {
     receipt5.note = receipt5.note ? `${receipt5.note}
 ${STDIN_SILENT_NOTE}` : STDIN_SILENT_NOTE;
   }
-  if (result3.warnings.length > 0) receipt5.warnings = result3.warnings;
+  const findings = result3.changed ? await writeFindings(bundle, saved, registry2, prior) : [];
+  const warnings = [...result3.warnings, ...findings];
+  if (warnings.length > 0) receipt5.warnings = warnings;
   if (result3.guidance.length > 0) receipt5.guidance = result3.guidance;
   if (isLegacyPageDoc(saved.frontmatter)) receipt5.hint = LEGACY_PAGE_TYPE_HINT;
-  receipt5.help = [`${cliInvocation()} doc read ${commandToken(saved.id)}`];
+  receipt5.help = [`${cliInvocation()} doc read ${commandToken(saved.id)}`, ...writeFindingsHelp(findings)];
   stdout(render(receipt5, resolveMode(values)));
 }
 var init_write2 = __esm({
@@ -47546,6 +48072,7 @@ var init_write2 = __esm({
     init_command_spec();
     init_output2();
     init_invocation();
+    init_write_findings();
     init_mutate();
     init_legacy_page2();
     init_board_attribution();
@@ -48501,9 +49028,9 @@ async function sharedGitBoardAt(dir, home2 = homedir16()) {
   } catch {
     return null;
   }
-  const facts = await bundleHomeAt(root, { home: home2 });
-  if (facts.home !== "git") return null;
-  const board = facts.board;
+  const facts2 = await bundleHomeAt(root, { home: home2 });
+  if (facts2.home !== "git") return null;
+  const board = facts2.board;
   if (board.channel !== "branch" || !board.shared) return null;
   const block = await gitBoardSyncBlock(board);
   return {
@@ -57421,14 +57948,14 @@ async function defaultSummarizeBundle(dir, route) {
     const docs = await queryHeads2(bundle, {}, { onSkip: ({ id, reason }) => malformed6.push({ id, reason }) });
     const { name, source: source2 } = await deriveBundleDisplayName(bundle);
     const okfVersion = await readBundleOkfVersion2(bundle);
-    const facts = await bundleHomeAt(await realpath6(bundle.root).catch(() => bundle.root));
-    const copy = unboundCopyOf(facts).copy_of_checkout;
+    const facts2 = await bundleHomeAt(await realpath6(bundle.root).catch(() => bundle.root));
+    const copy = unboundCopyOf(facts2).copy_of_checkout;
     return {
       name,
       nameSource: source2,
       ...summarizeDocs(docs, collapseHomeDirectory(bundle.root), { okfVersion }),
-      home: facts.home,
-      ...facts.home === "hosted" ? { hostedDefinitionWrites: facts.binding.definition_writes ?? null } : {},
+      home: facts2.home,
+      ...facts2.home === "hosted" ? { hostedDefinitionWrites: facts2.binding.definition_writes ?? null } : {},
       ...copy ? { copyOfCheckout: copy } : {},
       ...malformed6.length > 0 ? { malformed: malformed6.sort((a, b) => a.id.localeCompare(b.id)) } : {}
     };
@@ -60131,7 +60658,7 @@ async function driveObservation(options) {
   const sourceComplete = bound2.source.completeness === "complete";
   let stop;
   let stopUrl;
-  const errorText = (error62) => error62 instanceof Error ? error62.message : String(error62);
+  const errorText2 = (error62) => error62 instanceof Error ? error62.message : String(error62);
   const store = async (next) => {
     try {
       if ((qualified || options.prepareCommit || hasProtectedSourcePending(state)) && ((qualified ? Object.keys(next.pending ?? {}).length : Object.values(next.pending ?? {}).filter((p) => p.establishment).length) > 100 || new TextEncoder().encode(JSON.stringify(next)).length > 4194304)) throw new Error("source establishment state limit");
@@ -60188,7 +60715,7 @@ async function driveObservation(options) {
         })));
       } catch (error62) {
         receipt5.held += ids.length;
-        stop = { outcome: "failed", reason: "establishment_pending", retry: true, detail: errorText(error62) };
+        stop = { outcome: "failed", reason: "establishment_pending", retry: true, detail: errorText2(error62) };
         return;
       }
       if (ids.some((id) => result3.hold.has(id) || result3.retry.has(id))) {
@@ -60229,7 +60756,7 @@ async function driveObservation(options) {
             ...marked.length ? { establishments } : {}
           })));
         } catch (error62) {
-          failure4 = errorText(error62);
+          failure4 = errorText2(error62);
         }
       }
       if (marked.some((id) => failure4 !== void 0 || result3.retry.has(id) || result3.hold.has(id))) {
@@ -60306,7 +60833,7 @@ async function driveObservation(options) {
         if (!stop && signal.aborted) stop = { outcome: "deferred", reason: "deadline", retry: true };
         if (!stop) {
           const code3 = record12(error62) ? error62.code : void 0;
-          stop = code3 === UNSUPPORTED_CONTENT ? { outcome: "unsupported_content", retry: false, detail: String(error62.detail ?? "") } : { outcome: "failed", reason: "profile_error", retry: false, detail: errorText(error62) };
+          stop = code3 === UNSUPPORTED_CONTENT ? { outcome: "unsupported_content", retry: false, detail: String(error62.detail ?? "") } : { outcome: "failed", reason: "profile_error", retry: false, detail: errorText2(error62) };
         }
         stopUrl = lastRequestUrl();
         break;
@@ -60326,7 +60853,7 @@ async function driveObservation(options) {
         }
         page = JSON.parse(JSON.stringify(raw));
       } catch (error62) {
-        stop = { outcome: "failed", reason: "page_invalid", retry: false, detail: errorText(error62) };
+        stop = { outcome: "failed", reason: "page_invalid", retry: false, detail: errorText2(error62) };
         break;
       }
       const nextCursor = page.nextCursor ?? null;
@@ -60416,7 +60943,7 @@ async function driveObservation(options) {
           return;
         }
       } catch (error62) {
-        stop = { outcome: "failed", reason: "commit_failed", retry: true, detail: errorText(error62) };
+        stop = { outcome: "failed", reason: "commit_failed", retry: true, detail: errorText2(error62) };
         break;
       }
       const notWritten = (id) => byId2.has(id) && (result3.hold.has(id) || result3.retry.has(id));
@@ -60593,7 +61120,7 @@ async function observeSource(options) {
     stop = { outcome: "refused", reason, retry: false, ...detail2 !== void 0 ? { detail: detail2 } : {} };
     return finish();
   };
-  const errorText = (error62) => error62 instanceof Error ? error62.message : String(error62);
+  const errorText2 = (error62) => error62 instanceof Error ? error62.message : String(error62);
   if (bound2.source.request?.read_policy !== void 0) {
     try {
       const inspected = inspectSourceReadPolicy(connector, bound2);
@@ -60627,7 +61154,7 @@ async function observeSource(options) {
     spec = checked.spec;
     hosts = profile.hostsFor(spec, structuredClone(bound2));
   } catch (error62) {
-    stop = { outcome: "failed", reason: "profile_error", retry: false, detail: errorText(error62) };
+    stop = { outcome: "failed", reason: "profile_error", retry: false, detail: errorText2(error62) };
     return finish();
   }
   if (!Array.isArray(hosts) || !hosts.every((host) => typeof host === "string")) return refuse3("hosts_invalid");
@@ -60646,7 +61173,7 @@ async function observeSource(options) {
     version5 = stored?.version ?? null;
     state = stored?.state ?? emptyState2(profile);
   } catch (error62) {
-    stop = { outcome: "failed", reason: "state_unreadable", retry: true, detail: errorText(error62) };
+    stop = { outcome: "failed", reason: "state_unreadable", retry: true, detail: errorText2(error62) };
     return finish();
   }
   const baseline = version5 === null;
@@ -62060,9 +62587,9 @@ function capacityFacts(bound2, snapshot3, state, input2) {
     complete_observations: Number.MAX_SAFE_INTEGER,
     last_complete_at: time3
   }) + bytes({ v: 1, entries: candidates });
-  const facts = { retainedIds: bags.size, acceptedTuples: tupleKeys.size, upperBoundBytes, maxEnvelopeBytes: input2.maxEnvelopeBytes };
-  if (facts.retainedIds > SNAPSHOT_MAX_RECORDS || facts.acceptedTuples > SNAPSHOT_MAX_RECORDS || facts.upperBoundBytes > facts.maxEnvelopeBytes) return refuse("SNAPSHOT_CAPACITY_EXCEEDED");
-  return facts;
+  const facts2 = { retainedIds: bags.size, acceptedTuples: tupleKeys.size, upperBoundBytes, maxEnvelopeBytes: input2.maxEnvelopeBytes };
+  if (facts2.retainedIds > SNAPSHOT_MAX_RECORDS || facts2.acceptedTuples > SNAPSHOT_MAX_RECORDS || facts2.upperBoundBytes > facts2.maxEnvelopeBytes) return refuse("SNAPSHOT_CAPACITY_EXCEEDED");
+  return facts2;
 }
 function snapshotStateValid(value) {
   if (!isSourceState(value) || !isJsonData(value) || value.pending_commit !== void 0) return false;
@@ -62511,7 +63038,7 @@ var init_source_profiles = __esm({
         };
       }
     });
-    SOURCE_PLUGIN_CORE_VERSION = "0.2.0-pre.41";
+    SOURCE_PLUGIN_CORE_VERSION = "0.2.0-pre.43";
     SOURCE_PROFILES = Object.freeze([restJsonProfile].map((profile) => Object.freeze({ id: profile.id, version: profile.version, kind: profile.kind })));
   }
 });
@@ -63184,6 +63711,9 @@ Options:
   --json               Emit compact JSON instead of TOON
   -h, --help           Show this help without reading a bundle
 
+A changed type is checked as 'doc write' checks it: a near miss of a declared Kind's type
+is named in the receipt's warnings (KIND_TYPE_UNDECLARED). It never refuses the write.
+
 Literal strings are never split on commas or parsed as key/value pairs. Put flags
 before -- when passing a dash-leading literal. Field actions never read stdin.
 Resource selection refuses an ID-bearing entry and directs you to its ID.
@@ -63268,6 +63798,7 @@ async function docField(argv2, deps2) {
   const operation = action === "edit" ? { action, field, selector: selector2, patch: value } : action === "remove" && field === "sources" ? { action, field, selector: selector2 } : { action, field, value };
   const registry2 = await loadKinds(bundle);
   const edition = await readBundleOkfVersion2(bundle) === "0.2" ? "0.2" : "0.1";
+  let prior;
   if (route) await assertResolvedLocalRouteIdentity(route);
   try {
     const result3 = await mutateDoc({
@@ -63282,6 +63813,7 @@ async function docField(argv2, deps2) {
       persistActor: true,
       expectedVersion: expectedVersion?.trim(),
       input: (existing, context3) => {
+        prior = existing;
         if (context3.okfVersion !== edition) fail4("The bundle edition changed; retry against its current declaration.");
         if (action === "set") {
           const kind2 = registry2.kinds.get(String(existing.frontmatter.type));
@@ -63299,6 +63831,8 @@ async function docField(argv2, deps2) {
     });
     const scope = result3.scope;
     const { affectedSourceIds, ...boundedScope } = scope;
+    const findings = result3.changed ? await writeFindings(bundle, result3.doc, registry2, prior) : [];
+    const warnings = [...result3.warnings, ...findings];
     stdout(render({
       doc: "field",
       id: result3.doc.id,
@@ -63307,9 +63841,9 @@ async function docField(argv2, deps2) {
       changed: result3.changed,
       version: result3.version,
       scope: { ...boundedScope, ...affectedSourceIds === void 0 ? {} : { affectedSourceIds: affectedSourceIds.slice(0, 20), affectedSourceIdCount: affectedSourceIds.length } },
-      ...result3.warnings.length ? { warnings: result3.warnings } : {},
+      ...warnings.length ? { warnings } : {},
       ...result3.guidance.length ? { guidance: result3.guidance } : {},
-      help: [`${cliInvocation()} doc read ${commandToken(result3.doc.id)}${routeFlag}`]
+      help: [`${cliInvocation()} doc read ${commandToken(result3.doc.id)}${routeFlag}`, ...writeFindingsHelp(findings)]
     }, resolveMode(values)));
   } catch (error62) {
     if (error62 instanceof CliError && error62.code === "USAGE" && !error62.help) {
@@ -63341,6 +63875,7 @@ var init_field = __esm({
     init_command_spec();
     init_command_text();
     init_invocation();
+    init_write_findings();
     init_errors6();
     init_external_file();
     init_bundle2();
@@ -109924,64 +110459,30 @@ Options:
 
 // ../cli/src/commands/link.ts
 import { parseArgs as parseArgs21 } from "node:util";
-function docType2(doc2) {
+function docType3(doc2) {
   return typeof doc2.frontmatter.type === "string" ? doc2.frontmatter.type : "";
 }
 async function lintLinkType(bundle, args, registry2) {
-  const declarations = collectLinkDeclarations(registry2);
-  if (declarations.size === 0) return [];
-  const exact = declarations.get(args.text);
-  if (exact && exact.length > 0) {
-    let targetType;
-    let targetResolved = true;
-    try {
-      targetType = docType2(await readDoc2(bundle, args.to));
-    } catch (err) {
-      if (err?.code === "ENOENT") {
-        targetResolved = false;
-      } else {
-        throw classifyBundleError(err);
-      }
-    }
-    const matched = exact.find((d) => d.governs === args.sourceType) ?? exact[0];
-    const qualified = parseQualifiedKindTarget(matched.target);
-    if (qualified) {
-      return [
-        {
-          code: "LINK_TYPE_VIOLATION",
-          message: `'${args.text}' is declared by '${matched.governs}' -> ${matched.target}, a link into the bundle aliased '${qualified.alias}'; write it with --bundle ${commandToken(qualified.alias)}.`,
-          field: "text",
-          severity: "warning"
-        }
-      ];
-    }
-    const sourceOk = exact.some((d) => d.governs === args.sourceType);
-    const targetOk = !targetResolved || targetType === matched.target;
-    if (!sourceOk || !targetOk) {
-      return [
-        {
-          code: "LINK_TYPE_VIOLATION",
-          message: `'${args.text}' is declared by '${matched.governs}' -> ${matched.target}; this link is ${args.sourceType || "(untyped)"} -> ${targetResolved ? targetType || "(untyped)" : "(unresolved)"}.`,
-          field: "text",
-          severity: "warning"
-        }
-      ];
-    }
-    return [];
+  let finding;
+  try {
+    finding = await linkTypeFinding(registry2, args, bundleTargetReader(bundle));
+  } catch (err) {
+    throw classifyBundleError(err);
   }
-  for (const declaredText of declarations.keys()) {
-    if (declaredText.toLowerCase() === args.text.toLowerCase()) {
-      return [
-        {
-          code: "LINK_TYPE_CASE_VARIANT",
-          message: `'${args.text}' is a case-variant of the declared link type '${declaredText}' \u2014 did you mean --text ${commandQuoted(declaredText)}?`,
-          field: "text",
-          severity: "warning"
-        }
-      ];
-    }
+  if (!finding) return [];
+  if (finding.code === "LINK_TYPE_CASE_VARIANT") {
+    return [
+      {
+        code: finding.code,
+        message: `'${args.text}' is a case-variant of the declared link type '${finding.details.declaredText}' \u2014 did you mean --text ${commandQuoted(finding.details.declaredText)}?`,
+        field: "text",
+        severity: "warning"
+      }
+    ];
   }
-  return [];
+  const d = finding.details;
+  const message = d.targetAlias !== void 0 ? `'${args.text}' is declared by '${d.declaredBy}' -> ${d.declaredTarget}, a link into the bundle aliased '${d.targetAlias}'; write it with --bundle ${commandToken(d.targetAlias)}.` : `'${args.text}' is declared by '${d.declaredBy}' -> ${d.declaredTarget}; this link is ${d.sourceType || "(untyped)"} -> ${d.targetType === null ? "(unresolved)" : d.targetType || "(untyped)"}.`;
+  return [{ code: finding.code, message, field: "text", severity: "warning" }];
 }
 async function assertTargetNotAlias(bundle, to) {
   try {
@@ -109991,18 +110492,14 @@ async function assertTargetNotAlias(bundle, to) {
   }
 }
 async function targetAbsentWarning(bundle, to) {
-  try {
-    await readDoc2(bundle, to);
-    return void 0;
-  } catch (err) {
-    if (err?.code !== "ENOENT") throw err;
-    return {
-      code: "LINK_TARGET_ABSENT",
-      message: `target '${to}' has no document yet \u2014 this link is a forward-declaration (dangling links stay allowed); create it with \`${cliInvocation()} doc write ${commandToken(to)} --type <t>\`.`,
-      field: "to",
-      severity: "warning"
-    };
-  }
+  const finding = await linkTargetAbsentFinding({ to }, bundleTargetReader(bundle));
+  if (!finding) return void 0;
+  return {
+    code: finding.code,
+    message: `target '${to}' has no document yet \u2014 this link is a forward-declaration (dangling links stay allowed); create it with \`${cliInvocation()} doc write ${commandToken(to)} --type <t>\`.`,
+    field: "to",
+    severity: "warning"
+  };
 }
 async function link2(argv2, deps2 = {}) {
   const stdout = deps2.stdout ?? ((s) => void process.stdout.write(s));
@@ -110073,7 +110570,7 @@ async function addLink(bundle, from, to, opts = {}) {
     maxAttempts: LINK_ADD_MAX_ATTEMPTS,
     buildCandidate: (source2, context3) => {
       const existing = source2;
-      sourceTypeAtWrite = docType2(existing);
+      sourceTypeAtWrite = docType3(existing);
       const already = parseLinks2(bundle, existing).some((l) => l.to === normalizedTo && l.text === text7);
       if (already) return { frontmatter: { ...existing.frontmatter }, body: existing.body };
       const trimmed = existing.body.replace(/\s*$/, "");
@@ -110188,7 +110685,7 @@ async function addQualifiedLink(bundle, from, to, opts = {}) {
     maxAttempts: LINK_ADD_MAX_ATTEMPTS,
     buildCandidate: (source2, context3) => {
       const existing = source2;
-      sourceTypeAtWrite = docType2(existing);
+      sourceTypeAtWrite = docType3(existing);
       const already = parseQualifiedLinks(existing).some(
         (l) => l.ref?.alias === finalAlias && l.ref.id === id && l.text === text7
       );
@@ -110570,6 +111067,7 @@ var init_link = __esm({
     init_command_spec();
     init_output2();
     init_invocation();
+    init_write_findings();
     init_src();
     init_bundle_bindings();
     init_actor();
@@ -112630,8 +113128,6 @@ async function newCommand(argv2, deps2 = {}) {
     stdout(renderKindHelp(projectKindForAuthoring(okfVersion, kind2), registry2, cliInvocation()));
     return;
   }
-  const authoringKind = projectKindForAuthoring(okfVersion, kind2);
-  const declaredFields = [...authoringKind.fields.required, ...authoringKind.fields.optional];
   const fieldNames = kindInputFieldNames(okfVersion, kind2).filter((f) => f !== "actor" && f !== "link");
   const fieldOptions = Object.fromEntries(
     fieldNames.map((f) => [f, { type: "string", multiple: true }])
@@ -112649,9 +113145,10 @@ async function newCommand(argv2, deps2 = {}) {
       if (err?.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") {
         const raw = /'([^']+)'/.exec(err.message)?.[1] ?? "";
         const field = raw.replace(/^--?/, "");
+        const { kind: governs, declared } = kindFieldsUndeclaredFinding(okfVersion, kind2, [field]).details;
         throw new CliError(
           "USAGE",
-          `unknown field(s) for kind '${kind2.governs}': ${field}` + (declaredFields.length > 0 ? ` (declared: ${declaredFields.join(", ")})` : " (this kind declares no fields)") + ` \u2014 to ADD it to the '${kind2.governs}' kind: \`${cliInvocation()} kind field ${commandToken(kind2.governs)} add ${commandToken(field)}\` (then re-run).`,
+          `unknown field(s) for kind '${governs}': ${field}` + (declared.length > 0 ? ` (declared: ${declared.join(", ")})` : " (this kind declares no fields)") + ` \u2014 to ADD it to the '${governs}' kind: \`${cliInvocation()} kind field ${commandToken(governs)} add ${commandToken(field)}\` (then re-run).`,
           { help: `${cliInvocation()} kinds` }
         );
       }
@@ -112774,7 +113271,9 @@ async function newCommand(argv2, deps2 = {}) {
   const conventionWarnings = registry2.warnings.filter(
     (warning) => warning.message.startsWith(conventionWarningPrefix)
   );
-  if (conventionWarnings.length > 0) receipt5.warnings = conventionWarnings;
+  const findings = await writeFindings(bundle, saved, registry2, void 0);
+  const warnings = [...conventionWarnings, ...findings];
+  if (warnings.length > 0) receipt5.warnings = warnings;
   if (result3.guidance.length > 0) receipt5.guidance = result3.guidance;
   if (targetId !== id) {
     receipt5.note = `id prefixed with the '${kind2.governs}' kind's path \u2192 '${targetId}' (you passed '${id}')`;
@@ -112784,9 +113283,9 @@ async function newCommand(argv2, deps2 = {}) {
   let finalVersion = result3.version;
   let firstLinkFailure;
   for (const { type, target: target3 } of parsedLinks) {
-    const warnings = [];
+    const warnings2 = [];
     if (kind2.links && Object.keys(kind2.links).length > 0 && !hasOwn4(kind2.links, type)) {
-      warnings.push({
+      warnings2.push({
         code: "LINK_TYPE_UNDECLARED_FOR_KIND",
         message: `'${type}' is not declared in the '${kind2.governs}' kind's link vocabulary (declared: ${Object.keys(kind2.links).join(", ")}) \u2014 added anyway.`,
         field: "text",
@@ -112796,13 +113295,13 @@ async function newCommand(argv2, deps2 = {}) {
     try {
       const added = await addLink(bundle, saved.id, target3, { text: type, actor });
       finalVersion = added.version;
-      if (added.warnings) warnings.push(...added.warnings);
+      if (added.warnings) warnings2.push(...added.warnings);
       linkResults.push({
         type,
         target: target3,
         changed: added.changed,
         href: added.href,
-        ...warnings.length > 0 ? { warnings } : {}
+        ...warnings2.length > 0 ? { warnings: warnings2 } : {}
       });
       satisfiedOutboundTypes.add(type);
     } catch (err) {
@@ -112811,7 +113310,7 @@ async function newCommand(argv2, deps2 = {}) {
         type,
         target: target3,
         error: { code: classified.code, message: classified.message },
-        ...warnings.length > 0 ? { warnings } : {}
+        ...warnings2.length > 0 ? { warnings: warnings2 } : {}
       });
       if (!firstLinkFailure) firstLinkFailure = classified;
     }
@@ -112819,7 +113318,7 @@ async function newCommand(argv2, deps2 = {}) {
   if (parsedLinks.length > 0) receipt5.links = linkResults;
   receipt5.version = finalVersion;
   if (isLegacyPageDoc(saved.frontmatter)) receipt5.hint = LEGACY_PAGE_TYPE_HINT;
-  const help2 = [`${cliInvocation()} doc read ${commandToken(saved.id)}`];
+  const help2 = [`${cliInvocation()} doc read ${commandToken(saved.id)}`, ...writeFindingsHelp(findings)];
   const HINTS_PER_DIRECTION = 3;
   for (const { source: source2, linkType } of inboundLinkDecls(registry2, kind2).slice(0, HINTS_PER_DIRECTION)) {
     help2.push(
@@ -112861,6 +113360,7 @@ var init_new = __esm({
     init_command_spec();
     init_output2();
     init_invocation();
+    init_write_findings();
     init_mutate();
     init_kind_authoring();
     init_legacy_page2();
@@ -112885,6 +113385,8 @@ The kind's declared body 'sections' (if any) are scaffolded as empty '# Heading'
 'path' prefix (if any) is prepended onto <id> unless <id> already carries it. Validation is
 STRICT: a missing required field, a disallowed enum value, or a value that does not match the
 field's declared type (fields.types) rejects the write (exit 2) rather than writing-with-a-warning.
+Links in the body that will not register, or whose target does not exist yet, are named in the
+receipt's warnings (LINK_NOT_RECOGNIZED, LINK_TARGET_ABSENT) without refusing the create.
 A typed number, integer, latitude, longitude, or boolean field is stored as that YAML type
 (--latitude 43.1 stores the number 43.1; pass a negative number as --longitude=-77.4); a
 string-list or https-url-list field is always stored as a list, even from one flag. An integer
@@ -114852,8 +115354,8 @@ async function ordinaryDirectory(value, home2, bundle) {
 async function localBundle(dir, cwd = process.cwd(), home2 = homedir37()) {
   const target3 = await resolveLocalBundleTarget(dir, cwd);
   assertBundleOutsidePrivateState(target3.canonicalRoot, home2);
-  const facts = await bundleHomeAt(target3.canonicalRoot, { home: typeof home2 === "string" ? home2 : homedir37() });
-  if (facts.home === "hosted") throw refuse2("hosted_local_execution_not_supported");
+  const facts2 = await bundleHomeAt(target3.canonicalRoot, { home: typeof home2 === "string" ? home2 : homedir37() });
+  if (facts2.home === "hosted") throw refuse2("hosted_local_execution_not_supported");
   if (process.platform !== "darwin" && process.platform !== "linux") throw refuse2("unsupported_supervision_platform");
   return target3.canonicalRoot;
 }
@@ -116980,12 +117482,12 @@ async function status(argv2, deps2 = {}) {
     stdout(render(record19, resolveMode(values)));
     return;
   }
-  const facts = await bundleHomeAt(await realpath13(bundle.root), { home: home2 });
-  if (facts.home === "git") {
-    const block = await gitBoardSyncBlock(facts.board);
-    const record19 = { home: "git", sync: block, ...unboundCopyOf(facts), ...out };
+  const facts2 = await bundleHomeAt(await realpath13(bundle.root), { home: home2 });
+  if (facts2.home === "git") {
+    const block = await gitBoardSyncBlock(facts2.board);
+    const record19 = { home: "git", sync: block, ...unboundCopyOf(facts2), ...out };
     if (block.state !== "clean") {
-      const first = block.conflicts ? (await unsettledConflicts(facts.board.top, resolveBundleKey(facts.board.top)))[0] : void 0;
+      const first = block.conflicts ? (await unsettledConflicts(facts2.board.top, resolveBundleKey(facts2.board.top)))[0] : void 0;
       const row5 = first ? unsettledRow(first, cliInvocation(), values.dir) : void 0;
       const onlySaved = block.state === "needs_decision" && !block.ahead && !block.uncommitted;
       record19.help = [
@@ -116996,7 +117498,7 @@ async function status(argv2, deps2 = {}) {
     stdout(render(record19, resolveMode(values)));
     return;
   }
-  stdout(render({ home: "local", sync: "none (local only)", ...unboundCopyOf(facts), ...out }, resolveMode(values)));
+  stdout(render({ home: "local", sync: "none (local only)", ...unboundCopyOf(facts2), ...out }, resolveMode(values)));
 }
 var STATUS_USAGE, DEFAULT_LIMIT4;
 var init_status2 = __esm({
@@ -117359,7 +117861,7 @@ __export(util_exports, {
   own: () => own4,
   parsedType: () => parsedType,
   partial: () => partial,
-  pick: () => pick,
+  pick: () => pick2,
   prefixIssues: () => prefixIssues,
   primitiveTypes: () => primitiveTypes,
   promiseAllObject: () => promiseAllObject,
@@ -117659,7 +118161,7 @@ function optionalKeys(shape3) {
     return shape3[k]._zod.optin !== void 0 && shape3[k]._zod.optout === "optional";
   });
 }
-function pick(schema, mask) {
+function pick2(schema, mask) {
   const currDef = schema._zod.def;
   const checks = currDef.checks;
   const hasChecks = checks && checks.length > 0;
@@ -154496,10 +154998,10 @@ function unboundCopyGuard(copy, home2, folder, options) {
     freshen: async () => adopted?.freshen(),
     async admit(method, args) {
       if (!adopted) {
-        const facts = await bundleHomeAt(copy.folder, { home: home2 });
-        if (facts.home === "hosted") adopted = checkoutGuard(facts.binding, home2, folder, options);
-        else if (facts.home === "local" && facts.copy) {
-          throw unboundCopyRefusal(facts.copy, "FORBIDDEN", `'mcp write' refused: ${copy.folder} is a copy of a hosted checkout of '${facts.copy.marker.bundle_id}' that is not bound here, so nothing written in it reaches the host`, { command: "mcp write" });
+        const facts2 = await bundleHomeAt(copy.folder, { home: home2 });
+        if (facts2.home === "hosted") adopted = checkoutGuard(facts2.binding, home2, folder, options);
+        else if (facts2.home === "local" && facts2.copy) {
+          throw unboundCopyRefusal(facts2.copy, "FORBIDDEN", `'mcp write' refused: ${copy.folder} is a copy of a hosted checkout of '${facts2.copy.marker.bundle_id}' that is not bound here, so nothing written in it reaches the host`, { command: "mcp write" });
         } else return;
       }
       return adopted.admit(method, args);
@@ -154762,8 +155264,8 @@ function createCatalogMcpWorkspaceResolver(options = {}) {
   };
   const checkoutOf2 = async (selector2) => {
     const { target: target3 } = await select(selector2, async () => void 0);
-    const facts = await bundleHomeAt(target3.canonicalRoot, { home: home2 });
-    return facts.home === "hosted" ? facts.binding : { stop: "no_host_operations", home: facts.home };
+    const facts2 = await bundleHomeAt(target3.canonicalRoot, { home: home2 });
+    return facts2.home === "hosted" ? facts2.binding : { stop: "no_host_operations", home: facts2.home };
   };
   const connect = async (binding2) => {
     const resume2 = commandFragment`${cliInvocation()} login --host ${commandToken(bindingHostArgument(binding2))}`;
@@ -157439,17 +157941,17 @@ import { homedir as homedir46 } from "node:os";
 import { parseArgs as parseArgs33 } from "node:util";
 import path66 from "node:path";
 async function bundleFreshness(root, userHome, now, signIn, env) {
-  const facts = await bundleHomeAt(root, { home: userHome });
-  if (facts.home === "hosted") {
-    const age = ageMs((await readFreshness(userHome, facts.binding.checkout_id).catch(() => null))?.pulled_at ?? null, now);
+  const facts2 = await bundleHomeAt(root, { home: userHome });
+  if (facts2.home === "hosted") {
+    const age = ageMs((await readFreshness(userHome, facts2.binding.checkout_id).catch(() => null))?.pulled_at ?? null, now);
     const pulled = age === null ? "never pulled" : `pulled ${describeAge(age)} ago`;
-    const key4 = `${facts.binding.origin} ${facts.binding.audience}`;
-    if (!signIn.has(key4)) signIn.set(key4, storedSessionMayNeedSignIn(userHome, facts.binding, env, now.getTime()).catch(() => false));
+    const key4 = `${facts2.binding.origin} ${facts2.binding.audience}`;
+    if (!signIn.has(key4)) signIn.set(key4, storedSessionMayNeedSignIn(userHome, facts2.binding, env, now.getTime()).catch(() => false));
     return { home: "hosted", freshness: await signIn.get(key4) ? `${pulled}; may need sign-in` : pulled };
   }
-  if (facts.home === "git") {
-    if (!facts.board.shared) return { home: "git", freshness: "not shared yet" };
-    const age = ageMs(await lastFetch(facts.board.top).catch(() => null), now);
+  if (facts2.home === "git") {
+    if (!facts2.board.shared) return { home: "git", freshness: "not shared yet" };
+    const age = ageMs(await lastFetch(facts2.board.top).catch(() => null), now);
     return { home: "git", freshness: age === null ? "never fetched" : `fetched ${describeAge(age)} ago` };
   }
   return { home: "local", freshness: "local only" };
@@ -159184,10 +159686,10 @@ function homeOf(deps2) {
 }
 async function locate(sub, rawId, dir, deps2) {
   const target3 = await resolveLocalBundleTarget(dir, deps2.cwd ?? process.cwd());
-  const facts = await bundleHomeAt(target3.canonicalRoot, { home: homeOf(deps2) });
-  if (facts.home !== "hosted") {
-    throw new CliError("USAGE", `view ${sub} reaches a hosted checkout's host; this is a ${facts.home} bundle, whose View pages are plain files: ${sub === "read" ? "read" : "edit"} the file directly`, {
-      details: { reason: "not_a_hosted_checkout", home: facts.home },
+  const facts2 = await bundleHomeAt(target3.canonicalRoot, { home: homeOf(deps2) });
+  if (facts2.home !== "hosted") {
+    throw new CliError("USAGE", `view ${sub} reaches a hosted checkout's host; this is a ${facts2.home} bundle, whose View pages are plain files: ${sub === "read" ? "read" : "edit"} the file directly`, {
+      details: { reason: "not_a_hosted_checkout", home: facts2.home },
       help: `${cliInvocation()} view list --dir ${commandToken(target3.canonicalRoot)} names each View; its page is the registration's entry file`
     });
   }
@@ -159195,10 +159697,10 @@ async function locate(sub, rawId, dir, deps2) {
   const registryId = await resolveConceptIdCliArgument(bundle, rawId);
   if (!isAnyRegistryId(registryId)) {
     throw new CliError("USAGE", `'${registryId}' is not a View registration id (views-registry/<name>)`, {
-      help: `${cliInvocation()} view list --dir ${commandToken(facts.binding.path)}`
+      help: `${cliInvocation()} view list --dir ${commandToken(facts2.binding.path)}`
     });
   }
-  return { binding: facts.binding, root: target3.canonicalRoot, registryId };
+  return { binding: facts2.binding, root: target3.canonicalRoot, registryId };
 }
 async function hostRegistration(connection, located) {
   const { binding: binding2, registryId } = located;
@@ -163602,8 +164104,8 @@ async function op(argv2, deps2 = {}) {
 }
 async function homeOf2(dir, deps2) {
   const target3 = await resolveLocalBundleTarget(dir, deps2.cwd ?? process.cwd());
-  const facts = await bundleHomeAt(target3.canonicalRoot, { home: deps2.hosted?.auth?.home ?? homedir56() });
-  return facts.home === "hosted" ? { home: "hosted", binding: facts.binding } : { home: facts.home };
+  const facts2 = await bundleHomeAt(target3.canonicalRoot, { home: deps2.hosted?.auth?.home ?? homedir56() });
+  return facts2.home === "hosted" ? { home: "hosted", binding: facts2.binding } : { home: facts2.home };
 }
 function noHostOperations(home2) {
   return `no host operations for a ${home2} bundle; use the typed verbs (${TYPED_VERBS}, ...)`;
@@ -163915,8 +164417,8 @@ async function checkoutOf(scope, deps2) {
     if (scope.dir === void 0 && error62 instanceof CliError && error62.code === "NOT_FOUND") return null;
     throw error62;
   }
-  const facts = await bundleHomeAt(canonicalRoot, { home: deps2.hosted?.auth?.home ?? homedir57() });
-  return facts.home === "hosted" ? facts.binding : null;
+  const facts2 = await bundleHomeAt(canonicalRoot, { home: deps2.hosted?.auth?.home ?? homedir57() });
+  return facts2.home === "hosted" ? facts2.binding : null;
 }
 async function openInboxSession(command, scope, deps2, resumeFor, options = {}) {
   const explicit = scope.host !== void 0 || scope.workspace !== void 0 || scope.bundle !== void 0;
@@ -164037,7 +164539,7 @@ async function inboxFailure(error62, session2, extra = {}) {
       case "invalid_input":
         return new CliError("USAGE", message, { details, help: `${cliInvocation()} notify --help` });
       case "attention_disabled":
-        return new CliError("FORBIDDEN", message, { details, help: "a workspace admin turns the inbox on for the workspace" });
+        return new CliError("FORBIDDEN", message, { details, help: "the inbox is turned off for this workspace: ask Superbee support to turn it on" });
       case "insufficient_scope":
       case "workspace_not_available":
       case "workspace_unsupported":
@@ -164397,17 +164899,17 @@ function itemIdOf(value, sub) {
   if (!ITEM_ID.test(value)) throw usage3(`'${value}' is not an item id as inbox list reports it`, sub);
   return value;
 }
-function sender(facts, display, you) {
-  const yours = facts.principalId === you;
+function sender(facts2, display, you) {
+  const yours = facts2.principalId === you;
   return {
     person: yours ? "you" : display.personName ?? "a workspace member",
-    principal: facts.principalId ?? null,
-    ...facts.surface ? { surface: facts.surface } : {},
+    principal: facts2.principalId ?? null,
+    ...facts2.surface ? { surface: facts2.surface } : {},
     ...display.firstPartyName ? { app: display.firstPartyName } : {},
     ...display.clientName ? { client: display.clientName } : {},
     ...display.agentName ? { agent: display.agentName } : {},
-    ...facts.via ? { tool_label: facts.via } : {},
-    ...facts.job ? { job: facts.job } : {}
+    ...facts2.via ? { tool_label: facts2.via } : {},
+    ...facts2.job ? { job: facts2.job } : {}
   };
 }
 function labelOf(entry) {
@@ -166056,28 +166558,28 @@ async function rootTitle(folder) {
 function cleanName(name) {
   return stripHostText(name, 128);
 }
-async function assertPublishable(canonical2, facts) {
-  if (facts.home === "hosted") {
-    throw new CliError("FORBIDDEN", `${canonical2} is already a hosted checkout of '${facts.binding.bundle_id}' on ${facts.binding.origin}`, {
-      details: { reason: "already_hosted", folder: canonical2, bundle_id: facts.binding.bundle_id, host: facts.binding.origin },
+async function assertPublishable(canonical2, facts2) {
+  if (facts2.home === "hosted") {
+    throw new CliError("FORBIDDEN", `${canonical2} is already a hosted checkout of '${facts2.binding.bundle_id}' on ${facts2.binding.origin}`, {
+      details: { reason: "already_hosted", folder: canonical2, bundle_id: facts2.binding.bundle_id, host: facts2.binding.origin },
       help: `${cliInvocation()} sync --dir ${commandToken(canonical2)}`
     });
   }
-  if (facts.copy) {
-    throw unboundCopyRefusal(facts.copy, "FORBIDDEN", `${canonical2} is a copy of a hosted checkout of '${facts.copy.marker.bundle_id}'; adopt it instead of publishing a second bundle`);
+  if (facts2.copy) {
+    throw unboundCopyRefusal(facts2.copy, "FORBIDDEN", `${canonical2} is a copy of a hosted checkout of '${facts2.copy.marker.bundle_id}'; adopt it instead of publishing a second bundle`);
   }
-  if (facts.home === "git" && facts.board.channel === "in-tree") {
-    throw new CliError("FORBIDDEN", `${canonical2} is committed with the code on ${facts.board.branch ?? "this branch"}; publishing it would leave two authorities`, {
+  if (facts2.home === "git" && facts2.board.channel === "in-tree") {
+    throw new CliError("FORBIDDEN", `${canonical2} is committed with the code on ${facts2.board.branch ?? "this branch"}; publishing it would leave two authorities`, {
       details: { reason: "in_tree_board", folder: canonical2 },
       help: `move it to its own board branch first: ${cliInvocation()} sync --establish`
     });
   }
   const dotGit = await lstat17(path79.join(canonical2, ".git")).catch(() => null);
   if (dotGit) {
-    const linkedBoard = facts.home === "git" && facts.board.channel === "branch" && dotGit.isFile() && isLinkedWorktree2(canonical2);
+    const linkedBoard = facts2.home === "git" && facts2.board.channel === "branch" && dotGit.isFile() && isLinkedWorktree2(canonical2);
     if (!linkedBoard) {
-      throw new CliError("FORBIDDEN", `${canonical2} is a Git ${dotGit.isFile() ? "worktree" : "repository"} that publish cannot unbind${facts.home === "git" ? " (a clone of the board branch, not a project's board worktree)" : ""}`, {
-        details: { reason: facts.home === "git" ? "board_clone" : "git_working_tree", folder: canonical2 },
+      throw new CliError("FORBIDDEN", `${canonical2} is a Git ${dotGit.isFile() ? "worktree" : "repository"} that publish cannot unbind${facts2.home === "git" ? " (a clone of the board branch, not a project's board worktree)" : ""}`, {
+        details: { reason: facts2.home === "git" ? "board_clone" : "git_working_tree", folder: canonical2 },
         help: "copy the bundle's files (without .git) into a new folder and publish that, or publish from the project whose board worktree this is"
       });
     }
@@ -166316,10 +166818,10 @@ async function publish(argv2, partial2 = {}) {
   const located = await resolveLocalBundleTarget(values.dir, deps2.cwd);
   const canonical2 = located.canonicalRoot;
   assertBundleOutsidePrivateState(canonical2, home2);
-  const facts = await bundleHomeAt(canonical2, { home: home2 });
-  await assertPublishable(canonical2, facts);
+  const facts2 = await bundleHomeAt(canonical2, { home: home2 });
+  await assertPublishable(canonical2, facts2);
   refuseTreePrivateState(canonical2, "publish --to hosted", String(commandFragment`${cliInvocation()} publish --to hosted${values.dir !== void 0 ? commandFragment` --dir ${commandToken(canonical2)}` : commandFragment``}`));
-  const board = facts.home === "git" ? facts.board : null;
+  const board = facts2.home === "git" ? facts2.board : null;
   if (values.yes && board?.channel === "branch") {
     try {
       fetchOrigin(board.top);
@@ -166375,7 +166877,7 @@ async function publish(argv2, partial2 = {}) {
           publish: "preview",
           ready: blockers.length === 0,
           folder: canonical2,
-          home: facts.home,
+          home: facts2.home,
           to: {
             host: target3?.origin ?? null,
             ...chosen ? { host_from: chosen.source } : ambiguous ? { signed_in_hosts: ambiguous.details?.hosts } : {},
@@ -166459,7 +166961,7 @@ async function publish(argv2, partial2 = {}) {
             provenance: { carried: plan.provenance.carried, dropped: plan.provenance.dropped }
           },
           folder: canonical2,
-          home: facts.home,
+          home: facts2.home,
           checkout: `not converted: ${uncheckable}`,
           diverges: `this folder${board ? " and its Git board" : ""} and the hosted bundle '${bundleId2}' are now separate copies: edits here do not reach the hosted bundle`,
           help: [hostedListCommand(target3)]