Start with AGENTS.md at the repo root — it is the short version, and it links here for
anything that needs more than a line.
Each document below has one job and one trigger: the change that obliges you to edit it. A document that contradicts the code is a defect, so fix it in the commit that made it wrong.
| Document | Covers | Edit it when |
|---|---|---|
| architecture.md | How the app is wired: the layers, who owns what, the windows, the Observation model, the folder tree | a layer boundary, an owner, or the tree changes |
| standards.md | How code here is written: posture, naming, style, concurrency, performance budgets, comments | a convention changes, or a check is added |
| testing.md | How to verify a change: the definition of done, the harnesses, purity checks, budgets, the manual sweep | a harness moves, or a budget changes |
| development.md | The local loop: setup, build, dev channel, editor, format/lint, generated data | the local toolchain changes |
| release.md | How a build reaches a user: packaging, CI, releases, the Homebrew tap, the website | the pipeline changes |
| signing.md | The self-signed identity and the two CI secrets | the signing setup changes |
| ui.md | The design system: tokens, panel chrome, row grammar, glass, dialogs and HUDs | a token or a presentation rule changes |
One document per feature, covering its invariants and internals. A few span more than one source
folder — palette.md covers Tinycast/Palette/, backup.md covers two. Every one of them must
open with an ## Invariants section; read it before changing anything in that area.
palette · launcher · AI providers and chat · quick actions · clipboard · calculator · calendar · camera · emoji · file search · menu search · notes · snippets · quicklinks · Apple Shortcuts · hotkeys · navigation · window management · window layouts · custom commands · uninstall · backup · Raycast import · Raycast extensions · updates · support
CONTRIBUTING.md covers the workflow — what to open, what to test, what a PR needs.
SECURITY.md covers vulnerability reports.