docs: README overhaul + documentation restructure

README.md rewritten as a focused landing page:
- Kept the 1st-person Quorum voice
- Compelling narrative → quick demo → comparison → install
- Platform ports section (Copilot CLI, Claude Code)
- ~120 lines vs ~400 lines before

Documentation reorganized by intent:
- docs/getting-started/ — install, quick start, beginners, models
- docs/configuration/ — config reference
- docs/guides/ — rubric building, cross-artifact design
- docs/architecture/ — spec, the nine, implementation
- docs/critics/ — security, code hygiene, tester, SEC-02 through SEC-07
- docs/reviews/ — external reviews

New files:
- docs/getting-started/QUICK_START.md — first validation in 60 seconds
- docs/README.md — navigation hub with categorized links

All internal cross-references updated across 30+ files.

Author: Akkari

CONTRIBUTING.md

@@ -54,7 +54,7 @@ Improvements to docs, tutorials, and examples are always welcome. If something w
 
 ### 🔬 External Reviews
 
-Run Quorum against your own system and share the results. See `docs/EXTERNAL_REVIEWS.md` for how to submit.
+Run Quorum against your own system and share the results. See `docs/reviews/EXTERNAL_REVIEWS.md` for how to submit.
 
 ## Pull Request Process
 

README.md

@@ -24,10 +24,10 @@ Run `python tools/validate-docs.py` to find stale references, then fix:
 - [ ] `README.md` — "What's coming" section (remove shipped items)
 - [ ] `SPEC.md` — status matrix / implementation checklist updated
 - [ ] `SPEC.md` — shipped critic counts in prose
-- [ ] `docs/FOR_BEGINNERS.md` — critic counts and cost estimates
-- [ ] `docs/CONFIG_REFERENCE.md` — critic status markers
-- [ ] `docs/TUTORIAL.md` — critic descriptions and status markers
-- [ ] `docs/IMPLEMENTATION.md` — critic status markers and depth profiles
+- [ ] `docs/getting-started/FOR_BEGINNERS.md` — critic counts and cost estimates
+- [ ] `docs/configuration/CONFIG_REFERENCE.md` — critic status markers
+- [ ] `docs/getting-started/TUTORIAL.md` — critic descriptions and status markers
+- [ ] `docs/architecture/IMPLEMENTATION.md` — critic status markers and depth profiles
 - [ ] `SKILL.md` — critic counts in depth descriptions
 
 **⚠️ Note on Cross-Consistency:** Cross-Consistency is a shipped critic but requires the `--relationships` flag. When updating counts, use language like: "6 shipped critics (including Cross-Consistency, activated with `--relationships`)".

SHIPPING.md

