mdx-artifacts 0.1.2 → 0.2.0

package/docs/cli-structure.md

@@ -0,0 +1,141 @@
+# CLI Structure
+
+This document describes how the CLI source tree is organized and where new code should go.
+
+The CLI entry remains `src/cli/index.ts`. It wires the command parser and delegates to command modules. Most implementation code should live below one of the focused subdirectories instead of growing inside the entry file.
+
+## Maintenance Summary
+
+The current CLI structure is the result of two stabilization passes:
+
+1. The source tree was moved from a flat `src/cli` directory into command, service, MDX, state, dev-server, config, diagnostics, and resources boundaries.
+2. The interaction and review commands were split so command modules stay focused on argument parsing, terminal output, and exit-code behavior, while service modules own stateful workflow operations.
+3. Validation now emits structured diagnostics and resource checks share a project-root safety policy.
+
+This means future CLI changes should start by identifying the real owner of the behavior:
+
+- command shape and terminal output belong in `commands/`
+- artifact state mutation belongs in `services/`
+- persisted MDX source changes belong in `mdx/`
+- browser-local endpoint handling belongs in `dev-server/`
+- state file format and route helpers belong in `state/`
+- config loading and config types belong in `config/`
+- structured diagnostic types belong in `diagnostics/`
+- local resource path safety and resource policy checks belong in `resources/`
+
+Do not put reusable workflow logic into a command module just because the first caller is a CLI command. If the same behavior could be triggered by the dev server, an agent, or a future automation entry point, place it below `services/` and keep the command as a thin wrapper.
+
+## Directory Map
+
+```text
+src/cli/
+  index.ts
+  commands/
+  config/
+  dev-server/
+  diagnostics/
+  mdx/
+  resources/
+  services/
+  state/
+```
+
+| Directory | Responsibility | Examples |
+|---|---|---|
+| `commands/` | Command-level orchestration for each public CLI command. | `build`, `components`, `dev`, `interactions`, `review`, `scaffold`, `validate` |
+| `config/` | Shared CLI config loading and public config types. | `loadMdxArtifactsConfig`, `MdxArtifactsConfig` |
+| `dev-server/` | Vite dev server integration and browser-facing dev endpoints. | artifact dev server middleware |
+| `diagnostics/` | Shared structured diagnostic types used by validation and resource checks. | `ArtifactDiagnostic` |
+| `mdx/` | MDX source updates, parsing helpers, and document mutation helpers. | `sortable-list` source patching |
+| `resources/` | Project-root resource safety and resource policy diagnostics. | safe path checks, resource policy checks |
+| `services/` | Reusable CLI workflows that sit below commands but above low-level helpers. | interaction and review operation handling |
+| `state/` | Artifact state file IO and state-shape helpers. | artifact state snapshots |
+
+## Boundaries
+
+Command modules should stay thin. They may parse arguments, call shared services, print concise CLI output, and return an exit code. They should not accumulate reusable state, MDX mutation, or dev server internals.
+
+Service modules can own workflow behavior that is shared by commands, the dev server, or future automation entry points. A service should not print CLI output directly unless the output is part of its public contract.
+
+MDX modules should keep document-level mutations close to the syntax they operate on. When a behavior changes persisted artifact source, prefer placing that logic under `mdx/` and calling it from a command or service.
+
+Current examples:
+
+- `commands/interactions.ts` parses interaction CLI arguments and formats CLI output.
+- `services/interaction-service.ts` owns SortableList runtime overlay writes and source promotion.
+- `mdx/sortable-list.ts` owns SortableList-specific MDX source inspection and patching.
+- `commands/review.ts` parses review CLI arguments, formats review output, and owns validate exit-code behavior.
+- `services/review.ts` owns review thread add, reply, validation, state writes, and anchor discovery.
+
+State modules should own local state file formats and persistence helpers. They should not know about command names, terminal output, or Vite middleware.
+
+Dev server modules should own runtime endpoints, Vite configuration, and browser integration. They may call services or state helpers, but should not become the source of truth for persisted document changes.
+
+Config modules should remain small and stable. Runtime UI components may import config types, but should not import command or service modules.
+
+Diagnostics modules should stay data-focused. They define result shapes that commands, validation, resource checks, and future agent repair loops can consume without depending on terminal formatting.
+
+Resources modules should own path safety and resource policy decisions. They may return diagnostics, but they should not read arbitrary MDX import graphs or turn artifacts into a data-loading framework.
+
+## Import Direction
+
+Prefer this dependency direction:
+
+```text
+index.ts
+  -> commands/
+    -> services/
+    -> config/
+    -> diagnostics/
+    -> resources/
+    -> state/
+    -> mdx/
+    -> dev-server/
+
+dev-server/
+  -> services/
+  -> state/
+  -> config/
+
+services/
+  -> state/
+  -> mdx/
+  -> config/
+
+resources/
+  -> diagnostics/
+```
+
+Avoid importing from `commands/` into lower-level modules. If logic is needed outside a command, move it into `services/`, `mdx/`, `state/`, or `config/` first.
+
+## Tests
+
+Keep tests next to the module they cover. For example:
+
+```text
+src/cli/commands/components.test.ts
+src/cli/state/artifact-state.test.ts
+src/cli/dev-server/vite-artifact.test.ts
+```
+
+Use focused CLI tests for command behavior and lower-level tests for state, MDX, and server helpers. Avoid testing the same behavior only through the CLI entry point when a narrower module test can cover it directly.
+
+For commands backed by services, prefer this test split:
+
+- Test the service directly for state mutations, MDX mutations, validation, and result shapes.
+- Test the command for argument parsing, output formatting, and exit-code behavior.
+- Test dev-server endpoints only for request validation, response shape, and whether they call the same service path as the CLI.
+
+This keeps behavior coverage close to the owner while still protecting the public command shape.
+
+## Future Split Points
+
+The current structure is only a directory boundary. It does not require every large module to be split immediately.
+
+Good next split candidates:
+
+- Keep interaction ordering and item mutation logic inside `services/` or `mdx/`, with commands and dev server endpoints calling that shared layer.
+- Keep dev server HTTP endpoint code inside `dev-server/`, but move reusable artifact operations out when they become useful from CLI commands.
+- Consider a dedicated interaction domain directory only after another interaction type, such as a board component, proves that `services/` plus focused `mdx/` modules are no longer enough.
+
+The goal is to keep the CLI queryable and agent-friendly without turning it into a framework. Add a new directory only when an existing boundary is no longer enough.

