CLAUDE.md

1# CLAUDE.md — sno-ai/mda
2 
3Project memory for Claude Code. Read on every session.
4 
5## Release process for @markdown-ai/cli
6 
7**No more asking the user about version numbers, npm tokens, trusted
8publishing, or auth.** Everything below is settled. Just execute.
9 
10### To cut a release (any 1.1.x, 1.2.0, 2.0.0 — same flow)
11 
121. Edit `apps/cli/package.json` → bump `version`
132. `pnpm cli:test` (must pass; tests dynamically read the version)
143. `git add apps/cli/package.json && git commit -m "chore(cli): bump to <version>"`
154. `git push origin main`
165. `git tag v<version> HEAD`
176. `git push origin v<version>`
187. `gh run watch $(gh run list --workflow=publish-cli.yml --limit 1 --json databaseId --jq '.[0].databaseId')`
198. `npm view @markdown-ai/cli@<version> version` to confirm registry
209. **Write real GitHub Release notes by hand and publish them.** See
21   "Release notes — non-negotiable" below. This step is part of the
22   release; the release is not done until the GitHub Release exists
23   with a written body.
24 
25The user does not need to do anything for any of these steps. Do not ask
26which version number to use — for a publish-only request, increment the
27patch. Do not ask whether to write release notes — always write them.
28 
29### Release notes — non-negotiable
30 
31The GitHub Release body **must** be hand-written for every version.
32`--generate-notes` produces a useless "Full Changelog: vA...vB" one-liner
33when there are no merged PRs between tags (which is most patch releases
34in this repo), so the workflow no longer creates the Release
35automatically. Writing the body is the agent's responsibility.
36 
37Minimum required structure:
38 
39```md
40## What's new
41 
42<one sentence per user-facing change, lead with the change name in bold.
43example: **`mda demo`** — one command to see the four-artifact flow ...>
44 
45## Other changes
46 
47<bullet list of smaller things: docs, CI, internal>
48 
49## Why the version jump (only if patches were skipped)
50 
51<one paragraph explaining which version numbers were skipped and why>
52 
53## Install / upgrade
54 
55<copy-pasteable npm install + npx invocation>
56```
57 
58Source for the notes: `git log --oneline <previous-shipped-tag>..v<new>
59-- apps/cli/` plus `git show <commit>` on anything that looks
60user-facing. Ignore `chore(cli): bump to ...` and pure-CI commits — they
61are not what users care about. Group by user-visible feature, not by
62commit.
63 
64Write the body to a temp file, then:
65 
66```sh
67gh release create v&lt;version&gt; \
68  --title &quot;@markdown-ai/cli &lt;version&gt;&quot; \
69  --notes-file /tmp/v&lt;version&gt;-notes.md \
70  --latest \
71  --verify-tag
72```
73 
74(Use `gh release edit ... --notes-file` if the release already exists.)
75 
76After creation, eyeball https://github.com/sno-ai/mda/releases/tag/v<version>
77once to confirm the body actually renders the way you expect. If it
78shows only "Full Changelog: vA...vB", the notes file was wrong — fix
79and re-edit.
80 
81### Auth — already configured, do not touch
82 
83- npmjs.com has a Trusted Publisher binding on `@markdown-ai/cli`:
84  - Repo: `sno-ai/mda`
85  - Workflow: `publish-cli.yml`
86  - Environment: (blank)
87- Workflow uses OIDC via `id-token: write` permission. No NPM_TOKEN, no
88  `registry-url` on setup-node, no `env: NODE_AUTH_TOKEN` block.
89- Provenance is signed with sigstore via the same OIDC token.
90 
91If CI ever fails with `OIDC token exchange error - package not found`,
92the binding was removed/changed npmjs-side. That is the only npmjs.com
93issue worth flagging to the user — and only after confirming via the
94verbose publish log. Do not preemptively ask them to "verify the
95binding."
96 
97### What NOT to do (lessons from the v1.1.3–v1.1.6 publish loop)
98 
99- Do not add `NODE_AUTH_TOKEN` env or `registry-url` to setup-node.
100  Either one breaks OIDC: empty `NODE_AUTH_TOKEN` makes npm send an
101  empty bearer (404 from registry); a configured token blocks OIDC
102  auto-detection entirely.
103- Do not assume a 404 means "package missing" — npm registry returns
104  404 for "auth ok but no permission" too. Read `--loglevel=verbose`
105  output before guessing.
106- Do not reuse a failed tag (don't delete and recreate `vX.Y.Z`). Bump
107  the patch instead — tag deletion is destructive and unnecessary.
108- Do not amend release commits or force-push. New commits only.
109- Failed publish tags from 2026-05-26 (v1.1.3 through v1.1.6) are
110  harmless leftovers. Do not delete them without explicit ask.
111 
112### When the publish fails
113 
1141. `gh run view <run-id> --log 2>&1 | awk '/Run npm publish/,/Process completed/'`
1152. Diagnose from the verbose log alone — do not add diagnostic steps to
116   the workflow unless the log is genuinely insufficient.
1173. Communicate the exact npm error + the exact fix in one message. Do
118   not ask the user to "check" or "verify" anything they can read off
119   the URL you'd link them to.
120