cinny/docs/handoff/README.md

Handoff documentation

Handoff docs capture what a new maintainer needs to own a feature: behavior, architecture, data model, sharp edges, and how to verify changes.

When to write one

Create or update a handoff when:

• A feature is Paarrot-specific (not vanilla Cinny upstream)
• The feature spans multiple layers (UI + Matrix + Electron/Android)
• You are about to hand work to another person or pause development

Inherited Cinny features (basic room timeline, auth flows, etc.) do not need handoffs unless Paarrot has materially changed them.

Folder convention

handoff/features/<kebab-case-name>/
  HANDOFF.md

Use short, product-facing names: voice-calls, sub-rooms, local-api.

How to fill in a handoff

1. Copy TEMPLATE.md to features/<name>/HANDOFF.md
2. Fill every section — delete "Add your extra things here" placeholders
3. Link to existing reference docs instead of duplicating them
4. Add the feature to the table in ../README.md
5. List real file paths (grep the codebase; do not guess)

Sections explained

Section	Purpose
Summary	One paragraph: what it does and why it exists
User-facing behavior	What users see and configure
Architecture	Layers, main modules, request/event flow
Key files	Paths a maintainer will touch first
Data model	Matrix state events, account data, local storage
Dependencies	External services, npm packages, OS APIs
Integration points	Other features, IPC, plugins, API
Testing	Manual steps and any automated tests
Known issues	Bugs, limitations, tech debt
Related docs	Links to API refs, READMEs, upstream specs

Keeping handoffs current

Update the handoff in the same PR when you:

• Add a new Matrix event type or account data key
• Change IPC or HTTP API contracts
• Move or rename core modules