docs(reference): add reference documentation index

CHANGELOG.md

@@ -203,6 +203,10 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   `pr-merge-pool-supervisor` to the product-builder's supervisor launch list (18 total
   supervisors). Updated all numeric references, pre-flight checklists, and validation logic.
 
+### Documentation
+
+- Add `docs/reference/index.md` — reference documentation landing page and index
+
 ---
 
 ## [3.8.0] — 2026-04-05

docs/reference/index.md

@@ -0,0 +1,82 @@
+# Reference Documentation
+
+This section provides comprehensive reference material for CleverAgents. Reference
+documentation is precise and complete — it describes every command, configuration
+option, term, and error code without assuming prior familiarity with the subject.
+Use it when you need to look up exact syntax, understand a specific option, or
+diagnose an error.
+
+For conceptual background and architectural rationale, see the
+[Architecture Decision Records](../adr/index.md). For the public Python API, see
+the [API Reference](../api/index.md).
+
+---
+
+## Contents
+
+| Section | Description |
+|---------|-------------|
+| [CLI Reference](cli.md) | Complete reference for the `agents` command-line tool — every sub-command, flag, and option with usage examples. |
+| [Configuration Reference](configuration.md) | YAML schema for `agents.yml` and all environment variables that control runtime behaviour. |
+| [Glossary](glossary.md) | Definitions of key terms and concepts used throughout CleverAgents documentation and source code. |
+| [Error Codes](errors.md) | Catalogue of error codes and exception types, with causes and recommended remediation steps. |
+
+---
+
+## CLI Reference
+
+The CleverAgents command-line tool is named **`agents`**. It is the primary
+interface for running plans, managing actors and skills, inspecting configuration,
+and operating the server.
+
+```
+agents [global-flags] <command> [sub-command] [flags] [args]
+```
+
+The [CLI Reference](cli.md) documents every command group (`plan`, `actor`,
+`skill`, `tool`, `config`, `session`, `resource`, `mcp`, `project-context`,
+`action`) together with their flags, accepted values, and output formats.
+
+---
+
+## Configuration Reference
+
+CleverAgents is configured through a YAML file (default: `agents.yml`) and a set
+of environment variables. The [Configuration Reference](configuration.md) covers:
+
+- The full YAML schema with field types, defaults, and validation rules.
+- Environment variable names, precedence rules, and accepted values.
+- Per-provider configuration blocks for AI providers.
+- Logging, metrics, and security-scanning settings.
+
+---
+
+## Glossary
+
+The [Glossary](glossary.md) defines the vocabulary used across CleverAgents
+documentation, ADRs, and source code. Entries include:
+
+- Core domain concepts: *Actor*, *Skill*, *Tool*, *Plan*, *Resource*, *Session*.
+- Protocol terms: *A2A*, *MCP*, *LSP*, *ACMS*, *UKO*.
+- Operational terms: *Automation Profile*, *Sandbox*, *Checkpoint*, *Invariant*.
+
+---
+
+## Error Codes
+
+The [Error Codes](errors.md) reference lists every structured error and exception
+type that CleverAgents can raise, organized by subsystem. Each entry includes:
+
+- The error code or exception class name.
+- A description of when the error occurs.
+- Common causes and recommended remediation steps.
+
+---
+
+## Cross-References
+
+| Related Section | Relationship |
+|-----------------|--------------|
+| [API Reference](../api/index.md) | Python-level API documentation for the `cleveragents` package modules. |
+| [Architecture Decision Records](../adr/index.md) | Architectural rationale behind the design of CLI commands, configuration schema, and error handling. |
+| [Development — Testing Guide](../development/testing.md) | How to write and run tests that exercise CLI commands and configuration loading. |

mkdocs.yml

@@ -43,7 +43,11 @@ nav:
     - Documentation Writer: development/docs-writer.md
   - Implementation Timeline: timeline.md
   - FAQ: faq.md
-  - Reference: reference/
+  - Reference:
+    - Overview: reference/index.md
+    - CLI Reference: reference/cli.md
+    - Configuration: reference/configuration.md
+    - Glossary: reference/glossary.md
   - Architecture Decision Records (ADRs):
     - Overview: adr/index.md
     - ADR-001 Layered Architecture: adr/ADR-001-layered-architecture.md