Restructure AGENTS.md into scoped guides
Trim AGENTS.md to whole-repo, every-session facts (154 -> 110 lines) and move subsystem guidance into docs/guides/*.md, each with paths: frontmatter and a one-line index entry in AGENTS.md. Symlink each guide from .claude/rules/ so Claude Code lazy-loads it by matching path; track those symlinks via a .gitignore exception (.claude/settings.local.json stays ignored).
This commit is contained in:
Keysat
@@ -1,122 +1,110 @@
|
||||
# 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.
|
||||
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 and paths reflect that, not Docker).
|
||||
- **Payment providers**: BTCPay Server (required dep); Zaprite (optional, gated by `zaprite_payments` entitlement).
|
||||
- **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`).
|
||||
|
||||
## Build / test / run
|
||||
## Subsystem guides (read before editing the area)
|
||||
|
||||
From `licensing-service-startos/`:
|
||||
- Before editing the daemon source, read `docs/guides/daemon-architecture.md`.
|
||||
- Before editing payment / provider / merchant-profile code or migrations 0020–0022, 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 adding/altering tests or relying on lint/CI, read `docs/guides/testing.md`.
|
||||
|
||||
```
|
||||
make x86 # build keysat_x86_64.s9pk
|
||||
make arm # build keysat_aarch64.s9pk
|
||||
make universal # single multi-arch package
|
||||
make install # install to StartOS; auth via the developer key at ~/.startos/developer.key.pem (private — never commit/share)
|
||||
make clean
|
||||
npm run check # tsc --noEmit on the wrapper
|
||||
npm run prettier # format startos/*.ts
|
||||
```
|
||||
## Build / test / run (quick ref)
|
||||
|
||||
From `licensing-service-startos/licensing-service/`:
|
||||
|
||||
```
|
||||
cargo check # type-check daemon
|
||||
cargo build --release # release build
|
||||
cargo test # all suites
|
||||
cargo test --test api # one suite (suites: api crosscheck migrations subscriptions upgrades worker)
|
||||
cargo test <name> # single test by name pattern
|
||||
cargo fmt --check # TODO: confirm CI gate
|
||||
```
|
||||
|
||||
Operator-local scripts (live in `~/.keysat/`, gitignored, not in this repo):
|
||||
|
||||
```
|
||||
~/.keysat/publish.sh # version-gate → make x86 → FileBrowser upload → registry register → GitHub release mirror
|
||||
~/.keysat/deploy-sites.sh landing docs # push static sites to FileBrowser; accepts: landing | docs | registry-landing
|
||||
```
|
||||
|
||||
Credentials for those scripts: `~/.keysat/filebrowser.env` (`chmod 600`), env vars `KEYSAT_FB_USER`, `KEYSAT_FB_PASS`. Daemon env vars at runtime: `KEYSAT_ADMIN_API_KEY`, `KEYSAT_LICENSE`, `KEYSAT_OPERATOR_NAME`, `KEYSAT_PUBLIC_URL`, `BTCPAY_URL`, `BTCPAY_BROWSER_URL`, `BTCPAY_PUBLIC_URL`.
|
||||
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
|
||||
licensing-service/src/ Rust daemon → guides/daemon-architecture.md
|
||||
licensing-service/migrations/ SQLite migrations (numbered, additive)
|
||||
licensing-service/web/index.html embedded admin SPA (rust-embed)
|
||||
licensing-service/tests/ integration suites
|
||||
licensing-service/tests/crosscheck/ wire-format fixtures the four SDKs cross-verify
|
||||
startos/ wrapper TS (manifest/, versions/, actions/, interfaces.ts, backups.ts, init/)
|
||||
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
|
||||
Dockerfile Makefile s9pk.mk build pipeline
|
||||
keysat-xyz-landing/ keysat.xyz
|
||||
keysat-docs/ docs.keysat.xyz (incl. shared docs.js)
|
||||
keysat-registry-landing/ registry.keysat.xyz stub
|
||||
keysat-xyz-landing/ keysat-docs/ keysat-registry-landing/ public sites → guides/website-copy.md
|
||||
licensing-client-{rust,ts,python,go}/ the four SDK source repos
|
||||
activate-license-template/ Tauri desktop template for license activation
|
||||
keysat-design-system/ design tokens / brand assets
|
||||
plans/ historical plan files (gitignored or archived — TODO confirm)
|
||||
tests/ TODO: confirm vs licensing-service/tests/
|
||||
plans/ design specs (multi-provider-payment-model.md, keysat-smtp-emails.md)
|
||||
tests/crosscheck/ cross-language LIC1 verifier → guides/crypto-wire-format.md
|
||||
```
|
||||
|
||||
## Conventions
|
||||
Note: `licensing-service-startos/` and each SDK are **separate git repos**; the
|
||||
root `Licensing` repo is a workspace backup that tracks docs (AGENTS.md, plans,
|
||||
guides) but not the code. Commit code changes in their own repo.
|
||||
|
||||
## Conventions (whole-repo)
|
||||
|
||||
- Daemon licensed `LicenseRef-Keysat-1.0` (custom, source-available); SDKs MIT.
|
||||
- Commits in imperative mood, no AI co-authorship trailers, body only when the "why" isn't obvious.
|
||||
- Direct push to `main` + run `~/.keysat/publish.sh` is the authorized release flow until launch.
|
||||
- Admin UI pills: navy-filled for selected/on; cream-outlined for off; opacity for muted; **gold reserved for marketing accents only** (most-popular badge, launch-special ribbon).
|
||||
- No em-dashes in user-facing copy on the website or docs. Exceptions: decorative ornaments and verbatim third-party UI labels (e.g. BTCPay's "Network — mDNS"). Comments and docstrings inside source code are fine to keep em-dashes.
|
||||
- Pricing/tier copy on the docs site is a snapshot only. The canonical sources are `keysat.xyz#tiers` (live tier cards rendered from the master Keysat) and `GET licensing.keysat.xyz/v1/products/keysat/policies`.
|
||||
|
||||
## Always
|
||||
|
||||
- **Bump version + add changelog entry before building.** Edit `startos/versions/v0.2.0.ts` — increment the `version: '0.2.0:N'` field and prepend a `ROUTINE_NOTES[0]` entry — before running `make x86` or `publish.sh`. Start9 0.4.x silently no-ops an install of an un-bumped package.
|
||||
- **`cargo check` from `licensing-service/` before bumping the version**, so the build doesn't fail downstream.
|
||||
- **Use the SDK's StartOS dependency discovery for BTCPay**, not hardcoded hostnames. Pattern is in `licensing-service-startos/startos/main.ts:156–175` (`sdk.serviceInterface.getAll(effects, { packageId: 'btcpayserver' })`).
|
||||
- **For tier gates, expect LIVE entitlements** from `licenses.entitlements` (refreshed hourly by `refresh_self_tier_from_db` in `src/license_self.rs`), not the entitlements baked into the signed payload at issue time.
|
||||
- **BTCPay Connect: use the one-click authorize flow.** `POST /v1/admin/btcpay/connect` returns `{ authorize_url }`; the operator opens it, BTCPay callbacks `/v1/btcpay/authorize/callback`, and the daemon auto-detects store + registers webhook. The admin UI's `openBtcpayConnectModal` in `web/index.html` is the reference flow. Don't ask the operator to paste an API key + store id by hand.
|
||||
- **Sign all release commits as Keysat (Grant), not Claude.** Git user is `Keysat` per repo config.
|
||||
- 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
|
||||
|
||||
- **Don't add AI co-authorship to commits or PRs.** No "Co-Authored-By", no "Generated with Claude Code".
|
||||
- **Don't push `--no-verify`** or bypass pre-commit hooks unless explicitly authorized.
|
||||
- **Don't rewrite user-facing copy outside the explicit scope of a request.**
|
||||
- **Don't silently expand entitlements in `tier::current()`** (e.g., "patron implies pro"). Tried in `0.2.0:41`, reverted in `0.2.0:42`. The right fix when an operator is stuck on an old-scheme self-license is: re-issue + run the StartOS "Activate Keysat license" action — the new key overwrites `/data/keysat-license.txt` and `self_tier` refreshes without a daemon restart.
|
||||
- **Don't assume `start-cli registry info set-icon` is sufficient for the registry icon to render in the StartOS marketplace UI.** The icon round-trips through `registry info` correctly at 96×96 and 256×256 PNG, but the marketplace header may still show the storefront fallback. The operator may have to paste the data URL into the local "Configure Registry" modal manually. Confirm visually before claiming "done."
|
||||
- **Don't commit built artifacts** (`*.s9pk`, `keysat-*.s9pk`, `javascript/`) — they're build outputs.
|
||||
- **Don't commit secrets.** Reference env-var names; real values live in `~/.keysat/filebrowser.env` and `/data/keysat-license.txt` outside the repo.
|
||||
- **Don't claim multi-arch when only x86_64 ships.** Manifest currently declares `['x86_64', 'aarch64']` but `publish.sh` only builds + uploads x86_64. See TODO.
|
||||
- **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
|
||||
|
||||
Persistent operator-specific memories live at `~/.claude/projects/-Users-macpro-Projects-licensing-Licensing/memory/`. Worth scanning before a major change:
|
||||
Operator-specific memories at `~/.claude/projects/-Users-macpro-Projects-licensing-Licensing/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`.
|
||||
|
||||
- `keysat_release_workflow.md` — push-to-main + publish.sh is authorized.
|
||||
- `no_unauthorized_copy_changes.md` — never rewrite copy outside scope.
|
||||
- `keysat_admin_ui_pill_convention.md` — navy/cream/gold pill rules.
|
||||
- `startos_lxc.md` — StartOS 0.4 runtime model.
|
||||
- `startos_registry_icon_unrenderable.md` — known issue with custom registry icons.
|
||||
- `keysat_open_threads.md` — parked follow-ups from prior sessions.
|
||||
## Open TODOs
|
||||
|
||||
## TODO (unverified or pending — flag if you touch)
|
||||
- Extend `publish.sh` to build + upload aarch64 (arm builds fine; only x86 ships
|
||||
today), or narrow the manifest's arch claim. `riscv` target unverified.
|
||||
- StartOS Community Registry submission criteria — Start9 hasn't published the
|
||||
checklist; reach out directly when ready.
|
||||
- Registry icon doesn't render in the StartOS marketplace (see `guides/startos-packaging.md`).
|
||||
|
||||
- `cargo fmt --check` / `clippy` — confirm whether either gates CI.
|
||||
- Top-level `tests/` directory — confirm whether it's used or stale vs `licensing-service-startos/licensing-service/tests/`.
|
||||
- Manifest `license: 'LicenseRef-Proprietary'` (in `startos/manifest/index.ts`) vs the LICENSE file's `LicenseRef-Keysat-1.0` header — align before submitting to any Start9-curated registry.
|
||||
- Publish pipeline only builds x86_64; the Makefile targets `arm` and `riscv` exist and work. Either tighten the manifest's `arch` claim or extend `publish.sh` to build + upload all declared arches.
|
||||
- StartOS Community Registry submission criteria — Start9 docs say "objective technical criteria" exist but don't publish the checklist. Reach out to Start9 directly when ready.
|
||||
## Current state (2026-06-12)
|
||||
|
||||
## Current state
|
||||
|
||||
- **Live**: daemon `0.2.0:45` on `registry.keysat.xyz` (named "Keysat"); four SDKs published; `keysat.xyz` + `docs.keysat.xyz` deployed. BTCPay one-click connect and Zaprite recurring auto-charge both work.
|
||||
- **In progress**: source is at `0.2.0:52` (multi-merchant-profile / multi-provider payment model), committed, tree clean, **not yet published** (gap `:46–:52` unpublished). Migrations 0020–0022 are one-way; 0020 ports the singleton provider config into per-profile tables.
|
||||
- **Decided, not built**: `:52` ships the data model but defers four UIs — buy-page rail picker, product-edit merchant-profile picker, per-profile SMTP override form, rail-preference editing. Master Keysat's Pro/Patron policies still need `unlimited_merchant_profiles` added (data action on keysat.xyz admin, no code).
|
||||
- **Known issues**: custom registry icon round-trips through `start-cli registry info` but the StartOS marketplace shows the storefront fallback (likely needs the data URL pasted into the local Configure Registry modal). After `:52` installs, the master Zaprite webhook still points at the legacy URL — works via back-compat, needs re-register for per-provider isolation.
|
||||
- **Next steps**: (1) publish `:52` via `~/.keysat/publish.sh`; (2) add `unlimited_merchant_profiles` to master Pro/Patron policies; (3) re-register master Zaprite webhook at the path-keyed URL; (4) build the buy-page rail picker + product-edit profile picker; (5) resolve the registry-icon render issue.
|
||||
- **Live**: operator's server `immense-voyage.local` runs daemon `0.2.0:52`
|
||||
(installed from `:45`; migrations 0020–0022 applied). Registry
|
||||
`registry.keysat.xyz` still publishes `:45` — `:52` built/installed but **not
|
||||
published**. Four SDKs published; `keysat.xyz` + `docs.keysat.xyz` deployed.
|
||||
- **`:52` = multi-provider/merchant-profile model**: data model + backend
|
||||
resolution shipped and audited sound. **Deferred (parked):** four UIs (buy-page
|
||||
rail picker, product-edit profile picker, per-profile SMTP form, rail-preference
|
||||
editor) and the `unlimited_merchant_profiles` master-policy entitlement. See
|
||||
`docs/guides/payments.md`.
|
||||
- **Open bug fix not yet shipped**: a purchase-path SQL bug (ambiguous column,
|
||||
broke every paid purchase on `:52`) is **fixed in the working tree but
|
||||
uncommitted**, so prod `:52` is still broken until a `:53` rebuild+reinstall. No
|
||||
live buyers yet, so not urgent. Working tree also has the test compile-fixes, a
|
||||
new query-audit test, the manifest license fix, and an unused-import removal —
|
||||
all uncommitted. See `docs/guides/payments.md` and `docs/guides/testing.md`.
|
||||
|
||||
Reference in New Issue
Block a user