deckhearth/.convoys/pick-a-name/brief-1-display-and-comment-sweep.md

convoy	brief_number	depends_on	files
pick-a-name	1		AGENTS.md .cursor/rules/ui-and-theming.mdc .cursor/rules/auth-and-permissions.mdc scripts/README.md pages/api/cards/import-lorcana.js pages/api/cards/import-pokemon.js scripts/import-lorcana.js

Brief 1: In-repo display + comment sweep (User-Agent strings, branding notes, rule descriptions)

Goal (1 sentence)

Sweep the seven repo files whose ONLY brand references are display / comment / external-HTTP-User-Agent strings (NOT emails, NOT Redis prefixes, NOT package.json identifiers), renaming each occurrence of TCG Vault, TCG-Vault, and standalone-product-identity tcg-vault to the operator-ratified Deck Hearth / Deck-Hearth / deck-hearth per D1 + D2, while leaving every literal-repo-name reference (cd tcg-vault, directory-tree diagrams, workflow YAML comments) byte-identical because the repo + Vercel project rename is the queued rename-repo-and-vercel-project convoy.

Files in scope (do not edit anything else)

The 7 files listed in files: above (all modified, no new files, no deletions).

Files explicitly out of scope (do not touch even if it seems related):

• README.md — title + admin-email mentions are in Brief 2 (file-disjoint per the slice plan; B2 owns README to keep the title + email changes atomic with the migration). Do NOT touch README in B1.
• TESTING_GUIDE.md — title + test-user email table are in Brief 2 (same reason).
• lib/rate-limit.js, package.json, package-lock.json, scripts/setup-neon-db.js, scripts/reset-db.js, scripts/create-test-users.js, pages/login.js, test/lib/permission-middleware.test.js, scripts/migrations/2026-05-24-rename-admin-email.js — all in Brief 2 (infrastructure + emails).
• components/Layout.js, components/AnimatedFireLogo.js, components/ShareModal.js, pages/index.js, pages/login.js (welcome copy at lines 76 + 158), pages/signup.js, styles/globals.css — already render Deck Hearth correctly. Do NOT touch.
• Repo-name references (literal tcg-vault describing the GitHub repo / Vercel project / directory): README.md lines 30 + 105, AGENTS.md line 1, .github/workflows/ci.yml lines 12 + 123, .github/workflows/visual-diff.yml line 5, .agent-context-manifest.yml lines 84/89/99/104/109/114. These stay byte-identical — the queued rename-repo-and-vercel-project convoy will sweep them when the repo + Vercel project are actually renamed. Per .convoys/pick-a-name.md § "Keep the repo tcg-vault for now". Do NOT rename in this brief.
• AGENTS.md Gotcha #4 (line 53, admin@tcgvault.com reference) and AGENTS.md Gotcha #12 (rate-limit env-var explanation) — the doc-writer pass at convoy close updates these to reflect the post-migration admin email + post-rename Redis prefix. Do NOT preempt that edit here.
• AGENTS.md line 1 (# AGENTS.md — AI collaboration (tcg-vault)) and AGENTS.md line 13 (Project overview admin@tcgvault.com mention) — repo-name reference (line 1) and email reference (line 13). Line 1 stays per the repo-rename scoping rule above; line 13 is updated by the doc-writer pass at convoy close (same as Gotcha #4) because it's email-bound and would otherwise contradict B2's migration outcome. Do NOT preempt those edits here.
• .convoys/** history files — append-only per .cursor/rules/no-go-zones.mdc. The 30+ tcgvault / Deck Hearth references inside .convoys/ describe historical state at write-time and stay byte-identical. Doc-writer pass at this convoy's close ADDS a new "As-shipped" section to .convoys/pick-a-name.md; it does NOT rewrite history in other convoy files.
• scripts/seed-collections-*.js, scripts/add-*.js, scripts/fix-*.js, components/Layout.js.backup — historical / legacy per .cursor/rules/no-go-zones.mdc § Append-only / historical. Do NOT touch.
• pages/login.js quick-login fixture emails (lines 172, 184) — these are in Brief 2 because the email rename must coordinate with the seed scripts + migration. Do NOT touch login.js in B1.
• tests/**, test/** — smoke spec, visual spec, and unit tests are untouched by B1. test/lib/permission-middleware.test.js line 87's negative regression assertion is in B2 (email-bound). The Playwright smoke spec's text matchers ('sign in' regex, /api/health) are brand-agnostic — verified at architect time.

Conventions to follow

Decisions from the convoy file (cite when implementing)

• D1 (operator-ratified at gate-1): The canonical display string is "Deck Hearth" — two words, internal cap, space-separated. Use this for every user-facing-style replacement (titles, branding notes, descriptions).
• D2 (operator-ratified at gate-1): The canonical kebab string is deck-hearth — used in User-Agent HTTP headers per the lowercase-hyphenated convention of HTTP user-agent product tokens (e.g. Mozilla/5.0, curl/8.4.0).

Repo conventions (cite + match)

• .cursor/rules/no-go-zones.mdc. None of the 7 source files are listed under no-go zones. The "Card-import jobs" entry warns "Don't run them ad-hoc against prod data; use staging" — this brief edits only the User-Agent string sent in the HTTP request; the import behavior itself (Scryfall / Pokémon TCG / Lorcana API calls) is byte-identical post-edit.
• .cursor/rules/ui-and-theming.mdc § Branding — line 61 currently states "The repo says 'TCG Vault' everywhere except components/Layout.js, which renders 'Deck Hearth' and 'DH' logo. A naming convoy is open. Until resolved, do not introduce a third name in new copy." That advice expires the moment the operator ratifies D1; the verbatim replacement copy is in the per-file Acceptance criteria below.
• No fail-loud test gate for this kind of edit. There's no CI grep job that fails on tcgvault (we don't want one — convoy history references the literal). Validation is via per-file git diff review + the post-edit cross-file Repo-wide grep clean check in § Cross-file checks below.

Acceptance criteria

AGENTS.md (modified)

Replace line 5 — the branding note — with a one-line post-decision callout. Keep every other line byte-identical.

Current line 5:

> Branding note: the repo, README, and seed data say "TCG Vault" and `admin@tcgvault.com`, but the Layout component renders "Deck Hearth". Pick one before launch — see `.convoys/` for tracking.

Replace with:

> Branding note: **Deck Hearth** is the canonical product brand (ratified 2026-05-24 in the `pick-a-name` convoy). The repo directory name `tcg-vault` stays for now — see queued `rename-repo-and-vercel-project`. The seed admin email migrated from `admin@tcgvault.com` to `admin@deckhearth.com` in the same convoy; see Gotcha #4 + `.convoys/pick-a-name.md` for the rotation flow.

Acceptance:

• Line 5 matches the verbatim replacement above (including the leading > blockquote marker, the two **-emphasis spans, the four backtick-quoted identifiers, and the trailing period).
• Lines 1-4 and lines 6-end stay byte-identical. Do NOT touch line 1 (# AGENTS.md — AI collaboration (tcg-vault) — repo-name reference, scoped to rename-repo-and-vercel-project convoy).
• Do NOT touch line 13 (Project overview Auth bullet's admin@tcgvault.com mention) — the doc-writer pass at convoy close updates that line together with Gotcha #4 to reflect the post-migration admin email; preempting here would contradict B2's migration outcome and create merge conflicts.
• Do NOT touch Gotcha #4 (line 53) or Gotcha #12 (line 61-77) — those are doc-writer pass at convoy close.
• Net diff: 1 line changed, 0 lines added, 0 lines deleted.

.cursor/rules/ui-and-theming.mdc (modified)

Replace line 61 — the "Branding" subsection content — with a post-decision sentence. Keep the heading ## Branding (the line ABOVE it, line 60 in the unedited file) byte-identical.

Current line 61:

The repo says "TCG Vault" everywhere except `components/Layout.js`, which renders "Deck Hearth" and "DH" logo. A naming convoy is open. Until resolved, **do not introduce a third name** in new copy.

Replace with:

The canonical product brand is **Deck Hearth** (two words, internal cap), ratified 2026-05-24 in the `pick-a-name` convoy. The repo directory + GitHub project name remain `tcg-vault` until the queued `rename-repo-and-vercel-project` convoy ships. New UI copy MUST use `Deck Hearth` verbatim — do not introduce a third name, do not abbreviate to "DH" outside the logo glyph (currently used in `components/Layout.js` lines 621, 714 as the sidebar logo monogram).

Acceptance:

• Line 61 matches the verbatim replacement above.
• Every other line in the file stays byte-identical.
• Net diff: 1 line changed, 0 lines added, 0 lines deleted.
• The two referenced line numbers in the new copy (621, 714) are architect-verified against the current components/Layout.js — those are the two <span className="text-white font-bold text-sm">DH</span> lines.

.cursor/rules/auth-and-permissions.mdc (modified)

Replace line 2 — the frontmatter description: value — with the new product name. Keep lines 1 (---), 3 (globs: ...), and 4 (---) byte-identical.

Current line 2:

description: Auth model + permission model for tcg-vault (JWT + collection roles)

Replace with:

description: Auth model + permission model for Deck Hearth (JWT + collection roles)

Acceptance:

• Line 2 matches the verbatim replacement above (no trailing whitespace).
• Frontmatter delimiters and globs: line stay byte-identical.
• Every line below the frontmatter (# Auth + permissions heading down) stays byte-identical. In particular, do NOT touch the body's tcgvault references — there are none in this file outside the frontmatter description.
• Net diff: 1 line changed.

scripts/README.md (modified)

Replace line 1 — the title. Keep every other line byte-identical (line 3 contains the generic phrase TCG card data referring to trading-card-game card data, NOT the product brand "TCG Vault"; preserve unchanged).

Current line 1:

# TCG Vault Bulk Import Scripts

Replace with:

# Deck Hearth Bulk Import Scripts

Acceptance:

• Line 1 matches the verbatim replacement above.
• Line 3 (This directory contains scripts for bulk importing TCG card data into the database.) stays byte-identical — TCG card data is the generic acronym for "trading card game", NOT the product brand.
• Every other line stays byte-identical.
• Net diff: 1 line changed.

pages/api/cards/import-lorcana.js (modified)

Replace the User-Agent product token on line 14. This is the external HTTP identity sent to the Lorcana API and is part of our brand contract with the upstream service (Lorcana operators may rate-limit or contact us via this UA — better that they see the current brand name).

Current line 14:

          'User-Agent': 'TCG-Vault/1.0',

Replace with:

          'User-Agent': 'Deck-Hearth/1.0',

Acceptance:

• Line 14 matches the verbatim replacement above (preserves the surrounding 10-space indent, the trailing comma, the version 1.0).
• No other line in the file changes. Specifically: the auth check (line 2 getUserFromRequest import), the rate-limit check (line 3 checkImportRateLimit import), the delay() helper, fetchWithRetry() retry logic, and the handler body all stay byte-identical. The add-rate-limiting Brief 1 contract for this file (auth → admin-role → import rate-limit gate ordering) is preserved.
• Net diff: 1 line changed.

pages/api/cards/import-pokemon.js (modified)

Same change as import-lorcana.js — replace the User-Agent product token on line 14.

Current line 14:

          'User-Agent': 'TCG-Vault/1.0',

Replace with:

          'User-Agent': 'Deck-Hearth/1.0',

Acceptance:

• Line 14 matches the verbatim replacement above.
• No other line in the file changes (including the Pokémon TCG fetch + INSERT loop, the fetchWithRetry + delay helpers, and the add-rate-limiting-installed gates).
• Net diff: 1 line changed.

scripts/import-lorcana.js (modified — standalone CLI variant)

Replace the User-Agent product token on line 20. This is the CLI-script variant of the Lorcana importer (independent of the API route); per .cursor/rules/no-go-zones.mdc § "Card-import jobs" the script runs against external APIs with rate limits — same brand-identity argument as the API route.

Current line 20:

          'User-Agent': 'TCG-Vault/1.0',

Replace with:

          'User-Agent': 'Deck-Hearth/1.0',

Acceptance:

• Line 20 matches the verbatim replacement above.
• No other line in the file changes.
• Net diff: 1 line changed.

Cross-file checks

• npm run lint exit code unchanged. The baseline is whatever the convoy/pick-a-name branch tip currently reports — none of B1's edits introduce ESLint surface (no new code, no removed imports, no new syntax). If the count changes by even 1, investigate before commit.

• npm run test:run (vitest) passes 21/21. No test file is touched in B1. Re-run after the sweep to confirm.

• npm run build exit 0. Turbopack should compile cleanly — all edits are string literals or markdown.

• Smoke spec still passes 3/3 (npm run test:smoke against a preview, or skip locally — the smoke spec's text matchers are 'sign in' regex + /api/health + HTTP status < 500, brand-agnostic).

• Repo-wide grep check (post-B1, expect B2 still pending). After running B1, the following rg invocations should show ONLY the still-pending B2 surfaces (no B1 surfaces should remain):

  # B1 should have eliminated these:
  rg "TCG-Vault/1.0" .
  

  Expected: zero matches. (Architect verified pre-B1: 3 matches — the three User-Agent strings touched by B1.)

  rg '"TCG Vault"' AGENTS.md .cursor/rules/ scripts/README.md
  

  Expected: zero matches in the listed paths. (Architect verified pre-B1: 1 match in AGENTS.md line 5, 1 match in .cursor/rules/ui-and-theming.mdc line 61, 0 in scripts/README.md — the # TCG Vault Bulk Import Scripts title is unquoted.)

  rg "for tcg-vault" .cursor/rules/
  

  Expected: zero matches. (Architect verified pre-B1: 1 match in auth-and-permissions.mdc line 2.)

• No collateral damage in .convoys/. The 30+ historical references stay byte-identical:

  rg "TCG Vault|tcgvault|tcg-vault" .convoys/ | wc -l
  

  Expected: same count as pre-B1 (architect-verified: ~25 lines across .convoys/).

• No collateral damage in already-correct files. The seven Deck Hearth-correct files (components/Layout.js, components/AnimatedFireLogo.js, components/ShareModal.js, pages/index.js, pages/login.js welcome copy, pages/signup.js, styles/globals.css) stay byte-identical:

  git diff --stat -- components/Layout.js components/AnimatedFireLogo.js components/ShareModal.js pages/index.js pages/signup.js styles/globals.css
  

  Expected: no diff for those six. (pages/login.js is touched by B2 — that's the only listed file with expected B2-side changes.)

• Diff hygiene. git diff main..HEAD --stat (after B1 commit only) should show:

  • AGENTS.md: 1 line + / 1 line -.
  • .cursor/rules/ui-and-theming.mdc: 1 line + / 1 line -.
  • .cursor/rules/auth-and-permissions.mdc: 1 line + / 1 line -.
  • scripts/README.md: 1 line + / 1 line -.
  • pages/api/cards/import-lorcana.js: 1 line + / 1 line -.
  • pages/api/cards/import-pokemon.js: 1 line + / 1 line -.
  • scripts/import-lorcana.js: 1 line + / 1 line -.
  • No whitespace-only changes elsewhere.
  • Total: ~7 lines + / ~7 lines -.

Manual verification (in addition to CI on push)

• Visual sanity. Open AGENTS.md and .cursor/rules/ui-and-theming.mdc in an editor. The branding-note paragraphs should read coherently — no orphaned "see .convoys/ for tracking" reference left after the rewrite.
• Import job smoke (optional, against staging only). If a staging Postgres is available, run one of the gated import jobs (POST /api/cards/import-mtg with an admin token + a small set code like neo) and confirm the response succeeds. The User-Agent change is observed by the upstream API, not by the response — but the request should still 200 if our auth + rate-limit + admin-role chain is intact. Skip if no staging is available. Per .cursor/rules/no-go-zones.mdc § Card-import jobs: do NOT run against prod.
• Read the convoy file's § "Boot-the-brief findings" below before commit to make sure no architect note was missed.

Boot-the-brief findings (preempted by the architect; do not re-investigate)

Finding 1 — None of the 7 B1 files have NPM dependency churn

Architect-verified: every edit in B1 is a string-literal replacement inside an already-committed file. Zero new imports, zero new dependencies, zero version pin changes. package.json and package-lock.json are NOT in B1's files: (they're in B2).

Finding 2 — User-Agent rename is observable to external services (not user-facing)

The three User-Agent strings on line 14 of import-lorcana.js, line 14 of import-pokemon.js, and line 20 of scripts/import-lorcana.js are sent in the fetch() headers to the respective upstream APIs. They identify OUR app to the upstream — Scryfall (MTG; note: import-mtg.js does NOT set a custom UA, falling back to Node's default), Pokémon TCG, and the Lorcana API. Renaming aligns with the post-D1 brand. Upstream API responses are not affected by the UA string change (they use the UA for logging / contact, not for routing).

Architect ran rg "User-Agent" pages/api/cards/ scripts/ at brief time — exactly three matches (the three lines above). No fourth import-mtg.js UA setting was found; Scryfall is fine with Node's default UA.

Finding 3 — AGENTS.md line 5 rewrite must NOT pre-empt Gotcha #4 / #13 updates

The convoy file's .convoys/pick-a-name.md § Known constraints explicitly notes that AGENTS.md line 5 is the "canonical historical record of the inconsistency" and that "the doc-writer pass MUST update it from 'Pick one before launch' to ''". This brief does the line-5 callout rewrite; the doc-writer pass at convoy close adds an "As-shipped" milestone entry to .convoys/pick-a-name.md AND updates Gotcha #4's admin-email caveat to reflect the migration outcome AND adds a NEW Gotcha #13 (or amends #12) for the Redis prefix rename. Do NOT preempt those Gotcha edits in B1. The line-5 callout rewrite is the line that needs to "stop saying the brand is unresolved" — that's what unlocks the rest of the doc-writer's milestone copy.

Finding 4 — .cursor/rules/auth-and-permissions.mdc line 2 is a YAML frontmatter description, not body markdown

Architect-verified by reading lines 1-4 of the file: it's standard Cursor .mdc rule frontmatter. The description: field shows in the rule-picker UI when a user is browsing rules. Changing it from tcg-vault to Deck Hearth updates the human-facing tag in the rule picker. Do NOT add a body-markdown edit chasing other tcgvault strings in the file body — architect ran rg "tcgvault" .cursor/rules/auth-and-permissions.mdc and found ZERO matches outside line 2.

Finding 5 — scripts/README.md line 3's "TCG card data" is the GENERIC acronym, not the product

Architect read line 3 in full: "This directory contains scripts for bulk importing TCG card data into the database." — TCG here is "trading card game" (the industry generic), NOT "TCG Vault" the product. Architect verified this elsewhere in the file: lines 14, 18, 29, 33 use "TCGs", "Magic", "Pokemon", "Lorcana" all in the trading-card-game generic sense. Only line 1 (the title) is the product-brand reference. Replace line 1 only.

Finding 6 — Workflow YAML comments referring to "tcg-vault" describe the literal repo, not the product

.github/workflows/ci.yml line 12 (# NOTE: tcg-vault is JavaScript (not TypeScript). …) and line 123 (# The tcg-vault frontend and API are served from the same Vercel deployment …), and .github/workflows/visual-diff.yml line 5 (# Paths are tcg-vault-specific …) all use tcg-vault as the literal repo / deployment name. Per the convoy seed § "Keep the repo tcg-vault for now" and § "GitHub rename is a separate concern … track as a queued follow-up convoy rename-repo-and-vercel-project", these stay byte-identical. Do NOT add .github/workflows/*.yml to B1's files: — they're out of scope.

Finding 7 — .agent-context-manifest.yml source: "tcg-vault-local" tags stay (internal sync-tracking)

Architect read the manifest: 6 entries reference source: "tcg-vault-local" as an internal source identifier for the sync-agent-context skill's drift detection. The skill compares an installed artifact's content against the "tcg-vault-local" source to detect drift. Renaming the source tag to deck-hearth-local could break the sync skill's behavior (it tracks "what shipped from this source"); the rename belongs to rename-repo-and-vercel-project when the actual repo name changes. Do NOT touch .agent-context-manifest.yml in B1.

Out of scope (do not do these)

• Do NOT edit README.md, TESTING_GUIDE.md, lib/rate-limit.js, package.json, package-lock.json, scripts/setup-neon-db.js, scripts/reset-db.js, scripts/create-test-users.js, pages/login.js, or test/lib/permission-middleware.test.js — all in B2.
• Do NOT touch any file under .convoys/ (append-only history per no-go-zones).
• Do NOT touch components/Layout.js.backup (legacy snapshot per no-go-zones).
• Do NOT touch scripts/seed-collections-*.js, scripts/add-*.js, or scripts/fix-*.js (historical migration jobs per no-go-zones).
• Do NOT touch repo-name references (README.md cd / tree, AGENTS.md line 1, .github/workflows/*.yml, .agent-context-manifest.yml source tags) — those are in rename-repo-and-vercel-project.
• Do NOT touch AGENTS.md Gotcha #4 / Gotcha #12 — doc-writer pass at convoy close.
• Do NOT touch AGENTS.md line 1 (# AGENTS.md — AI collaboration (tcg-vault)) or line 13 (project overview Auth bullet's admin@tcgvault.com mention).
• Do NOT preempt visual-baseline regeneration. tests/visual/__screenshots__/ does not exist; the queued seed-visual-baselines-on-linux convoy seeds it AFTER pick-a-name lands.
• Do NOT introduce a new file (no migration scripts, no helper modules). All B1 edits are in-place.
• Do NOT bump any dependency or run npm install (that's a B2 step for the package.json name change).

Rationale (≤3 sentences)

B1 is the lowest-risk, lowest-blast slice of the convoy: 7 files, ~7 lines net, no infrastructure changes, no test or DB impact — purely the in-repo display / comment / external-HTTP-User-Agent strings that match the operator-ratified D1 ("Deck Hearth") and D2 (deck-hearth) decisions. Splitting it from B2 keeps the email-migration + Redis-prefix-rename + lockfile-regen blast radius isolated, AND lets the conductor dispatch both briefs in parallel via /multitask because their files: sets are disjoint. The only soft scope edge — repo-literal references like cd tcg-vault — is explicitly deferred to the queued rename-repo-and-vercel-project convoy so this brief stays mechanical.