Initial scaffold: spec, architecture playbook, and M0 skeleton

2026-08-08 02:02:33 +00:00 · 2026-06-04 22:14:33 +03:00
commit 056644450c
51 changed files with 13754 additions and 0 deletions
@@ -0,0 +1,94 @@
+---
+name: release
+description: Bump the app version, update the changelog, and prepare a git tag for release
+disable-model-invocation: false
+---
+
+# Release
+
+Bump the app version, update the changelog, and prepare a git tag.
+
+## Process
+
+### 1. Determine what changed since the last version
+
+Run `git log` from the last version tag (or all history if no tags exist) and review the
+changes. Categorize:
+
+- **Features**: new user-facing capabilities
+- **Fixes**: bug fixes
+- **Improvements**: performance, UX polish, refactoring that affects behavior
+- **Internal**: refactoring, docs, tests, build (don't list individually — summarize if substantial)
+
+### 2. Determine bump type
+
+Read the current version from `package.json`. The project uses **simplified semver during
+pre-1.0**:
+
+| Bump | When | Example |
+| --- | --- | --- |
+| **Minor** (`0.x.0`) | New features, UI changes, behavior changes | `0.1.0` → `0.2.0` |
+| **Patch** (`0.x.y`) | Bug fixes, polish, performance, internal | `0.1.0` → `0.1.1` |
+| **Major** (`1.0.0`) | Only when declaring public stability (user decision) | — |
+
+Present the categorized changes and your recommended bump type to the user **for confirmation
+before proceeding**.
+
+### 3. Update version
+
+Update the `version` field in `package.json`. This is the **single source of truth** — Vite
+injects it as `__APP_VERSION__` at build time (shown in the header badge, and in Settings /
+the export envelope once those exist).
+
+### 4. Update the changelog
+
+Maintain `docs/CHANGELOG.md`. If it doesn't exist yet, create it with a top-level `# Changelog`
+heading. Add a new entry under a month heading:
+
+```markdown
+## June 2026
+
+### v0.2.0
+
+- **New feature** — description…
+
+### v0.1.1
+
+- **Bug fix** — description…
+```
+
+- Group by feature/change, not by commit.
+- Lead with the name in bold, then a dash and description.
+- Most important changes first; summarize related commits into coherent items.
+
+### 5. Cross-check user-facing docs
+
+Scan hand-maintained user-facing surfaces against the changes landing in this release and fix
+drift **before** the version-bump commit (the CHANGELOG entry is not the place to quietly slip
+in doc fixes):
+
+- `README.md` — the status line and any feature claims still accurate?
+- Any in-app help / about / onboarding content that exists at release time.
+
+(When narrative content pages are added later, list them here so this net catches accumulated
+drift across many changes.)
+
+### 6. Suggest the git tag
+
+After the user stages and commits the version bump, suggest:
+
+```bash
+git tag v{version}
+git push --tags
+```
+
+If/when a deploy pipeline is wired, note here what publishing the tag triggers.
+
+## Rules
+
+- **Never bump the version without user confirmation** on the bump type.
+- **Never stage or commit** — the user handles git operations.
+- The export-format `version` (the import/export envelope) is **independent** of the app
+  version — only bump it when the export schema actually changes.
+- Keep commit subjects single-line; no `Co-Authored-By` trailers (the user handles the commit
+  regardless).