Add agent-readable Markdown links

[johnnygreco]

Summary

• publish byte-identical Markdown sources for canonical Dev Notes and documentation pages
• add visible “View Markdown” actions and machine-readable rel="alternate" discovery links
• keep production and pull-request previews revision-correct with same-origin exports
• enforce the content scope in tests and documentation workflow validation

Why

Agents consuming the documentation should be able to discover and fetch the underlying Markdown without parsing rendered page chrome. Zensical’s built-in source action points at a repository branch, which can become stale on pull-request previews, so the build publishes the matching Markdown artifact alongside each eligible page.

Impact

Canonical pages under docs/dev-notes/posts/ and docs/documentation/ opt into Markdown publication with agent_markdown: true. Landing pages, redirects, obsolete pages, internal development pages, and the 404 page remain excluded.

Validation

• python3 -m unittest discover -s tests
• scripts/build-docs.sh
• git diff --check
• local HTTP verification of /documentation/index.md returning 200 OK with Content-Type: text/markdown

[github-actions]

Documentation preview

The preview has been removed.

[johnnygreco]

Panel review results

Review target: main at 74eb834 through e198317.

Panel

• Pathwarden — robustness/correctness, security/privacy, integration/operations
• Meridian — user and agent experience, accessibility/discoverability, documentation/adoption, static-site URL behavior
• Rowan — maintainability/complexity, tests/coverage, developer and agent ergonomics

Data/migrations, API contracts, performance/concurrency, and dependency/supply-chain lenses were skipped as inapplicable to this static documentation build change.

Findings and resolution

The first round identified one shared issue: the maintainer guide said to exclude all section landing pages, while the implementation intentionally treats every page in the two canonical content directories as publishable, including the Documentation index.

• Accepted: the documentation contract was contradictory.
• Fixed: commit e198317 clarifies that every page in docs/dev-notes/posts/ and docs/documentation/ is canonical and published, while presentation-only, redirect, obsolete/orphan, internal, and 404 pages remain outside those directories.
• Rejected behavior change: removing the Documentation index or making documentation publication optional would weaken the invariant that every durable documentation page receives an agent-readable Markdown link.

Both affected reviewers reran against e198317 and returned clean verdicts. The correctness/security/operations review was clean in the first round and its risk surface did not change.

Validation

• python3 -m unittest discover -s tests
• scripts/build-docs.sh
• git diff --check
• local HTTP verification: Markdown returned 200 OK with Content-Type: text/markdown
• GitHub Actions: all required checks passed
• GitHub merge state: CLEAN / MERGEABLE

Final verdict: clean and merge-ready. No unresolved panel findings remain.