From c5648ce154dbc0e2f5fab1078015a8aa289e9c59 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Troed=20S=C3=A5ngberg?= <github@troed.se>
Date: Fri, 21 Aug 2026 17:25:07 +0200
Subject: [PATCH] docs: add AGENTS.md describing test gate and registry publish
 flows

---
 AGENTS.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..9acb9c6
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,50 @@
+# oc-ls-stats
+
+OpenCode TUI plugin that displays live prefill (PP) and generation (TG) rates from a llama.cpp llama-server. Polls `/slots`, classifies slot activity, renders into the session status bar.
+
+## Test / release gate
+
+- All tests live in `test-backoff.ts` (node:test, run via tsx): `npx tsx test-backoff.ts`
+- `prepack` runs this suite automatically on every `npm pack` / `npm publish`. A failing suite blocks publishing.
+- No separate lint/typecheck scripts exist; the test suite is the gate.
+
+## Conventions
+
+- Commits: lowercase conventional style — `fix: …`, `feat: …`, `docs: …`, and release bumps as `chore: vX.Y.Z — <summary>`.
+- Tags: lightweight, named `vX.Y.Z`.
+- Version bump lands in the same release commit chain as the changes it ships.
+
+## Registries
+
+Two registries are used:
+
+| Target | Scope mapping in `~/.npmrc` |
+|---|---|
+| Local Gitea | `@troed:registry=https://git.sync.wtf/api/packages/troed/npm/` |
+| Public npmjs | `@troed:registry=https://registry.npmjs.org/` |
+
+Gotchas learned the hard way:
+
+- The Gitea mapping MUST include the full API path (`/api/packages/troed/npm/`). Mapping the bare host breaks both `npm publish` auth (ENEEDAUTH) and plugin installation/loading.
+- A `--registry` CLI flag does NOT override `@scope:registry` config. Scoped operations always use the scope registry — to query a different registry for a scoped package, use its HTTP API directly (e.g. `curl https://registry.npmjs.org/@troed%2foc-ls-stats`).
+- Auth tokens are per path in `~/.npmrc`: `//git.sync.wtf/api/packages/troed/npm/:_authToken=…` and `//registry.npmjs.org/:_authToken=…`.
+
+### Publish to local Gitea registry
+
+```sh
+# ensure @troed:registry points at https://git.sync.wtf/api/packages/troed/npm/
+npm publish
+```
+
+### Publish to public npmjs
+
+1. Back up the config: `cp ~/.npmrc ~/.npmrc.bak-$(date +%Y%m%d-%H%M%S)`
+2. Point the scope at npmjs: set `@troed:registry=https://registry.npmjs.org/` in `~/.npmrc`
+3. Authenticate (browser flow): `npm login --scope=@troed` — open the printed URL, then `npm whoami` should print `troed`
+4. Publish: `npm publish`
+   - npmjs additionally requires a fresh **publish-time** web authentication (separate from login). Headless, npm masks that URL with `***`; run under a pseudo-TTY to get the real link and let it poll until you finish in the browser:
+     ```sh
+     script -qec "npm publish --browser=/bin/echo" /dev/null
+     ```
+5. Verify: `curl -s https://registry.npmjs.org/@troed%2foc-ls-stats | jq '.dist-tags'`
+6. Restore the backup (`cp ~/.npmrc.bak-<timestamp> ~/.npmrc`) before the next local-registry publish.