docs: OPS checklist for npm token + Outline scopes

Record outstanding one-time UI steps after v0.4.0, add publish-gitea-npm.sh,
and align outline-sync body with the live Playkit page format.

docs/NPM_REGISTRY.md

@@ -27,13 +27,16 @@ npm i git+https://git.levkin.ca/ilia/playkit.git#v0.4.0
 
 On `vX.Y.Z` tag, `.gitea/workflows/ci.yml` `release` job:
 
-1. Creates the Gitea Release + attaches `npm pack` tarball (existing)
+1. Creates the Gitea Release + attaches `npm pack` tarball
 2. Runs `npm publish` to `https://git.levkin.ca/api/packages/ilia/npm/`
-   using `RELEASE_TOKEN` (needs **`write:package`** in addition to release scopes)
+   using `NPM_PUBLISH_TOKEN` if set, else `RELEASE_TOKEN`
+   (needs **`write:package`**)
 
-One-time: edit the `RELEASE_TOKEN` personal access token / app token on Gitea
-to include package write, or add a dedicated `NPM_PUBLISH_TOKEN` secret and
-wire it in CI (preferred if you want least privilege).
+Manual one-shot:
+
+```bash
+NPM_PUBLISH_TOKEN=… ./scripts/publish-gitea-npm.sh
+```
 
 ## Verify
 
@@ -41,10 +44,7 @@ wire it in CI (preferred if you want least privilege).
 npm view @levkin/playkit versions --registry https://git.levkin.ca/api/packages/ilia/npm/
 ```
 
-## Outstanding ops
+## Token setup
 
-First `v0.4.0` Gitea Release succeeded; `npm publish` returned **E401** because `RELEASE_TOKEN` lacks `write:package`. Create/refresh a token with package write (or add `NPM_PUBLISH_TOKEN`) and either re-run the release job or publish once by hand:
-
-```bash
-npm publish --registry https://git.levkin.ca/api/packages/ilia/npm/
-```
+See **`docs/OPS.md`** (Outstanding → Gitea npm publish token). First `v0.4.0`
+publish hit E401 until a package-scoped token is stored as `NPM_PUBLISH_TOKEN`.

docs/OPS.md

@@ -0,0 +1,61 @@
+# Ops checklist (playkit)
+
+Living ops/status after releases. Update when an item closes.
+
+## Done
+
+| Item | Status |
+|------|--------|
+| Pushgateway + `live-playkit` Grafana board | Applied (`10.0.10.24:9091`) |
+| Tag release workflow + `RELEASE_TOKEN` | Working (`v0.3.1`, `v0.4.0` Gitea releases) |
+| Selftest CI | Green (Playwright image pinned to package version) |
+| Outline **QA & Dev → Playkit** content @ v0.4.0 | Updated 2026-07-15 (browser sync); keep in sync via script once API scopes fixed |
+| v0.4 CLI / retry presets / registry wiring | Shipped on `main` |
+
+## Outstanding (needs human UI once)
+
+### 1. Gitea npm publish token (`write:package`)
+
+`v0.4.0` **Gitea Release** succeeded; `npm publish` failed with **E401** because
+Actions `RELEASE_TOKEN` lacks package scopes.
+
+1. Gitea → **Settings → Applications → Generate New Token**
+2. Scopes: **`write:package`** (implies read) + keep `write:repository` if this token also cuts releases
+3. Prefer a dedicated token named `playkit-npm-publish`
+4. Store as repo Action secret **`NPM_PUBLISH_TOKEN`** on `ilia/playkit`
+   (optional: also `vault_playkit_npm_token` in ansible vault — see ansible `docs/hardening/SECRETS.md`)
+5. Publish once:
+
+```bash
+cd /path/to/playkit   # on main @ v0.4.0
+npm ci && npm run build
+npm publish --registry https://git.levkin.ca/api/packages/ilia/npm/
+# or: ./scripts/publish-gitea-npm.sh
+```
+
+6. Verify: `npm view @levkin/playkit version --registry https://git.levkin.ca/api/packages/ilia/npm/`
+
+Until then consumers use the git pin: `#v0.4.0`.
+
+### 2. Outline API key scopes
+
+Vault `vault_outline_api_key` can **list/create/info/export** but **not**
+`documents.update` / `delete` / `archive` (HTTP 403).
+
+1. Outline → **Settings → API** (API & Access)
+2. Edit/recreate key with scopes at least:
+
+```
+collections.list documents.list documents.info documents.create documents.update documents.delete documents.archive documents.search
+```
+
+(Full recommended list: ansible `docs/guides/authentik-apps.md` → Outline API key)
+
+3. Update vault + `make vault-export-env`
+4. `python3 scripts/outline-sync-playkit.py`
+5. Delete leftover **QA & Dev → Playkit sync probe** if still present
+
+### 3. Adoption soak
+
+Keep **no new consumer repos** until punimtag e2e + kit CI + metrics stay green
+for a few days. Then prefer `screening` as the next adopter.

docs/OUTLINE.md

@@ -2,14 +2,17 @@
 
 Canonical prose stays in git (`README.md`, `docs/*`, `ROADMAP.md`).
 Browsable front door: **Outline** → collection **QA & Dev** → doc **Playkit**
-(`https://notes.levkin.ca`).
+(`https://notes.levkin.ca/doc/playkit-3ekU0eghbV`).
+
+Ops status for this page (scopes, last sync): **`docs/OPS.md`**.
 
 ## Sync script (preferred)
 
 From this repo, with Outline credentials loaded:
 
 ```bash
-# from ansible: make vault-export-env && set -a && source .env && set +a
+# from ansible: make vault-export-env
+# then export OUTLINE_URL / OUTLINE_API_KEY (safe parse — .env may contain shell-special chars)
 python3 scripts/outline-sync-playkit.py
 python3 scripts/outline-sync-playkit.py --dry-run
 ```
@@ -19,8 +22,13 @@ version, install pin, what’s-in-the-box digest, and links to repo docs.
 
 **Required API scopes** (Outline → Settings → API & Access): at least
 `collections.list`, `documents.list`, `documents.info`, `documents.create`,
-`documents.update`. Without `documents.update` the script can create a first
-doc but cannot refresh an existing Playkit page (HTTP 403).
+`documents.update`, and preferably `documents.delete` / `documents.archive`.
+Without `documents.update` the script can create a first doc but cannot refresh
+an existing Playkit page (HTTP 403).
+
+As of 2026-07-15 the living page was synced to **v0.4.0** via signed-in UI
+because the vault API key still lacked `documents.update`. Fix the key scopes,
+then prefer this script for every future release.
 
 ## When to update Outline
 
@@ -33,19 +41,3 @@ changes consumer behavior:
 3. Spot-check in Outline (search “Playkit” under QA & Dev)
 4. Optional: `make outline-setup` from ansible only if collections are missing —
    prefer the sync script for the living Playkit page
-
-Paste template (if editing by hand — adjust version):
-
-```markdown
-# @levkin/playkit
-
-Shared Playwright + API e2e kit. **Source of truth is the git repo.**
-
-- Repo: https://git.levkin.ca/ilia/playkit
-- Current: vX.Y.Z
-- Consumers: punimtag (e2e/) — *pause further adoption until soak completes*
-
-## Quick links
-- README · CONSUMER.md · NETWORK.md · IDEAS.md · SELFTEST.md · ROADMAP · CHANGELOG
-- Metrics: dash.levkin.ca → Live — Playkit e2e
-```