# Docs

This directory is the system-of-record for durable project knowledge.

## Quick Links

| Category | Index | Type | Purpose |
|----------|-------|------|---------|
| **Guides** | [guides/README.md](guides/README.md) | how-to | Practical step-by-step procedures |
| **Design** | [design-docs/index.md](design-docs/index.md) | explanation | Feature design, ADRs, decision rationale |
| **ADR Template** | [design-docs/decisions/0001-template.md](design-docs/decisions/0001-template.md) | reference | Decision record template |
| **Core Beliefs** | [design-docs/core-beliefs.md](design-docs/core-beliefs.md) | explanation | Agent-first operating principles |
| **Discovery** | [discovery/index.md](discovery/index.md) | explanation | Validate ideas and capture taste |
| **Delivery Specs** | [delivery-specs/index.md](delivery-specs/index.md) | reference | Engineering handoff specs |
| **Exec Plans** | [exec-plans/README.md](exec-plans/README.md) | how-to | Complex multi-step work tracking |
| **Tech Debt** | [exec-plans/tech-debt-tracker.md](exec-plans/tech-debt-tracker.md) | how-to | Known debt and cleanup opportunities |
| **Exploration** | [exploration/README.md](exploration/README.md) | exploration | Ideas, research, scratchpad |
| **Learnings** | [learnings/README.md](learnings/README.md) | reference | Durable patterns from completed work |
| **Archived Learnings** | [learnings/archived/README.md](learnings/archived/README.md) | reference | Overflow learnings archive |
| **References** | [references/README.md](references/README.md) | reference | External docs for agent context |

## Learnings by Category

| Category | File |
|----------|------|
| Architecture | [learnings/architecture.md](learnings/architecture.md) |
| Conventions | [learnings/conventions.md](learnings/conventions.md) |
| Gotchas | [learnings/gotchas.md](learnings/gotchas.md) |
| Integrations | [learnings/integrations.md](learnings/integrations.md) |
| Security | [learnings/security.md](learnings/security.md) |
| Testing | [learnings/testing.md](learnings/testing.md) |
| Workflow | [learnings/workflow.md](learnings/workflow.md) |

## System Docs

- Architecture: [ARCHITECTURE.md](ARCHITECTURE.md)
- Operations: [RUNBOOK.md](RUNBOOK.md)
- Taxonomy: [DOCS_TAXONOMY.md](DOCS_TAXONOMY.md)
- Quality: [QUALITY_SCORE.md](QUALITY_SCORE.md)
- Feature Slicing: [FEATURE_SLICING.md](FEATURE_SLICING.md)
- Contract: [DOCS_CONTRACT.json](DOCS_CONTRACT.json)

## Directory Structure

```
docs/
├── README.md                    # This file (index)
├── ARCHITECTURE.md              # System design overview [reference]
├── RUNBOOK.md                   # Operations guide [how-to]
├── DOCS_TAXONOMY.md             # Where to put new docs [reference]
├── QUALITY_SCORE.md             # Domain quality grades [reference]
├── FEATURE_SLICING.md           # Feature slicing strategy [reference]
├── DOCS_CONTRACT.json           # Validation config [reference]
├── guides/                      # How-to guides [how-to]
│   └── README.md                # Guide index
├── design-docs/                 # Decision rationale [explanation]
│   ├── index.md                 # Design docs catalogue
│   ├── core-beliefs.md          # Agent-first principles
│   └── decisions/               # Architectural Decision Records
├── discovery/                   # Idea validation [explanation]
│   └── index.md                 # Discovery index
├── delivery-specs/              # Engineering handoff [reference]
│   └── index.md                 # Delivery specs index
├── exec-plans/                  # Work tracking [how-to]
│   ├── README.md                # Exec plans index
│   └── tech-debt-tracker.md     # Technical debt
├── exploration/                 # Ideas, scratchpad [exploration]
│   └── README.md                # Exploration index
├── learnings/                   # Durable patterns [reference]
│   ├── README.md                # Learnings index
│   ├── architecture.md          # Architecture learnings
│   ├── conventions.md           # Convention learnings
│   ├── gotchas.md               # Gotcha learnings
│   ├── integrations.md          # Integration learnings
│   ├── security.md              # Security learnings
│   ├── testing.md               # Testing learnings
│   ├── workflow.md              # Workflow learnings
│   └── archived/                # Overflow archive
│       └── README.md            # Archive policy
└── references/                  # External docs [reference]
    └── README.md                # External docs for agent context
```

## Adding Documentation

| If you need... | Create in... | Type |
|----------------|--------------|------|
| Step-by-step procedure | `docs/guides/<topic>.md` | how-to |
| Design for a feature | `docs/design-docs/<feature>.md` | explanation |
| External library docs | `docs/references/<library>-llms.txt` | reference |