# site-ng Cutover Checklist

Tracking checklist of everything that must happen before site-ng replaces
the legacy Perl CGI on `arpartsfinder.com`. Each item gets a brief note
on what + why; remove it when done.

Last updated: 2026-06-04 (closed several go-live bars: ≥10-retailer
coverage met = 17 live, incl. Fulton Armory cut over today; GA4 wired
into base.html, config-driven; home hero "Not a store." removed in the
home relaunch. Also landed but not checklist items: the /instock pages
now filter like /browse, two-tier footer, "major retailers" dropped
site-wide.)
2026-06-02 (single-file config.ini model — deploy.sh ships
code only, all config in the remote config.ini; staging re-deployed +
validated end-to-end incl. magic-link email with dkim/spf/dmarc pass;
prod mail decision revised to apex-via-VPS interim, SES deferred).
2026-05-31 (DDL applied + verify script; staging deploy end-to-end with
SMTP/DKIM/SPF; pair email-auth setup notes).
2026-05-28: added section H. 2026-05-25: initial creation. See
[[builds-vs-drafts-model]], [[site-ng-decisions]],
[[site-migration-perl-to-flask]] for context.

---

## ⚠️ NEXT — jump.cgi must be rewritten into site-ng (cutover blocker)

site-ng currently REUSES the legacy Perl `jump.cgi` for affiliate
redirects + click logging ([[site-ng-decisions]]). That only works while
the legacy CGI site is still live alongside us. **At cutover, when site-ng
replaces the legacy Perl site, `jump.cgi` (and the Apache CGI handler /
`.htaccess` it depends on) goes away — every outbound product link and all
click tracking break.** This is the affiliate revenue path, so it must be
ported BEFORE go-live. Highest priority after the config work.

- [x] **Rewrite `jump.cgi` as a native site-ng route** — DONE 2026-06-03
      (commit 905ae50): `/jump` canonical + `/jump.cgi` alias, both
      blueprint routes in `ngsite/views/jump.py`; `%AFFILIATE` map ported
      to `data/affiliates.yml` (data, not code). Preserves the OPT-IN wrap
      (unmapped still redirect, [[jump-affiliate-not-allowlist]]), the
      `jump_log` upsert (count+1 on `(url,day)`), and 302 semantics. The 4
      product templates now emit relative `/jump?site=`. Validated in dev +
      on staging.
- [x] **PROD `.htaccess` `.cgi` rewrite — DONE 2026-06-06.** deploy.sh
      (blue-green) now writes `public/.htaccess` into EVERY release in both
      envs: the `RewriteRule ^jump\.cgi$ /jump [QSA,L]` + `^static/` bypass
      always; basic-auth + noindex robots layered on only for staging
      (`LOCKDOWN=1`). Prod releases get the rewrites with no auth, and the
      Flask `/robots.txt` route serves robots. Verified on staging (auth +
      rewrites present). See [[jump-cgi-rewrite-cutover-blocker]].
- [x] **Audit every affiliate / merchant ID in the `%AFFILIATE` map** — DONE
      2026-06-05. Verified each `data/affiliates.yml` entry against Mike's live
      AvantLink links. 8 active AvantLink retailers all correct (Brownells, PSA,
      Primary Arms, Stag, WMD Guns, GunMag, AR15Discounts, Faxon) — merchant_id
      + website_id match. Disabled Rainier (booted from AvantLink, pending
      Pepperjam), removed Aero Precision (unscanned) and New Frontier Armory
      (direct program ended) — all now redirect raw.
- [x] Test on staging: click-through to a mapped retailer (AvantLink wrap)
      AND an unmapped one (plain redirect) — DONE 2026-06-03, both `/jump`
      and `/jump.cgi` 302 correctly and `jump_log` increments.

---

## A. DDL — apply to prod MySQL (`arpartsfinder` / vdb1b)

Dev runs against `arpartsfinder_dev`. These tables/columns exist there but
need to be created on the live `arpartsfinder` database before site-ng
can be served from pair.com. Apply via phpMyAdmin (per memory:
[[db-user-privileges]], `easyperl_5_w` has no DDL grant — needs the
admin/phpMyAdmin path).

