docs: add AGENTS.md describing test gate and registry publish flows

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.