reckon build — CI static site generation

§ 1 — Problem

The reckon server (v8+) serves UI assets via canonical routes: /_ui/<file> and /_shared/<file>. Generated index.html uses these absolute paths. This works perfectly with the live server but breaks for static deployment — GitHub Pages has no reckon process to serve those routes.

Additionally, sprint and milestone definitions currently require authoring index.json by hand. This is the last piece of wiring that plans do not have: plans auto-discover from HTML meta tags; sprints and milestones do not.

§ 6 — Implementation review & recommendations (2026-05-27, Opus)

6 of 6 actions landed Distribution naming, installed-wheel assets, uv CI, build tests, release tagging, and distributed project state are complete. The historical analysis below is retained as the record that motivated the package and storage corrections. Final evidence.

Reviewed the shipped code against this plan. The build command, sprint/milestone HTML discovery, and the sync --generate-ci flag all landed. But the CI install story (§4 + §5) is not deployable as written — three blockers, detailed below. The driving fix is the user's instinct: CI should pull reckon in as a uv-managed dependency, not pip install reckon.

§ 6.1 — Section-by-section status

§ 6.2 — The three blockers

A. PyPI name collision (§4, §5). https://pypi.org/project/reckon/ resolves to "reckon: Dead simple, dynamic caching" by Sean Stewart — not this project. Any CI that runs pip install reckon installs that package, and reckon build is simply not found. The distribution must be renamed to an available name (e.g. reckon-plans) while keeping the reckon import package and reckon console-script unchanged.

B. The wheel does not ship the UI assets (§2, §4). build copies assets from Path(__file__).parent.parent / "docs" / {ui,_shared}, but the wheel ([tool.hatch.build.targets.wheel] packages = ["reckon"]) contains only reckon/*.py — verified: 11 entries, no docs/. So from an installed wheel the if ui_src.is_dir() guard is false and asset copying is silently skipped — producing a broken static site with no error. build only works today when run from a git checkout (where docs/ui/ exists beside the package). Fix: ship the assets in the wheel via hatch force-include, or move them under reckon/_assets/ and resolve with importlib.resources.

C. CI is pip-based, not uv-managed (§4) — the user's ask. Even after A+B, the workflow should use uv for reproducibility and to match how reckon is run everywhere else on this host (uv run --project ~/Code/reckon reckon …).

§ 6.3 — Recommendation: bring reckon in as a uv-managed CI dependency

Variant 1 — works today, no packaging changes (source checkout via uv). Because the wheel omits assets (blocker B), the only correct install is from source. Check out reckon as a second repo and run it through uv from that tree — pin with ref: for reproducibility:

name: Deploy plans to GitHub Pages
on: { push: { branches: [main] }, workflow_dispatch: {} }
permissions: { contents: read, pages: write, id-token: write }
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4                 # the project whose docs/ we publish
      - uses: actions/checkout@v4                 # reckon itself (ships docs/ui + docs/_shared)
        with: { repository: Simon-McIntosh/reckon, ref: v0.2.0, path: .reckon-src }
      - uses: astral-sh/setup-uv@v6
      - run: uv run --project .reckon-src reckon build "$GITHUB_WORKSPACE/docs"
      - uses: actions/upload-pages-artifact@v3
        with: { path: docs/ }
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment: { name: github-pages, url: "${{ steps.deployment.outputs.page_url }}" }
    steps:
      - uses: actions/deploy-pages@v4
        id: deployment

Variant 2 — after blockers A + B are fixed (packaged + published). Once assets ship in the wheel and the dist is renamed, the install collapses to one uv line, pinned to a published version:

      - uses: astral-sh/setup-uv@v6
      - run: uvx --from "reckon-plans==0.2.0" reckon build docs/
        # or, git-pinned without a PyPI release:
        # uvx --from "git+https://github.com/Simon-McIntosh/reckon@v0.2.0" reckon build docs/

A consuming repo that already uses uv can instead declare reckon in its own pyproject.toml under [tool.uv.sources] (git + ref) and call uv run reckon build docs/ — same lockfile-pinned reproducibility, no extra checkout step.

§ 6.4 — Recommended next steps (queued as the followup below)

1. Open a dist-name decision and rename the distribution off the squatted reckon name.
2. Ship UI assets in the wheel (hatch force-include or reckon/_assets/ + importlib.resources); add a wheel-install smoke test.
3. Rewrite the generated CI template to uv (Variant 1 now; Variant 2 after 1+2), and commit a copy for reckon's own Pages deploy.
4. Add tests/test_build.py covering asset copy, relative paths, .nojekyll, inventory.
5. Reconcile index-json-fate: realise "deprecate entirely" or reopen the decision via the dissent flow — today it is locked but unimplemented.
6. Cut the first git tag so hatch-vcs emits a real version.