docs: fix 34 broken in-doc cross-references; extend link-check CI (closes #62)

[initializ-mk]

Summary

Sibling of #58 / #61. The same canonical-name mismatch and relative-path errors that broke 21 README links also broke 34 in-doc cross-references across 14 doc files. A reader on docs/core-concepts/runtime-engine.md who clicked "Memory" or "Tools" hit a GitHub 404; docs/security/overview.md alone had 10 broken links to a half-dozen renamed siblings.

Audit

before:  34 broken across 14 doc files
after:    0 broken; 37 files checked  (1 README + 36 docs)

The link-check workflow (added in #61) is extended to walk docs/**/*.md in addition to README.md, so this can't regress on future PRs.

Causes — same shape as #58

Three patterns account for all 34 occurrences:

Cause 1 — Missing ../ (21 links)

Authors wrote paths as if relative to docs/ root, but Markdown link resolution is relative to the file's directory. From docs/core-concepts/hooks.md, a link to security/guardrails.md resolves to docs/core-concepts/security/guardrails.md (does not exist), not the actual docs/security/guardrails.md. Fix: add the ../.

Affected files:

• docs/core-concepts/channels.md — 1 link
• docs/core-concepts/hooks.md — 2 links
• docs/core-concepts/how-forge-works.md — 2 links
• docs/core-concepts/runtime-engine.md — 3 links
• docs/core-concepts/skill-md-format.md — 1 link
• docs/core-concepts/tools-and-builtins.md — 5 links
• docs/skills/embedded-skills.md — 2 links
• docs/skills/skills-cli.md — 1 link
• docs/skills/writing-custom-skills.md — 2 links
• docs/reference/cli-reference.md — 1 link
• docs/reference/web-dashboard.md — 1 link
• docs/deployment/production-checklist.md — 1 link

(Some same-directory references — like runtime.md from channels.md — also got their file extension fixed: runtime.md → runtime-engine.md.)

Cause 2 — Canonical-name mismatch in docs/security/overview.md (10 links)

This single file accounts for 10/34 (29%) of the breakage. Pre-dated the doc rename to *-control, *-management, *-signing and never got updated; also contained four ../*.md references to flat names that never existed in the post-reorg tree:

Was	Now
egress.md (×2)	egress-control.md
secrets.md (×2)	secret-management.md
signing.md (×2)	build-signing.md
../architecture.md	../core-concepts/how-forge-works.md
../tools.md	../core-concepts/tools-and-builtins.md
../skills.md	../skills/writing-custom-skills.md
../commands.md	../reference/cli-reference.md

Cause 3 — Wrong base (3 links)

• docs/getting-started/contributing.md linked to ../README.md (= docs/README.md, missing). Fix: ../../README.md.
• command-integration.md cross-references in deployment/production-checklist.md and getting-started/contributing.md needed ../reference/ prefix.

Anchor preservation

Several broken links carried #anchor suffixes (e.g. [external auth](runtime.md#external-authentication)). The fixer is a small Python script that uses a regex with an optional anchor group and preserves the fragment when rewriting the path, so deep links remain pointed at the right heading.

Workflow change

.github/workflows/docs-links.yaml:

• Renamed job readme-links → doc-links.
• Extended the script to walk docs/**/*.md in addition to README.md.
• Same fail-on-broken behavior, same path filter (already covered docs/** from docs: fix 21 broken doc links in README (closes #58) #61).
• Local dry-run: Checked 37 doc files: all relative .md links resolve.

Acceptance criteria from #62

• Every relative .md link inside docs/** resolves to a file that exists on main.
• CI link-check is extended to cover docs/**/*.md.
• No new doc files; every target maps mechanically to an existing one.

Out of scope

• Anchor-fragment validation against actual headings inside linked files. Could be a separate enhancement.
• External (https://...) link rot — different tooling.

Cross-reference

• Broken doc links in main README.md (21 of 25 are 404s) #58 — parent issue (README links). Fixed by docs: fix 21 broken doc links in README (closes #58) #61.
• docs: fix 21 broken doc links in README (closes #58) #61 — added .github/workflows/docs-links.yaml; this PR extends it.

Diff stats

 .github/workflows/docs-links.yaml        | 33 +++++++++++++++++++-------------
 docs/core-concepts/*.md                  | 28 lines across 6 files
 docs/skills/*.md                         | 10 lines across 3 files
 docs/reference/*.md                      |  4 lines across 2 files
 docs/security/overview.md                | 20 lines
 docs/deployment/production-checklist.md  |  2 lines
 docs/getting-started/contributing.md     |  2 lines
 15 files changed, 53 insertions(+), 46 deletions(-)

Every change is a link substitution. No prose modified.