---
id: release-readme
name: Crate README (written last, honestly) + LICENSE + CHANGELOG
status: pending
depends_on: [release-crate-docs, release-deployment-matrix, release-contract-window-close, release-findings-2-3-disposition, release-n1-growth-posture]
scope: narrow
risk: low
impact: component
level: implementation
tags: [wave-8, docs, readme]
---

## Description

The plan's wave-8 "crate README (written last, honestly)" — the root
`README.md` does not exist yet, and it is written *last* so it
describes the shipped thing, not the intended one. Its dependencies
are the wave's other doc-shaped tasks for exactly that reason.

1. **`README.md`** (root, the crates.io-facing front page): what
   alkstore is (one reactive store interface — notify, streams,
   queues, locks, scheduler, outbox — over SQLite, Postgres, and the
   in-process mem engine), the crate family table (which crate to
   pick, per ADR-016's compile-time engine identity), the honest
   posture lines per engine (single-host file-backed / multi-host /
   honest-ephemeral, never fleet-valid), a minimal usage sketch
   (compile-checked against the real API — the mem engine is the
   zero-config example carrier), the contract-suite pointer (three
   engines, one pinned contract), and the license note. No
   aspirational claims: only what waves 1–7 shipped.
2. **LICENSE files**: `LICENSE-MIT` + `LICENSE-APACHE` at the root per
   the family pattern (alkcall/alksocks ship both; the workspace
   `license = "MIT OR Apache-2.0"` field is set but no license files
   exist). The substrate's in-tree dual-license notice (ADR-018) stays
   as landed — the root files do not replace it.
3. **`CHANGELOG.md`**: seeded per the family pattern — the 0.1.0
   initial-release entry summarizing the contract v1 surface and the
   three engines (honest, brief; the family's changelogs are
   release-note-shaped, not commit logs).
4. **Per-crate readme wiring**: decide whether each published crate's
   `[package] readme` points at the root README or gets its own short
   crate-specific readme (the engines' lib docs already carry their
   posture — a pointer-style per-crate readme is the likely honest
   shape); land the decision.
5. **Honesty cross-check**: every README claim traceable to a spec
   (core-contract.md, deployment.md, the engine specs) — this is the
   "written last, honestly" discipline, and the review gate will
   audit it.

## Acceptance Criteria

- [ ] Root `README.md` exists: family table, per-engine honest
      postures, compile-checked usage sketch, suite pointer, license
      note; no aspirational/unshipped claims
- [ ] `LICENSE-MIT` + `LICENSE-APACHE` at the root (MIT + Apache-2.0
      canonical texts); ADR-018's in-tree substrate notice untouched
- [ ] `CHANGELOG.md` seeded with the 0.1.0 entry
- [ ] The per-crate readme wiring decided + landed
- [ ] Every README claim traceable to a spec (the trace list in Notes)
- [ ] Workspace gates green (docs-only expected)

## References

- docs/plans/implementation.md §Wave 8 (written last, honestly)
- docs/architecture/overview.md (the family/feature source)
- docs/architecture/deployment.md (the posture lines)
- docs/architecture/decisions/016-deployment-honesty.md,
  docs/architecture/decisions/018-provenance-register-and-cherry-picks.md
- /workspace/@alkdev/alkcall/README.md + CHANGELOG.md (the family
  pattern)

## Notes

> To be filled by implementation agent

## Summary

> To be filled on completion