Mount docs under /docs/ so the 173 internal links resolve

[LayerDynamics]

Problem

The docs site is up, but ~173 internal links 404. The site has a marketing landing page at / (src/pages/index.astro) and the Starlight docs were intended to live under /docs/ — every cross-link is authored as ](/docs/...). But Starlight derives each URL from the page's slug: frontmatter, and all 89 pages had root slugs (crates/forge, api/runtime-fs), so docs rendered at the site root (/crates/forge/) and the /docs/ links never resolved. base: was never set — this never worked since the site landed.

Verified live before the fix: https://forge-deno.com/docs/crates/forge/ → 404, https://forge-deno.com/crates/forge/ → 200.

Fix — mount the docs under /docs/ (match the authored links, don't dumb them down to root)

• 89 content slugs → prefixed with docs/.
• 15 root-relative links rewritten (6 in content, 9 in the landing page / Hero / QuickStart / CodeExample).
• 4 sidebar slug entries in astro.config.mjs (the autogenerate directories are filesystem paths — unchanged).
• 3 pre-existing dangling links fixed (surfaced by the link audit): /docs/crates/forge-cli → /docs/crates/forge (×2), /docs/guides/permissions → /docs/internals.

Result: landing page stays at /; docs move to /docs/crates/forge/, /docs/getting-started/, /docs/api/runtime-fs/, etc.

Durability (keeps the pipeline self-maintaining)

• cratepage.rs now emits slug: docs/crates/<name>.
• New slug-prefix drift rule: every docs page slug must start with docs/, so any generator or hand-edit emitting a root slug fails CI instead of silently breaking navigation.

Test plan

• npm run build succeeds — 91 pages; dist/index.html at root, docs under dist/docs/..., old root paths gone
• Link integrity: all 57 unique internal /docs/ targets resolve to built pages (0 missing)
• Drift gate in sync; forge-docs-check 17 rule fixtures + docs_sync + slug_prefix unit test
• fmt --check + clippy -D warnings clean
• CI inherits the rusty_v8 cache fix from main

On merge, deploy-site.yml redeploys (the change touches site/**).

🤖 Generated with Claude Code

[sourcery-ai]

Sorry @LayerDynamics, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[gemini-code-assist]

Code Review

This pull request introduces a new documentation check, slug-prefix, which ensures that all markdown and MDX documentation pages are served under the /docs/ path to prevent broken links and 404 errors. Along with the check and its tests, the PR updates all existing documentation files, Astro components, and configuration files to prepend docs/ to their slugs and internal links. Feedback on the implementation highlights potential robustness issues in the frontmatter parser, specifically regarding UTF-8 BOM handling and nested key false positives, and provides a suggestion to address them.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The current frontmatter parser has two robustness issues:

1. UTF-8 BOM Bypass: If a markdown file starts with a UTF-8 Byte Order Mark (\u{FEFF}), strip_prefix("---") will fail, causing the file to be silently skipped by this check.
2. Nested Key False Positives: Trimming leading whitespace (line.trim()) before checking for the slug: prefix means nested keys (e.g., inside a description block or a nested YAML object) will be incorrectly parsed as the page's slug.

We can fix both issues by stripping the BOM if present and matching slug: only at the start of the line (without trimming leading whitespace).

Suggested change

	fn frontmatter_slug(src: &str) -> Option<String> {
	let body = src.strip_prefix("---")?;
	let end = body.find("\n---")?;
	for line in body[..end].lines() {
	let line = line.trim();
	if let Some(rest) = line.strip_prefix("slug:") {
	return Some(rest.trim().trim_matches(['"', '\'']).to_string());
	}
	}
	None
	}
	fn frontmatter_slug(src: &str) -> Option<String> {
	let src = src.strip_prefix("\u{feff}").unwrap_or(src);
	let body = src.strip_prefix("---")?;
	let end = body.find("\n---")?;
	for line in body[..end].lines() {
	if let Some(rest) = line.strip_prefix("slug:") {
	return Some(rest.trim().trim_matches(['"', '\'']).to_string());
	}
	}
	None
	}