package/docs/component-protocol.md

@@ -9,19 +9,27 @@ Agents should write MDX that calls high-level components. They should not genera
 Typical source:
 
 ```mdx
-import { DecisionMatrix, ExportPanel } from "mdx-artifacts/react";
-
-<DecisionMatrix
-  question="Should stage one focus on a **single HTML artifact**?"
-  options={[
-    {
-      name: "Vite artifact",
-      pros: ["Short feedback loop"],
-      cons: ["No docs-site navigation yet"],
-      verdict: "Recommended"
-    }
-  ]}
-/>
+import { ContentSet, ExportPanel } from "mdx-artifacts/react";
+
+<ContentSet
+  id="set.stage-one"
+  title="Should stage one focus on a **single HTML artifact**?"
+  columns={3}
+>
+  <ContentSet.Item
+    id="vite"
+    title="Vite artifact"
+    badge="Recommended"
+    tone="positive"
+    emphasis="primary"
+    summary="Validate the shortest artifact loop first."
+  >
+    ### Tradeoffs
+
+    - Short feedback loop
+    - No docs-site navigation yet
+  </ContentSet.Item>
+</ContentSet>
 
 <ExportPanel
   value={{ recommendation: "Start with the single artifact loop." }}
@@ -42,14 +50,170 @@ import { DecisionMatrix, ExportPanel } from "mdx-artifacts/react";
 The CLI reads the same registry:
 
 ```bash
