Post-merge doc cleanup for PR #21. Resolves the AGENTS.md line-5 'Pick one before launch' branding question. Updates AGENTS.md top branding note + Gotcha #4 + Gotcha #12, adds full as-shipped to .convoys/pick-a-name.md, adds 4 queued-convoy entries to ship-readiness.md, adds pick-a-name attribution to .cursor/rules/api-routes.mdc. Pure docs (+357/-15 across 4 files).
Reflects the merged add-rate-limiting convoy (PR #20, squash commit
708ef45) in repo documentation. **This is the milestone cleanup** —
add-rate-limiting closed P0 #6 (No rate limiting anywhere), the LAST
open P0 ship-blocker. `.convoys/ship-readiness.md`'s § Status summary
flips from "7 of 8 RESOLVED; 1 remains" to **"8 of 8 RESOLVED.
Launch-readiness P0 checklist is empty."** One brief in the convoy:
Brief 1 shipped as planned with no scope expansions and no implementer
deviations from the verbatim spec; all six architect decisions ratified
verbatim at gate 1 (D1 operator-ratified Option A; D2-D6
architect-self-ratified).
.convoys/add-rate-limiting.md:
- frontmatter status: in-progress -> shipped (added shipped: 2026-05-24)
- new ## As-shipped section. Opens with the milestone language
pointing back at ship-readiness.md's flipped § Status summary.
Decisions section captures all 6 ratifications (D1 operator-
ratified Option A — Critical: WHY the atomic admin UI fix in
pages/admin/card-import.js was Decision 1's hidden coupling
requirement, since API gating alone would have broken every
"Import Cards" click; D2 hybrid named-limiter shape with
Map<className, Ratelimit> cache; D3 per-class table including
the two D3 tuning-evidence raises — search 30 -> 60/min because
ShareModal.handleSearch has no debounce so a 17-char email = 16
requests in <5s, and generate kept at 5/hour because DiceBear is
free not paid AI; D4 two-extractor shape with defensive THROW
on null/empty userId; D5 uniform 429 message; D6 no new vitest
or playwright specs deferred to fill-vitest-handler-coverage).
As-shipped surface broken into 4 layers (1 lib refactor + 6 route
gates + 1 atomic admin UI fix + 1 rule extension) mirroring the
cors-tighten cleanup's pattern-split shape. Empirical CI metrics
from post-merge run 26382185019 (Playwright smoke 59s 3/3 in
3.8s, forbidden-cors-headers pass, vitest 21/21, lint 128 baseline,
Screenshot diff continue-on-error swallow per Decision 4).
Cross-validation finding: smoke test 2 still passes against the
post-rate-limit preview — that's three convoys in a row (PR #15
Layout default-user, PR #19 CORS-tighten, PR #20 rate-limiting)
where the same 3-test smoke spec defended the auth surface
through sweeping changes. Operator-action-required: none. What
did NOT change audit trail.
.convoys/ship-readiness.md:
- § Status summary at the top flipped from 7/8 to 8/8 RESOLVED.
Header text updated to "Launch-readiness P0 checklist is empty."
P0 #6 row in the table flips from PARTIAL to RESOLVED with the
two-convoy lineage (fix-auth-bypass Brief 4 + add-rate-limiting).
Trailing paragraph rewritten as a milestone note: security gate
closed; remaining launch work is P1 quality bar + P2/P3 polish.
- P0 #6 entry flipped from PARTIAL to RESOLVED with the full
add-rate-limiting as-shipped block (8 sub-bullets covering the
lib refactor shape, the per-class table, the defensive THROW,
the three import routes' auth-gating, the atomic admin UI fix
and WHY, the rule extension, the 6 decisions, and the diff
breakdown). Brief 4's 2026-05-23 partial is preserved as the
prior as-shipped layer to maintain the audit trail.
- Launch sequence step 4 marked RESOLVED 2026-05-24 with the
squash commit + smoke metrics inline.
- Queued convoys: removed the add-rate-limiting entry (it shipped).
Added a new delete-dead-lorcana-import entry (P3 polish; the
Lorcana import route was gated defensively in PR #20 despite
zero current frontend callers — pages/admin/card-import.js's
<select> only offers mtg + pokemon — so if Lorcana stays
permanently out of the admin UI, this is the cleanup PR).
Added three "flagged but kept out of scope" follow-ups per the
convoy's § What did NOT change: harden-multipart-parser (P2;
5MB body still consumed before the 429 path on avatar.js),
god-function-split / refactor-cards-search-sql (P2; 240-line
7-branch SQL in cards/search.js), and withAdmin(handler) wrapper
extraction (P3 DX; the three import routes are call sites #3-5
in the codebase but uniform inline shape was preserved for
convoy atomicity). Updated tighten-visual-diff-path-filter to
note PR #20 also tripped the same false-positive.
AGENTS.md:
- Gotcha #12 extended end-to-end. Was the single-class auth-only
lib + the env-var contract; is now the 5-class reality with a
full per-class table (helper / limit-window / key / routes),
the defensive THROW pattern in extractUserIdentifier, the
gate-ordering rule for per-user limiters, and the
auth → admin-role → rate-limit ordering for the three import
routes. Prominent milestone line opens the new content:
"add-rate-limiting convoy (squash 708ef45, PR #20, 2026-05-24)
closed P0 #6 — all 8 P0s now RESOLVED." Original env-var
contract paragraph (KV_REST_API_URL / KV_REST_API_TOKEN,
fail-closed-in-prod / warn-and-noop-in-dev) is preserved
verbatim above the new content.
- § 6 Testing: intentionally untouched (no test surface changed;
vitest 21/21 and smoke 3/3 still apply).
- § 7 Deployment: intentionally untouched (no deployment-shape
changed; same KV_REST_API_* env vars from Brief 4).
.cursor/rules/api-routes.mdc:
- The implementer extended § Rate limiting in PR #20 with the
per-class table + verbatim call shape + gate-ordering rules +
identifier-extraction + uniform 429 + fail-closed env-var
contract + fail-open Upstash-outage behavior. Doc-writer pass
verified completeness; added a one-sentence convoy-attribution
line at the top of § Rate limiting citing the two-convoy
lineage (fix-auth-bypass Brief 4 for the auth class +
add-rate-limiting for the other four classes and 7 newly-gated
routes), mirroring the post-cors-tighten § CORS attribution
shape. No other touch-ups needed.
No changes to: package.json, package-lock.json, lib/rate-limit.js,
pages/**, components/**, scripts/**, test/**, tests/**,
.github/workflows/**, README.md, TESTING_GUIDE.md, playwright.config.js,
eslint.config.mjs.
Co-authored-by: Cursor <cursoragent@cursor.com>
Closes P0 #6 from PARTIAL to RESOLVED. 8/8 P0s now closed. Extends lib/rate-limit.js from single-class to 5 named limiters (auth/search/upload/generate/import). Atomically gates the 3 import routes (auth + admin-role check + rate limit) and fixes pages/admin/card-import.js's missing Bearer header in the same commit (architect's critical discovery: API gating alone would have broken the admin UI). Per Decision 1 Option A. 10 files +185/-23. Local: lint 128 baseline, vitest 21/21. CI: Playwright smoke 3/3 in 3.8s, forbidden-cors-headers pass, all gates green. PR #20 architect-commit 60b842e, implementer-commit 51a3a97. Brief 4's login.js + register.js byte-identical.
Reflects the merged cors-tighten convoy (PR #19, squash commit da50d78)
in repo documentation. Closes P0 #5 (Wildcard CORS on API surface) from
PARTIAL -> RESOLVED, leaving only P0 #6 (full add-rate-limiting) open
of the original P0 ship-blocker set. One brief in the convoy: Brief 1
shipped as planned with no scope expansions and no implementer deviations
from the verbatim spec.
.convoys/cors-tighten.md:
- frontmatter status: in-progress -> shipped (added shipped: 2026-05-24)
- new ## As-shipped section: all 5 architect-self-ratifiable decisions
ratified verbatim (D1 Option B / D2 delete OPTIONS / D3 moot / D4
no new tests / D5 add CI lock); Pattern split (16 Pattern A + 8
Pattern B) per architect's 10-file audit + implementer's per-file
diff review; diff size (25 files, +29/-261); empirical CI metrics
from post-merge run 26378806555 (forbidden-cors-headers 4s PASS,
Playwright smoke 56s 3/3 in 3.3s, Screenshot diff continue-on-error
0 with the documented Decision-4 missing-baseline failure beneath);
cross-validation that Playwright smoke continues to pass post-CORS
removal (the auth + public surfaces don't depend on the wildcard
header); implementer subagent-retry footnote (HEAD already at
a843736 when retry woke up - transient retry, work is canonical);
operator-action-required-going-forward: none; What did NOT change
audit trail.
.convoys/ship-readiness.md:
- new ## Status summary at the top (right after the code-graph line):
P0 set is now 7/8 RESOLVED; only #6 (rate-limiting) remains. Table
lists each P0 with its resolving convoy + squash commit for a quick
scan of remaining work.
- P0 #5 marked RESOLVED 2026-05-24. Added the cors-tighten as-shipped
block (24 files swept, new CI job, 16/8 Pattern split, 5 decisions
ratified, diff stat, post-merge CI metrics, transient retry
footnote, operator-action: none). Brief 4's 2026-05-23 partial
is preserved as the prior as-shipped layer above the cors-tighten
layer to maintain the audit trail.
- Queued convoys: removed the cors-tighten entry (no longer queued).
Added a new tighten-visual-diff-path-filter entry (P3 polish) -
Screenshot diff workflow triggered on API-only PR #19 because its
paths: filter is pages/** which matches pages/api/** too. ~55s of
CI waste per API-only PR; one-line YAML tweak; verify GitHub
Actions' negated-glob semantics before merging.
.cursor/rules/api-routes.mdc:
- new ## CORS section near the existing ## Dev/test endpoints
(removed) section. Documents the no-CORS-by-default convention,
the brief-4 + cors-tighten lineage, the new forbidden-cors-headers
CI gate, and three forward-conventions (no setHeader for CORS,
no OPTIONS preflight handlers, design a proper middleware layer
if a future cross-origin caller is needed - not wildcards in
individual handlers).
AGENTS.md intentionally untouched. Gotcha #5 (the public
setup-database.js endpoint) is already RESOLVED by fix-auth-bypass
Brief 3 and unrelated to this convoy. The new convention belongs in
.cursor/rules/api-routes.mdc (where API conventions live) rather than
AGENTS.md; the convoy file + the new CI gate are sufficient
documentation for the audit trail. Per convoy spec, no new gotcha
entry needed.
No changes to: package.json, package-lock.json, pages/api/**, lib/**,
components/**, scripts/**, test/**, tests/**, .github/workflows/**,
README.md, TESTING_GUIDE.md, playwright.config.js.
Co-authored-by: Cursor <cursoragent@cursor.com>
Reflects the merged drop-public-setup convoy (PR #13) in repo
documentation. Small focused pass; no behavior changes.
AGENTS.md:
- § 1 auth bullet: replace "seed admin row still ships in
setup-neon-db.js" claim with the new env-var-gated reality and
the R1 operator-rotation caveat.
- § 4 Gotcha #4: mark RESOLVED with commit refs (ff80753 + b63b509),
document the as-shipped behavior, the Brief 2 CJS→ESM Node 22.x
fix, and the R1 operator caveat. Entry kept (not renumbered) per
the same convention used for resolved gotchas #2, #3, #5.
- § 5 Running locally: add ADMIN_INITIAL_PASSWORD to the env-var
template list with a note that setup-db exits 1 if it's unset.
.convoys/ship-readiness.md:
- P0 #3: mark RESOLVED 2026-05-23 with commit refs, document the
full as-shipped behavior including Brief 2's CJS→ESM bonus,
the R1 operator caveat (Decision A — going-forward only),
and the deferred sibling weak-cred references queued for
purge-weak-creds-from-helpers.
.cursor/rules/no-go-zones.mdc:
- Editing rules of thumb: clarify the schema-vs-operational
distinction for scripts/setup-neon-db.js. drop-public-setup
set the precedent that operational changes (env-var gating,
pre-flight validation, module-system fixes) are allowed in
place, while DDL changes still need a separate migration
script. Documented so future agents don't have the same
confusion the drop-public-setup architect did (see Decision B
in .convoys/drop-public-setup.md).
No changes to: package.json, lib/**, pages/**, components/**,
scripts/**, .github/**, README.md (already updated in PR #13).
Co-authored-by: Cursor <cursoragent@cursor.com>
varutasu