Reorganize documentation for clearer navigation

[fitchmultz]

Summary

Documentation was hard to navigate: overlapping onboarding guides, legacy combined references, RFC-style SHALL requirements in the task-decompose PRD, and decorative formatting noise across many feature pages.

This PR reorganizes docs/ around a single hierarchical hub, archives historical audits, and consolidates duplicate entry points without removing deep reference material.

Changes

• docs/index.md — Rewritten as the primary map with reader paths, topic tables, mermaid navigation diagram, and links to start guides, features, reference, maintainer docs, and archive.
• docs/archive/ — New archive index; docs/audits/ moved to docs/archive/audits/.
• Legacy hubs — getting-started.md, queue-and-tasks.md, and workflow.md are now short navigation pages pointing at canonical feature/reference docs (old URLs preserved).
• PRD — docs/prd/cueloop-task-decompose.md functional requirements rewritten as grouped bullets (no SHALL boilerplate).
• Cleanup — Trimmed features/README.md and scan intro; removed --- horizontal-rule noise from 42 markdown files (~2k net lines removed).

Validation

make ci-docs

Passed (markdown links and documented path guards).

Follow-ups (optional)

• Further trim the largest feature references (scan.md, phases.md, runners.md) if we want another pass below ~85k words.
• Move guides/stack-audit-2026-03.md into docs/archive/ when no active links need the old path.

  

[cursor]

Stale comment

Documentation automation summary

Docs added or updated

• docs/index.md — Primary navigation hub: reading-order diagram, goal-based tables (start here, core concepts, feature area, reference, operations, maintainer), runtime path table, and explicit pointers to legacy hubs and docs/archive/.
• docs/features/README.md — Feature-area index (core, execution, integrations, workflow tools, configuration slice, security/schemas, “by goal”) without repeating long tutorials.
• docs/guides/getting-started.md — Shortened guided path: defers install/first steps to Quick start, keeps init wizard vs --non-interactive, task/run/doctor commands, macOS app note, and daily-loop diagram with links into feature docs.
• docs/queue-and-tasks.md and docs/workflow.md — Legacy thin hubs so existing links and test evidence paths (e.g. docs/queue-and-tasks.md in queue insert tests) stay valid while detailed content lives under docs/features/* and related guides.
• docs/archive/README.md — Index for superseded or point-in-time audits, with guidance to trust CLI/config/schemas when archived text disagrees with behavior.
• README.md — Product overview and doc entry points; follow-up commit 672b08a aligns the GitHub release badge and link with crates/cueloop/Cargo.toml (v0.7.2) so the landing page matches the shipped crate.
• Boilerplate cleanup — Many docs/features/* and docs/guides/* files had redundant front-matter trimmed (large net deletion in the reorg commit) so scanning stays focused on substance.
• docs/prd/cueloop-task-decompose.md and a few archive/guide cross-links — Adjusted as part of the same navigation pass.

Codepaths and behavior these docs track

• CLI surfaces documented in onboarding: init, task, task decompose, queue list/show/validate, run one/loop, doctor, runner list, app open — aligned with the Rust CLI in crates/cueloop.
• Repo-local state under .cueloop/ (queue, done, config, prompts, cache paths called out in workflow hub) — matches the on-disk contract described in architecture and machine-contract docs.
• Validation — make agent-ci / make ci-docs and classifier notes tie to Makefile and scripts/agent-ci-surface.sh as documented in CI strategy.
• Integration tests that still cite docs/queue-and-tasks.md as scope/evidence remain meaningful because that file remains a maintained stub with correct deep links.

Knowledge gaps this PR closes

• “Where do I start?” — One ordered path (README → evaluator path → quick start → smoke test → getting started) instead of overlapping mega-guides.
• Duplicate maintenance — Long combined queue/workflow prose removed in favor of feature pages + legacy stubs for backward-compatible URLs.
• Archive vs current — Explicit archive index and parent links so readers do not treat old audits as live runbooks.
• Public version signal — README release badge now matches the 0.7.2 crate version (verified from crates/cueloop/Cargo.toml).

Validation

• make ci-docs passed on the branch after the README badge change (markdown link check included in that gate).

If you want a follow-up outside this PR: scan other badges or copy for any remaining v0.6.x references outside CHANGELOG.md/history.

  

_{Sent by Cursor Automation: Generate docs}

[cursor]

Documentation automation summary

Docs added/updated

• docs/troubleshooting.md — New section Environment-dependent integration tests covering (1) Git init.defaultBranch / main + origin/main expectations for disposable-repo suites, and (2) why doctor_contract_test expects the pi runner on PATH (cached cueloop init --non-interactive writes minimal .cueloop/config.jsonc; loaded config merges schema defaults to the built-in pi runner, so cueloop doctor probes pi).
• CONTRIBUTING.md — Testing requirements now cross-link that troubleshooting anchor so contributors land on the concrete fixes.

Codepaths / fixtures covered

• crates/cueloop/tests/test_support/test_support_command.rs — git_init (-b main), seed_cueloop_dir / cached non-interactive init template.
• crates/cueloop/tests/parallel_done_json_safety_test/support.rs — origin/main merge-base / merge-tree helpers.
• crates/cueloop/tests/doctor_contract_test/** — doctor success + auto-fix contract tests that assume a resolvable default runner binary.

Knowledge gaps addressed

• Explains isolated cargo test -p cueloop failures (missing pi, or Git branch naming) that do not necessarily indicate a product regression—aligned with repo AGENTS.md Cursor Cloud notes.

Validation: make ci-docs (passed). Heavier Rust gates not run (docs-only change).

Commit: 2624d996 on cursor/docs-reorg-0c25.

  

_{Sent by Cursor Automation: Generate docs}