create-ailk 0.1.1 → 0.2.0

package/component-catalog.md

@@ -2,22 +2,26 @@
 
 <!-- GENERATED FILE — do not hand-edit. Regenerate with `pnpm --filter create-ailk run build-catalog`. -->
 
-The composed-component inventory of `@working-theory/ui`, the library an AI Launch Kit site is built from. It exists because a name search fails: a site rebuilt five components AILK already had, because it searched for the names IT would have used and AILK uses different ones — `ContactOverlay`→`FormLightbox`, `SearchOverlay`→`SpotlightPanel`/`NavSearchTrigger`, `SiteRail`→`SidebarNav`, `FunnelNav`→`Nav`, `NumberedWorkList`→`Steps`/`StairSteps`.
+The component inventory of `@working-theory/ui` and the shells of `@working-theory/templates` — the library an AI Launch Kit site is built from. It exists because a name search fails: a site rebuilt five components AILK already had, because it searched for the names IT would have used and AILK uses different ones — `ContactOverlay`→`FormLightbox`, `SearchOverlay`→`SpotlightPanel`/`NavSearchTrigger`, `SiteRail`→`SidebarNav`, `FunnelNav`→`Nav`, `NumberedWorkList`→`Steps`/`StairSteps`.
 
-**What this file does NOT cover.** Only three tiers are indexed: `sections/`, `blocks/` and `chrome/`. The `tokens/`, `primitives/` (Button, Heading, Text, Link, Icon, Badge, Input, Dialog, Command, Tooltip, `ThemeToggle`, …) and `panels/` (FixedPanel, ResizablePanel, CardGrid, …) tiers are **absent from this file**. Finding nothing here does not mean AILK lacks it — check `packages/ui/src/primitives` and `packages/ui/src/panels` before concluding anything about a low-level control.
+**What this file does NOT cover.** All six component tiers are indexed — Sections, Blocks, Chrome, Primitives, Panels and Shells — so a component absent from these tables is genuinely absent from the library. Outside the file: the **design tokens** (tier 0 — colors, spacing, typography, radius and the rest are values in `@working-theory/theme`, not components; `packages/ui/src/tokens/` holds their Storybook stories and the small display components those stories use); the **page compositions** in `packages/ui/src/pages/` and `packages/templates/src/pages/`, which assemble whole pages from the tiers below; and every non-component module (hooks, `utils/`, `.ts` helpers).
+
+**Two things a listing does not promise.** First, the tables index every component file in the six tiers, **including the paid module slices** — the `Booker` family is here, and a build with the scheduling module switched off will not contain it. Listed is not the same as present in your tree; check the modules your site was scaffolded with. Second, this file carries no **props or data shapes**: it says what a component is FOR, never what it accepts. For a section's accepted `data` fields, read its Zod schema, or the `component-catalog.json` manifest the AILK source repo generates alongside this file.
 
 **Before you build a component, search this file for what it DOES.**
 
 1. Read **Find by capability** below — it maps the words people actually type to the names AILK uses.
 2. If nothing matches, grep the per-tier tables for a verb or noun from your requirement (`grep -i backdrop`, `grep -i "multi-step"`), not for your working name for the component.
-3. Check the primitives and panels tiers, which this file does not index (see above).
+3. Check the Primitives, Panels and Shells tables too — a low-level control, a collapsible layout container, or a route-level frame lives there, not under Sections or Blocks.
 4. Only then build. If you do build, you are declaring the capability is genuinely absent.
 
-Inventory: **187 component files** across 3 tiers — 56 sections, 113 blocks, 18 chrome. 186 distinct names: `SchedulerEmbed` exists in more than one tier as genuinely different components, listed once per tier with its own source path.
+Inventory: **286 component files** across 6 tiers — 59 sections, 115 blocks, 18 chrome, 79 primitives, 7 panels, 8 shells. 283 distinct names: `SchedulerEmbed`, `Separator`, `Tabs` exist in more than one tier as genuinely different components, listed once per tier with its own source path.
+
+Description coverage: **282/286** components carry a capability description derived from source — 41 from the section registry's hand-authored when-to-use text, 204 from the component's own doc-comment header, 37 from its tier barrel's roster line. **4** have none; they are listed under [Undescribed components](#undescribed-components) rather than given a sentence invented from their name.
 