- [x] **`app_user`** — Flask session identity (email-only, magic-link auth) — APPLIED 2026-05-31
  ```sql
  CREATE TABLE `app_user` (
    `id` int unsigned NOT NULL AUTO_INCREMENT,
    `email` varchar(255) NOT NULL,
    `created` datetime NOT NULL,
    `last_login` datetime DEFAULT NULL,
    PRIMARY KEY (`id`),
    UNIQUE KEY `uq_email` (`email`)
  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;
  ```

- [x] **`magic_link`** — magic-link auth tokens + 6-digit codes. — APPLIED 2026-05-31
      `user_id` is nullable (deferred app_user creation per L2);
      `email` carries the auth identity until consume, when the
      app_user row is materialized and `user_id` is backfilled.
  ```sql
  CREATE TABLE `magic_link` (
    `id` int unsigned NOT NULL AUTO_INCREMENT,
    `user_id` int unsigned DEFAULT NULL,
    `email` varchar(255) NOT NULL DEFAULT '',
    `token` char(32) NOT NULL,
    `code` char(6) DEFAULT NULL,
    `failed_attempts` int unsigned NOT NULL DEFAULT 0,
    `created` datetime NOT NULL,
    `expires_at` datetime NOT NULL,
    `consumed_at` datetime DEFAULT NULL,
    PRIMARY KEY (`id`),
    UNIQUE KEY `uq_token` (`token`),
    KEY `idx_user` (`user_id`),
    KEY `idx_email` (`email`),
    KEY `idx_code` (`code`),
    CONSTRAINT `fk_link_user` FOREIGN KEY (`user_id`)
        REFERENCES `app_user` (`id`) ON DELETE CASCADE
  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;
  ```
  Notes:
  - `code` + `idx_code` were added 2026-05-25 for the 6-digit code
    login flow.
  - `failed_attempts` was added 2026-05-26 for code-brute-force
    lockout (security finding C1).
  - `email` + `idx_email` + nullable `user_id` were added 2026-05-26
    to defer app_user creation until consume (security finding L2 —
    prevents `app_user` bloat from unauthenticated /login spam and
    keeps unconfirmed emails out of the table).
  - If the schema lands first via an earlier migration, the
    add-column / modify forms are:
    ```sql
    ALTER TABLE magic_link
      ADD COLUMN code CHAR(6) DEFAULT NULL,
      ADD KEY idx_code (code);
    ALTER TABLE magic_link
      ADD COLUMN failed_attempts INT UNSIGNED NOT NULL DEFAULT 0;
    ALTER TABLE magic_link
      MODIFY COLUMN user_id INT UNSIGNED NULL,
      ADD COLUMN email VARCHAR(255) NOT NULL DEFAULT '',
      ADD KEY idx_email (email);
    ```

- [x] **`build`** — saved-build lineage rows (one per VERSION, lineage tied by `root_build_id`) — APPLIED 2026-05-31
  ```sql
  CREATE TABLE `build` (
    `id` int unsigned NOT NULL AUTO_INCREMENT,
    `code` char(8) NOT NULL,
    `owner_user_id` int unsigned DEFAULT NULL,
    `parent_build_id` int unsigned DEFAULT NULL,
    `root_build_id` int unsigned DEFAULT NULL,
    `is_latest` tinyint(1) NOT NULL DEFAULT '1',
    `title` varchar(120) DEFAULT NULL,
    `notes` varchar(1000) DEFAULT NULL,
    `votes` int unsigned NOT NULL DEFAULT '0',
    `status` enum('draft','public') NOT NULL DEFAULT 'public',
    `created` datetime NOT NULL,
    `updated` datetime NOT NULL,
    PRIMARY KEY (`id`),
    UNIQUE KEY `uq_code` (`code`),
    KEY `idx_owner` (`owner_user_id`),
    KEY `idx_parent` (`parent_build_id`),
    KEY `idx_root` (`root_build_id`),
    KEY `idx_owner_latest` (`owner_user_id`,`is_latest`),
    CONSTRAINT `fk_build_owner` FOREIGN KEY (`owner_user_id`)
        REFERENCES `app_user` (`id`) ON DELETE SET NULL
  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;
  ```

