Follow-up (#1032→concepts scale): design/plan for /concepts/ virtualization + CAP takeover (orphaned in local worktree)

[jung-thomas]

Surfaced during a stale-worktree cleanup sweep. A committed design spec for scaling the /concepts/ page exists only on a local branch (never PR'd). Filing for deeper analysis before salvage or drop.

Where it lives (local, not pushed)

• Worktree: .claude/worktrees/concepts-scale-design
• Branch: worktree-concepts-scale-design
• HEAD: 186a937d — docs(concepts): design spec for scale (virtualize list + CAP takeover) (2026-07-08)
• Plus untracked: ?? docs/superpowers/plans/2026-07-08-concepts-scale.md (the implementation plan)

What's uncovered

A full design + implementation plan to make /concepts/ scale from ~700 to 5k–10k concepts:

• Thread A: CAP-rendered list page — top-100 SSR cards + embedded JSON + vue-virtual-scroller windowing.
• Thread B: POST /content/publish/render-concepts phase in publish-content.ts → new CAP endpoint queries PublishedConcepts + phase-4 tables, writes concept-<slug> BLOBs into ContentFiles.
• New files planned: srv/lib/concept-list-page.js, srv/lib/concept-detail-render.js, srv/lib/publish-concepts.js, EJS templates, extracted ConceptCard.vue, + unit/hybrid/snapshot tests.
• Explicitly DEV-only; respects the LOB-vs-CDS-QL gotcha and the PublishedConcepts projection freeze.

Needs deeper analysis

1. Is this still relevant? Concept count today vs the 5k–10k trigger — is scale actually a problem yet?
2. Does any of this overlap work already merged since 2026-07-08?
3. If still wanted: convert the design doc to a tracked spec on main + reopen as an active workstream.

⚠️ Do not delete the worktree until resolved

The implementation-plan doc is untracked — exists only in this worktree. The design spec commit 186a937d is also un-pushed. Salvage before deleting.

[jung-thomas]

Salvaged → active workstream

Re-verified the premise against live DEV (2026-07-27): /concepts/ serves 5,425 items in a 2.07 MB HTML doc (215 KB gzipped) and App.vue still DOM-toggles hidden per <li> — the scale problem is real and current, and none of the design was ever built on main. So this is being salvaged and implemented, not dropped.

Progress

• PR feat(concepts): scale /concepts/ — salvaged design + Task 1 render fn (#1327) #1330 (MERGED) — salvaged both orphaned docs (design spec + implementation plan, which existed only in the un-pushed worktree) onto main, plus Task 1: renderConceptDetail pure render function (srv/lib/concept-detail-render.js + concept-detail.ejs, 10 unit tests, ejs promoted to direct dep). Dark-launch safe.
• PR docs(concepts): flesh out scale plan Tasks 2-6, reconciled against main (#1327) #1334 (open) — fleshed out the plan's Tasks 2–6 (it originally stopped at Task 1) and reconciled it against current main. Found several stale assumptions and added a Status & errata section as the source of truth. Biggest one: buildConceptsPayload(db) already exists and returns the full per-concept shape both threads need — no new queries required.

Remaining (all DEV-only, dark-launch-first)

• Task 2 — GET /content/concepts-index list backend
• Task 3 — POST /content/publish/render-concepts phase
• Task 4 — App.vue RecycleScroller virtualization
• Task 5 — cutover (route flip + publish wiring + LEGACY_CONCEPT_RENDER guard)
• Task 6 — snapshot parity gate + smoke + deferred legacy cleanup

Keeping this issue open as the workstream tracker. The stale concepts-scale-design worktree is now safe to delete (both docs are on main via #1330).