@@ -100,9 +100,9 @@ Each finding includes: severity (CRITICAL/HIGH/MEDIUM/LOW), evidence citations p
 ## More Information
 
 - [SPEC.md](https://github.com/SharedIntellect/quorum/blob/main/SPEC.md) — Full architectural specification
-- [MODEL_REQUIREMENTS.md](https://github.com/SharedIntellect/quorum/blob/main/docs/MODEL_REQUIREMENTS.md) — Supported models and tiers
-- [CONFIG_REFERENCE.md](https://github.com/SharedIntellect/quorum/blob/main/docs/CONFIG_REFERENCE.md) — All configuration options
-- [FOR_BEGINNERS.md](https://github.com/SharedIntellect/quorum/blob/main/docs/FOR_BEGINNERS.md) — New to agent validation? Start here
+- [MODEL_REQUIREMENTS.md](https://github.com/SharedIntellect/quorum/blob/main/docs/getting-started/MODEL_REQUIREMENTS.md) — Supported models and tiers
+- [CONFIG_REFERENCE.md](https://github.com/SharedIntellect/quorum/blob/main/docs/configuration/CONFIG_REFERENCE.md) — All configuration options
+- [FOR_BEGINNERS.md](https://github.com/SharedIntellect/quorum/blob/main/docs/getting-started/FOR_BEGINNERS.md) — New to agent validation? Start here
 
 
 ---

SKILL.md

@@ -3,7 +3,7 @@
 **Version:** 3.0  
 **Last Updated:** March 2026  
 **Status:** Documented and partially implemented — see §3 for implementation status per component  
-**Platform:** Designed for [OpenClaw](https://openclaw.ai) agent systems. Cross-platform compatibility with other agent frameworks is under active exploration — see [MODEL_REQUIREMENTS.md](docs/MODEL_REQUIREMENTS.md) for supported models and platforms.
+**Platform:** Designed for [OpenClaw](https://openclaw.ai) agent systems. Cross-platform compatibility with other agent frameworks is under active exploration — see [MODEL_REQUIREMENTS.md](docs/getting-started/MODEL_REQUIREMENTS.md) for supported models and platforms.
 
 ---
 
@@ -153,7 +153,7 @@ Pre-screen results are written to `prescreen.json` in the run directory. If any
 Supervisor (Orchestrator)
 ├─ Correctness Critic (Tier 2)      [IMPLEMENTED]
 ├─ Completeness Critic (Tier 2)     [IMPLEMENTED]
-├─ Security Critic (Tier 1)         [IMPLEMENTED] — grounded: OWASP ASVS 5.0, CWE Top 25, NIST SA-11; see docs/SEC02_BUSINESS_LOGIC_VALIDATION.md for business logic workflow
+├─ Security Critic (Tier 1)         [IMPLEMENTED] — grounded: OWASP ASVS 5.0, CWE Top 25, NIST SA-11; see docs/critics/SEC02_BUSINESS_LOGIC_VALIDATION.md for business logic workflow
 ├─ Code Hygiene Critic (Tier 2)     [IMPLEMENTED] — grounded: ISO 25010:2023, CISQ
 ├─ Cross-Artifact Consistency       [IMPLEMENTED] — Phase 2, separate from BaseCritic
 ├─ Architecture Critic (Tier 2)     [SPECIFIED, not yet built]
@@ -462,9 +462,9 @@ Quorum is built on these peer-reviewed papers:
 
 ## 11. Getting Started
 
-1. Read [IMPLEMENTATION.md](docs/IMPLEMENTATION.md) for a reference walkthrough
+1. Read [IMPLEMENTATION.md](docs/architecture/IMPLEMENTATION.md) for a reference walkthrough
 2. Review [examples/](examples/) for your use case
-3. Adapt built-in rubrics or build custom ones (see [RUBRIC_BUILDING_GUIDE.md](docs/RUBRIC_BUILDING_GUIDE.md))
+3. Adapt built-in rubrics or build custom ones (see [RUBRIC_BUILDING_GUIDE.md](docs/guides/RUBRIC_BUILDING_GUIDE.md))
 4. Run the tutorial: `quorum run --target examples/sample-research.md --depth quick`
 
 ---

SPEC.md

@@ -25,7 +25,7 @@ Every source file gets a metadata block at the top, using `@KEY: value` pairs in
 ```python
 # @module: quorum.critics.code_hygiene
 # @purpose: Code quality evaluation grounded in ISO 25010 + CISQ
-# @grounding: CODE_HYGIENE_FRAMEWORK.md
+# @grounding: critics/CODE_HYGIENE_FRAMEWORK.md
 # @owner: code-hygiene-critic
 # @version: 0.3.0
 # @tier: tier-2 (default model assignment)
@@ -34,7 +34,7 @@ Every source file gets a metadata block at the top, using `@KEY: value` pairs in
 
 **Markdown:**
 ```markdown
-<!-- @doc: CROSS_ARTIFACT_DESIGN.md -->
+<!-- @doc: guides/CROSS_ARTIFACT_DESIGN.md -->
 <!-- @purpose: Architectural decisions for cross-file consistency checking -->
 <!-- @status: design-complete -->
 <!-- @version: 1.0 -->
@@ -47,7 +47,7 @@ Every source file gets a metadata block at the top, using `@KEY: value` pairs in
 # @config: quorum-relationships.yaml
 # @purpose: Declared file relationships for cross-artifact consistency
 # @schema-version: 1.0
-# @see: CROSS_ARTIFACT_DESIGN.md
+# @see: guides/CROSS_ARTIFACT_DESIGN.md
 ```
 
 **Shell:**
@@ -199,9 +199,9 @@ This enables a future pre-screen check (`PS-011: Header validation`) that mechan
 - [ ] `prescreen.py`
 
 ### Phase 3: Framework & Design Docs
-- [ ] `CODE_HYGIENE_FRAMEWORK.md`
-- [ ] `SECURITY_CRITIC_FRAMEWORK.md`
-- [ ] `CROSS_ARTIFACT_DESIGN.md`
+- [ ] `critics/CODE_HYGIENE_FRAMEWORK.md`
+- [ ] `critics/SECURITY_CRITIC_FRAMEWORK.md`
+- [ ] `guides/CROSS_ARTIFACT_DESIGN.md`
 - [ ] `SPEC.md`
 - [ ] `CHANGELOG.md`
 
@@ -219,7 +219,7 @@ This enables a future pre-screen check (`PS-011: Header validation`) that mechan
 | Pipeline & CLI | `docs/PIPELINE_REFERENCE.md` | High — users need this |
 | Pre-Screen System | `docs/PRESCREEN_REFERENCE.md` | High — 10 checks need documentation |
 | Critic Framework | `docs/CRITIC_ARCHITECTURE.md` | Medium — developers extending Quorum |
-| Rubric System | `docs/RUBRIC_BUILDING_GUIDE.md` | **Already exists** ✅ |
+| Rubric System | `docs/guides/RUBRIC_BUILDING_GUIDE.md` | **Already exists** ✅ |
 | Cross-Artifact | `docs/CROSS_ARTIFACT_DESIGN.md` | **Already exists** ✅ |
 
 ---

docs/DOCUMENTATION_STANDARDS.md

@@ -1,28 +1,73 @@
-# Quorum Documentation Index
+# Quorum Documentation
+
+Everything you need to use, configure, and extend Quorum.
+
+---
 
 ## Getting Started
-- **[INSTALLATION.md](INSTALLATION.md)** — Setup, dependencies, and first run
-- **[TUTORIAL.md](TUTORIAL.md)** — Step-by-step walkthrough
-- **[FOR_BEGINNERS.md](FOR_BEGINNERS.md)** — What Quorum does and why, for newcomers
-- **[CONFIG_REFERENCE.md](CONFIG_REFERENCE.md)** — Depth profiles, model tiers, and all configuration options
-
-## Architecture & Design
-- **[THE_NINE.md](THE_NINE.md)** — The nine-agent target architecture
-- **[IMPLEMENTATION.md](IMPLEMENTATION.md)** — Current implementation status and technical details
-- **[MODEL_REQUIREMENTS.md](MODEL_REQUIREMENTS.md)** — Why Quorum needs capable models and what "Tier 1/Tier 2" means
-- **[CROSS_ARTIFACT_DESIGN.md](CROSS_ARTIFACT_DESIGN.md)** — Phase 2 cross-artifact consistency validation
-
-## Security & Code Quality Frameworks
-- **[SECURITY_CRITIC_FRAMEWORK.md](SECURITY_CRITIC_FRAMEWORK.md)** — SEC-01 through SEC-14: the full security critic rule set
-- **[SEC02_BUSINESS_LOGIC_VALIDATION.md](SEC02_BUSINESS_LOGIC_VALIDATION.md)** — Business logic validation workflow (requirements → critic path, threat_context integration)
-- **[CODE_HYGIENE_FRAMEWORK.md](CODE_HYGIENE_FRAMEWORK.md)** — Code quality rules grounded in ISO 25010:2023 and CISQ
-- **[POWERSHELL_COVERAGE.md](POWERSHELL_COVERAGE.md)** — Honest assessment of PowerShell SAST coverage (~70%) and landscape gaps
-
-## Building Rubrics
-- **[RUBRIC_BUILDING_GUIDE.md](RUBRIC_BUILDING_GUIDE.md)** — How to create domain-specific rubrics for Quorum
-
-## Project
-- **[CHANGELOG.md](CHANGELOG.md)** — Release history
-- **[EXTERNAL_REVIEWS.md](EXTERNAL_REVIEWS.md)** — Independent evaluations of Quorum's architecture
-- **[DOCUMENTATION_STANDARDS.md](DOCUMENTATION_STANDARDS.md)** — Standards for Quorum's own documentation
-- **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** — Community guidelines
+
+| Doc | Description |
+|-----|-------------|
+| [Quick Start](getting-started/QUICK_START.md) | Your first validation in 60 seconds |
+| [Installation](getting-started/INSTALLATION.md) | Detailed setup, dependencies, and troubleshooting |
+| [For Beginners](getting-started/FOR_BEGINNERS.md) | New to AI agent tooling? Start here |
+| [Tutorial](getting-started/TUTORIAL.md) | Walkthrough of a full validation workflow |
+| [Model Requirements](getting-started/MODEL_REQUIREMENTS.md) | Which models work with Quorum and why |
+
+## Configuration
+
+| Doc | Description |
+|-----|-------------|
+| [Config Reference](configuration/CONFIG_REFERENCE.md) | Every config option, rubric format, and CLI flag |
+
+## Guides
+
+| Doc | Description |
+|-----|-------------|
+| [Rubric Building Guide](guides/RUBRIC_BUILDING_GUIDE.md) | How to build rubrics for new domains step by step |
+| [Cross-Artifact Design](guides/CROSS_ARTIFACT_DESIGN.md) | Checking consistency between related files |
+
+## Architecture
+
+| Doc | Description |
+|-----|-------------|
+| [SPEC.md](../SPEC.md) | Full architectural specification |
+| [The Nine Critics](architecture/THE_NINE.md) | The critic architecture — what each one does and why |
+| [Implementation Notes](architecture/IMPLEMENTATION.md) | Technical decisions and internals |
+
+## Critics — Deep Dives
+
+| Doc | Description |
+|-----|-------------|
+| [Security Critic Framework](critics/SECURITY_CRITIC_FRAMEWORK.md) | OWASP ASVS 5.0, CWE Top 25, NIST SA-11 coverage |
+| [Code Hygiene Framework](critics/CODE_HYGIENE_FRAMEWORK.md) | ISO 25010:2023, CISQ quality model |
+| [Tester Critic Brief](critics/TESTER_CRITIC_BRIEF.md) | L1 deterministic + L2 LLM claim verification |
+| [Business Logic Validation](critics/SEC02_BUSINESS_LOGIC_VALIDATION.md) | SEC-02 workflow for business logic review |
+| [Evidence Integrity](critics/SEC03_EVIDENCE_INTEGRITY.md) | SEC-03 evidence grounding and integrity |
+| [Pipeline Resilience](critics/SEC05_PIPELINE_RESILIENCE.md) | SEC-05 crash recovery and fault tolerance |
+| [Rubric Framework](critics/SEC06_RUBRIC_FRAMEWORK.md) | SEC-06 rubric architecture and extensibility |
+| [Self-Validation Convergence](critics/SEC07_SELF_VALIDATION_CONVERGENCE.md) | SEC-07 Quorum validating itself |
+| [PowerShell Coverage](critics/POWERSHELL_COVERAGE.md) | PSScriptAnalyzer integration details |
+
+## Reviews & Research
+
+| Doc | Description |
+|-----|-------------|
+| [External Reviews](reviews/EXTERNAL_REVIEWS.md) | Independent evaluations of Quorum by other models |
+| [Changelog](CHANGELOG.md) | Version history and release notes |
+| [Code of Conduct](CODE_OF_CONDUCT.md) | Community guidelines |
+
+## Platform Ports
+
+Quorum runs natively in other agent platforms:
+
+| Port | Description |
+|------|-------------|
+| [Copilot CLI](../ports/copilot-cli/) | GitHub Copilot skill — stdlib-only pre-screen + 5 LLM critics |
+| [Claude Code](../ports/claude-code/) | Claude Code subscription — zero API cost validation |
+
+## Contributing
+
+→ [CONTRIBUTING.md](../CONTRIBUTING.md)
+
+We especially welcome rubric contributions for new domains.