- [x] **`build_item`** — saved-build line items (denormalized snapshot of part info at save time) — APPLIED 2026-05-31
  ```sql
  CREATE TABLE `build_item` (
    `id` int unsigned NOT NULL AUTO_INCREMENT,
    `build_id` int unsigned NOT NULL,
    `parts_id` int unsigned DEFAULT NULL,
    `qty` smallint NOT NULL DEFAULT '1',
    `type` varchar(20) NOT NULL,
    `company` varchar(120) NOT NULL,
    `description` varchar(255) NOT NULL,
    `url` varchar(500) NOT NULL,
    `img` varchar(500) DEFAULT NULL,
    `price_at_add` decimal(10,2) DEFAULT NULL,
    `position` smallint NOT NULL DEFAULT '0',
    `added` datetime NOT NULL,
    PRIMARY KEY (`id`),
    KEY `idx_build` (`build_id`),
    KEY `idx_parts` (`parts_id`),
    CONSTRAINT `fk_item_build` FOREIGN KEY (`build_id`)
        REFERENCES `build` (`id`) ON DELETE CASCADE
  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;
  ```

- [x] **`hide_rule`** — already on prod ([[feature-exclude-items-from-display]])
- [x] **`parts.hidden`** + the related FK — already on prod
- N/A `reclassify_rule` — Pi-local SQLite, not prod MySQL ([[hide-vs-reclassify-storage-split]])
- [x] **`category_count`** — materialized per-type nav counts + stockometer
  denominator, refreshed from `parts.type` by the scanner
  (`scanner-ng/ngscan/category_counts.py`; daily timer + scan-completion +
  on-demand). Replaces the legacy `scan_count` denominator that diverged from
  `parts.type` under reclassification (the "(371/131)" bug). APPLIED to prod
  2026-06-04 (by Mike, phpMyAdmin) + populated; in `verify-cutover-ddl.py`.
  ```sql
  CREATE TABLE `category_count` (
    `type` varchar(50) NOT NULL,
    `in_stock` int unsigned NOT NULL DEFAULT 0,
    `total` int unsigned NOT NULL DEFAULT 0,
    `updated_at` datetime NOT NULL,
    PRIMARY KEY (`type`)
  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
  ```

---

## B. Config (`/path/to/prod/config.ini` on pair.com)

> **SINGLE-FILE CONFIG MODEL (2026-06-02, commit 4abb375).** This whole
> section is now literally one file: `config.ini` at the prod docroot,
> mode 600. deploy.sh ships CODE ONLY (trivial `passenger_wsgi.py`, nothing
> baked) and ABORTS before restart if `config.ini` is missing. The app
> reads db / mail / SECRET_KEY / public_url_root / env from it at boot.
> Build prod's from `config.example.ini`. **Staging was re-deployed on
> this model and validated end-to-end 2026-06-02: browse 200, magic-link
> login, and email send with dkim/spf/dmarc all passing.** See
> [[site-ng-deploy-script-shape]].
>
> **Mail decision revised 2026-06-02 (interim).** Prod sends transactional
> mail from the **apex** (`noreply@arpartsfinder.com`) via the pair VPS
> Postfix. Verified from real headers that outbound egresses from Mike's
> own dedicated VPS IP (not a shared pair relay), so the IP-segregation
> concern that drove the "transactional provider" recommendation below is
> moot for now, and reputation is self-contained. The `mail.` subdomain +
> transactional provider (SES) items further down are therefore **DEFERRED
> to when volume/deliverability monitoring warrant it — NOT cutover
> blockers.** See [[site-ng-email-transport-prod-decision]] §8.

