---
name: pi-ext-readme
description: "Use when creating, updating, or reviewing an extension README in pi-ext, including demos and generated configuration references."
---

# Extension README

- Outcome: explain why the extension exists, when someone would choose it, how to use it in Pi.
- Authority: source + public-API tests → facts; root README → installation boundary; Mise → automation.
- Start from [template](references/template.md); compare [rtk exemplar](../../../extensions/rtk/README.md).
- Preserve useful existing details; do not rewrite every README for cosmetic uniformity.
- Banner first, blank line, H1; purpose sentence before supporting details.
- Embed `assets/demo.gif` iff `demo/scene.json` exists; describe what the recording actually shows.
- No scene → omit demo; do not invent one for provider plumbing or desktop integrations.
- Keep browser/IDE examples as concise links when a terminal recording cannot show the behavior.
- Read declarations, registration wrappers, tests before documenting commands, flags, settings, env vars.
- Keep only technical details needed for use: setup, commands, settings examples, limits, privacy, opt-out.
- Omit implementation architecture, hooks, internal types, debug plumbing, benchmarks, test commands, migration history.
- Exactly one `<!-- config:start -->` / `<!-- config:end -->` pair; never manually maintain its contents.
- Run `mise run //:readme-config <name>` then `mise run //:check-readmes <name>`.
- Extraction errors → fix generator; never claim an unknown surface is empty.
- Show a minimal, source-verified config example when setup requires one; never include credentials or edit user config.
- Parsed runtime types are not input schemas; generated references must not present them as required user settings.
- Link existing changelog; do not fabricate release history.
- One sentence per line; concrete behavior over adjectives; no internal function inventory.
- Documentation-only changes do not require new runtime behavior, wider CI, or deployment.