docs(studio): decompose the draft/preview/admin report into per-subsystem docs

[martyy-code]

What

The 2026-07-30 architecture report was one 653-line file covering seven subsystems. It becomes docs/reports/studio/ — 21 documents, following the docs/learnings/ convention (README index table, numbered reading order, per-document Sources with verification dates).

docs/reports/studio/
  README.md                    problem, 9 locked decisions, topology, index, reading order
  01-data-model.md             tables, immutability, the two version pointers, manifest
  02-single-tree.md            the collapse + per-item arbitration
  99-frictions-and-costs.md    limits, costs, deferred, not-first-hand claims
  admin/    README.md, 01-auth.md
  agent/    README.md, 01-validators.md, 02-cli.md, 03-mcp.md
  preview/  README.md, 01-transpile-and-imports.md, 02-css-compile.md, 03-security.md
  publish/  README.md, 01-shadcn-registry.md
  repo/     README.md, 01-decoupling.md, 02-pnpm-and-versions.md,
            03-nextjs-16.md, 04-template-reuse.md

The original file becomes a stub with a section-to-file map, so old links land somewhere useful.

No code touched. 132 relative links and 29 anchors verified to resolve.

Why not just split the file

Every factual claim was re-measured against the repo on 2026-07-30. Several did not survive, and two of them were load-bearing for a locked decision.

Claim in the report	Measured
"The showcase file is a re-export, no design content to lose"	Holds for 4 items of 9. Five carry real implementation; for input, textarea, colored-badge, icon-button there is no packages/ui primitive to re-export at all
"The drift apparatus guards a difference of one import specifier"	It asserts on 3 of 9 items. Three get zero assertions and the run reports green — which is how a real divergence in ds-icon-button sits in a passing build
"All nine items begin with use client"	True of the showcase tree, 5 of 9 in the shipped tree
Phase 0: "contract-test.mjs install list → derive from catalog"	Its item list is already dynamic (9/9). Only the npm install list is hardcoded, and it is currently complete — latent coupling, not a stale list
"The v16.2.6 release page lists the CVE-2026-44576 fix"	The fix ships in v16.2.5; v16.2.6 is a Turbopack follow-up with no security commits. §18 of the report noted this but left §8 uncorrected
"same six variants, same nine sizes"	6 variants, 8 sizes

The consequence that matters: the dual-tree arbitration is now per item, not blanket. "The consumer version wins" would publish ds-icon-button's trimmed base string — missing group/button, text-sm, the active translate, every aria-invalid:* and every [&_svg] rule — as the single source of truth. For icon-button and colored-badge the workspace copy wins, and both need rewriting into self-contained form before they can become the source. That is real work the "one import specifier" framing hid.

Two additions the decomposition surfaced

Validators go from six to eight. Added: manifest agreement against the imports actually present in source, and category membership in the closed set of 13. Both agreements hold today across all nine items and are maintained by hand — under decision 2 they lose their maintainer. The registryDependencies half is load-bearing: decision 8 resolves those against published items, so a missing entry becomes a blank preview frame the agent cannot diagnose from errors[] rather than a validation error.

Publishing has to write apps/web/lib/registry/index.tsx — a hand-maintained aggregator with 18 hardcoded imports, keyed by short ids while registry.json is keyed by ds- names, with nothing cross-validating the mapping. The report's generated-file list omitted it. This moves decoupling from hygiene to a publishing prerequisite.

Also in this PR

• Amends the shadcn-registry-adoption addendum, which repeated the first two corrections above and pointed at the now-stubbed report.
• Fixes .gitignore: inline comments are not supported, so the existing .contract-test/ rule never matched anything. Also ignores temp/saas-template — a vendored reference checkout with its own .git, one git add -A away from being committed.
• Memory: adds project_studio_decisions.md, and its decision 5 entry now records that arbitration is per item.

Review path

Reading the whole thing is not the point. Start with docs/reports/studio/02-single-tree.md and repo/01-decoupling.md — those two carry the corrections and describe work that has to land before anything else. agent/01-validators.md is the one to disagree with if you are going to disagree with something: it argues that with no PR in the authoring loop, those eight checks are the entire enforcement surface of the project's anti-slop thesis.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
ui-web	Ready	Preview	Jul 30, 2026 2:34pm