docs: make every AGENTS.md cite code, not docs or issues

A spec, ADR, plan file, or Gitea issue records what was true when it was
written and then goes stale silently, so an agent that follows the pointer
reads a decision that may already have been reversed. Code is the only
source true at read time.

Strip every non-code citation from the three AGENTS.md files (ADRs, spec
and plan files, docs/research, docs/agents/*, DEPLOY/REDEPLOY, and issue
numbers), restating inline any fact the linked doc actually carried: the
tea command set and triage label strings move into the root Forge section.
The Domain docs subsection goes entirely, as it pointed only at CONTEXT.md
and docs/adr/, neither of which exists.

Then rewrite the backend and userscript files around derivability, since
prose that restates mechanism rots the same way a doc link does. Structure
and mechanism now name a symbol and stop; rationale, rejected alternatives
and dated measurements stay written out, because code cannot carry them.
Record that split as a rule in the root file.

Verified by extracting all 118 backticked identifiers and checking each
against the Go, JS, SQL, HTML and CSS sources. That caught one claim that
was already lying: the old cover text said CoverFetcher was gone, but
NewCoverFetcher, TLSCoverFetcher and BrowserCoverFetcher are all live in
internal/latest, so the sentence now names only the dead /img/kagane route.

Also drop the "Guidance for OpenCode (and Claude Code)" openers, so the
files read the same under any harness.

AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-Guidance for OpenCode (and Claude Code) working in this repo.
+Repo-wide guidance for coding agents.
 
 ## What this is
 
@@ -13,15 +13,18 @@ One backend, one `bookmarks` table: a `kind` column (`manga`|`novel`) splits the
 
 ## Hard constraints (drive design — don't violate)
 
+Nothing below is derivable from reading the code — it is why the code looks the
+way it does, plus dated measurements against services we don't control.
+
 Userscript targets **Violentmonkey**, so `GM_*` APIs available, but stay GM-free where plain web APIs suffice — keeps portability across engines:
 - **Avoid `GM_*` unless needed.** Prefer page `localStorage` over `GM_setValue`/`GM_getValue`, on-page UI over `GM_registerMenuCommand`, plain `fetch()` over `GM_xmlhttpRequest` for cross-origin.
 - Cross-origin `fetch()` work **only** against CORS-enabled backend. Manga sites `https://`, so backend **must be HTTPS** (else mixed-content block).
 - Every site is its **own origin with its own `localStorage`** — a shared remote store is the only way to unify bookmarks. Cloud sync required, not optional.
 - Userscript run in **isolated world**, so embedded API token safe from site's JS.
-- Cloudflare's block on manga sites is **per-zone configuration plus request fingerprint, not IP reputation — and not reliably reproducible.** Verified 2026-07-26: plain `curl` from both CGNAT dev machine *and* deployed VPS got clean 200s with real HTML on both asurascans.com and demonicscans.org (homepage, series, chapter pages) — no interactive Turnstile challenge from either IP at test time. Contradicts earlier untested assumption CGNAT dev IP blocked; wasn't, at least this date. Treat "does curl work right now" as live, time-varying fact to re-check, not fixed property of machine — a Site can turn its protection on overnight, which is exactly what comix.to did on 2026-08-12. An earlier version of this line blamed "Cloudflare's bot scoring"; that was wrong. The 1-99 bot score is Enterprise Bot Management only and does not exist for a free-plan zone, and no per-IP request rate is documented as an input to challenge issuance — `docs/research/cloudflare-bot-scoring-and-poll-cadence.md`. Backend fetcher still needs graceful-degrade path for when challenged, and adapters should be **verified against live pages** (Playwright MCP, on-device devtools, direct probe) before finalizing, not assumed from single earlier test.
-- **kagane.to, comix.to and novelfull.com are the exception to the above** — all three sit behind a Cloudflare JavaScript challenge no TLS fingerprint clears, so the backend polls them over CDP (`BROWSER_WS_URL`). When that's unset, kagane and comix are skipped entirely (a plain fetch would only retrieve a challenge page) while novelfull pages are still attempted over plain TLS — its challenge is a live time-varying fact and its cover bytes never need the browser. comix turned hostile on 2026-08-12 (#98): its cover host `static.comix.to` is gated too, so its cover bytes go through the browser as well, and its page is read as an in-tab `fetch()` of the series URL rather than a rendered DOM — comix is an SPA, and rendering costs ~65 requests for the same server-rendered HTML one fetch returns. The three other sites poll fine over plain TLS.
+- Cloudflare's block on manga sites is **per-zone configuration plus request fingerprint, not IP reputation — and not reliably reproducible.** Verified 2026-07-26: plain `curl` from both CGNAT dev machine *and* deployed VPS got clean 200s with real HTML on both asurascans.com and demonicscans.org (homepage, series, chapter pages) — no interactive Turnstile challenge from either IP at test time. Contradicts earlier untested assumption CGNAT dev IP blocked; wasn't, at least this date. Treat "does curl work right now" as live, time-varying fact to re-check, not fixed property of machine — a Site can turn its protection on overnight, which is exactly what comix.to did on 2026-08-12. An earlier version of this line blamed "Cloudflare's bot scoring"; that was wrong. The 1-99 bot score is Enterprise Bot Management only and does not exist for a free-plan zone, and no per-IP request rate is documented as an input to challenge issuance. Backend fetcher still needs graceful-degrade path for when challenged, and adapters should be **verified against live pages** (Playwright MCP, on-device devtools, direct probe) before finalizing, not assumed from single earlier test.
+- **kagane.to, comix.to and novelfull.com are the exception to the above** — all three sit behind a Cloudflare JavaScript challenge no TLS fingerprint clears, so the backend polls them over CDP (`BROWSER_WS_URL`). When that's unset, kagane and comix are skipped entirely (a plain fetch would only retrieve a challenge page) while novelfull pages are still attempted over plain TLS — its challenge is a live time-varying fact and its cover bytes never need the browser. comix turned hostile on 2026-08-12: its cover host `static.comix.to` is gated too, so its cover bytes go through the browser as well, and its page is read as an in-tab `fetch()` of the series URL rather than a rendered DOM — comix is an SPA, and rendering costs ~65 requests for the same server-rendered HTML one fetch returns. The three other sites poll fine over plain TLS.
 - **The CDP browser must look like a real browser, and stock headless images don't.** Measured 2026-08-08 against kagane.to, all from the same IP: `chromedp/headless-shell:stable` never cleared the challenge in 90s (`navigator.webdriver` true, empty plugin list, Chromium-branded client hints — suppressing `webdriver` alone changed nothing); `zenika/alpine-chrome` ships Chrome 124, refused outright; real Chrome with the default `--headless=new` UA never cleared, because the UA says `HeadlessChrome`; real Chrome with a stock UA **and** a non-UTC clock zone cleared in ~4s. Hence `chrome/` — a Debian image with `google-chrome-stable`, a version-derived UA, and `TZ`/`BROWSER_TZ`. Chrome reads the zone *name* through ICU from `/etc/localtime`'s symlink target, ignoring the file's contents, so mounting the host's `/etc/localtime` does **not** work; `/etc/timezone` is mounted instead.
-- **The browser is not in the API stack and must not be put back.** It's its own compose unit (`chrome/docker-compose.yml`) on a second machine, reached over the tailnet — it held 471 MiB on a 1974 MiB swapless VPS, and a residential egress avoids the cloud-hosting-IP signature Bot Fight Mode documentedly challenges (ADR-0006; not a better "score" — free-plan zones have no score). Consequences that constrain code: `BROWSER_WS_URL` must be a tailnet **IP** (a MagicDNS name 500s at `/json/version`, same trap as the old Docker service name); the CDP port binds to the tailnet address only, since CDP authenticates nothing and that host has a real LAN; and the browser is on-demand (ADR-0005), so an unreachable or asleep one must degrade exactly as an unset `BROWSER_WS_URL` — plain-TLS libraries unaffected, kagane/comix logged and skipped, stored covers still served. Never add `chromedp.NoModifyURL`: discovery per fetch is what makes a restarted Chrome invisible.
+- **The browser is not in the API stack and must not be put back.** It's its own compose unit (`chrome/docker-compose.yml`) on a second machine, reached over the tailnet — it held 471 MiB on a 1974 MiB swapless VPS, and a residential egress avoids the cloud-hosting-IP signature Bot Fight Mode documentedly challenges (not a better "score" — free-plan zones have no score). Consequences that constrain code: `BROWSER_WS_URL` must be a tailnet **IP** (a MagicDNS name 500s at `/json/version`, same trap as the old Docker service name); the CDP port binds to the tailnet address only, since CDP authenticates nothing and that host has a real LAN; and the browser is on-demand, so an unreachable or asleep one must degrade exactly as an unset `BROWSER_WS_URL` — plain-TLS libraries unaffected, kagane/comix logged and skipped, stored covers still served. Never add `chromedp.NoModifyURL`: discovery per fetch is what makes a restarted Chrome invisible.
 - **UTC is the tell, not a country mismatch.** A UTC clock is the datacenter default, and the challenge refuses it; any real zone clears. Measured 2026-08-08, identical container, one Indonesian egress IP: UTC never cleared in 60s (twice), while `Asia/Jakarta` **and** `America/New_York` both cleared in 4s. An earlier note here claimed the zone had to match the egress IP's country — that was wrong, inferred from the host clock (`Asia/Bangkok`) rather than the measured egress. A second earlier claim, that Cloudflare "scores" a UTC clock, was also wrong: the measurement is real but the mechanism is not documented anywhere — Cloudflare publishes no timezone signal, and free-plan zones carry no score at all. `BROWSER_TZ` therefore needs a plausible zone, not a geolocated one.
 - **A challenged page needs the tab kept open.** The interstitial takes seconds to solve and only then writes clearance into the browser's shared cookie jar. Navigate-read-close never clears anything; `BrowserFetcher.run` holds one tab and re-reads until the payload arrives.
 
@@ -36,7 +39,7 @@ Two Violentmonkey userscripts (isolated world, per-site adapters, localStorage c
                                             on-demand Chrome, separate machine (chrome/)
 ```
 
-Two deployable units on two machines: the API stack (`docker-compose.yml` + `docker-compose.prod.yml`, on the VPS) and the browser (`chrome/docker-compose.yml`, on the home machine). They share nothing but `BROWSER_WS_URL` and update independently. Backend-specific architecture (packages, endpoints, poller, config env vars) lives in `backend/AGENTS.md`. Userscript-specific structure (adapters, retry queue, UI, live URL shapes) lives in `userscript/AGENTS.md`. Deploy order `DEPLOY.md` (§7 for the browser), redeploy `REDEPLOY.md` (§8 for the browser).
+Two deployable units on two machines: the API stack (`docker-compose.yml` + `docker-compose.prod.yml`, on the VPS) and the browser (`chrome/docker-compose.yml`, on the home machine). They share nothing but `BROWSER_WS_URL` and update independently. Backend-specific detail lives in `backend/AGENTS.md`, userscript-specific detail in `userscript/AGENTS.md`.
 
 ## Commands
 
@@ -64,28 +67,29 @@ Smoke test: `curl` endpoints with `Authorization: Bearer <token>`; confirm `OPTI
 
 ## Forge: Gitea, not GitHub
 
-`origin` is self-hosted Gitea instance (`gitea.violetcrown.my.id`), so **`gh` don't work here — use `tea` (Gitea CLI) for anything past plain git.** Common ones:
+`origin` is self-hosted Gitea instance (`gitea.violetcrown.my.id`, repo `sulthan/mangaBookmark`), so **`gh` don't work here — use `tea` (Gitea CLI) for anything past plain git.** `tea` infers the repo from `origin`; auth lives in `tea login`, not a `GH_TOKEN` env var. It prints rendered boxes rather than plain text, so pass `-o json` when parsing; a PR URL lands on the last line.
 
-- Open PR: `tea pr create --head <branch> --base main --title "..." --description "..."`
-- List / view / check out: `tea pr list`, `tea pr <n>`, `tea pr checkout <n>`
-- Issues: `tea issue create`, `tea issue list`
-- Auth lives in `tea login`, not `GH_TOKEN` env var.
-
-`tea` print output as rendered boxes rather than plain text; PR URL lands on last line.
+- PRs: `tea pr create --head <branch> --base main --title "..." --description "..."`, `tea pr list`, `tea pr <n>`, `tea pr checkout <n>`.
+- Issues: `tea issue create --title "..." --description "..."` (`--labels`, `--assignees` optional), `tea issue <n> --comments`, `tea issue list --state open|closed|all -o json`, `tea issue close <n>`.
+- Comments: `tea comment <n> "..."` — `tea issue close` takes no `--comment` flag.
+- Labels: `tea issue edit <n> --add-labels "..."` / `--remove-labels "..."`. Gitea will **not** auto-create a label, so `tea labels create --name "..." --color "#rrggbb"` first.
+- Triage vocabulary is `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`.
+- Gitea shares one index space across issues and PRs, so a bare `#42` may be either — try `tea pr 42`, fall back to `tea issue 42`.
 
 ## Design system
 
-Web UI + userscript panel follow **Cinder**, rules in `docs/design-system.md`
-— source of truth Claude Design project `BookmarkManager Web UI`
-(`969ac210-fe02-4c01-ae1b-9a271dcc779a`). Read it before touching
-`backend/internal/web/static/style.css`, `backend/internal/web/templates/*`, or userscript
-`TEMPLATE`/`CSS`. Core law: **ember means new chapter only** — no other
-state (busy, error, destruction) may use `--ember`; destruction gets
-`--danger`. No cards/corners/shadows, one `--measure: 760px` column, tokens
-only (never hardcode hex outside `:root`), both colour branches touched
-together. Any move that pulls series out of list (archive/finish/remove)
-must be confirm-gated via its own `.confirm-row`; only restore fires
-instantly.
+Web UI + userscript panel follow **Cinder**. Tokens are the `:root` block in
+`backend/internal/web/static/style.css`; that file, `backend/internal/web/templates/*`,
+and the userscript `TEMPLATE`/`CSS` are the only places it is expressed.
+Source of truth for the visual language is the Claude Design project
+`BookmarkManager Web UI` (`969ac210-fe02-4c01-ae1b-9a271dcc779a`).
+
+Core law: **ember means new chapter only** — no other state (busy, error,
+destruction) may use `--ember`; destruction gets `--danger`. No
+cards/corners/shadows, one `--measure: 760px` column, tokens only (never
+hardcode hex outside `:root`), both colour branches touched together. Any move
+that pulls a series out of the list (archive/finish/remove) must be
+confirm-gated via its own `.confirm-row`; only restore fires instantly.
 
 ## Security invariants
 
@@ -127,13 +131,19 @@ Review gate: auth, CORS, session, crypto, and the fetch gate are security-critic
 ## Comments
 
 Comment only if code alone can't carry info. Cost per read — must earn spot.
+Wrong comment worse than none: it misleads readers and measurably degrades
+LLM performance on the file. Missing comment costs little. Bias to fewer.
 
-Write for:
-- Why not what. Tradeoffs, non-obvious decisions.
-- Load-bearing detail looking incidental — say so if "simplify" breaks it.
+Docstring on public/exported surface — exception, near-always worth it.
+Contract only: what it takes, returns, throws, mutates; units; pre/post
+conditions. Not a restatement of the body. Skip on private/obvious.
+
+Inline — write for:
+- Why not what. Tradeoffs, non-obvious decisions, rejected alternatives.
+- heavy detail looking incidental — say so if "simplify" breaks it.
 - Non-local consequence, invisible from function alone.
-- Wire format / encoding / interface contract — save callers re-deriving.
-- Gotcha/workaround, with ref if exists.
+- Wire format / encoding / ordering / invariant — save callers re-deriving.
+- Gotcha/workaround, with ref (issue, RFC, vendor bug) if exists.
 - Domain/business rule not derivable from code.
 
 Skip:
@@ -142,24 +152,49 @@ Skip:
 - Banners, dividers, `// helpers`.
 - Change narration (`// fix bug`, `// as requested`, `// new impl`) — git's job.
 - Commented-out code — delete.
-- TODO without concrete action.
+- TODO without concrete action + owner.
+- Narrating the plan you just reasoned through. Plan in prose or in your head;
+ship the code, not the transcript.
+- Anything restating a name that could be fixed by renaming instead.
 
-Style: one dense comment over function beats one per line inside. Tight, no worked example unless bug subtle. Wrong comment worse than none — update/delete on change. Default fewer — sparse+high-signal beats comprehensive.
+Staleness filter: if the comment describes something likely to change
+independently of this line, it will rot and start lying. Either anchor it to
+something stable, assert it in a test, or leave it out.
 
-Test: "competent reader get this from code in few sec?" Yes → skip. Needs detour through another file/spec/git-blame → write it.
+Style: one dense comment over a function beats one per line inside. Tight; no
+worked example unless the bug is subtle. On edit, update or delete stale
+comments in the code you touch — silence beats a lie.
 
-## Agent skills
+Test: "competent reader get this from code in a few sec?" Yes → skip.
+Needs detour through another file/spec/git-blame/external doc → write it.
 
-`AGENTS.md` is the single source of truth for agent guidance; every `CLAUDE.md` in this repo is a symlink to the `AGENTS.md` beside it. Edit `AGENTS.md`.
+## Writing an AGENTS.md
 
-### Issue tracker
+`AGENTS.md` is the single source of truth for agent guidance; every `CLAUDE.md`
+in this repo is a symlink to the `AGENTS.md` beside it. Edit `AGENTS.md`.
 
-Issues live as Gitea issues on `gitea.violetcrown.my.id` (`sulthan/mangaBookmark`), driven by the `tea` CLI — not `gh`. See `docs/agents/issue-tracker.md`.
+**Cite code, never docs, issues, or plans.** A spec, ADR, plan file, or Gitea
+issue records what was true when it was written and then goes stale silently;
+an agent that follows the pointer reads a decision that may already have been
+reversed. Code is the only source true at read time — cite a package, file,
+symbol, env var, or route. The sole non-code exception is a sibling
+`AGENTS.md`. If a doc holds a fact an agent needs, restate the fact here rather
+than linking to it.
 
-### Triage labels
+**State a fact in prose only if the code cannot answer it.** Split by
+derivability:
 
-Default five-role vocabulary, label strings unchanged (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See `docs/agents/triage-labels.md`.
+- *Structure* — packages, routes, env vars, columns, struct fields. Rots fast,
+  cheap to re-read. **Name the symbol, write nothing else.**
+- *Mechanism* — what a function does, how a flow proceeds. **Name the symbol
+  plus at most one line of orientation.**
+- *Rationale* — why it is this way, what a "simplify" would break, what was
+  tried and rejected. Not in the code and cannot be re-derived. **Write it out.**
+- *Measurement* — an observation against something we don't control. **Write it
+  out with the date**; a dated fact is honest, an undated one pretends to be
+  permanent.
 
-### Domain docs
-
-Single-context: one root `CONTEXT.md` plus `docs/adr/`, both created lazily. See `docs/agents/domain.md`.
+Restating mechanism in prose is how these files rot: the code changes, the
+paragraph doesn't, and the next agent trusts the paragraph. A pointer degrades
+more honestly — and every symbol you name must actually exist, since a dead
+pointer is a bug, not a stale sentence.