keysat-root/AGENTS.md

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 <suite> | cargo test <name>. 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 — prepare.sh shipped (2026-06-18). Submission is email-based (no PR, no form): mail submissions@start9labs.com a link to the public wrapper repo; Start9 builds-from-source on a clean box → Community Beta → production-on-reply. Resolve two unknowns with Start9 before submitting: (1) source-available LicenseRef-Keysat-1.0 acceptability, (2) whether the 0.4.x build still invokes prepare.sh. On-box manual verification still pending. Detail in ROADMAP.
• 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.

• This session — full eval + three P1 fixes (all committed & pushed). Ran the five-agent /full-eval (evaluator, security-auditor, exerciser, doc-auditor, start9-spec-checker); report in EVALUATION.md (no P0s; strong crypto/auth/webhook posture). Fixed all three P1s: (1) crosscheck harness run_ts.mjs hardcoded /sessions/... path → resolves relative to repo (keysat-root); (2) Rust SDK + keysat-docs imported licensing_client not keysat_licensing_client — fixed, plus two latent bugs it masked (example's undeclared anyhow → stdlib; doctest include_str! of a missing file → inline PEM); (3) added licensing-service-startos/prepare.sh clean-Debian build bootstrap. Reviewer-approved; verified green.

• Registry submission mechanism researched. Email-based (no PR/form) — see Open TODOs + ROADMAP. Two blocking unknowns to clear with Start9 first: license acceptability + whether 0.4.x still uses prepare.sh.

• Prior context still current: :60 Zaprite silent-lapse fix shipped; Keysat sends no buyer email (SMTP path dormant); docs reconciled; unlimited_merchant_profiles live on Pro+Patron (not Creator).

• Next (priority): 1) email Start9 re: license + 0.4.x build flow (gates the whole submission). 2) eval P2 hardening — XFF rate-limit bypass, dep-advisory bumps, admin/public port split (ROADMAP "Security & hardening"). 3) automated multi-profile webhook routing test (Effort S). 4) split audit:read scope.

• Tests/build: daemon cargo test ~117–131 green across 8 suites; wrapper tsc clean; Rust SDK cargo build --examples + doctest now green; crosscheck harness passes end-to-end. No CI enforces any of it.