# AGENTS.md — Keysat workspace Self-hosted, Bitcoin-native software licensing service running as a StartOS 0.4.x package, with four wire-compatible SDKs and a public landing/docs site. This file holds whole-repo, every-session facts. Subsystem detail lives in scoped guides under `docs/guides/` (symlinked to `.claude/rules/` so Claude Code auto-loads each when you edit matching files). **Before editing a subsystem, read its guide** — see the index below. ## Stack - **Daemon**: Rust 1.88, `axum`, `sqlx` + SQLite, Ed25519 signing. - **Wrapper**: TypeScript, `@start9labs/start-sdk ^1.3.2`, `@vercel/ncc` bundle, Node 22. - **SDKs**: TS (npm), Rust (crates.io), Python (PyPI), Go (proxy.golang.org). - **Platform**: StartOS 0.4.0.x (LXC under the hood — commands/paths reflect that, not Docker). - **Payment providers**: BTCPay Server (required dep); Zaprite (optional, gated by `zaprite_payments`). ## Subsystem guides (read before editing the area) - Before editing the daemon source, read `docs/guides/daemon-architecture.md`. - Before editing payment / provider / merchant-profile code, the scoped-connect gate, or migrations 0020–0022 + 0024–0025, read `docs/guides/payments.md`. - Before touching self-license or tier-gating code, read `docs/guides/licensing-tiers.md`. - Before changing the LIC1 wire format, crypto, or crosscheck fixtures, read `docs/guides/crypto-wire-format.md`. - Before building, bumping the version, or editing the StartOS wrapper, read `docs/guides/startos-packaging.md`. - Before editing the admin SPA (`web/index.html`), read `docs/guides/admin-ui.md`. - Before editing public site/docs copy, read `docs/guides/website-copy.md`. - **Before building or changing any user-facing UI (landing, docs, admin SPA), read `design/DESIGN.md` and `design/tokens.tokens.json` and conform to them** — the brand contract; pull colors/type/space/radii/shadows from the tokens, never hardcode off-scale values. - Before adding/altering tests or relying on lint/CI, read `docs/guides/testing.md`. ## Build / test / run (quick ref) From `licensing-service-startos/`: `make x86` | `make arm` | `make universal` | `make install` | `make clean` | `npm run check`. From `licensing-service-startos/licensing-service/`: `cargo check` | `cargo build --release` | `cargo test` | `cargo test --test ` | `cargo test `. Details, the version-bump-before-build rule, and release scripts: `docs/guides/startos-packaging.md`. Test suites, the no-CI / formatting-not-enforced status, and known-failing tests: `docs/guides/testing.md`. ## Directory layout ``` licensing-service-startos/ daemon + StartOS wrapper (s9pk package source) licensing-service/src/ Rust daemon → guides/daemon-architecture.md licensing-service/migrations/ SQLite migrations (numbered, additive) licensing-service/web/index.html embedded admin SPA → guides/admin-ui.md licensing-service/tests/ integration suites → guides/testing.md startos/ wrapper TS → guides/startos-packaging.md onboarding-harness/ docs-onboarding test rig → onboarding-harness/README.md Dockerfile Makefile s9pk.mk build pipeline keysat-xyz-landing/ keysat-docs/ public sites → guides/website-copy.md licensing-client-{rust,ts,python,go}/ the four SDK source repos activate-license-template/ StartOS license-activation wrapper template (drop-in actions) design/ design contract (DESIGN.md + tokens.tokens.json) + brand/ assets; original Claude Design system archived in design/_imports/ plans/ design specs (multi-provider-payment-model.md, keysat-smtp-emails.md) tests/crosscheck/ cross-language LIC1 verifier → guides/crypto-wire-format.md ``` Note: the daemon (`licensing-service-startos`, repo `keysat`), each SDK, and `plans/` are **separate git repos** — commit code/plan changes in their own repo. The root `Licensing` repo (`keysat-root`) tracks only `AGENTS.md` + `docs/guides/` + `.claude/rules/` + `EVALUATION.md` (the latest full-eval report; overwritten each run, history in git log). **Remotes differ per repo**: the daemon's `main` tracks **GitHub** (`origin`, the public upstream) with a `gitea` backup — plain `git push` goes to GitHub, so also `git push gitea main`; root + plans are **Gitea-only**. Run `git remote -v` (full) and check what the branch tracks before pushing. ## Conventions (whole-repo) - Daemon licensed `LicenseRef-Keysat-1.0` (custom, source-available); SDKs MIT. - Commits in imperative mood, body only when the "why" isn't obvious. **Sign as Keysat (Grant), not Claude** — git user is `Keysat`. - Direct push to `main` + run `~/.keysat/publish.sh` is the authorized release flow until launch. - Never rewrite user-facing copy outside the explicit scope of a request. ## Never - **No AI co-authorship** on commits or PRs (no "Co-Authored-By", no "Generated with…"). - **Don't push `--no-verify`** or bypass hooks unless explicitly authorized. - **Don't commit built artifacts** (`*.s9pk`, `keysat-*.s9pk`, `javascript/`) or **secrets** — reference env-var names; real values live in `~/.keysat/filebrowser.env` and `/data/keysat-license.txt` outside the repo. ## Memory references Operator-specific memories at `~/.claude/projects/-Users-macpro-Projects-keysat/memory/` (scan before a major change): `keysat_release_workflow.md`, `no_unauthorized_copy_changes.md`, `keysat_admin_ui_pill_convention.md`, `startos_lxc.md`, `startos_registry_icon_unrenderable.md`, `keysat_open_threads.md`. ## Open TODOs - `riscv` build target is unverified and not declared in the manifest; the wrapper `Makefile` now pins `ARCHES` to `x86 arm` so no target (even a bare `make`) attempts it. Revisit only if a riscv StartOS target appears. - StartOS Community Registry submission — remaining gap is a `prepare.sh` for the clean-Debian first build (plus the on-box manual verification); functional criteria otherwise pass. Detail in ROADMAP. Submission criteria themselves still unpublished; reach out when ready. - Split `audit:read` out of the blanket `:read` scope into its own tier so a Read-only scoped key can read dashboards/licenses but NOT the full audit log (`api/api_keys.rs::Role::grants`). Deferred from the scoped-keys session. ## Current state (2026-06-18) - **Live / canonical: `0.2.0:60`** — universal s9pk at `files.keysat.xyz/keysat.s9pk` (byte-verified) + GitHub release `v0.2.0-60` + registry-registered; installed on the live box `immense-voyage.local` and serving (master `licensing.keysat.xyz` returns 200 post-restart). Migrations through 0025; four SDKs published; two public sites (keysat.xyz, docs.keysat.xyz) live. All repos synced to **both** GitHub + gitea. `keysat-registry-landing` remotes deleted by the operator. - **Shipped `:60` — Zaprite auto-charge silent-lapse fix.** `try_auto_charge_zaprite` suppresses manual-pay only for a settled status (`PAID`/`COMPLETE`/`OVERPAID`, via the new `zaprite_charge_settled` helper + unit test); any other/unknown status falls through to the manual-pay pay link. Allowlist by design. No schema/SDK change. - **Decided — Keysat sends no buyer email.** Buyer email + the per-profile SMTP send path are dropped (`plans/keysat-smtp-emails.md` superseded; dormant `merchant_profiles.smtp_*` flagged in code). The surviving kernel, operator failure alerts, is reframed onto StartOS notifications/health (ROADMAP "Operability & alerts"). - **Docs reconciled:** false "Keysat emails the license" claim removed from docs.keysat.xyz; `HOW_IT_WORKS.md` corrected (subscriptions + merchant profiles shipped, no email); new design-checker-clean Merchant profiles docs section. `unlimited_merchant_profiles` confirmed live on Pro + Patron policies (Creator excluded). - **Next (priority):** 1) automated multi-profile webhook routing test (ROADMAP, Effort S). 2) split `audit:read` from the blanket `:read` scope. 3) operator-alerts-via-StartOS (verify the start-sdk 1.3.2 API first). 4) registry-submission `prepare.sh` + on-box verification. - **Tests/build:** `cargo check` + wrapper `tsc` clean; `zaprite_charge_settled` unit test green; full suite through 0025 last green. Pre-existing docs.css radius drift (10px vs 12px `r-lg`, 3 spots) noted; not blocking.