- [ ] `[app] secret_key = <64+ hex chars>` — replaces the dev sticky-key
      fallback. Generate with `python -c "import secrets; print(secrets.token_hex(32))"`.
      Required — without it every prod restart logs everyone out (the
      sticky-dev fallback writes to a `.flask-secret-key` file the prod
      process may not have permission to create).
- [ ] `[app] NGSITE_ENV` absent OR not equal to `dev` — gates the
      Werkzeug debugger and the "verbose error → user" path. Prod must
      have the info-free 500 page.
- [x] `[mail] transport = smtp` — magic-link delivery. **Staging fully
      validated end-to-end on the single-file model 2026-06-02** (smtp via
      `easyperl.mail.pairserver.com:587`, STARTTLS, auth as
      `noreply@staging.arpartsfinder.com`; email delivered, dkim/spf/dmarc
      all pass). **Interim prod plan: same `smtp` transport to the same VPS
      Postfix host, auth as the apex `noreply@arpartsfinder.com`** — egress
      verified to come from Mike's own dedicated VPS IP (not a shared pair
      relay), so the earlier "use a transactional provider to avoid IP
      leakage" concern is moot for the interim. SES + the `mail.` subdomain
      are deferred (see banner + [[site-ng-email-transport-prod-decision]] §8).
- [ ] `[mail] from_addr = noreply@arpartsfinder.com` — apex sender for prod
      magic-link emails (needs apex DKIM signing as `d=arpartsfinder.com`;
      Mike activated apex DKIM/SPF 2026-05-31 — confirm it signs on the
      first prod test mail). **Staging uses
      `noreply@staging.arpartsfinder.com`** (validated, dkim `d=` aligned).
- [ ] **DEFERRED (not a cutover blocker) — Move prod sending identity to a
      dedicated subdomain (`mail.arpartsfinder.com`).** Superseded for the
      interim by apex-via-VPS (banner above); revisit at SES-migration time.
      Originally decided 2026-05-31, see
      [[site-ng-email-transport-prod-decision]] §7. Sender
      reputation builds on the DKIM `d=` domain, so sending
      directly from the apex would expose the apex's reputation to
      any future email mishap (compromised account, misconfigured
      campaign, deliverability incident). Dedicated subdomain
      isolates that. Mirrors what staging already does
      (`noreply@staging.arpartsfinder.com`).
- [ ] **Mail-auth DNS on `mail.arpartsfinder.com`** — required
      before flipping prod outbound. Set up via the chosen
      transactional provider (Postmark / Resend / SendGrid / SES
      / Mailgun) which will issue specific DKIM + SPF + DMARC
      records for the subdomain. Apex SPF activation Mike did on
      2026-05-31 stays useful (catches any incidental apex sends,
      bounces). Apex DKIM activation can either retire or stay
      dormant — harmless either way.
- [ ] **Create `noreply@mail.arpartsfinder.com` sending identity**
      with the chosen transactional provider. Use that as
      `MAIL_FROM` + the SMTP auth user in prod's
      `passenger_wsgi.py`. Aligns DKIM `d=mail.arpartsfinder.com`
      with the From header.
- [ ] **Publish DMARC on `_dmarc.mail.arpartsfinder.com`** —
      minimum `v=DMARC1; p=none`, with `rua=mailto:dmarc@arpartsfinder.com`
      once that mailbox is created. Subdomain DMARC policy can be
      stricter than the apex's (eventually `p=quarantine` or
      `p=reject` on the mail. subdomain while keeping apex at
      `p=none` for safety).
- [ ] **Create `dmarc@arpartsfinder.com` mailbox/alias** to
      receive DMARC aggregate reports — useful for spotting
      spoofing and finding any senders impersonating the domain.
      Deferred 2026-05-31 because the mailbox wasn't created yet.
      Apex DMARC was published as `v=DMARC1; p=none` (no rua=)
      tonight; this item adds the rua= once the mailbox exists.
- [ ] **`[app] public_url_root = https://arpartsfinder.com` — REQUIRED
      in prod.** The app refuses to start when `NGSITE_ENV != "dev"`
      and this is missing (security finding H2 enforcement, see
      `ngsite/__init__.py`). Used to build absolute magic-link URLs
      without trusting the inbound request's `Host:` header — without
      it, an attacker could host-header-inject to redirect the magic-
      link click to their domain and steal the token.
