feat(ci): resolve docs #anchor links against real headings (#7484)

.github/workflows/check-links.yml

@@ -13,6 +13,13 @@ name: Check Links
 # advisory gate does not get to consume merge-queue capacity. If it is ever
 # promoted into the required set, `merge_group` MUST be added in the same
 # change or the queue stalls on a required check that never reports (#6121).
+#
+# ⚠️ This job checks a link's FILE, never its `#anchor` — `lychee.toml` sets
+# `include_fragments = "none"`, and a link to a heading that does not exist is
+# reported `[200] OK` here (measured, #7484). Do NOT read a green run as
+# "the anchors are fine". The fragment half is owned by `pnpm check:doc-anchors`
+# in `lint.yml`, which is REQUIRED where this lane is advisory; `lychee.toml`'s
+# `include_fragments` comment records why the enum is not the fix.
 on:
  workflow_dispatch:
  pull_request:

.github/workflows/lint.yml

@@ -169,6 +169,24 @@ jobs:
  - name: Doc/skill authoring guard
  run: pnpm check:doc-authoring
 
+ # #7484 docs anchors: `lychee.toml` sets `include_fragments = "none"`, so
+ # the `Check Documentation Links` job resolves a link's FILE and never its
+ # `#anchor` — measured with the pinned lychee 0.24.2 under the CI argv, a
+ # link to a heading that does not exist is reported `[200] OK`. So a
+ # cross-file anchor was a two-sided invariant with no owner: rename the
+ # heading, leave the inbound link, ship green. This resolves every internal
+ # `#fragment` against the destination page's real heading ids, computed
+ # with `github-slugger` — the same package fumadocs-core renders the site
+ # with, so the gate and the renderer cannot disagree about a slug.
+ #
+ # It lives in this job rather than in check-links.yml for two reasons: it
+ # needs a workspace install (that job is deliberately a checkout plus two
+ # dependency-free `node` checks), and it is REQUIRED where that lane is
+ # advisory. The four anchors that were already dead were fixed in the same
+ # PR, so this ships with no baseline and no allowlist.
+ - name: Docs anchors resolve to real headings
+ run: pnpm check:doc-anchors
+
  # #4851: the docs-accuracy-audit workflow carries its default scope inline
  # (a workflow script runs in a vm with no filesystem, so it cannot enumerate
  # content/docs/ itself). Hand-kept, that list rotted in BOTH directions —

content/docs/automation/flows.mdx

@@ -237,7 +237,7 @@ Replace them per branch — they are different mechanisms, not one rename:
 
 | Retired shape | Use instead |
 | --- | --- |
