# Release procedure

Read this file whenever I ask for a release. Do the whole thing in one turn except for the
question in §1, which always gets asked.

**The version number lives in `README.md`** — the `**Version**` line under the title is the
single source of truth. `CHANGELOG.md` records what each version contained; `README.md`
records which version *is*. If the two disagree, README is wrong: correct it to the
changelog's newest shipped entry and report the correction.

---

## 1. Ask first — always

Never assume the version. Ask, with a form:

1. **Same version or new one?**
   - *Same* — a re-cut of the current version. No bump, no new changelog entry; add a
     one-line note under the current entry only if the contents changed.
   - *New* — ask, in the same form: **patch**, **minor** or **major**.
2. **One freeform field** for the release note, in the changelog's voice. If it comes back
   empty, write it from what changed since the last release and say that you did.

Bump rules, applied to `MAJOR.MINOR.PATCH`:

| Bump | When | From this project's history |
|---|---|---|
| **patch** | Fixes and copy corrections only. No new rule, no new component, no new template, nothing removed. | — |
| **minor** | Additions that don't invalidate existing work: new components, templates, cards, or rules that only add a requirement. | 0.4, 0.6, 0.8 |
| **major** | Anything that makes a screen built against the previous version wrong: token re-resolution, renamed rules, removed templates, changed defaults. | 0.7, 0.9, 1.0 |

A breaking change is named as such in the changelog entry and is never cut as a minor.

---

## 2. Before packaging

Stop and report rather than packaging around a failure.

- [ ] **`check_design_system` clean** — orphan `.d.ts`, unresolved `@font-face`, a card
      loading raw `.jsx`, duplicate component names or a stale readme all block the
      release. Fix, re-run, and only then package.
- [ ] **`README.md` §5 inventory** matches what is actually in the project — files, cards,
      components and templates added or removed since the last release are reflected.
- [ ] **`CHANGELOG.md`** has the new entry with the **real date** (never a relative date
      for a release you just cut), its bump class named, and the **Current** row and marker
      moved onto it.
- [ ] **`github.md` `## Last sync`** refreshed: real ISO timestamp, the previous sync moved
      into `## Sync history`.
- [ ] **`LICENSE.md`, `NOTICE.md` and `licenses/AGPL-3.0.txt`** current. Reckon is
      **AGPL-3.0-or-later** — the token layer is derived from `packages/ui/`, which carries
      the upstream default, and no MIT-licensed copy of those values exists (`NOTICE.md`
      §0). The full licence text ships with every package. Re-read `NOTICE.md` at every
      release: if assets were added or removed, its list changes with them.
- [ ] **Public release only:** nothing in `NOTICE.md` still marked **UNVERIFIED** or
      **UNRESOLVED**. Three items stand today — the Cal Sans and Paper Mono binaries, the
      wordmark trademark, and the consent status of the photography. Until they clear, the
      release is internal and the changelog entry says so in one line. An internal release
      is not blocked by them.

---

## 3. Package A — `reckon.zip`

The full project: everything a consumer needs to use the system.

Included — `styles.css`, `tokens/`, `css/`, `assets/`, `components/`, `guidelines/`,
`templates/`, `thumbnail.html`, `licenses/`, every root markdown
file (`LICENSE.md` and
`NOTICE.md` included),
and the compiler
output (`_ds_bundle.js`, `_ds_manifest.json`, `_adherence.oxlintrc.json`,
`_thumbnail.webp`) — consumers load the bundle.

Excluded — `scraps/`, `uploads/`, screenshot folders, and any working file that isn't part
of the system.

---

## 4. Package B — `reckon-rules.zip`

The layer that travels without the code, for dropping into another project or another
agent's context:

- `CLAUDE.md` — the project instruction that points at the rules
- `AGENTS.md` — the assembly and derivation rules
- `SKILL.md` — the Agent-Skills front matter
- `README.md` — the system guide
- `CHANGELOG.md`, `RELEASE.md`
- `LICENSE.md`, `NOTICE.md` and `licenses/AGPL-3.0.txt` — both packages carry all three; a
  rules-only drop is still an AGPL-3.0 distribution
- `PROMPTS.md` — the worked example prompts (§5)
- every `components/**/*.prompt.md` usage note, folder structure kept, so a reader gets the
  usage guidance for all 54 families without the implementations

No `.jsx`, no `.d.ts`, no CSS, no fonts, no images in this package.

---

## 5. `PROMPTS.md`

Lives at the project root, ships in Package B, and is **re-read at every release** to check
it still matches the rules. It carries worked full-product prompts — the
`templates/<slug>/` desk shape — each with the shape of the answer it should get.

If a rule changed in this release, the affected example is updated in the same turn.

---

## 6. Delivery

Neither zip carries the version in its filename. Offer both as downloads in the same
message, Package A first, and state in one line: the version, the bump taken, and what the
release contains.

**Staging is temporary and must be deleted in the same turn it is presented.** The packages
are assembled by copying files into `dist/reckon/` and `dist/reckon-rules/`, and while that
folder exists the compiler reads it as part of the design system: the staged files register
as duplicate components, every one colliding with its own original on `window.<Namespace>`.
Present the two downloads, then delete `dist/` immediately — never end a turn with it in the
project, and never include it in Package A.

`CHANGELOG.md` is the record — there is no second release log, and no release zips are kept
in the project.
