deckhearth/.convoys/rename-collections-vocabulary.md

name	classification	success_metric	skip	status	created
rename-collections-vocabulary	feature	UI copy reads "My Collection" (ownership) and "Lists" / "Binders" (curated lists); no rendered string "Owned Cards" / "Mark Owned" / "All My Cards" remains in pages/ or components/; schema unchanged; AGENTS.md extended with vocabulary table.	arch	open	2026-05-27

Convoy: rename-collections-vocabulary

Align user-facing copy with the product taxonomy: owned cards vs curated lists.

Why

The scanner audit and IA review found inconsistent vocabulary: "Owned Cards", "Mark Owned", and "All My Cards" imply a different mental model than the schema (global cards catalog vs per-user ownership via user_cards vs curated collections). Users confuse "my collection" (everything I own) with "lists/binders" (curated subsets). This convoy is copy + docs only — no schema migration.

Scope

In scope

• Brief 1 — UI copy sweep (~20 files in pages/ + components/):
  • Replace stale strings per vocabulary table (IA architect supplies full inventory).
  • Target removals: "Owned Cards", "Mark Owned", "All My Cards".
  • Canonical replacements: "My Collection" (ownership), "Lists" / "Binders" (curated lists).
• Brief 2 — docs + rules
  • AGENTS.md § Branding — vocabulary table.
  • .cursor/rules/ui-and-theming.mdc — copy conventions.
  • docs/SCHEMA_MAP.md — clarify naming vs UI labels (no DDL change).
• .github/workflows/ci.yml — new forbidden-stale-strings grep gate (~30s): fail if "Mark Owned", "Owned Cards", or "All My Cards" appear in pages/ or components/.

Out of scope

• Schema renames — table/column names stay; UI copy only.
• URL slug changes — /collections path unchanged in v1.
• Architecture decisions — skip: arch; IA + UX run explicitly.

Roles invoked

1. role-ia-architect — vocabulary table + file inventory (primary owner).
2. role-ux-reviewer — scan flow + nav label consistency.
3. role-implementer — 2 briefs (serial: Brief 2 after Brief 1).
4. role-reviewer + role-design-system-auditor + role-a11y-auditor — copy changes affect screen reader strings.

Note: role-architect skipped per skip: arch. IA architect owns taxonomy; implementer briefs written by IA + conductor handoff or parent agent.

Todos

• IA: publish vocabulary table + grep inventory of stale strings
• UX: review scanner + nav + collection views for consistency
• Brief 1 — pages/ + components/ copy sweep
• Brief 2 — AGENTS.md + rules + SCHEMA_MAP glossary
• Add forbidden-stale-strings CI job

Operator action required

None.

Multitask dispatch

Slice dependencies

slice_dependencies:
  - brief: 1
    depends_on: []
    files:
      - pages/**/*.js
      - components/*.js
    notes: exclude pages/api/**
  - brief: 2
    depends_on: [1]
    files:
      - AGENTS.md
      - .cursor/rules/ui-and-theming.mdc
      - docs/SCHEMA_MAP.md
      - .github/workflows/ci.yml

Serial: Brief 2 after Brief 1 (docs reference final copy).

Cross-convoy: parallel with #1+#2 after secure-scanner-gemini-key merges — /multitask role-implementer #5 Brief 1 + #6 + #2 Brief 1 (disjoint files).

Post-PR audit:

/multitask role-reviewer + role-design-system-auditor + role-a11y-auditor

Group id: audit-rename-collections-vocabulary-<pr>.

CI impact

Workflow / job	Behavior
forbidden-stale-strings	New blocking job — grep pages/ + components/.
visual-diff.yml	Likely fires — widespread UI string changes in pages/components.
preview-smoke.yml	Fires; sign-in CTA wording must stay smoke-compatible.

Smoke caveat: smoke test 2 asserts /sign in/i on login page — do not rename that CTA in this convoy.

Decisions to ratify (IA architect)

1. "Lists" vs "Binders" — when to use each term in nav vs empty states.
2. Scanner button label — replacement for "Mark Owned" (e.g. "Add to session" vs "Confirm card").
3. Admin UI — out of copy sweep or separate pass?

Acceptance criteria

1. Zero rendered occurrences of the three forbidden strings in pages/ + components/.
2. Vocabulary table committed in AGENTS.md.
3. forbidden-stale-strings CI green.
4. Schema DDL unchanged (grep migrations/ — no new files).
5. Vitest 21/21; smoke 3/3 (sign-in CTA intact).

Out of scope follow-ups

• schema-cleanup-from-scanner-audit — is_system_collection vs user_cards unification (separate convoy).
• rename-repo-and-vercel-project — infra naming, not UI copy.