Broken doc links in main README.md (21 of 25 are 404s)

[initializ-mk]

Summary

The top-level README.md references 25 docs by relative path. 21 of them are 404s — the README links to canonical flat-named files like docs/runtime.md and docs/security/secrets.md, but the actual docs live under subdirectories with different names (docs/core-concepts/runtime-engine.md, docs/security/secret-management.md, etc.).

A newcomer clicking "Quick Start", "Installation", "Architecture", "Skills", "Tools", "Runtime", "Memory", "Channels", "Scheduling", "Egress Security", "Secrets", "Build Signing", "Commands", "Configuration", "Dashboard", "Deployment", "Hooks", "Plugins", or "Command Integration" from the README lands on a GitHub 404. That's a serious first-impression bug for the project's most visible doc.

This was first noticed in passing during the sync-docs runs for v0.10.0 (same canonical-name mismatch affects 34 in-doc links too; that's a separate but related cleanup). The README is the priority because it's the primary discovery surface.

Audit

Run inside the repo root:

python3 - <<'PY'
import re, os
text = open('README.md').read()
for m in re.finditer(r'\[([^\]]+)\]\(([^)]+\.md)(#[^)]*)?\)', text):
    label, target = m.group(1), m.group(2)
    if target.startswith('http'):
        continue
    resolved = os.path.normpath(os.path.join('.', target))
    print(('OK   ' if os.path.exists(resolved) else 'BAD  ') + f'[{label}]({target})')
PY

Result (May 2026, on main at v0.10.0): 21 BAD, 4 OK.

Concrete remap

The fix is mostly mechanical — point each broken README link at the doc that already exists. Suggested mapping:

README label	Current (broken) link	Should point to
Quick Start	docs/quickstart.md	docs/getting-started/quick-start.md
Installation	docs/installation.md	docs/getting-started/installation.md
Runtime	docs/runtime.md	docs/core-concepts/runtime-engine.md
Memory	docs/memory.md	docs/core-concepts/memory-system.md
Channels	docs/channels.md	docs/core-concepts/channels.md
Scheduling	docs/scheduling.md	docs/core-concepts/scheduling.md
Tools	docs/tools.md	docs/core-concepts/tools-and-builtins.md
Hooks	docs/hooks.md	docs/core-concepts/hooks.md
Egress Security	docs/security/egress.md	docs/security/egress-control.md
Secrets	docs/security/secrets.md	docs/security/secret-management.md
Build Signing	docs/security/signing.md	docs/security/build-signing.md
Commands	docs/commands.md	docs/reference/cli-reference.md
Configuration	docs/configuration.md	docs/getting-started/configuration.md (and/or docs/reference/forge-yaml-schema.md)
Dashboard	docs/dashboard.md	docs/reference/web-dashboard.md
Plugins	docs/plugins.md	docs/reference/framework-plugins.md
Command Integration	docs/command-integration.md	docs/reference/command-integration.md
Skills	docs/skills.md	No 1:1 match. Pick one of: docs/skills/skills-cli.md, docs/skills/writing-custom-skills.md, docs/skills/embedded-skills.md. Or create a docs/skills/README.md index that links to all three.
Architecture	docs/architecture.md	No direct match. Closest: docs/core-concepts/how-forge-works.md. May warrant a dedicated docs/architecture.md if the README intends an architecture-deep-dive distinct from "how it works".
Deployment	docs/deployment.md	No flat file; docs/deployment/ is a directory containing docker.md, kubernetes.md, monitoring.md, production-checklist.md. Either create docs/deployment/README.md as an index or link the README to one specific file (e.g. docs/deployment/kubernetes.md).

The four links currently working — docs/security/overview.md, docs/security/guardrails.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md — stay as-is.

Why this matters

• First-impression UX: a 404 from the README is the first thing a new user clicks. We've shipped a banner and badges (PR feat(slack): admit bot @mentions via allow_bot_ids, drop self always (closes #55) #56 / 008007e); broken docs underneath them undermines the polish.
• Search ranking: GitHub indexes README links into its search and sitemap. 21 broken links pull down the docs' overall discoverability and let third-party indexers (Google, useforge.ai sync) think the docs are missing.
• Documentation sync (/sync-docs): the sync-docs skill assumes README → docs link integrity. Every PR that touches docs currently surfaces these same 34 latent broken links plus the 21 README ones.

Proposed fix shape

Option A (smallest, recommended for first pass): one PR that only edits README.md, updating each broken relative link to the correct existing path. Three of the entries (Skills, Architecture, Deployment) need a content decision — either pick a target or stub an index file.

Option B (broader): same as A, plus add docs/<topic>/README.md index pages for each subdirectory so the URLs docs/skills/, docs/deployment/, docs/core-concepts/, docs/security/, docs/reference/, docs/getting-started/ render properly when linked.

Option C (broader still): also fix the 34 in-doc cross-references that share the same canonical-name mismatch (e.g. docs/core-concepts/runtime-engine.md links to tools.md and memory.md which don't exist by those names). Surface during the v0.10.0 sync-docs runs.

Acceptance criteria

• Every relative .md link in README.md resolves to a file that exists on main.

• A CI check (or pre-commit hook) catches future README link breakage before merge — for example:

  # tools/check-readme-links.sh
  python3 -c "
  import re, os, sys
  text = open('README.md').read()
  bad = []
  for m in re.finditer(r'\[([^\]]+)\]\(([^)]+\.md)(#[^)]*)?\)', text):
      t = m.group(2)
      if t.startswith('http'): continue
      if not os.path.exists(os.path.normpath(os.path.join('.', t))):
          bad.append(t)
  if bad: print('Broken README links:', bad); sys.exit(1)
  "

• Clicking from the README to each linked doc lands on a non-404 page.

Out of scope (separate follow-ups worth considering)

• The 34 in-doc cross-references that share the same canonical-name mismatch — file as a separate cleanup so this issue stays README-focused.
• Whether to create docs/architecture.md and docs/skills.md as new top-level entry pages, or fold them into existing files.