-| `actionType: 'email'` (+ `template` / `recipients` / `variables`) | a [`notify` node](#notify) — it delivers through the messaging service: the in-app inbox by default, real email once `@objectstack/plugin-email` is installed |
+| `actionType: 'email'` (+ `template` / `recipients` / `variables`) | a [`notify` node](#node-types) — it delivers through the messaging service: the in-app inbox by default, real email once `@objectstack/plugin-email` is installed |
 | `actionType: 'slack'` | a `connector_action` node with the Slack connector, or an `http` node posting to an incoming webhook |
 | `actionType: 'my_fn'` (shorthand) | `function: 'my_fn'` — the conversion moves it for you |
 | inline `config.script` | move the logic into a registered function and call it via `config.function` |

content/docs/concepts/metadata-lifecycle.mdx

@@ -74,7 +74,7 @@ any production path: every `new LayeredRepository(...)` call site is a test
 When a user edits a view in Studio:
 
 1. Studio calls `PUT /api/v1/meta/view/case_grid` (REST).
-2. `protocol.ts:saveMetaItem()` runs the two-tier gate (see [overlay whitelist](#overlay-whitelist)): an item that already exists as a packaged artifact requires `MetadataTypeRegistryEntry.allowOrgOverride`; a brand-new item requires `allowRuntimeCreate` **or** `allowOrgOverride`.
+2. `protocol.ts:saveMetaItem()` runs the two-tier gate (see [overlay whitelist](#overlay-whitelist-shared-db-tenancy-invariant)): an item that already exists as a packaged artifact requires `MetadataTypeRegistryEntry.allowOrgOverride`; a brand-new item requires `allowRuntimeCreate` **or** `allowOrgOverride`.
 3. If allowed, the call lands on `MetadataRepository.put(ref, body, { parentVersion, actor })`.
 4. The repository:
  - Verifies `parentVersion` matches the current head (`ConflictError` on mismatch).

content/docs/permissions/authentication.mdx

@@ -72,7 +72,7 @@ Under `--json` this command is the CLI's **one declared NDJSON exception**: it
 emits the verification-URL record before you authorize and the result record
 afterwards, one compact JSON document per line, so stdout must be parsed line by
 line rather than with a single `JSON.parse`. See
-[the CLI reference](/docs/deployment/cli#os-login--json-is-ndjson--the-one-exception).
+[the CLI reference](/docs/deployment/cli#os-login---json-is-ndjson--the-one-exception).
 
 The email/password path is still supported for CI and non-interactive shells:
 

content/docs/protocol/kernel/http-protocol.mdx

@@ -761,7 +761,7 @@ POST /api/v1/batch
 ```
 
 The typed SDK surface for this route is
-[`client.data.batchTransaction(operations)`](/docs/api/client-sdk#clientdata--crud-operations).
+[`client.data.batchTransaction(operations)`](/docs/api/client-sdk#clientdata--crud--batch).
 
 Each operation specifies an `action` (`create`, `update`, or `delete`), the
 target `object`, and the relevant `data` / `id`. A field value of

lychee.toml

@@ -34,6 +34,22 @@ max_retries = 2
 # ⛔ Not a boolean on the pinned lychee (0.24.2) -- it takes one of
 # none | anchor-only | text-only | full, and a bare `false` is a HARD parse
 # error. "none" preserves the original `false` semantics: fragments unchecked.
+#
+# ⚠️ "none" means a link to a heading that DOES NOT EXIST is reported
+# `[200] ✅ OK` -- measured with 0.24.2 under this repo's CI argv (#7484). Read
+# that as a scope statement, not a gap: since #7484 the fragment half of an
+# internal link is owned by `pnpm check:doc-anchors`
+# (scripts/check-doc-anchors.mjs, a REQUIRED step in Lint & Type Check), which
+# resolves every `#fragment` in content/**, README.md and ARCHITECTURE.md
+# against the destination page's real heading ids.
+#
+# ⛔ Do not "fix" this by flipping the enum. `include_fragments` is global: it
+# cannot be scoped to internal links, so it would pull in external-anchor
+# checking -- which needs the remote page fetched and parsed, the one thing the
+# `--offline` lane exists to never do. It also cannot know how Fumadocs slugs a
+# heading (github-slugger + a `[#custom-id]` suffix), so it would disagree with
+# the rendered site. Both reasons are recorded in check-doc-anchors.mjs's
+# header, with the measurement behind them.
 include_fragments = "none"
 
 # Verbose output

package.json

@@ -36,6 +36,7 @@
  "check:nul-bytes": "node scripts/check-nul-bytes.mjs --self-test && node scripts/check-nul-bytes.mjs",
  "check:stack-collection-maps": "node scripts/check-stack-collection-maps.mjs --self-test && node scripts/check-stack-collection-maps.mjs",
  "check:doc-authoring": "node scripts/check-doc-authoring.mjs --self-test && node scripts/check-doc-authoring.mjs",
+ "check:doc-anchors": "node scripts/check-doc-anchors.mjs --self-test && node scripts/check-doc-anchors.mjs",
  "check:docs-audit-scope": "node scripts/docs-audit/affected-docs.mjs --self-test && node scripts/docs-audit/check-audit-scope.mjs --self-test && node scripts/docs-audit/check-audit-scope.mjs",
  "check:role-word": "node scripts/check-role-word.mjs",
  "check:quick-reference-counts": "node scripts/check-quick-reference-counts.mjs --self-test && node scripts/check-quick-reference-counts.mjs",
@@ -102,6 +103,7 @@
  "@types/node": "^26.1.2",
  "@typescript-eslint/parser": "^8.65.0",
  "eslint": "^10.8.0",
+ "github-slugger": "2.0.0",
  "semver": "^7.8.5",
  "svelte": "^5.56.8",
  "tsup": "^8.5.1",