# Design Docs

This section holds the human-written design layer for the repo. Use it for
cross-cutting architecture decisions, guiding principles, and docs that should
outlive a single ticket.

## What Lives Here

- Cross-cutting design decisions that affect more than one module
- Operating principles for how the repo should evolve
- References to stable architecture documents and future ADR-style notes

## Main Entry Points

- [`../ARCHITECTURE.md`](../ARCHITECTURE.md): system topology and request paths
- [`./design-docs/index.md`](./design-docs/index.md): design-doc catalog
- [`./design-docs/core-beliefs.md`](./design-docs/core-beliefs.md): base
  beliefs for documentation and architecture changes

## Authoring Rules

- Prefer small, topic-specific documents over one long catch-all page.
- Link to code paths and operational docs instead of duplicating them.
- If a design decision becomes stale, either update it in the same change or
  delete it.