# REF-TASK-003 — Make documentation navigation declarative and complete

**Status:** Implemented  
**Kind:** Documentation tooling  
**Depends on:** REF-TASK-002

## Problem and evidence

`scripts/build-docs-site.mjs` contains a long hand-maintained `projectPages` array that repeats
file, slug, title, and grouping for every rendered page. New Epic 003 task pages are copied as raw
Markdown but only task indexes are rendered, while changes require touching generator code. The
544-line builder mixes content inventory, Markdown rendering, link rewriting, templates, and
filesystem output. Its inventory can drift from the repository's documentation placement rules.

## Proposed change

Introduce one small, explicit documentation manifest (data, not a framework) used by site generation
and relevant documentation checks. Extract rendering/template and inventory concerns into named
script modules only where this makes tests possible. Include the new Epic 004 index and define
whether individual refactor tasks are rendered or intentionally raw-linked. Preserve current URLs
unless a redirect/update plan is included, and update `docs/documentation.md` with how a new
canonical guide/spec index enters navigation.

## Constraints and sequence

First characterize current generated routes and links with tests. Move the existing array unchanged
to the manifest, validate identical output, then add missing intended pages. Do not add a docs
framework or change Markdown semantics. Generated `docs-site/` remains untracked output.

## Validation

Add/adjust `tests/ci/documentation-gates.test.mjs` at the manifest/site level. Run that focused Node
test, `pnpm docs:build`, `pnpm docs:site:check`, inspect changed navigation, and run `pnpm quality`.

## Guidance / ADR

Update `docs/documentation.md`; no ADR.

## Implementation record

The hand-maintained `projectPages` array moved unchanged into a new declarative manifest,
`scripts/docs-site-manifest.mjs`, which now also exports `documentGroups()` and `renderedPage()`
derived lookups. Markdown rendering, `.md` link rewriting, the sidebar, and the shared HTML template
moved into `scripts/docs-site-render.mjs`; `scripts/build-docs-site.mjs` now owns only filesystem
orchestration and consumes both modules. No docs framework was added and Markdown semantics are
unchanged.

The Epic 004 index was added as one manifest entry (`refactor` →
`docs/specs/004-refactor/README.md`, group `Specifications`); individual `REF-TASK-*.md` records
remain intentionally raw-linked, matching Epic 003. Existing page slugs and URLs are preserved: a
byte-for-byte diff of the regenerated site against the prior output shows only the added sidebar
link on every page plus the new `refactor.html`, and the one pre-existing raw link to the Epic 004
README in `current-state.md` now resolves to the rendered page. `docs/documentation.md` §7 documents
the manifest, its entry fields, the module split, and the rule for adding a canonical guide or
specification index. Focused manifest/site-level tests were added to
`tests/ci/documentation-gates.test.mjs`. No application behavior, public contract, dependency,
specification, or ADR changed.