Establish the shared docs source and information architecture

[Fuiste]

Summary

Add the initial docs information architecture as a canonical docs/ Markdown tree, including a repository-visible docs home, stable section pages, and a navigation manifest that future site wiring can consume without introducing a second prose corpus.

Demo

• Open docs/README.md and verify it links to quick-start.md, composition.md, combinators.md, api-reference.md, semantics-and-laws.md, and best-practices.md.
• Open docs/navigation.json and verify it points at the same Markdown files rather than duplicating content.
• Open README.md and verify it still acts as the primary install and quick-start entry point while linking to the docs home for deeper material.

Verification

No verification commands configured.

Known Risks

• Repo-wide pnpm format is already red on untouched files in this branch, so formatting validation was narrowed to the files changed by this task.

Context

• Reason: Planned from the Night Shift brief.
• Run: 2026-04-15_08-27-34-07-00-157
• Task: docs-foundation
• Brief: /Users/rudy/work/side-projects/optics/.night-shift/runs/2026-04-15_08-27-34-07-00-157/brief.md

Scope

• Files touched: README.md, docs/README.md, docs/navigation.json, docs/quick-start.md, docs/composition.md, docs/combinators.md, docs/api-reference.md, docs/semantics-and-laws.md, docs/best-practices.md
• Branch: night-shift/2026-04-15_08-27-34-07-00-157-docs-foundation
• Supersedes: (none)

Summary

Add the initial docs information architecture as a canonical docs/ Markdown tree, including a repository-visible docs home, stable section pages, and a navigation manifest that future site wiring can consume without introducing a second prose corpus.

Evidence

Demo evidence:

• docs/README.md now serves as the discoverable docs home and links the planned sections for quick start, composition, combinators, API reference, semantics and laws, and best practices.
• docs/navigation.json defines the same page set and paths as repository-local navigation metadata so a Pages wrapper can consume the docs tree without a duplicate prose corpus.
• README.md now points readers to docs/README.md for deeper documentation while remaining the primary installation and first-run surface.
• Validation run: pnpm exec prettier --check README.md docs/README.md docs/quick-start.md docs/composition.md docs/combinators.md docs/api-reference.md docs/semantics-and-laws.md docs/best-practices.md docs/navigation.json, pnpm lint, pnpm test:types, and pnpm test.

Verification digest: 696cf4995b322eb610db8fec5d6a85c1aece7c167be0befd21cc401b068964ca

No verification commands configured.

Known Risks

• Repo-wide pnpm format is already red on untouched files in this branch, so formatting validation was narrowed to the files changed by this task.

Provenance

• Planning provenance: notes only
• Execution summary source: model-authored
• Planning agent: codex model=gpt-5.4
• Execution agent: codex model=gpt-5.4
• Deterministic evidence: run id, task id, files touched, verification output, superseded lineage
• Inferred/model-authored: PR summary, risks, demo narrative
• Verification digest: 696cf4995b322eb610db8fec5d6a85c1aece7c167be0befd21cc401b068964ca
• Task status: completed
• Task ref: docs-foundation