-Description coverage: **187/187** components carry a capability description derived from source — 40 from the section registry's hand-authored when-to-use text, 113 from the component's own doc-comment header, 34 from its tier barrel's roster line. No component was given a sentence invented from its name.
+Of those, **252** are *strong* — a capability sentence you could match a requirement against — and **30** are *weak*: either one short clause, or a long one that spends itself on wiring (client boundaries, class names, which primitives it composes) instead of on what the thing is for. Weak rows are marked `(weak)` and listed in full under [Weak descriptions](#weak-descriptions). Coverage is 99%, but **findable-without-luck coverage is 88%**.
 
-Of those, **175** are *strong* — a capability sentence you could match a requirement against — and **12** are *weak*: either one short clause, or a long one that spends itself on wiring (client boundaries, class names, which primitives it composes) instead of on what the thing is for. Weak rows are marked `(weak)` and listed in full under [Weak descriptions](#weak-descriptions). Coverage is 100%, but **findable-without-luck coverage is 94%**.
+Per tier, strong out of total: **Sections** 58/59 · **Blocks** 110/115 · **Chrome** 11/18 · **Primitives** 64/79 (4 undescribed) · **Panels** 6/7 · **Shells** 3/8. A tier low on this line is a tier where a capability search is most likely to come up empty on something that exists.
 
 That grade is **mechanical**. It counts what it can measure — how much a description adds beyond the component's own name, how much of it is spent on wiring, whether the extraction came out damaged — and it cannot tell a fluent paragraph about the wrong subject from a useful one. A person reading these tables will find more rows unusable than the weak count admits. Treat it as a floor on the problem, not a measurement of it, and read the source before concluding a capability is absent.
 
@@ -34,7 +38,7 @@ The left column is search vocabulary — how a person phrases the need. It is ha
 | site rail · vertical nav column · left rail · app sidebar · icon rail · dashboard sidebar | `SidebarNav` (chrome) · `SidebarNavRailItems` (chrome) · `DocsSidebar` (chrome) · `SidePanel` (chrome) | Pick by context: SidebarNav is the DASHBOARD rail (it hardcodes a teams section and a user footer, and is the `sidebar` prop of DashboardShell) — fighting it into a marketing site is the wrong call; DocsSidebar is the DOCS rail (takes a page tree); SidebarNavRailItems is SidebarNav's collapsed icon-rail row. SidePanel is the RIGHT edge, not a left rail. |
 | funnel nav · minimal chrome with one CTA · stripped-down header · landing-page nav · one-action header · sticky CTA | `Nav` (chrome) · `SectionNav` (chrome) · `FloatingCta` (chrome) | There is no separate funnel-nav component, and there does not need to be: this is a CONFIGURATION of Nav — pass it one action and no link list. SectionNav is the in-page section jump nav; FloatingCta is the persistent floating single-action affordance. |
 | numbered work list · ordered steps · process list · how it works · 1-2-3 steps · staircase | `Steps` (blocks) · `StepFlow` (sections) · `StairSteps` (sections) · `FlowStepper` (sections) | For a numbered LIST you want Steps (presentational block) or StairSteps (staggered staircase section). StepFlow and FlowStepper are listed because the phrase collides, but they are the interactive multi-step FORM and its progress indicator — not a work list. |
-| accordion · collapsible · expand/collapse · show more · disclosure | `FaqItem` (blocks) · `FAQ` (sections) · `Objection` (sections) | There is no standalone Accordion — the expand/collapse behavior lives in FaqItem and the FAQ/Objection sections that compose it. |
+| accordion · collapsible · expand/collapse · show more · disclosure | `Accordion` (primitives) · `Collapsible` (primitives) · `FaqItem` (blocks) · `FAQ` (sections) · `Objection` (sections) | `Accordion` is the standalone primitive (Radix, multi-panel) and `Collapsible` is the single show/hide — reach for those for generic disclosure. FaqItem and the FAQ/Objection sections carry their own expand/collapse and are the right choice for question-and-answer CONTENT, because they also feed the page's JSON-LD. |
 | banner · announcement bar · cookie consent · notification strip | `Banner` (chrome) · `AlertSection` (sections) | Banner is chrome (announcement + consent, with dismiss/consent islands); AlertSection is the in-page dismissible strip. |
 | logo wall · client logos · trusted by · partner marks | `LogoCloud` (sections) · `Awards` (sections) |  |
 | pricing table · plan comparison · feature matrix · tier cards | `Pricing` (sections) · `PricingTierCard` (blocks) · `ComparisonMatrix` (blocks) · `ComparisonTable` (sections) · `BillingToggle` (blocks) |  |
@@ -44,12 +48,12 @@ The left column is search vocabulary — how a person phrases the need. It is ha
 | email capture · newsletter signup · subscribe box | `Newsletter` (sections) · `NewsletterFormInline` (blocks) · `NewsletterDetail` (blocks) |  |
 | video player · embedded video · video modal | `VideoSection` (sections) · `VideoEmbed` (blocks) · `VideoLightbox` (blocks) |  |
 | image slider · gallery · carousel · lightbox for images | `Carousel` (sections) · `Gallery` (sections) · `MediaBand` (sections) |  |
-| locale switcher · language picker · region selector · view toggle | `LocaleSwitcher` (blocks) · `MarkdownViewToggle` (blocks) | Dark-mode switching is `ThemeToggle`, a PRIMITIVE — primitives and panels are outside this catalog's three indexed tiers. Import it from `@working-theory/ui/primitives`. |
+| locale switcher · language picker · region selector · view toggle | `LocaleSwitcher` (blocks) · `MarkdownViewToggle` (blocks) | Dark-mode switching is `ThemeToggle`, a PRIMITIVE — see the Primitives table below. Import it from `@working-theory/ui/primitives`. |
 | table of contents · on-page nav · jump links · sticky outline | `SectionNav` (chrome) · `DocsTocButton` (blocks) · `DocumentChassis` (sections) |  |
 
 ---
 
-## Sections (56)
+## Sections (59)
 
 Page-level content bands. Most are MDX-driven (authored by `type` in page frontmatter and dispatched by `SectionRenderer`); a few are composed directly in a route.
 
@@ -76,6 +80,9 @@ Import: `import { X } from "@working-theory/ui/sections";` (or from the `@workin
 | `DecisionSplit` | An honest either-option decision block — use on /vs pages before any comparison. | MDX `type: decision-split` |
 | `Definition` | A single-term definition callout — use for one prominent 'What is X?' answer-first block. | MDX `type: definition` |
 | `DocumentChassis` | A long-read document page (privacy policy, terms, DPA, working agreement) — chrome-free header + optional stat strip + a sticky numbered section nav beside continuous prose; one document per page/route. The authored `sections` list drives both the nav and the body. | MDX `type: document-chassis` |
+| `DocumentViewer` | A paginated document embedded in a page (a report, a client deliverable) — use for a 10-50 page PDF at a closed 16:9 (deck) or letter (portrait) geometry, rendered by a dynamically-imported PDF.js so it never enters the main bundle. `src` accepts a public path or the authenticated `/v1/deliverables/:grantId` route. Not for long-read prose — that is `document-chassis`. | MDX `type: document-viewer` |
+| `DocumentViewerCanvas` | The PDF.js renderer for DocumentViewer. This file is reached ONLY via the dynamic import in DocumentViewerClient.tsx — that is deliberate: the static `import "pdfjs-dist"` below is what lands in this file's own route-split chunk instead of the main bundle (a static import of the renderer is a spec violation, not a style preference). | internal — compose from `packages/ui/src/sections/DocumentViewerCanvas.tsx` |
+| `DocumentViewerClient` | The interactive shell for DocumentViewer. Split out of DocumentViewer.tsx (which stays RSC) for the same reason AlertSection composes AlertSectionDismissIsland: interactivity is contained to one client island. *(weak)* | internal — compose from `packages/ui/src/sections/DocumentViewerClient.tsx` |
 | `FAQ` | Question-and-answer pairs — use to pre-empt buyer objections that are naturally phrased as questions. | MDX `type: faq` · `import { FAQ } from "@working-theory/ui/sections"` |
 | `Feature` | A multi-item benefit/feature highlight grid — use to walk through several product capabilities. | MDX `type: feature` |
 | `FlowStepper` | Rendering a served flow config as a real multi-step form. | `import { FlowStepper } from "@working-theory/ui/sections"` |
@@ -102,21 +109,21 @@ Import: `import { X } from "@working-theory/ui/sections";` (or from the `@workin
 | `SchedulerEmbed` | A declarative third-party booking iframe (e.g. Google Calendar Appointment Schedules) — use for a booking/scheduling moment; sets the provider's cookies on load, so a site classifying it as non-essential may wrap it in a consent gate. | MDX `type: scheduler-embed` · `import { SchedulerEmbed } from "@working-theory/ui/sections"` · `packages/ui/src/sections/SchedulerEmbed.tsx` |
 | `SectionEmpty` | The shared empty-state body every section's `*Empty` variant delegates to. | `import { SectionEmpty } from "@working-theory/ui/sections"` |
 | `SectionRenderer` | Typed dispatch table. Maps a section's `type` discriminant to its React component. | `import { SectionRenderer } from "@working-theory/ui/sections"` |
-| `Separator` | An inter-section spacer — use to add rhythm or a visible rule between two sections that need more separation than default spacing gives. | MDX `type: separator` · `import { Separator } from "@working-theory/ui/sections"` |
+| `Separator` | An inter-section spacer — use to add rhythm or a visible rule between two sections that need more separation than default spacing gives. | MDX `type: separator` · `import { Separator } from "@working-theory/ui/sections"` · `packages/ui/src/sections/Separator.tsx` |
 | `SocialProof` | Tweet/post-shaped social proof items — use for lightweight, screenshot-style endorsements. | MDX `type: social-proof` · `import { SocialProof } from "@working-theory/ui/sections"` |
 | `SplitContentMedia` | Lays out a SectionHeader (text, one side) beside a media slot (the other side) — the HubSpot/wealthsmyth split content+media pattern. | `import { SplitContentMedia } from "@working-theory/ui/sections"` |
 | `SpotlightPanel` | A full-width dimmed/blurred backdrop (abstract pattern or product image) behind a centered elevated card carrying a headline, support text, and a form/flow embed — use for a demo or signup moment that needs focus without leaving the page flow (apollo.io /demo pattern). | MDX `type: spotlight-panel` · `import { SpotlightPanel } from "@working-theory/ui/sections"` |
 | `StairSteps` | A 2-5 step staircase — use for process/journey narratives where direction carries meaning (an ascending 'up-right' staircase for a build-up story, a descending 'down-right' one for the conversionfactory.co 'from idea to impact' pattern). | MDX `type: stair-steps` · `import { StairSteps } from "@working-theory/ui/sections"` |
 | `Stats` | A number-led credibility row — use to show scale or outcome metrics. An optional leadQuote can front the row with an analyst quote (staggered variant mirrors apollo.io's mixed-size evidence band). | MDX `type: stats` |
 | `StepFlow` | A data-driven multi-step lead-capture form (one small field group per step, progress affordance, per-step advance) — use for a longer qualifying gate where a single-step ContactForm would feel too long; fires onStepComplete after each step so an abandoned flow still captures a partial lead. | MDX `type: step-flow` · `import { StepFlow } from "@working-theory/ui/sections"` |
-| `Tabs` | Tabbed content panels — use to let a reader choose between parallel content without scrolling. | MDX `type: tabs` · `import { Tabs } from "@working-theory/ui/sections"` |
+| `Tabs` | Tabbed content panels — use to let a reader choose between parallel content without scrolling. | MDX `type: tabs` · `import { Tabs } from "@working-theory/ui/sections"` · `packages/ui/src/sections/Tabs.tsx` |
 | `Team` | A team member grid — use on About pages to introduce the people behind the product. | MDX `type: team` · `import { Team } from "@working-theory/ui/sections"` |
 | `Testimonials` | Direct customer quotes — use for first-person social proof with attribution. | MDX `type: testimonials` |
 | `VideoSection` | The standard large-centered-video section (acquisition.com/workshop pattern) — optional headline/intro above a bounded-width centered video, optional caption/CTA below; renders a labeled placeholder until a real source is supplied. | MDX `type: video-section` · `import { VideoSection } from "@working-theory/ui/sections"` |
 
 ---
 
-## Blocks (113)
+## Blocks (115)
 
 Intermediate composition tiles — the pieces sections are built from. Compose primitives and panels; never import a section.
 
@@ -150,6 +157,8 @@ Import: `import { X } from "@working-theory/ui/blocks";` (or from the `@working-
 | `CodeBlock` | Read-only code display with syntax highlighting. Modeled on the Claude docs code-block pattern. | `import { CodeBlock } from "@working-theory/ui/blocks"` |
 | `ComparisonMatrix` | Full feature × tier comparison matrix for the Pricing 'with-comparison-table' variant. Renders N collapsible ComparisonGroups, each containing M feature rows with per-tier values. | `import { ComparisonMatrix } from "@working-theory/ui/blocks"` |
 | `Composer` | The chat input, per the ploy.ai capture contract. | `import { Composer } from "@working-theory/ui/blocks"` |
+| `ConsentGroup` | The composite control for the `consent` field kind: one real checkbox per consent purpose, each with its statement and inline policy links, inside one fieldset. | `import { ConsentGroup } from "@working-theory/ui/blocks"` |
+| `ConsentStatement` | The sentence a person agrees to, with its policy links inline. | `import { ConsentStatement } from "@working-theory/ui/blocks"` |
 | `ContactChannelItem` | Renders one support channel entry: colored icon square + headline + description paragraph + CTA link (with trailing arrow icon). | `import { ContactChannelItem } from "@working-theory/ui/blocks"` |
 | `ContactFormFields` | Renders the form field grid (Input / Textarea / Select primitives) + submit Button + optional consent text footer. | `import { ContactFormFields } from "@working-theory/ui/blocks"` |
 | `ContactInfoAside` | For ContactForm 'split-with-pattern' variant. Renders address / phone / email contact info rows. Each row: sr-only &lt;dt> label + visible &lt;dd> with Icon + Text. Phone and email render as tel:/mailto: links (click-to-call / click-to-email). | `import { ContactInfoAside } from "@working-theory/ui/blocks"` |
@@ -269,12 +278,140 @@ Import: `import { X } from "@working-theory/ui/chrome";` (or from the `@working-
 
 ---
 
+## Primitives (79)
+
+The base control and text vocabulary — Button, Heading, Text, Link, Icon, Input, Dialog, Command, Tooltip, ThemeToggle and the rest. This is the only tier allowed to render raw HTML elements; every tier above it composes these instead. Search here before building any low-level control.
+
+Import: `import { X } from "@working-theory/ui/primitives";` (or from the `@working-theory/ui` root barrel). Components marked *internal* are not re-exported — they are implementation details of a sibling in the same tier.
+
+| Component | What it does | How to use it |
+| --- | --- | --- |
+| `Accordion` | Collapsible panel set built on @radix-ui/react-accordion. | `import { Accordion } from "@working-theory/ui/primitives"` |
+| `Alert` | Contextual status message for user feedback. Supports four semantic variants (default, error, warning, success, info) that map to AILK Brand 1.3 status tokens. | `import { Alert } from "@working-theory/ui/primitives"` |
+| `AlertBanner` | Full-width status or promotional banner strip. Renders a horizontally-centered, full-width bar for site-level notices: informational, success, warning, error, and promotional messages. | `import { AlertBanner } from "@working-theory/ui/primitives"` |
+| `AlertDialog` | Confirmation overlay composed from @radix-ui/react-alert-dialog. Unlike Dialog, AlertDialog traps focus and requires the user to explicitly confirm or cancel before dismissing — appropriate for destructive actions. | `import { AlertDialog } from "@working-theory/ui/primitives"` |
+| `AlertDot` | Colored status dot with optional notification count. Use on integration cards, avatars, or any icon needing inline status indication. Pass `count` to render a capped badge (e.g. "99+") instead of a plain dot. Announces status to assistive technology via role="status" and a caller-supplied aria-label (required by accessibility contract). | `import { AlertDot } from "@working-theory/ui/primitives"` |
+| `AspectRatio` | Constrains content to a given width/height ratio. Thin re-export of @radix-ui/react-aspect-ratio. RSC-safe: no hooks or browser APIs — default server component. *(weak)* | `import { AspectRatio } from "@working-theory/ui/primitives"` |
+| `Avatar` | Circular or square user/company avatar with image, initials, or icon fallback. | `import { Avatar } from "@working-theory/ui/primitives"` |
+| `Badge` | Inline label chip with semantic status variants and size scale. | `import { Badge } from "@working-theory/ui/primitives"` |
+| `Breadcrumb` | Navigation primitive that renders an ordered wayfinding trail with accessible current-page marking and logical-direction separators. | `import { Breadcrumb } from "@working-theory/ui/primitives"` |
+| `Button` | `&lt;button>` (or any element via `asChild`) with cva variant + size styling via @working-theory/theme tokens. | `import { Button } from "@working-theory/ui/primitives"` |
+| `Calendar` | Date picker built on react-day-picker with AILK semantic tokens. | `import { Calendar } from "@working-theory/ui/primitives"` |
+| `Checkbox` | Accessible checkbox control backed by @radix-ui/react-checkbox. Renders a 16×16 checkbox with a Check icon when checked. Supports disabled state, custom className, and all Radix Checkbox.Root props. | `import { Checkbox } from "@working-theory/ui/primitives"` |
+| `ChipInput` | Row of dismissible chips with an optional add button. | `import { ChipInput } from "@working-theory/ui/primitives"` |
+| `CitationMarker` | Inline citation/source marker for agent-generated content. Renders a compact numbered or labeled source reference inline with text. Used alongside AI-generated content to surface provenance for individual claims. | `import { CitationMarker } from "@working-theory/ui/primitives"` |
+| `Code` | Code inline primitive — renders a semantic &lt;code> for code/variable spans inside prose. Inline sibling of Text. | `import { Code } from "@working-theory/ui/primitives"` |
+| `Collapsible` | Thin re-export of the Radix Collapsible root and content parts, plus the styled CollapsibleTrigger button. | `import { Collapsible } from "@working-theory/ui/primitives"` |
+| `Command` | Keyboard-navigable command palette / search input. Thin wrapper over the `cmdk` library (Command component) with AILK semantic token styling. Provides the full sub-component set: Command, CommandDialog, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator, CommandShortcut. | `import { Command } from "@working-theory/ui/primitives"` |
+| `ConfidenceIndicator` | Accessible confidence-level badge for AI-generated claims. Bound to the `@working-theory/validation` confidence shape: confidence_level = "low" \| "medium" \| "high" This matches the `overallConfidence` enum in market-landscape-summary and canonical-messaging-summary schemas, and the free-text `confidence_level` on HypothesisClaim. | `import { ConfidenceIndicator } from "@working-theory/ui/primitives"` |
+| `Container` | _no description in source — read `packages/ui/src/primitives/Container.tsx`_ | `import { Container } from "@working-theory/ui/primitives"` |
+| `ContextMenu` | Right-click / long-press contextual action menu. Thin wrapper over @radix-ui/react-context-menu with AILK semantic token styling. Provides the full Radix sub-component set: Root, Trigger, Portal, Content, Group, Label, Item, CheckboxItem, RadioGroup, RadioItem, ItemIndicator, Separator, Sub, SubTrigger, SubContent, Shortcut. | `import { ContextMenu } from "@working-theory/ui/primitives"` |
+| `CopyButton` | CopyButton Primitive. *(weak)* | `import { CopyButton } from "@working-theory/ui/primitives"` |
+| `Delta` | Sign-driven semantic indicator for numeric change. *(weak)* | `import { Delta } from "@working-theory/ui/primitives"` |
+| `Dialog` | Modal overlay composed from @radix-ui/react-dialog. *(weak)* | `import { Dialog } from "@working-theory/ui/primitives"` |
+| `DropdownMenu` | Contextual action menu anchored to a trigger. Thin wrapper over @radix-ui/react-dropdown-menu with AILK semantic token styling. Provides the full Radix sub-component set: Root, Trigger, Portal, Content, Group, Label, Item, CheckboxItem, RadioGroup, RadioItem, ItemIndicator, Separator, Sub, SubTrigger, SubContent, Shortcut. | `import { DropdownMenu } from "@working-theory/ui/primitives"` |
+| `EmptyState` | Purposeful empty / zero-item state indicator. Distinct from loading (`Skeleton`, `SectionSkeleton`) and error (`SectionErrorBoundary`) states. Use `EmptyState` when content is absent by design (no items yet, no search results, no activity), not when content is loading or a render error occurred. | `import { EmptyState } from "@working-theory/ui/primitives"` |
+| `Field` | Composes Label + a control slot + helper/error text. | `import { Field } from "@working-theory/ui/primitives"` |
+| `Form` | `preventDefault` + native Validity State + ARIA wiring. | `import { Form } from "@working-theory/ui/primitives"` |
+| `GradientText` | Mechanism (pure CSS, no client JS): the `.gt-text` utility in `@working-theory/theme`'s tokens.css sets `background-image: var(gradient-brand)` plus `background-clip: text` + transparent fill, so the gradient shows through the glyphs. That is the SAME technique `ShimmerText` uses via `.st-text`, minus the sweep: no `background-size` stretch, no `@keyframes`, no animate companion class. | `import { GradientText } from "@working-theory/ui/primitives"` |
+| `Heading` | _no description in source — read `packages/ui/src/primitives/Heading.tsx`_ | `import { Heading } from "@working-theory/ui/primitives"` |
+| `HoverCard` | Floating card revealed on hover, built on @radix-ui/react-hover-card. Exports Root, Trigger, and Content. The trigger is typically an anchor or interactive element; the content floats alongside it on pointer hover/focus. | `import { HoverCard } from "@working-theory/ui/primitives"` |
+| `Icon` | Single rendering path for Lucide UI icons and brand/channel logos (Simple Icons raw paths). | `import { Icon } from "@working-theory/ui/primitives"` |
+| `Image` | Wraps `next/image` and closes foot-guns at the type level. | `import { Image } from "@working-theory/ui/primitives"` |
+| `InlineMessage` | Quiet helper/error/warning text for forms. | `import { InlineMessage } from "@working-theory/ui/primitives"` |
+| `Input` | Single-line text input with variant styling. Supports default, warning, and error validation states, three size variants, and optional leading/trailing icon slots. | `import { Input } from "@working-theory/ui/primitives"` |
+| `Label` | Form field label with peer-disabled state styling. Wraps @radix-ui/react-label for correct association with form controls via `htmlFor`. Automatically dims and shows a not-allowed cursor when the associated control carries the `disabled` attribute (peer-disabled). | `import { Label } from "@working-theory/ui/primitives"` |
+| `Link` | _no description in source — read `packages/ui/src/primitives/Link.tsx`_ | `import { Link } from "@working-theory/ui/primitives"` |
+| `LoaderRing` | Compact loading-animation indicator. Renders the three loading animations (spinner, dots, check-transition) and, for terminal status, composes the shared StatusBadge primitive (success/error/warning). Sizes track the AILK icon-size token scale; all colors are AILK Brand 1.3 semantic tokens. | `import { LoaderRing } from "@working-theory/ui/primitives"` |
+| `Menubar` | Horizontal application menu bar with keyboard navigation. | `import { Menubar } from "@working-theory/ui/primitives"` |
+| `MenuItem` | Interactive menu item for dropdowns, context menus, etc. Full-width, left-aligned button with support for left/right icons, secondary text, selection state, and destructive variant. | `import { MenuItem } from "@working-theory/ui/primitives"` |
+| `MoneyAmount` | Locale-aware currency display. *(weak)* | `import { MoneyAmount } from "@working-theory/ui/primitives"` |
+| `NavigationMenu` | Accessible site navigation with flyout content. Thin wrapper over @radix-ui/react-navigation-menu with AILK semantic token styling. Provides the full Radix sub-component set: Root, List, Item, Trigger, Content, Link, Viewport, Indicator. | `import { NavigationMenu } from "@working-theory/ui/primitives"` |
+| `Pagination` | • Link mode (default, RSC-safe) — prev/next render as `&lt;a>` links built from `baseUrl` (`?page=N`); the inactive boundary control is a disabled `&lt;span>`. This is the original behaviour and is unchanged. | `import { Pagination } from "@working-theory/ui/primitives"` |
+| `PanelEdgeHandle` | Presentational primitive (Primitives tier, Tier 1). A full-height vertical edge handle with a ≥44px touch target (min-w-11). Used by tier-2 panels as the interactive edge handle — FixedPanel (collapse/expand) and ResizablePanel (drag-resize). | `import { PanelEdgeHandle } from "@working-theory/ui/primitives"` |
+| `Popover` | Floating content panel anchored to a trigger. Thin wrapper over @radix-ui/react-popover with AILK semantic token styling. Provides: Popover (root), PopoverTrigger, PopoverAnchor, PopoverContent, PopoverClose — the full Radix sub-component set. | `import { Popover } from "@working-theory/ui/primitives"` |
+| `Progress` | Wraps @radix-ui/react-progress with AILK token-driven styling. Supports three size variants (sm, md, lg) and two track colors (default, secondary). The indicator fill switches to the success emphasis token when `isComplete` is true. | `import { Progress } from "@working-theory/ui/primitives"` |
+| `ProgressRing` | Circular SVG progress indicator. Renders a ring (stroke arc) or pie (filled wedge) progress meter, plus success/error/warning filled-ring status states that mirror LoaderRing's status variants for consistent visual language. | `import { ProgressRing } from "@working-theory/ui/primitives"` |
+| `ProvenanceBadge` | Agent/human/system authorship chip with optional audit id. | `import { ProvenanceBadge } from "@working-theory/ui/primitives"` |
+| `RadioGroup` | Accessible radio button group backed by @radix-ui/react-radio-group. Exports RadioGroup (Root) and RadioGroupItem. The Root renders as a grid with gap-2 by default; items are 16×16 px filled circles. | `import { RadioGroup } from "@working-theory/ui/primitives"` |
+| `Rating` | Renders star icons for a 0–5 numeric rating, with full and half-star support and an accessible aria-label. | `import { Rating } from "@working-theory/ui/primitives"` |
+| `ScrollArea` | Custom-styled scroll container built on @radix-ui/react-scroll-area. Exposes ScrollArea (Root + Viewport + Corner composite) and ScrollBar as separately composable sub-components. | `import { ScrollArea } from "@working-theory/ui/primitives"` |
+| `SearchInputTrigger` | It is NOT search-or hero-specific: every visual axis (height, width, corner radius, background, border, placeholder, shortcut hint) is a token-driven prop so the same control can be restyled per placement. It does not own a real &lt;input>; clicking it (or pressing the hinted shortcut) fires `onClick`, which the caller wires to open a Command palette. | `import { SearchInputTrigger } from "@working-theory/ui/primitives"` |
+| `SectionErrorBoundary` | Wraps any section in a render-error containment layer. When a child throws during render, the boundary catches the error, logs it, and renders `&lt;SectionSkeleton>` as the fallback. | `import { SectionErrorBoundary } from "@working-theory/ui/primitives"` |
+| `SectionSkeleton` | Minimal animated placeholder block. Used as the default fallback by SectionErrorBoundary and as a loading skeleton in suspense-enabled section consumers. Renders a single animated rectangle respecting an optional aspect-ratio and className. | `import { SectionSkeleton } from "@working-theory/ui/primitives"` |
+| `SegmentedControl` | A compact single-select pill group with radiogroup semantics. | `import { SegmentedControl } from "@working-theory/ui/primitives"` |
+| `SegmentedProgress` | Discrete N-segment progress indicator. Renders `max` equal-width rounded bars in a row; the first `value` segments render filled (brand fill token), the remainder render as unfilled track segments. Distinct from the continuous `Progress` primitive (a single sliding-fill track) — use SegmentedProgress for step/checklist-style progress such as an onboarding checklist or a multi-step wizard. | `import { SegmentedProgress } from "@working-theory/ui/primitives"` |
+| `Select` | Accessible dropdown select backed by @radix-ui/react-select. Exports the full Radix sub-component set: Select (Root), SelectGroup, SelectValue, SelectTrigger, SelectContent, SelectLabel, SelectItem, SelectSeparator. | `import { Select } from "@working-theory/ui/primitives"` |
+| `Separator` | Thin divider line between content regions. | `import { Separator } from "@working-theory/ui/primitives"` · `packages/ui/src/primitives/Separator.tsx` |
+| `Sheet` | Slide-out panel anchored to any viewport edge. | `import { Sheet } from "@working-theory/ui/primitives"` |
+| `ShimmerText` | Mechanism (pure CSS, no client JS). All configurable values flow as CSS custom properties via the style prop so they are tunable at call-site without arbitrary Tailwind values. | `import { ShimmerText } from "@working-theory/ui/primitives"` |
+| `ShortcutTrigger` | Button-family primitive: a compact icon trigger with an optional keyboard-shortcut hint (e.g. ⌘K). | `import { ShortcutTrigger } from "@working-theory/ui/primitives"` |
+| `Skeleton` | Animated placeholder shown while content is loading. | `import { Skeleton } from "@working-theory/ui/primitives"` |
+| `Slider` | Range input built on @radix-ui/react-slider. Exposes the full Radix sub-component set (Root, Track, Range, Thumb) for composition, and provides a pre-composed &lt;Slider> default. | `import { Slider } from "@working-theory/ui/primitives"` |
+| `SplitButton` | A main action button paired with a dropdown trigger. *(weak)* | `import { SplitButton } from "@working-theory/ui/primitives"` |
+| `StatusBadge` | Colored circle + glyph status indicator. *(weak)* | `import { StatusBadge } from "@working-theory/ui/primitives"` |
+| `Surface` | Establishes a color-token context for its subtree. The `emphasis` variant marks the wrapper with `data-surface="emphasis"`, which remaps the theme-flipping semantic color tokens to their dark-palette values within the subtree (see the [data-surface="emphasis"] rule in @working-theory/theme/tokens.css). | `import { Surface } from "@working-theory/ui/primitives"` |
+| `Switch` | A toggleable on/off control built on @radix-ui/react-switch. | `import { Switch } from "@working-theory/ui/primitives"` |
+| `Table` | Semantic HTML table with token-driven styling. Exposes Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, and TableCaption as composable sub-components. | `import { Table } from "@working-theory/ui/primitives"` |
+| `Tabs` | Radix-backed tablist/tab/tabpanel with optional per-tab count badges and an optional "More ▾" overflow menu. | `import { Tabs } from "@working-theory/ui/primitives"` · `packages/ui/src/primitives/Tabs.tsx` |
+| `Text` | _no description in source — read `packages/ui/src/primitives/Text.tsx`_ | `import { Text } from "@working-theory/ui/primitives"` |
+| `Textarea` | Multi-line text input with variant styling. Supports default, warning, and error validation states and three size variants. Compose with &lt;Label> and &lt;Form> for accessible form fields. | `import { Textarea } from "@working-theory/ui/primitives"` |
+| `ThemeToggle` | Stateful 3-state theme owner. *(weak)* | `import { ThemeToggle } from "@working-theory/ui/primitives"` |
+| `ThemeToggleView` | 3-state icon segmented control. A presentational, controlled component. It renders what `value` says and calls `onChange` when the user picks a different mode. All theme persistence (cookies, DOM attribute writes) is the responsibility of the stateful owner {@link ThemeToggle}. | internal — compose from `packages/ui/src/primitives/ThemeToggleView.tsx` |
+| `TimePicker` | Time-of-day selector with 12h/24h formats. A dropdown of time slots (48 per day at the default 30-minute step), NOT an analog clock face. Composes the Select primitive — the generated slots render as Select options, inheriting Select's combobox/listbox a11y, keyboard, type-ahead, and styling (incl. the corner-radius fix). | `import { TimePicker } from "@working-theory/ui/primitives"` |
+| `Toast` | Radix-backed transient notification system. *(weak)* | `import { Toast } from "@working-theory/ui/primitives"` |
+| `Toaster` | Renders the toast viewport and maps queued toasts from `useToast` into individual `&lt;Toast>` instances. | `import { Toaster } from "@working-theory/ui/primitives"` |
+| `Toggle` | Toggle Primitive. *(weak)* | `import { Toggle } from "@working-theory/ui/primitives"` |
+| `Tooltip` | Radix-backed floating label anchored to a trigger element. | `import { Tooltip } from "@working-theory/ui/primitives"` |
+| `VisuallyHidden` | Renders its children so they are present in the DOM and the accessibility tree but visually hidden. Standardizes the ad-hoc `sr-only` className pattern previously hand-rolled across primitives (Dialog/Sheet/Toast close labels) and section headers. *(weak)* | `import { VisuallyHidden } from "@working-theory/ui/primitives"` |
+| `WorkingIndicator` | Renders the authentic Claude Code "working" indicator: a glyph that blooms frame-by-frame from a middle dot through increasingly complex Unicode star shapes to a full-star, then resets. Beside it sits a steady-colored label ("Thinking…" by default). | `import { WorkingIndicator } from "@working-theory/ui/primitives"` |
+
+---
+
+## Panels (7)
+
+Reusable layout containers that own their own interaction state (collapse, rail, drag-to-resize, off-canvas drawer below `lg`). Not page shells — composable containers that sit between primitives and blocks.
+
+Import: `import { X } from "@working-theory/ui/panels";` (or from the `@working-theory/ui` root barrel). Components marked *internal* are not re-exported — they are implementation details of a sibling in the same tier.
+
+| Component | What it does | How to use it |
+| --- | --- | --- |
+| `CardGrid` | The shared owner of how card-grid cells are arranged and separated — columns, gap, and the inter-cell SEPARATION treatment. Seven sections (BentoGrid, Items, Pricing, SocialProof, Stats, Testimonials, Team) currently hand-roll `grid gap-grid grid-cols-*`; this panel is the foundation they compose instead, the direct analogue of how `SectionFrame` collapsed 23× frame duplication. | `import { CardGrid } from "@working-theory/ui/panels"` |
+| `FixedPanel` | Collapsible layout-container primitive (Tier 2 — Panels). A three-state panel: expanded ↔ rail ↔ hidden. Controlled only — callers manage state via `state` + `onStateChange`. | `import { FixedPanel } from "@working-theory/ui/panels"` |
+| `FlowFrame` | The // frame: a full-viewport ground on the site `bg` token, two 50/50 regions (a persistent side panel + an active region) that stack below `md:` (side panel first, in DOM and visual order), and a bottom bar pinned to the VISIBLE viewport (`position: fixed`, safe-area aware) carrying a single continuous accent progress line, `leading` / `label` (center) / `trailing` slots, and a prop-controlled "Powered by Working Theory" line. *(weak)* | `import { FlowFrame } from "@working-theory/ui/panels"` |
+| `InvoiceDetail` | A single invoice's detail view, for the invoice surface (U4). Capability-bearing: binds a schema.org `Invoice` resource-payload fragment (imported from `@working-theory/schema`) — so a co-located `.text.ts` + `.text.test.ts` renderer is required and gated by `scripts/check-ax-parity.sh`. | `import { InvoiceDetail } from "@working-theory/ui/panels"` |
+| `ResizablePanel` | Drag-resizable layout-container primitive (Panels tier, Tier 2). Provides a resizable side panel container for layout composition. The panel width is controlled by the parent via `width` + `onWidthChange`/`onWidthChangeEnd`. The panel itself manages the drag interaction; the parent persists the committed width (e.g. via localStorage or server state). | `import { ResizablePanel } from "@working-theory/ui/panels"` |
+| `SectionFrame` | The shared frame the section tier composes instead of hand-rolling the `SectionErrorBoundary` + `&lt;section className="py-section bg-bg">` + `Container` plumbing (23× duplicated at time). | `import { SectionFrame } from "@working-theory/ui/panels"` |
+| `StickyColumn` | Makes one column of a two-column layout stick (`lg:sticky` with a top offset) while the sibling column scrolls — the HubSpot "left header sticks, right content scrolls" pattern. `lg`-only: below `lg` it is NOT sticky (normal flow, stacks). Consumed by SplitContentMedia; reusable by any two-column layout. | `import { StickyColumn } from "@working-theory/ui/panels"` |
+
+---
+
+## Shells (8)
+
+Route-level slot-frames — the outermost layout a page is placed into. They supply geometry and slots (nav / sidebar / main / footer), not content: you inject the real Nav, Footer and sidebar. A different package from every tier above: `@working-theory/templates`.
+
+Import: `import { X } from "@working-theory/templates/shells";` (or from the `@working-theory/templates` root barrel). Components marked *internal* are not re-exported — they are implementation details of a sibling in the same tier.
+
+| Component | What it does | How to use it |
+| --- | --- | --- |
+| `AdminShell` | @deprecated; use PortalShell with your own navItems. Internal admin dashboard layout shell. Thin composition of AppShell + SidebarNav. Converged from the hand-rolled layout in the prior MVP to match the AppShell pattern established by WorkspaceShell. | `import { AdminShell } from "@working-theory/templates/shells"` |
+| `AppShell` | Shared authed-app base frame. Layout ownership: AppShell is the SINGLE owner of the authed sidebar frame layout. The `sidebar` prop is CONTENT (e.g. a &lt;SidebarNav>), never a layout component. Do NOT pass SidebarShell or FixedPanel as the sidebar — that nests two incompatible layout systems (a fixed-width shell vs a variable-width panel). | `import { AppShell } from "@working-theory/templates/shells"` |
+| `ArtifactEditorShell` | Chat + artifact-canvas split-view slot-frame. Recomposes the ploy.ai Ploy Editor capture: a chat-driven artifact editor whose split view is LEFT = chat pane (conversation + composer) and RIGHT = artifact canvas (toolbar + preview/code), behind a drag-resizable divider. A blank session is chat-only, full width, until an artifact exists — then the canvas panel slides in. | `import { ArtifactEditorShell } from "@working-theory/templates/shells"` |
+| `BlogShell` | Blog reading **slot-frame** (DOCS-UI-8). Server Component (RSC default). A shell is a slot-defining frame: it carves out *where chrome goes* and *where content goes*, owning **geometry only**. Chrome (Nav/Footer) and content (the post meta rail + the reconciled BlogPost body) **fill** the slots — nothing is baked in. Peer to MarketingShell / DocsShell; see. *(weak)* | `import { BlogShell } from "@working-theory/templates/shells"` |
+| `DocsShell` | Documentation reading **slot-frame** (DOCS-UI-4). Server Component (RSC default). A shell is a slot-defining frame: it carves out *where chrome goes* and *where content goes*, owning **geometry only**. Chrome (DocsSidebar) and content (DocsArticleHeader + MDXContent + ArticlePager + DocsFeedback) **fill** the slots — nothing is baked in. Peer to MarketingShell; see. *(weak)* | `import { DocsShell } from "@working-theory/templates/shells"` |
+| `MarketingShell` | Public-facing marketing site **slot-frame**. Server Component (RSC default). A shell is a slot-defining frame: it carves out *where chrome goes* (top + bottom) and *where sections go* (the body), owning **geometry only**. Chrome (Nav/Footer) and sections **fill** the slots — nothing is baked into the component. See (first instance). *(weak)* | `import { MarketingShell } from "@working-theory/templates/shells"` |
+| `PortalShell` | Customer-facing portal (sidebar + branded top chrome + main);. Thin composition of AppShell + SidebarNav. Converged from the hand-rolled layout in the prior MVP to match the AppShell pattern established by WorkspaceShell. *(weak)* | `import { PortalShell } from "@working-theory/templates/shells"` |
+| `WorkspaceShell` | Application sidebar shell (thin AppShell composition);. Props are intentionally identical to the old DashboardShellProps — no additions beyond what AppShell provides — so any fork using DashboardShell can swap the import without changes. *(weak)* | `import { WorkspaceShell } from "@working-theory/templates/shells"` |
+
+---
+
 ## Weak descriptions
 
-These 12 components have a description that is accurate but does not do the job well: too short to match against, or long but spent on implementation. A capability search reaches them only if the searcher's word happens to be in it, so they are the most likely place for this catalog to repeat the failure it was built to fix. Read the source before concluding the capability is absent — and if you own one of these components, its header is the fix.
+These 30 components have a description that is accurate but does not do the job well: too short to match against, or long but spent on implementation. A capability search reaches them only if the searcher's word happens to be in it, so they are the most likely place for this catalog to repeat the failure it was built to fix. Read the source before concluding the capability is absent — and if you own one of these components, its header is the fix.
 
 | Component | Tier | What the source gives us |
 | --- | --- | --- |
+| `DocumentViewerClient` | sections | The interactive shell for DocumentViewer. Split out of DocumentViewer.tsx (which stays RSC) for the same reason AlertSection composes AlertSectionDismissIsland: interactivity is contained to one client island. |
 | `AgentContextCard` | blocks | Capability-bearing block that renders agent provenance. RSC note: no hooks or browser APIs — server-renderable by default. |
 | `PageHeader` | blocks | RSC. Page-level header composing the Breadcrumb primitive for the left-side wayfinding trail, a generic right-side `actions` slot, and an optional `switcher` slot for header-owned segment switching. Fills AppShell's `header` slot (DashboardShell and similar). No accent bar. No tab API. No named action props — the caller assembles whatever button/menu nodes it needs and passes them as `actions`. |
 | `PricingTierCardSeatControl` | blocks | Seat-count range picker for the Team tier card. Renders a Select primitive that lets the user choose an "Up to N seats" option from a caller-supplied list of numbers. The parent PricingTierCard stays a pure RSC; only this tiny island is hydrated. Pattern mirrors PageHeaderSwitcher.tsx: small "use client" island imported by an otherwise-server-rendered parent, keeping the client bundle minimal. |
@@ -287,9 +424,33 @@ These 12 components have a description that is accurate but does not do the job
 | `NavMobileMenu` | chrome | Client subcomponent for mobile hamburger state. Isolates "use client" to this narrow component so Nav (Server Component) stays clean. Renders a hamburger button + collapsible link list. Closes the menu automatically when the pathname changes (route navigation). |
 | `SidebarNav` | chrome | Application sidebar rail (nav + teams + user) for dashboard shells. Server Component (RSC). Renders the vertical sidebar rail for application-shell layouts. Used as the `sidebar` prop of DashboardShell. Wrap in a FixedPanel (panels tier) to get the expanded ↔ rail ↔ hidden state machinery. Independently reusable in future shells (settings, analytics, etc.). |
 | `SidebarNavRailItems` | chrome | Client boundary for the collapsed rail tooltip affordance. Isolated "use client" boundary so SidebarNav itself stays a Server Component. Renders icon-only nav links with Tooltip labels when the rail is collapsed. |
+| `AspectRatio` | primitives | Constrains content to a given width/height ratio. Thin re-export of @radix-ui/react-aspect-ratio. RSC-safe: no hooks or browser APIs — default server component. |
+| `CopyButton` | primitives | CopyButton Primitive. |
+| `Delta` | primitives | Sign-driven semantic indicator for numeric change. |
+| `Dialog` | primitives | Modal overlay composed from @radix-ui/react-dialog. |
+| `MoneyAmount` | primitives | Locale-aware currency display. |
+| `SplitButton` | primitives | A main action button paired with a dropdown trigger. |
+| `StatusBadge` | primitives | Colored circle + glyph status indicator. |
+| `ThemeToggle` | primitives | Stateful 3-state theme owner. |
+| `Toast` | primitives | Radix-backed transient notification system. |
+| `Toggle` | primitives | Toggle Primitive. |
+| `VisuallyHidden` | primitives | Renders its children so they are present in the DOM and the accessibility tree but visually hidden. Standardizes the ad-hoc `sr-only` className pattern previously hand-rolled across primitives (Dialog/Sheet/Toast close labels) and section headers. |
+| `FlowFrame` | panels | The // frame: a full-viewport ground on the site `bg` token, two 50/50 regions (a persistent side panel + an active region) that stack below `md:` (side panel first, in DOM and visual order), and a bottom bar pinned to the VISIBLE viewport (`position: fixed`, safe-area aware) carrying a single continuous accent progress line, `leading` / `label` (center) / `trailing` slots, and a prop-controlled "Powered by Working Theory" line. |
+| `BlogShell` | shells | Blog reading **slot-frame** (DOCS-UI-8). Server Component (RSC default). A shell is a slot-defining frame: it carves out *where chrome goes* and *where content goes*, owning **geometry only**. Chrome (Nav/Footer) and content (the post meta rail + the reconciled BlogPost body) **fill** the slots — nothing is baked in. Peer to MarketingShell / DocsShell; see. |
+| `DocsShell` | shells | Documentation reading **slot-frame** (DOCS-UI-4). Server Component (RSC default). A shell is a slot-defining frame: it carves out *where chrome goes* and *where content goes*, owning **geometry only**. Chrome (DocsSidebar) and content (DocsArticleHeader + MDXContent + ArticlePager + DocsFeedback) **fill** the slots — nothing is baked in. Peer to MarketingShell; see. |
+| `MarketingShell` | shells | Public-facing marketing site **slot-frame**. Server Component (RSC default). A shell is a slot-defining frame: it carves out *where chrome goes* (top + bottom) and *where sections go* (the body), owning **geometry only**. Chrome (Nav/Footer) and sections **fill** the slots — nothing is baked into the component. See (first instance). |
+| `PortalShell` | shells | Customer-facing portal (sidebar + branded top chrome + main);. Thin composition of AppShell + SidebarNav. Converged from the hand-rolled layout in the prior MVP to match the AppShell pattern established by WorkspaceShell. |
+| `WorkspaceShell` | shells | Application sidebar shell (thin AppShell composition);. Props are intentionally identical to the old DashboardShellProps — no additions beyond what AppShell provides — so any fork using DashboardShell can swap the import without changes. |
 
 ---
 
 ## Undescribed components
 
-None — every component in the inventory carries a real description.
+These 4 components carry no capability description recoverable from source: no section-registry entry, no substantive doc-comment header, no tier-barrel roster line. They are this catalog's blind spots — a capability search will not find them, so read the source before concluding AILK lacks something.
+
+| Component | Tier | Source |
+| --- | --- | --- |
+| `Container` | primitives | `packages/ui/src/primitives/Container.tsx` |
+| `Heading` | primitives | `packages/ui/src/primitives/Heading.tsx` |
+| `Link` | primitives | `packages/ui/src/primitives/Link.tsx` |
+| `Text` | primitives | `packages/ui/src/primitives/Text.tsx` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ailk",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Scaffolder for AI Launch Kit — `pnpm create ailk@latest <dir>` produces a starter repo consuming @working-theory/* from npm (per ADR 0007).",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,18 +30,6 @@
   "bugs": {
     "url": "https://github.com/working-theory-labs/ai-launch-kit/issues"
   },
-  "scripts": {
-    "lint": "tsx ../../scripts/lint-package.ts",
-    "build": "tsc -b",
-    "type-check": "tsc --noEmit",
-    "test": "tsc -b && node scripts/build-templates.mjs && jest",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage",
-    "build-templates": "node scripts/build-templates.mjs",
-    "build-catalog": "node scripts/build-component-catalog.mjs",
-    "check-catalog": "node scripts/build-component-catalog.mjs --check",
-    "prepublishOnly": "node scripts/build-templates.mjs && node scripts/build-component-catalog.mjs && tsc -b"
-  },
   "engines": {
     "node": ">=20.0.0"
   },
@@ -51,5 +39,16 @@
     "create-ailk",
     "ai-launch-kit"
   ],
-  "license": "Apache-2.0"
-}
+  "license": "Apache-2.0",
+  "scripts": {
+    "lint": "tsx ../../scripts/lint-package.ts",
+    "build": "tsc -b",
+    "type-check": "tsc --noEmit",
+    "test": "tsc -b && node scripts/build-templates.mjs && jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "build-templates": "node scripts/build-templates.mjs",
+    "build-catalog": "node scripts/build-component-catalog.mjs",
+    "check-catalog": "node scripts/build-component-catalog.mjs --check"
+  }
+}

package/templates/apps/api/CLAUDE.md

@@ -30,6 +30,7 @@ Routes are versioned under `/v1/*`:
 - `/v1/waitlist-experiments` (GET), `/v1/waitlist-experiments/:experimentId` (GET), `/v1/waitlist-experiments/:experimentId/signups` (GET), `/v1/waitlist-experiments/:experimentId/signups/:leadId` (GET) — the operator-dashboard read API for Parallel Waitlist Validation (#4665 D7, B0): tenant-scoped list + rollup, per-waitlist comparison, paginated signups, and a signup drill-down over A1's `WaitlistExperiment` / `WaitlistScore` / `Lead` rows (`src/services/waitlist-dashboard.ts`, #4671). Role floor `owner|admin` (signup PII); the platform-operator scope (`isSentinel(organizationId) && role === "owner"`, ALSO requiring `AILK_OPERATOR_EMAIL` to be set — fail-closed, PR #4687) sees every site, an ordinary owner/admin sees only its own `siteId`. No MCP twin — identity-bound tenant routes (#3591 exception, same shape as `/v1/billing/*`).
 - `/v1/waitlist-signups/me` (GET, `?experimentKey=<slug>`) — the respondent read (#4731): a signed-in, **email-verified** user's OWN newest signup for one experiment (`experimentKey`, `waitlistKey`, `completedAt`, `tier`, `score`, `aeoScore`, `answers.q3` — seven fields, nothing more; `src/services/waitlist-signups.ts` is the only read path). Registered in `authScope` only (auth, no tenant guard — a respondent has no workspace). Identity is `request.userId`; the email is the `User`'s, never a parameter; `emailVerified !== true` → 403 `email_unverified` before any `Lead` read; no match → 404 `signup_not_found`; every read scoped to `currentSiteId()`. No MCP twin — identity-bound (#3591 exception).
 - `/v1/flow-checkouts/me` (GET) — the respondent purchases read (#4984, FEAT-022 M2): a signed-in, **email-verified** user's OWN `FlowCheckout` rows, newest first, `[]` when none (`id`, `flowSlug`, `experimentKey`, `offerKey`, `status`, `amountMinor`, `currency`, `period`, `completedAt`, `createdAt` — ten fields, nothing more; `src/services/flow-checkouts.ts` is the only read path). Registered in `authScope` only, beside `/v1/waitlist-signups/me`. Identity is `request.userId`; rows are joined through the promotion link (`Lead.promotedUserId = userId`, `src/services/lead-promotion.ts`) — never by an email, and no query parameter is read; `emailVerified !== true` → 403 `email_unverified` before any `Lead` read; every read scoped to `currentSiteId()`. No MCP twin — identity-bound (#3591 exception).
+- `/v1/project-listings/me` (GET) — the FOUNDER'S OWN listings read (#5295): a signed-in user's own `ProjectListing` rows, newest first, `[]` when none. Registered in `authScope` only, beside `/v1/flow-checkouts/me` — a founder is not a workspace member, so the tenant guard's default-deny would answer 403 for their own submission. Identity is `request.userId`; rows are joined through the owner link (`ProjectListing.ownerUserId = userId`, stamped by `src/services/listing-promotion.ts`) — **never** by `founderEmail`, at any stage, and no query parameter is read. `founderEmail` is an unverified string typed into an anonymous form, so a read-time email match would hand one of two people sharing an address the other's submission. The row shape is `projectListingDraftSchema` (the founder-facing shape the anonymous draft read already uses — no `siteId`, `leadId`, `decidedBy`, `issueUrl`, or `experimentKey`). The route is ADDITIVE: `PROJECT_LISTING_ROLES` stays `owner|admin` and the tenant-scoped list/get/patch routes are unchanged. No MCP twin — identity-bound (#3591 exception).
 
 The workspace site-config routes are **identity-bound tenant routes** (guarded by the tenant preHandler; the write scope is the caller's active workspace, never a body-supplied id). Like the sibling `/v1/workspaces/*` routes they have **no anonymous MCP twin** — the OSS MCP surface is identity-blind (`apps/mcp/CLAUDE.md`), so the "1:1 MCP tool" rule above does not apply to them; the tenant-scoped authed MCP surface is tracked in #3591. The `/v1/billing/*` and `/v1/waitlist-experiments/*` routes are the same shape — identity-bound tenant routes, admin/settings-facing rather than agent-facing, no MCP twin.
 
@@ -118,7 +119,9 @@ sweep's own DB constraint (never a caller-side lock).
 - Don't read MDX directly — use `@working-theory/content-adapters`.
 - Don't put session state in `apps/api`. It's stateless.
 
-Last updated: 2026-09-07 — doc-sync: added `listing-csv:sweep` (#5001), the weekly founder-CSV sweep, to `## Scheduled sweeps (external cron)` — verified against `apps/api/src/bin/listing-csv-sweep.ts` and `apps/api/package.json`.
+Last updated: 2026-09-12 — doc-sync: added `GET /v1/project-listings/me` (#5295), the auth-scoped founder read joined on the owner link, to Endpoint conventions — verified against `apps/api/src/routes/project-listings/me.ts` and `apps/api/src/server.ts`.
+
+Prior: 2026-09-07 — doc-sync: added `listing-csv:sweep` (#5001), the weekly founder-CSV sweep, to `## Scheduled sweeps (external cron)` — verified against `apps/api/src/bin/listing-csv-sweep.ts` and `apps/api/package.json`.
 
 Prior: 2026-09-04 — doc-sync: added the `## Scheduled sweeps (external cron)` section documenting `abandon:sweep` and `followup:sweep` (#4732 AC-6) — verified against `apps/api/package.json` and `apps/api/src/bin/`.
 

package/templates/apps/api/src/lib/__mocks__/prisma.ts

@@ -21,6 +21,8 @@
  *   inbox model flowCheckout (create / update / updateMany / findUnique /
  *   findMany) — the recommender buyer record written by the
  *   recommender-capture service (#4837) and stamped by the webhook (#4838)
+ *   inbox model consentGrant (its `createMany` append-only writer + `findMany`
+ *   reader) — used by the #5275 consent service + project-listings draft tests
  *   inbox model waitlistFollowUpSend (its `create` stamp writer + `findMany`
  *   idempotency reader) + callback.findMany (booked-call suppression) +
  *   waitlistScore.findMany (tier lookup) — used by the #4732
@@ -241,6 +243,14 @@ export const prisma = {
     findFirst: jest.fn(),
     create: jest.fn(),
   },
+  // ── Inbox namespace (ConsentGrant — #5275) ───────────────────────────────
+  // `createMany` — the ONLY write path into consent_grants (recordConsent /
+  // recordLegacyConsent); append-only, never update/upsert. `findMany` — the
+  // "what did this subject agree to" read.
+  consentGrant: {
+    createMany: jest.fn(),
+    findMany: jest.fn(),
+  },
   // ── Content namespace (UsageEvent, UsagePeriod — FEAT-047 P1.S1/#3709) ──
   usageEvent: {
     create: jest.fn(),

package/templates/apps/api/src/routes/project-listings/__tests__/configured-application.test.ts

@@ -190,6 +190,17 @@ function installStore(): void {
     },
   );
 
+  // #5275 — the grant write `start` makes after the row. Append-only; it only
+  // needs to resolve here (drafts.test.ts asserts on what it is called with).
+  (prisma.consentGrant.createMany as jest.Mock).mockImplementation(
+    ({ data }: { data: Row[] }) => Promise.resolve({ count: data.length }),
+  );
+
+  // #5275 — `start` writes the row and its grant in one interactive
+  // transaction; the mock hands the same store-backed client through.
+  (prisma.$transaction as jest.Mock).mockImplementation(
+    async (fn: (tx: typeof prisma) => Promise<unknown>) => fn(prisma),
+  );
   (prisma.projectListing.create as jest.Mock).mockImplementation(({ data }: { data: Row }) => {
     const now = new Date();
     const row: Row = {