- [ ] `passenger_wsgi.py` entry point committed + points at the
      `create_app()` factory. The mod_passenger setup expects this.
- [x] ~~mod_passenger premise check on `staging.arpartsfinder.com`~~ —
      DONE 2026-05-30, all 7 checks green on pair Python 3.8.10
      (see `mod-passenger-premise-check` memory for the run details
      + pair-specific gotchas: public/ subdir layout required,
      Passenger* directives not allowed in .htaccess, env vars must
      go in passenger_wsgi.py via os.environ.setdefault). **EXTENDED
      2026-05-31: real site-ng deploy to staging end-to-end, including
      DB connectivity to prod `easyperl_inventory`, magic-link auth,
      and SMTP outbound — all green.** Smoke #2 on Python 3.12 still
      pending after pair's 24.04 upgrade if launch slips past
      2026-06-06; otherwise the 3.8.10 + real-site validation is the
      green light.
- [x] ~~**Deploy site-ng in the public/-subdir layout**~~ — DONE
      2026-05-31 for staging. `scanner-ng/scripts/deploy.sh` automates
      the layout (`passenger_wsgi.py` at app root, `public/` as docroot,
      tmp/restart.txt trigger). Pattern proven; prod is the same script
      with `--env prod --remote-root <path>`. pair won't
      auto-detect Passenger apps if `passenger_wsgi.py` sits at the
      docroot. Required structure:
      ```
      ~/public_html/arpartsfinder.com/
        passenger_wsgi.py       ← app root files
        ngsite/, run_dev.py, requirements.txt, .venv/, tmp/
        public/                 ← docroot points HERE in ACC
          .htaccess  (minimal — `RewriteRule ^static/ - [L]` only)
          static/   (built Tailwind CSS + sparkline SVGs)
      ```
      Repoint the prod docroot in ACC to the `public/` subdir during
      cutover.
- [x] ~~**Site-ng env vars in passenger_wsgi.py**~~ — DONE 2026-05-31
      via the deploy.sh-generated `passenger_wsgi.py` (mode 600 on the
      remote). Pattern: `os.environ.setdefault(...)` for all
      `NGSITE_*` keys (DB creds, secret key, public URL root, mail
      transport + SMTP_* when applicable). pair's shared hosting
      blocks `PassengerEnv` in .htaccess + has no ACC env-vars UI, so
      this is the working mechanism. setdefault means if pair ever
      gains an env-vars UI, that takes precedence.

---

## C. UI cleanup — remove dev scaffolding

- [x] ~~**Header wordmark "site-ng dev" badge**~~ — REMOVED 2026-05-31.
      Was an unconditional `<span>` next to the brand wordmark; just
      dropped it (along with its now-stale comment about being
      hidden on mobile). Same change committed for the footer below.
- [x] ~~**Footer "site-ng · Flask dev · data: local mirror"**~~ —
      REMOVED 2026-05-31. Was an unconditional `<div>` after the
      static-link row; just dropped it. The "since 2013" line + the
      What's New / FAQ / Resources / Terms row remain.

---

## D. Functional verification before flipping DNS / mod_passenger

- [x] ~~Magic-link email actually arrives in inbox~~ — VERIFIED ON
      STAGING 2026-05-31 (real send via pair-SMTP to a real Gmail;
      magic link clicked, app_user materialized, /auth/<token>
      logged in). SPF passes; DKIM passes with
      `d=staging.arpartsfinder.com`; DMARC display flagged FAIL
      until the staging `_dmarc` record propagates (UI quirk —
      Gmail shows "no DMARC record published" as FAIL rather than
      "none"). Re-verify on prod once apex DKIM propagates + the
      prod transport is wired (see [[site-ng-email-transport-prod-decision]]).
- [ ] 6-digit code login completes round-trip (POST `/auth/code`)
      — not yet exercised; magic-link path was the 2026-05-31
      verification, the 6-digit code branch hasn't been hit.
