docs: repair docs navigation and replay runbook

[cursor]

Overview

Repair stale and missing documentation entry points, and align the determinism/replay runbook with the shipped diagnostics CLI and CI replay gate.

Type of Change

• 📚 Documentation or research notes
• 🧰 Developer experience (CLI, codemod, viewer, tooling)

Motivation & Context

The docs navigation advertised reference/llms-txt without a backing page, several existing tutorials were not discoverable in the Mintlify sidebar, README links pointed at stale docs paths, and the determinism page referenced non-existent replay workflow/script names.

Technical Details

• Added docs/reference/llms-txt.mdx and kept llms.txt aligned with existing public pages.
• Updated docs/docs.json to include existing tutorial pages in navigation.
• Repaired README fenced code structure and current docs links.
• Updated replay guidance in docs/explanation/determinism.mdx and docs/reference/cli.mdx to cover noesis diagnostics replay, noesis.diagnostics.compare_runs(), scripts/replay_gate.py, and .github/workflows/determinism-replay.yml.
• Corrected the PR template docs path from docs/app/reference/* to docs/reference/*.

Validation

Required

• All tests pass locally (uv run pytest) or equivalent targeted suite
• Schema validation and export diff clean

Validation performed:

• git diff --check HEAD~1..HEAD
• Python docs validation for docs/docs.json navigation targets, llms.txt public URL targets, and fenced code block balance in changed Markdown/MDX files.

Schema validation was not run because this is a docs-only change with no schema files modified.

Situational

• Cognitive loop tested end-to-end (Observe → Learn)
• Docs build successfully (pnpm run build in docs/)
• CLI smoke tests pass (python scripts/pre_release.py --check-all)
• Benchmarks / eval sweeps reproduced
• Artifact integrity checked (hashes, licensing, storage footprint)

Docs build was not run because this repository does not include a docs package manifest; structural docs validation was run instead.

ADR-003 Schema Governance Checklist

• $schema_version bumped for every artifact whose stable fields changed
• docs/schema/** regenerated (no diff after python scripts/gen_schema.py)
• KPI updates include version bumps plus math/clamp/rationale updates in internal_docs/schema/kpi*.yaml
• Relevant entry added to MIGRATIONS.schema.md or MIGRATIONS.kpi.md
• python scripts/schema_guard.py --strict --json passes locally
• Docs under docs/reference/* updated when new fields/KPIs surface to users

Not applicable: documentation-only change; no artifact fields, schemas, or KPIs changed.

Observability & Safety

Improves operational docs for replay drift debugging and LLM-facing docs index hygiene. No runtime behavior changed.

Educational / Research Value

Makes determinism and replay workflows easier to discover and run for eval/regression work.

Screenshots / Logs

docs validation ok

Related Issues / References

• Codepaths documented: noesis/cli/commands/diagnostics.py, noesis/diagnostics/replay.py, scripts/replay_gate.py, .github/workflows/determinism-replay.yml.