docs(agents): record the three app metrics decisions that look wrong

[ZacxDev]

Adds items 5–7 to AGENTS.md → "Intentional decisions that look wrong (read before 'fixing')", and updates the section's framing sentence (items 1–3 mirrors, 4 a deliberate non-mirror, 5–7 the analytics read path).

⚠️ Merge order: this depends on #190

internal/cmd/app_metrics.go and internal/appapi/analytics.go exist only on feat/app-metrics — they are not on main. Merge this after #190, or AGENTS.md documents a command the tree does not have. Flagging rather than stacking, since stacking has its own hazards.

5. It calls tRPC, not REST — because there is no REST route to call

Owner analytics exist only as blocks.getMyAppAnalytics (civitai/civitai → src/server/routers/blocks.router.ts); there is no /api/v1 equivalent. So the command resolves <slug> → appBlockId through the existing REST GET /api/v1/blocks/submissions, then issues the non-batched tRPC GET (?input={"json":{…}}, unwrapping result.data.json) reusing the authedDo + envelope-unwrap pattern GetForgejoCloneInfo already established. Written down so nobody "fixes" the two-hop shape into a REST call that does not exist.

6. notOwned is a cross-repo contract

The proc sits behind the appBlocksAuthor feature flag and answers a caller who isn't entitled (or doesn't own the app) with HTTP 200 and every counter zeroed, not an error — so a renderer that ignores the field prints a plausible empty dashboard for what is really a permission failure. runAppMetrics refuses to render when it's true. Whoever changes that payload server-side has to keep the field. --json deliberately passes the payload through and still exits 0, so scripts must branch on notOwned themselves.

7. The exit-code contract needs errors.Is, not message assertions

The classification sentinels carry no visible text — Tag/TagStatus attach them while Error() stays byte-for-byte identical (pkg/civitai/errkind.go) — so a message assertion says nothing about the exit code. Measured on #190: stripping the classification while leaving every message identical left the entire suite green, and the README's 403 → exit 3 / not-found → exit 4 promise was unpinned. Generalised in the text to any command claiming an exit code.

One correction to the brief I was given, made from the code rather than paraphrased: there is no civitai.ErrUsage. The HTTP kinds (ErrUnauthorized, ErrNotFound) live in pkg/civitai/errkind.go; the usage sentinel is ErrUsage in internal/cmd/usage_error.go. The item states the split explicitly so the guidance is actionable rather than a name that won't compile.

Verification

make ci green in a clean worktree off origin/main: go mod tidy and go vet silent, 16/16 packages ok, zero FAIL, build succeeded. gofmt -s -l . prints nothing. Docs-only change, so no behaviour is claimed to be verified beyond the gate.

🤖 Generated with Claude Code

https://claude.ai/code/session_01858ymA3tEJQi83435u7npi