- [ ] `/jump.cgi` affiliate redirects still work — site-ng reuses the
      existing prod CGI per [[jump-affiliate-not-allowlist]]; not
      replacing it in this cutover.
- [ ] Anonymous-save flow works — POST `/build/save` with `anonymous=1`
      yields a `/b/<code>` URL, anonymous lineage banner appears on
      the public view.
- [ ] Stale-session self-heal works — manually delete an `app_user`
      row mid-session, hit any page, verify the amber flash + nav
      reverts to "Sign in".
- [ ] /instock/popular renders within an acceptable time
      (current dev: ~1.3s — see [[#E]] below for the caching fix).
- [ ] **Verify `mod_deflate` (gzip) is active on prod for `/static/`**
      (and ideally also on Flask-rendered HTML responses). Test:
      `curl -H "Accept-Encoding: gzip" -I https://arpartsfinder.com/static/js/browse.js`
      should return `Content-Encoding: gzip`. If missing, pair.com's
      Apache vhost needs `AddOutputFilterByType DEFLATE
      application/javascript text/css text/html` (or equivalent
      .htaccess directive). Mike 2026-05-30: skipped minification in
      favor of gzip + cache-buster, so this gates the actual perf win
      on first-visit.
- [ ] Tighten `Cache-Control` on `/static/`: with the `?v=<mtime>`
      cache-buster (commit `f809038`), max-age can safely be
      `31536000, immutable`. Flask's default is conservative; either
      override in app config or set via Apache. Repeat visits become
      essentially free on cached assets.

---

## E. Performance fixes deferred — not strictly blockers

- [x] ~~Skip `count_recent_popular` when `max_pages == 1`~~ — done
      2026-05-25, saved ~700ms per page load (the count query went
      from ~709ms to 0). Remaining cost is the page query itself
      + sparkline enrichment.
- [x] `/instock/popular` further optimization — DONE 2026-06-05. Shipped
      option 2: materialized `part_popularity` cache (parts_id -> clicks),
      refreshed by a nightly timer + scan-completion hook (scanner-ng commit
      9e4e5f2); `queries.recent_popular()` reads it via STRAIGHT_JOIN (site-ng
      afdd929). 603ms -> 49ms on prod. The full-scan + 28k jump_log lookups
      are gone.
- [ ] Mobile UX pass — [[site-ng-mobile-todo]]. Header crowding,
      build-chip dropdown overflow, missing bottom nav.
- [ ] Top-of-list spike protection on `/instock/new` after future
      retailer cutovers (PSA/AR15D currently dominate; will self-
      correct by ~May 28). Per-retailer fairness cap is the
      structural fix if it keeps mattering.

---

## F. Scanner adjacent work (not site-ng-blocking but coupled)

- [ ] PSA scanner-ng cutover ([[migration-cutover-status]] —
      currently marked pending; the data spikes in `parts.added`
      May 18-21 suggest something landed on PSA recently — verify).
- [ ] **Reach out to PSA about an IP whitelist** before live. PSA's
      Cloudflare managed-challenge hard-blocks our headless scanner
      after a few fast fetches ([[psa-cloudflare-volume-escalation]]);
      retry/pacing won't fix it. Whitelisting our scanner IP is the
      clean path to keep PSA inventory fresh (PSA is revenue-priority).
- [x] Bauer scanner-ng cutover — DONE (Bauer Precision is write_mode=live,
      one of the 17 live retailers).
- [ ] Confirm `scan_count` table is being kept fresh on prod through
      scanner-ng writes (the legacy frontend stockometer still reads
      it; site-ng has diverged but other surfaces may not have).

---

## G. Security findings (from pre-launch review 2026-05-26)

Subagent security review against the site-ng + scanner-ng code as of
commit `79ee9d9`. Items below are tracked by severity. Confirmed-clean
items (SQL injection across the read layer, XSS via `|safe`, Werkzeug
debugger gating, token entropy, etc.) are documented in the review
output but not repeated here.

### Not a concern (confirmed clean)

- SQL injection in `queries.py`, `saves.py`, `auth.py`, `housekeeping.py`,
  `purge-retailer` — all use PyMySQL `%s` placeholders for user input;
  string-interpolated SQL only uses hardcoded table/column names.
- XSS via `|safe` — only `sparkline_svg` SVGs, generated server-side
  from numeric data, no user input.
- Stale-session self-heal TOCTOU — worst case is a redirect + flash,
  no privilege upgrade possible.
- Token entropy (192 bits) and build short-code entropy (~47 bits).
- Werkzeug debugger in prod — explicitly gated by `is_dev`.
- `consume_code` / `consume_magic_link` UPDATE-then-SELECT atomicity —
  fine under InnoDB with autocommit=True.

---

## H. Pre-launch content, analytics & SEO (go-live bars, added 2026-05-28)

### Retailer coverage — at least 10 retailers live
- [x] **≥10 retailers showing live inventory on site-ng** — DONE 2026-06-04:
      **17 retailers live** on scanner-ng (Fulton Armory was the latest, cut
      over today). Bar comfortably met; onboarding continues breadth-first
      (the candidate notes below stay for the ongoing queue).
  - Start with retailers we already scanned, prioritizing those on
    AvantLink (commission path already wired via jump.cgi,
    [[avantlink-active-commissions]]).
  - Then work through AvantLink's current merchant list (a lot now).
    Weed out non-AR merchants: holster companies, general
    tactical/apparel, anything not selling AR parts. Follow up to
    onboard the legit AR-parts ones.
  - Cross-ref [[retailer-priority-order]] (Brownells, Primary Arms,
    Rainier, PSA first) + [[avantlink-feed-known-limitations]] (verify
    stock status / freshness / categories first).
  - Candidate sites (Mike 2026-05-28, full notes in
    [[retailer-onboarding-prelaunch]]): GunMag Warehouse / WMD Guns
    (affiliate, likely legacy scan), then apply-to-AvantLink: CMMG,
    Magpul, Ballistic Advantage (replaces Stag), Classic Firearms,
    Ammunition Depot, Redacted Arms (new, high commission). MidwayUSA =
    top of the next-to-add queue (verify listing-page stock status is
    back first). **Stag Arms ON HOLD** (legal / state-move / fulfillment
    concerns; revisit later).
  - Manufacturer-direct stores (CMMG/Magpul/Stag/WMD) need a per-retailer
    YAML flag to prepend the brand to item descriptions
    ([[manufacturer-direct-prepend-brand]]).

### Analytics — Google Analytics (GA4)
- [x] **GA4 on site-ng** — DONE 2026-06-04 (commit 480d427). gtag.js snippet
      in base.html, gated on a config-driven `[app] ga_measurement_id`:
      renders only when set, so it's off on dev/staging (no test traffic to
      the live property; staging runs as prod, which an env-based gate would
      have leaked). **Cutover action: set `ga_measurement_id = G-DV6K7L9ZGJ`
      in the prod config.ini.** Complements the server-side jump_log click
      tracking.

### Type-code cleanup — POST-LIVE (not launch blockers; re-verified 2026-06-05)
Re-checked against current prod 2026-06-05: `optics` is already handled, and
`blemished` / `pistolbrace` have **0 in-stock rows**, so they render nowhere
(the site surfaces in-stock parts only, and the sidebar nav is curated to
`TYPE_SECTIONS`). Mike 2026-06-05: treat as post-live TODO, not before-launch.
- [x] **`optics` (plural) → `optic`** — RESOLVED. `labels.py` now has a `TYPE_ALIASES` entry (`optics`→`optic`) that collapses the sidebar count, and `aliases_for()` makes `/browse?type=optic` return both `optic` + `optics` rows. The 94 in-stock optics render correctly as "Optic". No DB change needed.
- [ ] **`blemished` (28 rows, 0 in stock) — POST-LIVE.** Not in `TYPE_LABELS`, but with 0 in-stock it renders nowhere today. Only becomes a cosmetic raw card label (`{{ p.type|type_label }}` falls through) if a retailer restocks one. Decide then: labels entry, hide rule ([[feature-exclude-items-from-display]]), or retype.
- [ ] **`pistolbrace` (24 rows, 0 in stock) — POST-LIVE.** Same: 0 in-stock, renders nowhere now. Per [[scope-ar15-and-ar10]] AR pistol braces ARE in scope, so when restocked, add to `TYPE_LABELS` + a section (or retype to `stock`). Not a launch blocker.

### Pre-launch copy refinement
- [x] **Home page hero copy** — DONE 2026-06-04 (home relaunch, commit
      54529f1). The bold "Not a store." interjection is gone; the
      not-a-store framing now lives in the subhead ("...you buy direct
      from whoever has it") and the "how it works" step ("we don't handle
      checkout, cards, or shipping"). Per [[positioning-comparison-engine-not-retailer]].
- [x] **Validate every outbound URL on /resources** — DONE (Mike: the
      resources page has already been gone through and updated; dead/moved
      links fixed 2026-06-02, guns.com build guide added 2026-06-04).

### SEO — before live, especially build URLs
- [ ] **Share-URL slug inclusion — reevaluate after user feedback.**
      Today the `/b/<code>` share-card emits the BARE URL (no slug),
      even though canonical + sitemap + URLs that Google indexes
      all use the slugged form. SEO-wise the difference is
      negligible (single 301 hop carries ~99% link equity, Google
      honors canonical regardless of which URL was the backlink).
      But on plain-text forum/text contexts (ar15.com, older
      phpBB-style forums, IRC, README-style markdown) the bare URL
      has no keyword content visible to the reader. If we ever get
      "the URLs look generic on forums" feedback, the fix is a
      one-line template change (use `{{ public_url_root }}/b/{{
      head.code }}/{{ canonical_slug }}` in
      ngsite/templates/saves/public_view.html line ~100). No data
      migration; no breakage of existing links. 2026-05-31 Mike:
      put on the watch list, decide after we have real users.
- [ ] **General on-page SEO pass** per site-ng/docs/seo.md
      ([[seo-checklist-doc]]): titles, meta descriptions, canonicals,
      sitemap, robots.
- [ ] **Build-URL SEO (priority) — mostly DONE 2026-06-05; only `og:image` left.**
      SHIPPED: slugs on `/b/<code>/<slug>` (build_slug + sitemap + canonical);
      full Open Graph set (title/description/url/type/site_name + Twitter card);
      JSON-LD (ItemList of Product w/ Offer + InStock/OutOfStock on the build
      page, Organization sitewide). REMAINING: no `og:image` anywhere, so
      social shares render a text-only card. Add at minimum a static branded
      fallback og:image; optionally a per-build hero/composite image later.

---

## I. Things explicitly NOT in scope of this cutover

These are deferred to post-launch iterations; documented here so
nobody thinks they were forgotten:

- Restock alerts on build items ([[feature-site-build-alerts]]) — Phase 2 feature.
- OOS browse + per-part restock watches ([[feature-oos-browse-and-restock-watches]]) — Phase 2 alerts cluster, fills the gap where build-watch only catches parts a user added pre-OOS.
- Build comparison ([[feature-site-build-comparison]]).
- Completed-build photo gallery ([[feature-completed-build-photo-gallery]]) — Phase 2 community surface; two-sided market (existing rifle owners share retroactively-documented builds, new builders use the gallery as inspiration). Two visibility gates: user "Share to gallery" opt-in + moderator NSFW/on-topic approval.
- Per-product price-history chart ([[feature-site-price-history-view]]).
- Saved-search / price-watches ([[feature-site-price-watches]]).
- Interactive AR silhouette nav ([[feature-site-interactive-ar-silhouette-nav]]).
- Sister-site extraction ([[sister-sites-shared-infrastructure]]).
- Web URL config editor ([[web-url-config-editor]]).
- Category reclassification UI ([[category-reclassification-feature]]).
