Fill in the developer documentation gaps #514

Open

Smithy-bot wants to merge 5 commits from cursor/487-developer-docs into release/0.12.0

Smithy-bot commented

2026-09-02 12:20:57 +01:00

Member

Follow-up 2 of 3 from #487, split out as you asked on the issue. Documentation only, no code changes.

This covers all three items in the Documentation gaps section of the checklist.

README gets a Development section with the three CI commands in the order the workflows run them, the migration workflow (db:create -> build -> db:up, and why the build has to come first: the migrations run against dist/), where environment variables live, and what POST /api/reload-db is for.

New docs/development.md for the "how do I add a command" question. Everything is registered in src/registry.ts and nothing is auto-discovered, which is the bit worth writing down. It covers the id-then-instance registration signature, the Environment filter being applied at registration rather than dispatch, that buttons and dropdowns are routed on the first space-separated segment of the custom id, and the test conventions in tests/.

Cross-links in the three existing docs. Each of cards.md, google-drive-sync.md and logger.md now points at where its environment variables live and says what tests are expected when that area changes, plus links between themselves and the README.

Two small README bugs fixed while I was in there:

yarn Install -> yarn install. The capital I fails on a case-sensitive shell.
cp .env.template .env -> cp .env.example .env. There is no .env.template in the repo, so following the README as written left you without a config file.

Two things I chose to be explicit about rather than paper over. The dispatchers on this branch do not await execute, so docs/development.md says so and tells contributors to catch their own failures until #512 lands. Likewise the README says /api/reload-db is currently unauthenticated and points at #512 for the token. Both notes will need a trim once #512 merges - happy to do that as part of merging it, or leave them as accurate history.

yarn lint still passes. No overlap with #512 or #513: #512 adds docs/webhooks.md but touches neither the README nor these three docs.

Follow-up 2 of 3 from #487, split out as you asked on the issue. Documentation only, no code changes. This covers all three items in the Documentation gaps section of the checklist. **README gets a Development section** with the three CI commands in the order the workflows run them, the migration workflow (`db:create` -> `build` -> `db:up`, and why the build has to come first: the migrations run against `dist/`), where environment variables live, and what `POST /api/reload-db` is for. **New `docs/development.md`** for the "how do I add a command" question. Everything is registered in `src/registry.ts` and nothing is auto-discovered, which is the bit worth writing down. It covers the id-then-instance registration signature, the `Environment` filter being applied at registration rather than dispatch, that buttons and dropdowns are routed on the **first space-separated segment** of the custom id, and the test conventions in `tests/`. **Cross-links in the three existing docs.** Each of `cards.md`, `google-drive-sync.md` and `logger.md` now points at where its environment variables live and says what tests are expected when that area changes, plus links between themselves and the README. **Two small README bugs fixed while I was in there:** - `yarn Install` -> `yarn install`. The capital I fails on a case-sensitive shell. - `cp .env.template .env` -> `cp .env.example .env`. There is no `.env.template` in the repo, so following the README as written left you without a config file. Two things I chose to be explicit about rather than paper over. The dispatchers on this branch do not `await` `execute`, so `docs/development.md` says so and tells contributors to catch their own failures until #512 lands. Likewise the README says `/api/reload-db` is currently unauthenticated and points at #512 for the token. Both notes will need a trim once #512 merges - happy to do that as part of merging it, or leave them as accurate history. `yarn lint` still passes. No overlap with #512 or #513: #512 adds `docs/webhooks.md` but touches neither the README nor these three docs.

Smithy-bot added 5 commits

2026-09-02 12:20:57 +01:00

Add a development section to the readme 6533e0fc80