fix(docs): a documentation link names a page that exists, and a gate refuses the next one that does not (#1643)

[cjimti]

docs/scripts/running.md linked ../architecture/call-catalog.md. There is no docs/architecture/ directory and no page named call-catalog.md anywhere; the link arrived in 87b272f alongside the prose it belongs to, pointing at a page that was planned and never written. mkdocs build --strict (.github/workflows/docs.yml:39) fails on an unresolved link, so the Deploy Documentation workflow had failed on every push since 2026-09-05 04:46 UTC and the site was serving pre-1.130.3 content.

The link now names the "Call Catalog Configuration" section of docs/server/configuration.md:677. That is where docs/portal/admin-sessions.md:56 already sends a reader for the same noun, and it holds the ### The one caller you do not name subsection, which links back to docs/scripts/running.md — so the two pages describe the script-run exclusion to each other rather than at a page that does not exist.

A second link was broken where no gate could see it

MkDocs reports an unresolved anchor at info level rather than warning, and mkdocs.yml sets no validation: block, so --strict passes one. docs/reference/tools-api.md:334 linked [`fetch`](#fetch) on a page that has no fetch heading: a reader following it landed at the top of the same page with no error anywhere. fetch is documented at docs/server/tools.md:664, which the link now names.

Both classes now fail before a push

TestDocsMarkdownLinksResolve (test/structure/verify_test.go) walks docs/**/*.md and resolves every inline link: the path must name a file that exists and stay inside the repository, and a fragment on a Markdown target must be an anchor that file's headings actually produce.

scripts/doc-check.sh delegates to it as hard gate 2, the same way its orphaned-page gate delegates to TestDocsPagesInNavOrExcluded — the rule is the one MkDocs applies, and a bash reimplementation would drift from it. Living in Go is what gives the gate its reach: make verify never builds the documentation, so the path half is now enforced by go test ./... in both make verify and the CI unit lane instead of only by the deploy workflow after a merge, and the anchor half is enforced for the first time anywhere.

The gate reproduces python-markdown's behavior rather than approximating it, because each of these differences produces a false failure on this repository's docs:

• A fenced code block closes only on the marker that opened it. Closing ``` on ~~~ desynchronizes the walk on the indented fences inside pymdownx.tabbed blocks and hides every heading after them — 6 false failures across docs/server/ and docs/reference/.
• A heading slug drops backticks and emphasis but keeps underscores. ### manage_table anchors at manage_table, and stripping _ as an emphasis marker breaks every tool-name link in docs/server/tools.md.
• A repeated heading takes _1, _2. Seven pages under docs/ repeat one, ## Configuration twice being the common case, so #configuration_1 is a link that resolves.

Verification

• mkdocs build --strict exits 0 with zero warnings, which is the exact command the deploy workflow runs.
• TestDocsMarkdownLinksResolve passes on this tree, and fails naming file, line and target when either link is reverted: a missing path and a missing anchor are reported as distinct failures with distinct remedies.
• On the duplicate-slug case it accepts #configuration_1 and rejects #configuration_9.
• make doc-check reports all five hard gates OK. make verify is green.

docs/llms.txt and docs/llms-full.txt are unchanged: neither carries either link, and no documented behavior changed.

Closes #1643

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.59%. Comparing base (fcd4dc8) to head (1c47b14).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1645   +/-   ##
=======================================
  Coverage   91.59%   91.59%           
=======================================
  Files         777      777           
  Lines       77877    77877           
=======================================
+ Hits        71332    71335    +3     
+ Misses       4275     4273    -2     
+ Partials     2270     2269    -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.