-artifact-kit components
-artifact-kit components DecisionMatrix
-artifact-kit components --json
+mdx-artifacts components
+mdx-artifacts components ContentSet
+mdx-artifacts components --json
 ```
 
 When adding or changing a component, update the registry in the same change.
 
-Complex props must be self-describing through the registry. Do not rely on TypeScript LSP alone for agent usage. If a prop type references a named object or object array, such as `DecisionMatrixOption[]`, `DiffLine[]`, or `CodeAnnotation[]`, add a matching entry to the component's `types` metadata:
+## Content Slots
+
+Content components should use a small display-oriented slot model. Prefer these slots before inventing component-specific text props:
+
+- `title`: required visible heading or item label.
+- `badge`: optional short display label shown beside the title.
+- `summary`: optional one-line explanation below the title.
+- `children`: Markdown-rich body content for paragraphs, local headings, lists, quotes, and rationale.
+
+Use props for short display structure. Use `children` for long explanations, pros and cons, tradeoff lists, risks, and any content that should remain readable in MDX diffs.
+
+Do not parse headings inside `children` as a component protocol. Headings and lists in children are human-readable body structure, not machine-readable slot names.
+
+Content components may add decorative icon slots when the component owns the icon placement and the semantic meaning remains in text, tone, and body content. See [Content Icon Slots](./content-icon-slots/README.md) for the phased policy.
+
+## Content Items
+
+Use `ContentItem` when one reusable content block needs display slots, tone color, emphasis weight, a stable comment anchor, and Markdown-rich body content.
+
+Use `ContentSet` when multiple same-kind content items should be displayed together:
+
+```mdx
+<ContentSet id="set.authoring-paths" title="Authoring paths" layout="grid" columns={3} surface="subtle">
+  <ContentSet.Item
+    id="component-first"
+    title="Component-first"
+    badge="Recommended"
+    tone="positive"
+    emphasis="primary"
+    summary="Best for stable interaction and visual structure."
+  >
+    ### Tradeoffs
+
+    - Clear component boundaries
+    - Easy to debug
+    - Less natural for long prose
+  </ContentSet.Item>
+</ContentSet>
+```
+
+`tone` and `emphasis` are separate:
+
+- `surface` controls the `ContentSet` container treatment: `plain`, `subtle`, or `outlined`.
+- `surface` is not semantic color. Use it to decide whether the group should read as document flow, a soft section, or a bounded section.
+- `tone` controls semantic color: `neutral`, `info`, `positive`, `warning`, `danger`, or `accent`.
+- `emphasis` controls structural weight: `default`, `primary`, or `subtle`.
+- `badge` is visible text only. It does not choose color by itself.
+- `emphasis="subtle"` may mute the badge and summary, but body children should remain readable.
+
+`ContentSet` is not a workspace or large layout container. Use it for one group of same-kind items. Use layout primitives such as `SplitPane` or `Columns` for multi-region artifacts.
+
+## Interactive Data Components
+
+Use props-first APIs when a component owns user-controlled state such as sorting, board columns, selected values, or exportable edits.
+
+`SortableList` is the current baseline:
+
+```mdx
+<SortableList
+  id="list.launch-priority"
+  title="Launch priority"
+  summary="Drag items or use the controls to change the handoff order."
+  items={[
+    {
+      id: "contentset-api",
+      title: "Stabilize ContentSet API",
+      summary: "Must land before public examples.",
+      badge: "P0",
+      tags: ["api", "docs"]
+    }
+  ]}
+/>
+```
+
+For interactive data components:
+
+- Use structured props for stable ids, item labels, tags, and initial state.
+- Keep item records short. Do not put long prose, Markdown lists, or narrative rationale into item data.
+- Persist user-controlled state into artifact interactions when available.
+- Treat MDX props as the authored truth and artifact interactions as the runtime overlay.
+- Use `mdx-artifacts interactions inspect <file.mdx> <id>` to read the current truth from MDX plus the state overlay.
+- Use `Section` beside the component for long explanation, criteria, or rationale.
+
+`interactions inspect` is read-only. It reports the resolved order, ignores stale state ids that no longer exist in MDX, and appends new MDX item ids that are not yet present in the state overlay.
+
+Use narrow CLI writes for runtime interaction state:
+
+```bash
+mdx-artifacts interactions set-order artifact-docs/examples/decision-matrix.mdx \
+  list.next-priorities \
+  --ordered-ids example-output validate-build adapter-design
+
+mdx-artifacts interactions reset artifact-docs/examples/decision-matrix.mdx \
+  list.next-priorities
+
+mdx-artifacts interactions promote artifact-docs/examples/decision-matrix.mdx \
+  list.next-priorities
+
+mdx-artifacts interactions add-item artifact-docs/examples/decision-matrix.mdx \
+  list.next-priorities \
+  --item-id docs --title "Update docs" --tags docs,protocol
+
+mdx-artifacts interactions update-item artifact-docs/examples/decision-matrix.mdx \
+  list.next-priorities \
+  --item-id docs --summary "Document the workflow."
+
+mdx-artifacts interactions remove-item artifact-docs/examples/decision-matrix.mdx \
+  list.next-priorities \
+  --item-id docs
+```
+
+`set-order` writes only the runtime overlay and requires the ordered ids to match the current MDX item ids exactly. `reset` removes the runtime overlay for that component and falls back to the MDX default order. Neither command edits MDX.
+
+`promote` is the explicit authored-truth write. It reorders the static MDX `items` array to match the current runtime overlay, then clears that component's overlay. It rejects stale or incomplete runtime ids instead of guessing.
+
+The local dev server exposes the same interaction writes through narrow JSON endpoints:
+
+- `POST /__artifact/interactions/set-order`
+- `POST /__artifact/interactions/reset`
+- `POST /__artifact/interactions/promote`
+- `POST /__artifact/interactions/add-item`
+- `POST /__artifact/interactions/update-item`
+- `POST /__artifact/interactions/remove-item`
+
+These endpoints are for local artifact tooling and reuse the same state and source write rules as the CLI.
+
+Item editing commands and endpoints are authored-truth writes. They patch the static MDX `items` array and keep any existing runtime order overlay synchronized. They only support short structured fields: `title`, `summary`, `badge`, `tags`, and `disabled`.
+
+When a local writable dev server is available, `SortableList` may expose a small item editor that calls these endpoints. Static artifacts remain read-only.
+
+## Authoring Kinds
+
+Every public component should declare an authoring kind in `src/react/registry.ts`. This keeps the component API aligned with the product philosophy and gives `mdx-artifacts components <ComponentName>` enough guidance for agents.
+
+Use these kinds:
+
+| Kind | Use For | API Shape |
+|---|---|---|
+| `content-block` | Readable cards, options, findings, risks, callouts, and repeated items. | `title`, optional `badge`, optional `summary`, and Markdown-rich `children`. |
+| `structured-renderer` | Code, diffs, line annotations, and other domain-shaped renderers. | Explicit structured props such as `code`, `lines`, or `annotations`. |
+| `layout-primitive` | Arrangement-only helpers such as `Stack`, `Columns`, `Grid`, `SplitPane`, and `Frame`. | Layout props plus `children`; no workflow semantics. |
+| `interactive-data` | User-controlled structured state such as sortable lists and future boards. | Structured props for initial state plus artifact interactions for user edits. |
+| `export-editor` | Export docks, editors, and state handoff controls. | Structured `value`, state, format, or handoff props. |
+| `review-boundary` | Comment layers, stable review sections, and fine-grained comment targets. | Stable ids or target ids plus the visible reviewed `children`. |
+
+The kind is not a styling category. It tells an author where meaning belongs:
+
+- `content-block`: keep long human-readable text in MDX children.
+- `structured-renderer`: keep machine-shaped data in props.
+- `layout-primitive`: do not encode domain meaning.
+- `interactive-data`: keep stateful records structured and exportable.
+- `export-editor`: keep handoff data structured.
+- `review-boundary`: keep anchors durable and review targets meaningful.
+
+Low-level shared rendering primitives, such as `CodeSurface`, may be exported for composition but should not be the primary authoring contract for agents. Native fenced code, `CodeBlock`, and `DiffBlock` can share one surface while keeping distinct semantics.
+
+Complex props must be self-describing through the registry. Do not rely on TypeScript LSP alone for agent usage. If a prop type references a named object or object array, such as `DiffLine[]` or `CodeAnnotation[]`, add a matching entry to the component's `types` metadata:
 
 ```ts
 {
@@ -80,7 +244,7 @@ Complex props must be self-describing through the registry. Do not rely on TypeS
 }
 ```
 
-The CLI must show these nested fields in `artifact-kit components <ComponentName>` and return them in `artifact-kit components <ComponentName> --json`.
+The CLI must show these nested fields in `mdx-artifacts components <ComponentName>` and return them in `mdx-artifacts components <ComponentName> --json`.
 
 ## Extension Lifecycle
 
@@ -124,11 +288,11 @@ Preferred public code components:
 
 Examples:
 
-- `DecisionMatrix`
-- `DiffExplainer`
-- `PriorityBoard`
-- `PromptWorkbench`
-- `FeatureFlagEditor`
+- `ContentSet`
+- `ContentItem`
+- `AnnotatedCode`
+- `ExportPanel`
+- future workflow recipes such as `DiffExplainer`, `PriorityBoard`, `PromptWorkbench`, and `FeatureFlagEditor`
 
 Workflow-level names such as `DiffExplainer`, `FeatureExplainer`, `StatusReport`, and `IncidentReport` do not need to start as large React components. They can first exist as agent recipes or MDX templates that explain which semantic primitives to combine.
 
@@ -174,15 +338,17 @@ Content rendering primitives may grow beyond text and Markdown. Future candidate
 - Does not support tables, HTML, math, or code blocks.
 - Prefer component title props for main artifact structure.
 
-`DecisionMatrix`
+`ContentItem`
 
-- Use for tradeoff comparison.
-- Text fields should remain short and scannable.
+- Use for standalone readable content cards.
+- Use `title`, optional `badge`, optional `summary`, `tone`, `emphasis`, and Markdown-rich children.
 
-`OptionGrid`
+`ContentSet`
 
-- Use for side-by-side alternatives.
-- Each option should focus on intent and tradeoffs.
+- Use for a group of same-kind content items.
+- Use `ContentSet.Item` children.
+- Use `layout="grid" | "stack"` and `columns={2 | 3 | 4 | 5}` for arrangement.
+- Use `tone` for semantic color and `emphasis` for structural weight.
 
 `ExportPanel`
 
@@ -195,7 +361,7 @@ Reviewable content should use stable anchors:
 
 - Native MDX prose uses `Section id="..."`.
 - Structured components use their own `id` prop.
-- Component sub-items may derive child anchors from the parent id and item id, such as `decision.stage-one.vite`.
+- Component sub-items may derive child anchors from the parent id and item id, such as `set.stage-one.vite`.
 
 The source MDX remains the content truth. Review state lives in a sibling `.state.json` file and references anchors through `anchorId`.
 
@@ -241,16 +407,16 @@ Example state:
 Use narrow CLI writes for review state:
 
 ```bash
