Starting XI builder — implementation handoff

Updated: 9 October 2026. Stage: Builder, administration, fixture import, operational recovery and PNG export built; the admin restyle and connecting supporterxi.com (both with Codex) remain.

The current MVP is a next-match lineup builder with optional roles, browser-local memory, PNG export, and an administrator backoffice. There are no supporter accounts, Community XI, public lineup links, archives, or T-90 lock.

Starting in a new chat? Read the implementation handoff for current state, seed data, remaining decisions and the first implementation slice, then follow the authoritative reading order below.

Read in this order

1. Current PRD: approved scope and behaviour.
2. Formations: normative 14-formation catalogue.
3. Player roles: normative 25-role catalogue. Current PRD overrides references to MVP+ accounts, saved submissions and public links.
4. Application behaviour.
5. Data integrity.
6. Architecture decision.
7. Implementation plan.
8. Verification.
9. Decision status.

Product behaviour takes precedence over technical convenience. Architecture details are recorded separately from the PRD. Recommendations explicitly marked for confirmation are not prior product approval.

MVP+ preservation

The original documentation is preserved byte-for-byte under docs/mvp-plus/, including its original directory layout, catalogues, instructions and unresolved decisions. It is research/history for a possible later product, not authority for this MVP and not a promise to implement it next. Do not apply its release gates to current work.

The active formation and role catalogues retain their original taxonomy. The role document has an explicit applicability note; its impossible AR-05 example is superseded by the current verification contract without changing equivalence keys.

Naming and setup

The initial squad contains 36 numbered players transcribed from the user's screenshots. Its linked JSON is the seed source; it does not change the formation/role catalogue or decide pending admin validation policies.

The product name is Supporter XI, approved by the user on 9 October 2026. The user had supporterxi.com printed on the share image (9 October 2026); the domain is not yet connected to the site. docs/research/naming.md was missing at the audit and remains unavailable; do not fabricate it or treat Eleven Verdict as approved.

A UI redesign was agreed on 9 October 2026 and is live for the desktop and mobile builder (slices 1 to 3 and motion). Read the UI redesign handoff before changing any interface code. Two pieces remain: the admin restyle (slice 4, assigned to Codex) and sharing, the PNG export behind "Share your XI" (assigned to Claude; start from the sharing handoff). Sharing is built in three sizes (square, portrait, landscape); see sharing verification. Since 10 October 2026 a match locks 15 minutes after kickoff and the next one takes over at 120 minutes; see match lock verification. Later polish (logo order, phone header, desktop labels, search indexing that switches on with the domain) is in polish verification. The images print supporterxi.com at the user's direction; that domain is not yet connected to the site.

A design system was agreed on 10 October 2026: its values are in src/design/, the live reference is at /gameplan (public, never indexed), and the record and remaining steps are in the design system document. Use its tokens for any new public interface; the admin is outside it.

The public repository is tomasminarik/SupporterXI, connected to Vercel project supporterxi in the existing Tomo team. Production admin sign-in, content publication and the live featured-fixture response are verified. The football-data.org token is configured in Vercel Production, and the importer has published 32 Premier League/Champions League fixtures. The first scheduled run, live stale-write rejection, content rollback and isolated Preview failure/recovery are verified in operational readiness. The user waived the live alternate-account drill on 10 October 2026; automated identity rejection stays required. Provider credentials must never be committed.

Since 10 October 2026 the site has cookieless usage tracking (PostHog, production only), by user decision; what it may and may not send is in analytics.

Local development

Use Node 24 (nvm use if you have nvm), or another version supported by package.json.

npm ci
npm run dev

Open the homepage to build an XI for the currently published fixture. Open the interactive whiteboard to try all 14 formations, place the supplied players, assign optional roles, and move/swap/clear the XI. The whiteboard uses clearly synthetic match contexts and separate browser memory. Try reloading, toggling availability, and simulating the next fixture. No credentials are required for either public page.

For a production preview: npm run build, then npm start.

Checks and data ownership

npx playwright install chromium
npm run check

check runs lint, TypeScript, catalogue parity and unit tests, a production build, then Chromium browser/accessibility checks at four widths for both the production entry and local workbench. Production browser checks use port 3100; workbench checks start a development server on port 3101. Stop npm run dev before running the checks because Next.js permits only one development server for this directory. On Linux, use npx playwright install --with-deps chromium.

• Edit normative catalogue documents, then run npm run catalogues:generate. Do not edit src/data/*.generated.ts; build validation rejects stale outputs and specification/table discrepancies.
• content/shared.json is the single shared-content source. The original 36 squad records were moved here without changing IDs, names or numbers. Run npm run content:generate after player edits; src/data/squad.generated.ts is a generated public-only projection, never an independently edited roster. All 36 players start Active as approved; fixture availability defaults to Available.
• M-01 was approved on 8 October: Active players require unique integer numbers 1–99; only Inactive players may lack a number. M-02 is approved: existing selections survive availability changes, while removed ineligible players cannot be re-added.
• GitHub Actions runs validation and browser checks; Vercel builds from the connected repository. Verify deployment success separately from commit/push success.

See foundation verification for test mapping, limitations and the next slice.

npm run test:workbench verifies the development preview separately. /dev/workbench is enabled locally and on Vercel Preview deployments; it returns 404 on production deployments and local npm start.

Fixture content and rollover verification are documented in fixture-shell verification. The initial real fixture import and its publication are documented in import verification.

See browser-memory verification for fixture integration, storage recovery and approved availability behavior. The admin backoffice and fixture import are implemented. The Ant Design restyle is documented in admin restyle verification; purchased-domain cutover is tracked in domain launch. The 11 October usability pass (sign-in card, one availability list saved in one publication, unavailable players shown on the public list) is in Gaffer usability verification. Operational readiness records the latest production observations, recovery checks and remaining live drills. PNG export remains the last feature, immediately before final release checks.

Administration

Try the admin form preview locally or on a Vercel Preview deployment. Its edits stay in page memory. Production /gaffer now uses the configured GitHub administrator account. See admin setup and verification for secure configuration, limitations and checks.

The fixture import route and admin refresh action are described in import verification. Production has the provider token; an authorized refresh reports its import counts and checks publication. The public entry uses the published fixtures, with an honest no-fixture state if no future fixture qualifies.