# 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`](./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`](../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