-artifact-kit review add artifact-docs/examples/decision-matrix.mdx \
+mdx-artifacts review add artifact-docs/examples/decision-matrix.mdx \
   --anchor decision.stage-one \
   --body "Clarify why native MDX remains the default."
 
-artifact-kit review reply artifact-docs/examples/decision-matrix.mdx \
+mdx-artifacts review reply artifact-docs/examples/decision-matrix.mdx \
   --thread thr_decision_stage_one \
   --body "Updated the decision copy." \
   --status resolved
 
-artifact-kit review validate artifact-docs/examples/decision-matrix.mdx
+mdx-artifacts review validate artifact-docs/examples/decision-matrix.mdx
 ```
 
 `review add` creates one open thread for an existing anchor. `review reply` appends assistant messages to existing threads and may update status. `review validate` reports state threads whose `anchorId` no longer exists in the current MDX. None of these commands edits MDX.

package/docs/component-taxonomy.md

@@ -48,6 +48,41 @@ The common risk is exposing too many `Card`, `Panel`, or ad hoc `Grid` shapes. T
 
 Semantic examples matter. A code diff is not just a container with monospace text. It has files, hunks, line ranges, annotations, severity, findings, and review handoff. That is why `AnnotatedCode` belongs in the semantic layer, and why `DiffExplainer` should start as a workflow recipe before becoming a large code component.
 
+## Content Component Slot Model
+
+Use the shared display slot model for readable content components that render repeated cards, items, options, findings, risks, or sections.
+
+Default slots:
+
+- `title`: the primary visible label.
+- `badge`: an optional short status or category label beside the title.
+- `summary`: an optional one-line explanation below the title.
+- `children`: Markdown-rich body content for paragraphs, local headings, lists, quotes, risks, pros, cons, and rationale.
+
+This slot model applies to `ContentItem` and `ContentSet.Item`. It should also be the default for future components such as `FindingCard`, `RiskList.Item`, `StatusReport.Section`, or `ImplementationPlan.Step`.
+
+Do not apply the slot model blindly to every complex component:
+
+- Structured renderers such as `CodeBlock`, `DiffBlock`, and `AnnotatedCode` should keep their domain schemas.
+- Layout primitives such as `Stack`, `Columns`, `Grid`, `SplitPane`, and `Frame` should keep layout props and children.
+- Export or editor components such as `ExportPanel` should keep state and handoff props.
+- Document boundaries such as `Section` should stay focused on stable review anchors and native MDX children.
+
+The test is whether the component is primarily a readable content block. If yes, use `title`, `badge`, `summary`, and `children`. If the component primarily renders structured data, controls layout, or exports state, keep its domain-specific schema.
+
+## Authoring Metadata
+
+The registry records the same distinction through `authoring.kind`. This makes the taxonomy queryable from the CLI instead of leaving it only in prose docs.
+
+| Authoring Kind | Current Components | Guidance |
+|---|---|---|
+| `content-block` | `InlineText`, `MarkdownBody`, `ContentItem`, `ContentSet`, `SeverityBadge`, `Callout`, `ComparisonSet` | Use short display props plus Markdown-rich children for readable body content. |
+| `structured-renderer` | `CodeBlock`, `DiffBlock`, `AnnotatedCode` | Keep code, diff rows, and annotations in structured props. |
+| `layout-primitive` | `Stack`, `Columns`, `Grid`, `SplitPane`, `Frame` | Arrange content without owning workflow meaning. |
+| `interactive-data` | `SortableList` | Keep user-controlled state structured, short, and exportable through artifact interactions. |
+| `export-editor` | `ExportPanel`, `CommentExport` | Keep handoff data structured and copy/export behavior explicit. |
+| `review-boundary` | `CommentLayer`, `Section`, `CommentableBlock`, `CommentTarget` | Provide stable anchors around meaningful review targets. |
+
 ## Extension Lifecycle
 
 Component candidates do not all need to enter the core package. Use the lifecycle below to keep the core package small while still giving agents room to handle new artifact shapes.
@@ -102,6 +137,7 @@ Already available:
 - `MarkdownBody`: controlled block Markdown for component-local body copy.
 - `CodeBlock`: controlled code rendering with filename, language label, line numbers, and highlighted lines.
 - `DiffBlock`: structured diff rendering with add, remove, context rows, and compact effective line numbers.
+- `CodeSurface`: low-level shared code frame used by native fenced code, `CodeBlock`, and `DiffBlock`; prefer author-facing components or native Markdown in artifact source.
 - `Callout`: semantic note, warning, recommendation, or risk block with controlled Markdown body copy.
 - `SeverityBadge`: compact severity, confidence, status, or risk label.
 - `AnnotatedCode`: code block with line-level annotations and severity labels.
@@ -114,7 +150,7 @@ Candidate foundation components:
 | `Callout` | Highlight warnings, assumptions, gotchas, or decisions. | Shipped | Useful across reports, code review, research, and plans. |
 | `SeverityBadge` | Show severity, confidence, status, or risk. | Shipped | Small but widely reused by review/report components. |
 | `AnnotatedCode` | Render code with line notes and severity markers. | Shipped | First version uses a code block plus annotation list. |
-| `CodeBlock` | Render code with language, filename, line numbers, and highlighted lines. | Shipped | Syntax highlighting and copy affordance remain future enhancements. |
+| `CodeBlock` | Render code with language, filename, line numbers, copy affordance, and highlighted lines. | Shipped | Syntax highlighting can be added later without changing the authoring contract. |
 | `DiffBlock` | Render structured diff rows with compact effective line numbers. | Shipped | Accepts structured lines first; raw unified diff parsing can be a later helper. |
 | `Timeline` | Show ordered events, milestones, incidents, or plans. | P2 | Reusable for status reports, incidents, and implementation plans. |
 | `MetricCard` | Show compact numeric status with label and trend. | P2 | Useful for status reports and dashboards. |
@@ -130,8 +166,8 @@ Workflow recipes represent artifact-level jobs. They are usually better expresse
 
 Already available:
 
-- `DecisionMatrix`: compare options.
-- `OptionGrid`: show alternative directions side by side.
+- `ContentSet`: group same-kind content items in a grid or stack, with optional container surface treatment.
+- `ContentItem`: render a standalone readable content card.
 
 Candidate workflow recipes:
 
@@ -140,7 +176,7 @@ Candidate workflow recipes:
 | `DiffExplainer` | PR review with files, diff hunks, annotations, and findings. | P1 | `AnnotatedCode`, `SeverityBadge`, `Callout` |
 | `PRWriteup` | Reviewer-facing PR explanation with motivation, file tour, and review focus. | P2 | `Callout`, `AnnotatedCode` |
 | `ModuleMap` | Explain a package or module through nodes, edges, entry points, and hot paths. | P2 | Future diagram primitives |
-| `ImplementationPlan` | Show milestones, risks, data flow, and handoff tasks. | P2 | `Timeline`, `Callout`, `DecisionMatrix` |
+| `ImplementationPlan` | Show milestones, risks, data flow, and handoff tasks. | P2 | `Timeline`, `Callout`, `ContentSet` |
 | `FeatureExplainer` | Explain how a repo feature works with TL;DR, files read, steps, code tabs, gotchas, and FAQ. | P2 | `DisclosureSteps`, `TabsPanel`, `AnnotatedCode`, `Callout` |
 | `StatusReport` | Weekly or project status summary with shipped/slipped/risks. | P3 | `MetricCard`, `Timeline`, `Callout` |
 | `IncidentReport` | Post-mortem with TL;DR, severity, timeline, root cause, impact, and action items. | P3 | `Timeline`, `AnnotatedCode`, `DataTable`, `ActionItemList`, `Callout` |

package/docs/design.md

@@ -35,13 +35,14 @@ First-stage components:
 
 - `InlineText`: short text with controlled inline Markdown.
 - `MarkdownBody`: controlled component-local body Markdown.
-- `DecisionMatrix`: compare options.
-- `OptionGrid`: show alternatives side by side.
+- `ContentItem`: standalone readable content card.
+- `ContentSet`: grouped readable content cards with tone and emphasis.
+- `SortableList`: draggable structured priority list with persisted order.
 - `ExportPanel`: export Markdown or JSON.
 
 Planned components:
 
-- `PriorityBoard`: drag-and-drop priority sorting.
+- `KanbanBoard`: column-based card sorting.
 - `PromptWorkbench`: prompt variables and sample previews.
 - `DiffExplainer`: PR and diff explanation.
 - `ParameterTuner`: parameter tuning UI.
@@ -101,26 +102,29 @@ Second target: Astro docs site
 
 ## Styling Protocol
 
-Artifact Kit provides default CSS, but the default theme is not part of the core artifact contract.
+MDX Artifacts provides default CSS, but the default theme is not part of the core artifact contract.
 
-Users can inject brand styles through `artifact-kit.config.mjs`:
+Users can inject brand styles through `mdx-artifacts.config.mjs`:
 
 ```js
