# Build Ledger

A one-page ledger for the clinic recorder’s builds. Every build gets a human name — Carpal through Dexterity — with its date, one change score and where it runs, so “which version is live?” never needs a git hash. Notes pin themselves to a build, and a small MCP server lets my agents answer the same question. The live app is Tailscale-only; the public overview shows what’s inside.

**Status:** Live · Projects · 2026

- **Local checkout:** `/Users/simon/Developer/build-ledger` (branch `main`, last commit 041fce3, 2026-11-08 — Add pil-dataflow to the project gallery)
- **Repository:** https://github.com/ShimonNavon/build-ledger
- **On another machine:** `git clone https://github.com/ShimonNavon/build-ledger` — the paths below are Simon's Mac
- **Live:** https://builds.navonsimon.com/
- **Overview:** https://projects.navonsimon.com/build-ledger.html
- **Where it runs:** namespace build-ledger · NodePort 30096 · private tailnet gateway

## Stack

Single-file HTML, Python stdlib build, MCP stdio server, Kubernetes

## Start here

- `versions.json` — the ledger: builds, names, deploy targets, change scores, notes, rollbacks
- `projects.json` — portfolio catalogue mirrored by projects.navonsimon.com
- `template.html` — page look and behaviour
- `build.py` — renders dist/index.html
- `tools/ledger_mcp.py` — MCP server: list_versions, get_version, production, list_projects, get_project
- `tools/sync_branches.py, install_branch_sync.py` — LaunchAgent that publishes a live branch snapshot

## Commands

- **Build page:** `python3 build.py --open`
- **Focused tests:** `python3 -m unittest discover -s tests`
- **Publish:** `./deploy/deploy.sh`

## Deploy and where it runs

- Namespace build-ledger, NodePort 30096 on ubuntu04.
- Private gateway on ubuntu01 builds.navonsimon.com (tailnet only, TLS via Cloudflare DNS validation); the backend also requires a secret gateway header.
- Regular publishing preserves the gateway Secret and fails if it is missing.

## Current state

Live and private. Builds must be referred to by name (Carpal…Dexterity), never by tag or hash in conversation.

## Watch out

- Do not re-enable Cloudflare proxying for builds.navonsimon.com; the DNS-only record must resolve to the tailnet address.
- The ledger is only true after an edit: deployed, rolled back or renamed builds must update versions.json and be rebuilt.
- Branch tracking runs on Simon's Mac; an offline Mac keeps the last snapshot and marks it delayed after four minutes.

## Secrets — locations only, never print values

- .private/ (git-ignored); the gateway token lives in a Kubernetes Secret named access.

## Tags

MCP, Single-file HTML, Kubernetes

---

Brief generated 2026-11-08 from `~/Developer/my-projects/context/`. Canonical URL: https://projects.navonsimon.com/context/build-ledger.md
