Foundational Documents

The paddles repository contains a stack of markdown documents that define the project's architecture, philosophy, and operational commitments. This page explains the reading order and what each document covers.

Reading Order

Order	Document	What it covers
1	AGENTS.md	Operator guidance and the top-level working contract for agents
2	INSTRUCTIONS.md	The canonical Keel turn loop and procedural checklists
3	README.md	Backbone architecture narrative, current capabilities, growing edges, and the high-level steering-signal map
4	CONSTITUTION.md	Collaboration philosophy, environmental calibration, and core invariants
5	POLICY.md	Operational commitments: boot invariants, zero drift, model routing, steering-signal guarantees, mission criteria
6	ARCHITECTURE.md	Turn loop narrative, implementation map, context architecture, recorder boundary, and the detailed steering-signal taxonomy
7	PROTOCOL.md	Communications protocol, message format, routing rules
8	CONFIGURATION.md	Concrete lane and runtime configuration reference

Supplementary References

Document	What it covers
CODE_WALKTHROUGH.md	Source layout, key abstractions, data flows, where-to-look table
STAGE.md	Visual philosophy for scene-based CLI output
RELEASE.md	Versioning and release process
.keel/adrs/	Binding architecture decision records

Decision Hierarchy

The reading order is not the decision hierarchy. When documents disagree:

1. ADRs (binding decisions)
2. CONSTITUTION (philosophy and invariants)
3. POLICY (operational commitments)
4. ARCHITECTURE (implementation contracts)
5. Current planning artifacts (missions, epics, stories)

Pressure Reading Route

If you specifically want to understand how Paddles applies steering signals inside the harness, read these in order:

1. README.md for the high-level steering-signal families
2. POLICY.md for the binding controller commitments
3. ARCHITECTURE.md for the detailed runtime taxonomy, influence snapshots, and the boundary between the forensic inspector and the metaphorical manifold route
4. Steering Signals for the public-facing explanation, including the manifold route and its accountability limits
5. Recursive Planning for how steering signals change planner behavior

What To Read Next

• Turn Loop — the architectural narrative explained for newcomers
• Steering Signals — how steering signals shape the recursive harness
• Context Tiers — the four-tier context model
• Search and Retrieval — planner retrieval modes, caps, and trace