-/** @type {import("mdx-artifacts").ArtifactKitConfig} */
+/** @type {import("mdx-artifacts").MdxArtifactsConfig} */
 const config = {
   docsDir: "artifact-docs",
   outDir: "dist/artifacts",
   includeDefaultStyles: true,
-  styles: ["artifact-theme.css"]
+  styles: ["artifact-theme.css"],
+  tailwindSources: ["artifact-components/**/*.{ts,tsx}"]
 };
 ```
 
 Rules:
 
-- `includeDefaultStyles: true` imports Artifact Kit default styles first.
+- `includeDefaultStyles: true` imports MDX Artifacts default styles first.
 - `styles` are imported in array order after the default styles.
 - Users can override CSS variables or `ak-*` classes.
-- `includeDefaultStyles: false` means the user owns all styling.
+- `includeDefaultStyles: false` disables MDX Artifacts default styles.
+- The current MDX file is always registered as a Tailwind source for local MDX components.
+- `tailwindSources` registers additional project-local component files that use Tailwind classes.
 - The final CSS is still inlined into the standalone HTML artifact.
 
 ## UI Dependencies
@@ -153,8 +157,9 @@ Current workflow:
 
 ```text
 Component development: pnpm storybook
-Protocol verification: pnpm typecheck / pnpm test / pnpm artifact:validate
-Artifact verification: pnpm artifact:build
+Protocol verification: pnpm typecheck / pnpm test / pnpm mdx-artifacts:validate
+Artifact verification: pnpm mdx-artifacts:build
+Release readiness: pnpm release:check / pnpm pack:smoke / npm pack --dry-run
 ```
 
 ## Testing Protocol
@@ -175,7 +180,9 @@ Out of scope for the first baseline:
 - browser E2E
 - visual regression
 - Astro adapter tests
-- package tarball smoke tests
+- package tarball smoke tests as part of the default `pnpm check` baseline
+
+Package readiness is covered separately by `pnpm release:check`, `pnpm pack:smoke`, and manual `npm pack --dry-run` before publishing.
 
 ## Agent Contract
 
@@ -185,31 +192,44 @@ When generating an artifact, agents should:
 2. Prefer existing high-level components.
 3. Provide an export path for interactive artifacts.
 4. Move bulky data into adjacent `.json` files.
-5. Run `artifact-kit components <ComponentName>` when props are unclear.
-6. Run `artifact-kit components --json` for machine-readable metadata.
-7. Run `artifact-kit validate <file.mdx>` before build.
-8. Run `artifact-kit build <file.mdx>` to produce standalone HTML.
+5. Run `mdx-artifacts components <ComponentName>` when props are unclear.
+6. Run `mdx-artifacts components --json` for machine-readable metadata.
+7. Run `mdx-artifacts validate <file.mdx>` before build.
+8. Run `mdx-artifacts build <file.mdx>` to produce standalone HTML.
 
 ## CLI Component Query
 
 To keep skills and agent instructions short, the CLI exposes component metadata:
 
 ```bash
