fitchmultz · fitchmultz · May 20, 2026 · May 20, 2026 · May 20, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -192,6 +192,7 @@ All new or changed behavior must be covered by tests:
 - **Failure modes**: Error handling and edge cases
 - **Location**: Prefer tests near the code via `#[cfg(test)]`
 - **Integration tests**: Use `crates/cueloop/tests/` for cross-module behavior
+- **Disposable-repo fixtures**: Some suites assume `main` as the default branch name and exercise `cueloop doctor` against schema-merged defaults (including the built-in `pi` runner for cached non-interactive init fixtures). If only a handful of tests fail with `origin/main` or a missing `pi` binary, see [Environment-dependent integration tests](docs/troubleshooting.md#environment-dependent-integration-tests).
 - **Agent CI classifier**: If you change `scripts/agent-ci-surface.sh` or path allowlists in `scripts/lib/release_policy.sh`, extend `crates/cueloop/tests/agent_ci_surface_contract_test.rs` so representative `noop` / `ci-docs` / `ci-fast` / `ci` / `macos-ci` routing stays pinned (see `docs/guides/ci-strategy.md`).
 
 Example:

diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@ CueLoop is a Rust CLI and macOS app for queue-driven, auditable AI coding agent
 
 [![crates.io](https://img.shields.io/crates/v/cueloop.svg)](https://crates.io/crates/cueloop)
 [![docs.rs](https://img.shields.io/docsrs/cueloop)](https://docs.rs/cueloop)
-[![GitHub release v0.6.0](https://img.shields.io/badge/release-v0.6.0-blue)](https://github.com/fitchmultz/cueloop/releases/tag/v0.6.0)
+[![GitHub release v0.7.2](https://img.shields.io/badge/release-v0.7.2-blue)](https://github.com/fitchmultz/cueloop/releases/tag/v0.7.2)
 
 ![CueLoop three-phase agent workflow](docs/assets/images/2026-02-07-workflow-3phase.png)
 
@@ -187,19 +187,14 @@ make release-gate
 
 ## Documentation
 
-Start with:
-
-- [Documentation index](docs/index.md)
-- [Evaluator path](docs/guides/evaluator-path.md)
-- [Quick start](docs/quick-start.md)
-- [Local smoke test](docs/guides/local-smoke-test.md)
-- [CLI reference](docs/cli.md)
-- [Configuration](docs/configuration.md)
-- [Architecture overview](docs/architecture.md)
-- [Troubleshooting](docs/troubleshooting.md)
-- [Versioning policy](docs/versioning-policy.md)
-- [Contributing](CONTRIBUTING.md)
-- [Changelog](CHANGELOG.md)
+Start at [docs/index.md](docs/index.md) for the full map. Common entry points:
+
+- [Evaluator path](docs/guides/evaluator-path.md) — fastest review path
+- [Quick start](docs/quick-start.md) — install and first run
+- [Feature guides](docs/features/README.md) — queue, runners, phases, plugins
+- [CLI reference](docs/cli.md) and [Configuration](docs/configuration.md)
+- [Architecture](docs/architecture.md) and [Troubleshooting](docs/troubleshooting.md)
+- [Contributing](CONTRIBUTING.md) and [Changelog](CHANGELOG.md)
 
 ## Versioning and license
 

diff --git a/docs/archive/README.md b/docs/archive/README.md
@@ -0,0 +1,18 @@
+# Documentation archive
+
+Status: Archived  
+Owner: Maintainers  
+Source of truth: index for historical docs only  
+Parent: [Documentation index](../index.md)
+
+These files are kept for context and audit trails. They are not maintained as primary user documentation. For current guidance, start at [docs/index.md](../index.md).
+
+## Contents
+
+| Document | Why it is here |
+| --- | --- |
+| [Stack audit (2026-03)](../guides/stack-audit-2026-03.md) | Superseded by [Stack audit (2026-04)](../guides/stack-audit-2026-04.md) |
+| [Codebase audit (2026-03-31)](audits/codebase-audit-2026-03-31.md) | Point-in-time cleanup inventory; follow-ups captured in [roadmap](../roadmap.md) |
+| [CueLoopMac settings investigation (2026-03-13)](audits/2026-03-13-cueloopmac-settings-window-investigation.md) | Resolved UI investigation notes |
+
+When an archived doc disagrees with CLI behavior, trust [CLI reference](../cli.md), [configuration](../configuration.md), and the generated [schemas](../../schemas/).
diff --git a/...eloopmac-settings-window-investigation.md → ...eloopmac-settings-window-investigation.md b/...eloopmac-settings-window-investigation.md → ...eloopmac-settings-window-investigation.md
@@ -2,7 +2,7 @@
 Status: Archived
 Owner: Maintainers
 Source of truth: historical snapshot; current guidance lives in linked active docs
-Parent: [CueLoop Documentation](../index.md)
+Parent: [Documentation archive](../README.md)
 
 
 Date: 2026-03-13

diff --git a/docs/audits/codebase-audit-2026-03-31.md → ...chive/audits/codebase-audit-2026-03-31.md b/docs/audits/codebase-audit-2026-03-31.md → ...chive/audits/codebase-audit-2026-03-31.md
@@ -2,14 +2,13 @@
 Status: Archived
 Owner: Maintainers
 Source of truth: historical snapshot; current guidance lives in linked active docs
-Parent: [CueLoop Documentation](../index.md)
+Parent: [Documentation archive](../README.md)
 
 
 **Date:** 2026-03-31
 **Scope:** Full codebase (`crates/cueloop/src`, `crates/cueloop/tests`, `scripts/`, `Makefile`)
 **Auditor:** AI Agent (comprehensive-codebase-audit skill)
 
----
 
 ## Executive Summary
 
@@ -36,7 +35,6 @@ Parent: [CueLoop Documentation](../index.md)
 
 **Error Handling:** Two-tier `anyhow`/`thiserror` approach is consistently applied. Production code uses `?` operator almost universally. `unwrap()` is confined to test code and `LazyLock<Regex>` static initialization (acceptable).
 
----
 
 ## Metrics Dashboard
 
@@ -63,7 +61,6 @@ Parent: [CueLoop Documentation](../index.md)
 | `todo!()` macros | 0 |
 | `unreachable!()` in production | 1 |
 
----
 
 ## Full Findings
 
@@ -98,7 +95,6 @@ Parent: [CueLoop Documentation](../index.md)
 
 ✅ **[Module Documentation]** 100% coverage — all 826 source files have `//!` purpose/responsibilities/scope/usage/invariants headers.
 
----
 
 ### SECURITY
 
@@ -129,7 +125,6 @@ Parent: [CueLoop Documentation](../index.md)
 - **Impact:** Silent failure in daemon session isolation
 - **Fix:** Check `setsid()` return value and log on failure: `if libc::setsid() == -1 { log::warn!("setsid failed: {}", std::io::Error::last_os_error()); }`
 
----
 
 ### COMPLEXITY & COGNITIVE LOAD
 
@@ -139,7 +134,6 @@ Parent: [CueLoop Documentation](../index.md)
 - **Impact:** Regression risk on error handling changes
 - **Fix:** Consider a macro-driven approach or separate the `Display` impl into `runner/error/display.rs`
 
----
 
 ### CODE QUALITY
 
@@ -160,7 +154,6 @@ Parent: [CueLoop Documentation](../index.md)
 - **Impact:** Potential runtime crash if the invariant is violated
 - **Fix:** Return an error or no-op instead of panicking: `Ok(())` with a `log::warn!`
 
----
 
 ### ERROR HANDLING
 
@@ -178,7 +171,6 @@ Parent: [CueLoop Documentation](../index.md)
 - **Impact:** Future readers may wonder if the branch was forgotten
 - **Fix:** Add `// Intentional: success requires no action` comments
 
----
 
 ### RESOURCE MANAGEMENT
 
@@ -190,7 +182,6 @@ Parent: [CueLoop Documentation](../index.md)
 
 ✅ **[Temp Cleanup]** Startup runs `cleanup_default_temp_dirs` with configurable retention.
 
----
 
 ### PERFORMANCE
 
@@ -204,7 +195,6 @@ Parent: [CueLoop Documentation](../index.md)
 - **Impact:** Stale secrets won't be redacted if they change during process lifetime; memory grows with env size
 - **Fix:** Acceptable for a CLI tool — process lifetime is bounded. No action needed.
 
----
 
 ### TESTING
 
@@ -223,7 +213,6 @@ Parent: [CueLoop Documentation](../index.md)
 
 ✅ **[Integration Test Suite]** 176 integration test files with ~28K LOC provide substantial end-to-end coverage.
 
----
 
 ### OBSERVABILITY
 
@@ -235,7 +224,6 @@ Parent: [CueLoop Documentation](../index.md)
 - **Impact:** Difficult to diagnose streaming issues without RUST_LOG=debug
 - **Fix:** Add debug logging for session ID extraction, stream buffer growth, and timeout checkpoint transitions
 
----
 
 ### CONFIGURATION
 
@@ -245,7 +233,6 @@ Parent: [CueLoop Documentation](../index.md)
 
 ✅ **[JSONC Support]** Both JSON and JSONC config files supported with comments.
 
----
 
 ### SHELL SCRIPTS
 
@@ -264,7 +251,6 @@ Parent: [CueLoop Documentation](../index.md)
 - **Impact:** Undefined variable usage or failed commands could go undetected in library functions
 - **Fix:** Add `set -euo pipefail` to all library scripts, or add a guard: `[[ $- == *e* ]] || set -e` to inherit the caller's strict mode only if available. Given these are sourced libraries, adding `set -euo pipefail` at the top is safest and most explicit.
 
----
 
 ## Remediation Roadmap
 
@@ -310,7 +296,6 @@ Parent: [CueLoop Documentation](../index.md)
 
 10. **Proactive file decomposition** — split remaining 31 files in the 400-500 LOC range before they breach the hard limit. Prioritize `cli/scan.rs`, `cli/machine/task.rs`, `commands/init/writers.rs`.
 
----
 
 ## Appendix: Top 20 Largest Non-Test Source Files