Add package-first build and distribution workflow

docs/persona-and-distribution.md

@@ -0,0 +1,50 @@
+# Aman Target Persona and Distribution Strategy
+
+## Primary Persona: Desktop Professional
+
+This is the canonical Aman user.
+
+- Uses Linux desktop daily (X11 today), mostly Ubuntu/Debian.
+- Wants fast dictation and rewriting without learning Python tooling.
+- Prefers GUI setup and tray usage over CLI.
+- Expects normal install/uninstall/update behavior from system packages.
+
+Design implications:
+
+- End-user install path must not require `uv`.
+- Runtime defaults should work with minimal input.
+- Documentation should prioritize package install first.
+
+## Secondary Persona: Power User
+
+- Comfortable with CLI, package internals, and model customization.
+- Uses advanced config, external APIs, or custom models.
+- Can run diagnostics and debug logs when needed.
+
+Design implications:
+
+- Keep Make and Python workflows available.
+- Keep explicit expert-mode knobs in settings and config.
+- Keep docs for development separate from standard install docs.
+
+## Supported Distribution Path (Current)
+
+Tiered distribution model:
+
+1. Canonical: Debian package (`.deb`) for Ubuntu/Debian users.
+2. Secondary: Arch package inputs (`PKGBUILD` + source tarball).
+3. Developer: wheel/sdist from `python -m build`.
+
+## Out of Scope for Initial Packaging
+
+- Wayland production support.
+- Flatpak/snap-first distribution.
+- Cross-platform desktop installers outside Linux.
+
+## Release and Support Policy
+
+- App versioning follows SemVer (`0.y.z` until API/UX stabilizes).
+- Config schema versioning is independent (`config_version` in config).
+- Packaging docs must always separate:
+  - End-user install path (package-first)
+  - Developer setup path (uv/pip/build workflows)

docs/release-checklist.md

@@ -2,11 +2,16 @@
 
 1. Update `CHANGELOG.md` with final release notes.
 2. Bump `project.version` in `pyproject.toml`.
-3. Run:
-   - `python3 -m py_compile src/*.py tests/*.py`
-   - `python3 -m unittest discover -s tests -p 'test_*.py'`
-4. Build artifacts:
-   - `python3 -m build`
-5. Tag release:
+3. Run quality and build gates:
+   - `make release-check`
+4. Build packaging artifacts:
+   - `make package`
+5. Verify artifacts:
+   - `dist/*.whl`
+   - `dist/*.tar.gz`
+   - `dist/*.deb`
+   - `dist/arch/PKGBUILD`
+6. Tag release:
    - `git tag vX.Y.Z`
    - `git push origin vX.Y.Z`
+7. Publish release and upload package artifacts from `dist/`.