# Clavitor Agent Handbook — Section Count Analysis

**Question:** What is the optimal number of sections?

**Analysis:** The content naturally clusters by *reading pattern*, not arbitrary grouping.

---

## Content Inventory by Reading Pattern

| Pattern | When read | Content |
|---------|-----------|---------|
| **Onboard** | First day | Foundation First, KISS, DRY, personas, cardinal rules, threat model |
| **Daily** | Every work session | Git workflow, PRs, checklist |
| **Emergency** | When things break | Incident response, token compromise, lockouts |
| **Policy** | When questions arise | Compliance, retention, data governance |
| **Project** | Before touching code | Subproject specifics (vault, CLI, crypto, etc.) |

**That's 5 natural reading patterns.**

---

## Option Comparison

### Option A: 3 Sections (original proposal)

```
I. Who We Are      (onboard + emergency + policy mixed)
II. How We Work    (daily + emergency mixed)
III. What We Build (project)
```

**Problem:** Emergency procedures (read rarely, under stress) mixed with culture (read once). Workflow (daily) mixed with incident response (emergency).

---

### Option B: 4 Sections

```
I. Culture & Principles      (onboard)
II. Security & Threat Model    (onboard + reference)
III. Workflow & Operations     (daily + emergency mixed)
IV. Subproject Reference       (project)
```

**Problem:** Still mixing daily workflow with emergency operations.

---

### Option C: 5 Sections (RECOMMENDED)

```
I. Culture              (onboard)
II. Security            (onboard + reference)
III. Workflow           (daily)
IV. Operations          (emergency + policy)
V. Subprojects          (project)
```

**Benefits:**
- Each section has ONE reading pattern
- Clear mental model: "I need emergency help → Section IV"
- Culture and Security are separate (Security is technical, Culture is values)
- Workflow is daily, Operations is reference
- Can grow: add subprojects to V without touching I-IV

---

### Option D: 6 Sections

```
I. Culture
II. Security
III. Workflow
IV. Emergency Response
V. Compliance & Policy
VI. Subprojects
```

**Problem:** Emergency and Policy are both "read as needed" — splitting them creates a thin Section V (compliance is ~50 lines).

---

### Option E: 7+ Sections

Too granular. Hard to remember which section contains what. Defeats the purpose of a handbook.

---

## Final Recommendation: 5 Sections

```markdown
# Clavitor Agent Handbook

## Section I — Culture
Who we are, what we believe, how we treat foundations.
- Foundation First, KISS, DRY, Q&D is research
- Error handling philosophy (every if needs an else)
- Agent personas (Sarah, Charles, Maria, James, Emma, Arthur, Victoria, Luna, Thomas, Hugo, Hans, George)
- When principles conflict (escalation, violation handling)

## Section II — Security
The threat model and cardinal rules. Non-negotiable.
- Threats A, B, C
- Cardinal Rules #1-4 (Loud failures, dumb server, trust browser, FIPS 140-3)
- Exceptionally rare terms (master_key, L3, P3)
- Cryptographic hygiene

## Section III — Workflow
How we work together day-to-day.
- Git workflow (commit format, branches, push guidelines)
- Agent-authored PRs (template, review process)
- Daily review checklist (LLM-driven verification)

## Section IV — Operations
How we run the service and handle incidents.
- Incident Response (agent lock/unlock, token compromise)
- Emergency procedures (owner lockout, vault compromise)
- Data retention (paying vs non-paying)
- Compliance (cross-border, Zurich anchor)
- Adding new principles (format, deprecation)

## Section V — Subprojects
Domain-specific guidance. Read before touching that code.
- clavis-vault (Sarah)
- clavis-cli (Charles)
- clavis-crypto (Maria)
- clavis-chrome/firefox/safari (James)
- clavitor.ai/admin (Emma)
- clavis-telemetry (Hans)
- Localization (English-first, RTL not priority)
```

---

## Size Targets (with hard limits)

| Section | Target | Hard Limit | Escape Valve |
|---------|--------|------------|--------------|
| I. Culture | 250 lines | 400 | Stop adding philosophy |
| II. Security | 200 lines | 300 | Move threat details to `docs/THREAT-MODEL.md` |
| III. Workflow | 300 lines | 500 | Move checklists to subproject CLAUDE.md |
| IV. Operations | 350 lines | 500 | Move incident playbooks to `docs/RUNBOOKS/` |
| V. Subprojects | 300 lines | 600 | Add new subproject = add subsection |
| **Total** | **1,400** | **2,300** | If total > 2,000, split Section V to `docs/SUBPROJECTS.md` |

---

## Reading Guide (for agents)

| Situation | Read |
|-----------|------|
| First time here | Section I completely, skim II-IV |
| About to make a commit | Section III (Git workflow) |
| Security alert / incident | Section IV (Operations) |
| Touching vault code | Section V: clavis-vault |
| Not sure who you are | Section I: Agent personas |
| Principles conflict | Section I: When principles conflict |
| Adding a new principle | Section IV: Adding new principles |

---

**Conclusion:** 5 sections matches the 5 reading patterns. Each section has a clear purpose and audience. Not too many to remember, not too few to be cluttered.

**Does 5 sections feel right?**