-artifact-kit components
-artifact-kit components ExportPanel
-artifact-kit components --json
-artifact-kit components ExportPanel --json
+mdx-artifacts components
+mdx-artifacts components ExportPanel
+mdx-artifacts components --json
+mdx-artifacts components ExportPanel --json
 ```
 
 The data comes from `componentRegistry`. Future docs, Storybook docs, validation rules, and agent skills should derive from the same source.
 
 Component naming rules:
 
-- Names must be self-describing, such as `DecisionMatrix` and `ExportPanel`.
+- Names must be self-describing, such as `ContentSet` and `ExportPanel`.
 - Avoid generic names such as `Panel` or `CardList`.
 - A component should represent an artifact workflow, not a primitive UI element.
 - Text rendering is intentionally split into `InlineText`, `MarkdownBody`, and future long-form prose components.
 
+## Package Boundary
+
+MDX Artifacts remains a single npm package for now.
+
+The package exposes separate entry points for the current public surfaces:
+
+- `mdx-artifacts` for the CLI
+- `mdx-artifacts/react` for React components
+- `mdx-artifacts/registry` for registry metadata
+- `mdx-artifacts/styles.css` for default styles
+
+Do not split into packages such as `@mdx-artifacts/react`, `@mdx-artifacts/cli`, or `@mdx-artifacts/schema` until there is real maintenance pressure from independent versioning, dependency isolation, or adapter-specific release needs. The current priority is keeping installation, initialization, and agent guidance simple.
+
 ## Public Roadmap and Local Execution Notes
 
 Public project direction lives in:
@@ -219,6 +239,7 @@ Public project direction lives in:
 - `docs/naming.md`
 - `docs/component-protocol.md`
 - `docs/component-taxonomy.md`
+- `docs/cli-structure.md`
 - `docs/testing.md`
 
 Local phase execution notes belong in `docs/local/*.local.md` and are not committed. They can track temporary decisions, verification notes, and agent working state without adding process noise to the public repository.