Promote refrakt.config.json from a site-only file into the unified root config defined in ADR-010. Add type-level support for plugins, plan, site, and sites, normalize the three valid input shapes (flat / singular site / plural sites) into a canonical internal form, and publish a JSON Schema so editors can autocomplete and validate the file.
Replace the lazy runPlugin import-on-demand pattern in packages/cli/src/bin.ts with a first-class discoverPlugins() helper that returns the full set of installed plugins. The helper has four consumers in v0.11.0 — CLI dispatch, refrakt --help, refrakt plugins list, and the new MCP server — and centralizing the logic eliminates three different implementations of the same scan.
Add three optional fields to the CliPluginCommand interface so plugin commands can declare structured input/output schemas and an MCP-friendly handler that bypasses argv parsing. Existing plugins keep working unchanged — the fields are purely additive.
Switch the CLI's plugin dispatch in packages/cli/src/bin.ts from blind import('@refrakt-md/<namespace>/cli-plugin') to a discoverPlugins() lookup. This produces a friendlier "did you mean?" error when a namespace is misspelled (since we know the full set of installed plugins) and centralizes plugin loading on the new helper.
Update all five framework adapter packages — @refrakt-md/sveltekit, @refrakt-md/astro, @refrakt-md/nuxt, @refrakt-md/next, @refrakt-md/eleventy — to accept a site?: string option. Each adapter resolves its target site via the shared normalizer from WORK-159, then reads contentDir, theme, target, packages, routeRules, icons, backgrounds from the resolved site entry instead of the top-level config. Single-site projects and the legacy flat shape continue to work without changes; multi-site repos pick a target per adapter.
Wire the @refrakt-md/plan CLI commands with the new schema fields from WORK-161 so the MCP server exposes them as cleanly typed tools. Each command gets a JSON Schema for its inputs and an mcpHandler that bypasses argv parsing and accepts a structured object directly.
Wire @refrakt-md/plan to the unified refrakt.config.json. plan init scaffolds the config (creating it or extending an existing one with a plan section), and plan serve / plan build / other plan commands read plan.dir from the loaded config instead of relying solely on the --dir flag and defaults. The plan section currently exposes only dir; specs path remains derived from dir (a child folder), and surfacing it as a config field can come later if real-world projects demand it.
Create the @refrakt-md/mcp package: stdio MCP server entry point, auto-detection of plan and site contexts from the unified config and the filesystem, and the initial set of core CLI-mirroring tools (refrakt.inspect, refrakt.contracts, refrakt.validate, refrakt.reference, refrakt.package_validate).
Wire plugin-contributed tools (notably the @refrakt-md/plan commands) into the MCP server via discoverPlugins(), and implement the read-only resources (refrakt://detect, refrakt://reference, refrakt://contracts, refrakt://rune/<name>, refrakt://plan/*) so agents that prefer pull semantics have first-class URIs.
The collection rune core — a sentinel-emitting schema plus a postProcess resolver that queries the registry (filter/sort/group/limit) and renders the built-in layouts, with the pinned $item bound-variable contract and the per-layout body interpretation.
The built-in adapter (in @refrakt-md/content) that turns site.entityRoutes into contributed pages: selects entities by type + filter, substitutes placeholders, renders an inline render string or a render-template partial per entity with $item bound, and back-fills sourceUrl.
Make plan entities embeddable so {% expand $item.id /%} renders their bodies in entityRoutes detail pages. The plan register hook currently sets sourceUrl only; add sourceFile and an extract that returns the entity rune's transformed body. This is the prerequisite the SPEC-071 dogfood depends on.
Wire refrakt's own plan/ as a sites.plan site and author its plan-site/ content, proving that entityRoutes + collection replace the bespoke plan serve. This is the milestone's proof-of-practice.
Give work items an honest way to be retired: cancelled (deliberately not doing it) and superseded (replaced by another item), plus a supersedes attribute. Both are terminal and non-achieving. Builds on the consolidated vocabulary from WORK-492.
Close the "is it built / is it available?" gap on specs, and give ADRs an honest "considered and declined" state. Rides on the consolidated vocabulary from WORK-492.
Surface the installed plugin set in two places: the top-level refrakt --help output (so users discover available namespaces without reading docs) and a dedicated refrakt plugins list command (canonical machine-readable output for tooling, including MCP clients debugging their setup).
Site-scoped commands (inspect, contracts, validate, scaffold-css, package validate) need to know which site they are operating on when the project declares multiple. Add a --site <name> flag that selects an entry from the normalized sites map; for single-site projects the flag is optional and resolves to the lone entry.
Move site/refrakt.config.json to a unified refrakt.config.json at the repo root, declaring plugins, the plan section, and sites.main (or whatever name we settle on) for the existing site. Validates the design against our own project and gives us a multi-site-ready structure for any future additions (separate plan dashboard site, blog, etc.).
create-refrakt currently writes a flat-shape site/refrakt.config.json for site projects and (via plan init) no config at all for plan projects. Update both paths to produce the new unified root-shape config — site projects get a sites.main section, plan projects get a plan section, and any combined scaffolds (future) declare both.
Document the unified refrakt.config.json at site/content/docs/configuration/. Cover the three valid shapes (flat / singular site / plural sites), each section (plugins, plan, site/sites), the multi-site workflow, and the migration story for existing flat-shape configs.
Document the new @refrakt-md/mcp server (registration, tool reference, resource reference) at site/content/docs/mcp/, update the existing plugin authoring docs to cover the new cli-plugin schema fields (inputSchema, outputSchema, mcpHandler), and add a brief pointer in the root CLAUDE.md so AI agents know the MCP server exists when registered.
The rich-table path: a table collection's body uses the sections content model (heading = column separator + label, body = per-cell markdoc template with $item), with collection owning the <table>/<thead> and row alignment.
Add a plan project type to create-refrakt that scaffolds a complete, runnable plan site: config (plugin + entityRoutes), a seed plan/, and a plan-site/ content dir (layout + dashboards), for a chosen adapter target.
SPEC-104 §6 + docs: document the bg guest body, the bare-surface guardrail, the sandbox preset (with the refrakt.config.json example), and the boot-frame layering; ship the music-blog backdrop pattern as a working showcase exercising the layout-cascade + SPEC-006 audio-bridge composition.
The static gallery (the visual-regression harness from WORK-409) transforms pages with merged.config — i.e. coreConfig plus the enabled plugins' configs — but never calls assembleThemeConfig. The site assembles core → plugins → theme so theme-level overrides reach the engine; the gallery does not, so it can only ever render base output.This is a latent gap in the regression net: any override a theme applies via mergeThemeConfig (tints, icon swaps, and — after WORK-425 — per-rune defaultElevation/defaultProminence deltas) is invisible in the gallery. The gallery shows what a plugin ships, not what a theme actually renders.Not a blocker for WORK-425. Under the agreed Option A, base surface defaults live in core + plugin configs, which the gallery already loads, so default data-elevation/data-prominence emission is gallery-verifiable today. This item only matters once a theme overrides those defaults (Lumina currently inherits the base defaults unchanged).
Backfill the pr attribute on legacy done work / fixed bug items from git merge-commit history, so plan status rollups are rich from day one rather than skeletal (only ~2 of 177 items carry a PR today).
Add a lint pass to refrakt package validate that checks a package's cli-plugin export for structural issues — missing namespace, missing descriptions, malformed inputSchema, namespace conflicts with already-installed plugins. Catches problems at package-publish time rather than at runtime when the MCP server tries to advertise the broken tool.
Add a small migration command that rewrites a flat-shape refrakt.config.json into the nested form (site.* and explicit plugins). Optional for users — the flat shape stays valid indefinitely — but useful for projects adopting the unified config or moving to multi-site.
The first core plain-presentational card rune — ordinary attributes, no $item/registry knowledge — shipped as the reference implementation for collection body templates. Proves the "cards are plain runes; the template wires entity fields into attributes" model.
Mark plan build and plan serve deprecated, pointing users at the site approach, once refrakt's own plan site proves the replacement. Keep the authoring CLI. Removing the bespoke render stack is a later release, out of scope here.
Demand-driven follow-up to the WORK-333 seam: ship renderers beyond the built-in svg (e.g. a charting library) and the SSR capability, on the provider model resolved in SPEC-083.Status: draft — demand-driven (not blocked). The provider model is settled (single rf-chart delegating to an app-registered ChartProvider; selection author → site-default → svg; theme orthogonal via tokens). This item only makes sense once there's a concrete need for a second renderer — building one speculatively is the YAGNI trap SPEC-083 warns against.
The deferred "option B" from the WORK-296 achievement-status discussion. Today plan-progress computes its achieved subset with a hardcoded union of terminal statuses (value="status:/^(done|fixed|accepted|complete)$/", decision C). That is correct and minimal, but it bakes domain knowledge into the plan sugar and relies on achieved-status name uniqueness across types — which holds for the five first-party plan types but is not guaranteed for a third-party "trackable" type that introduces its own status lifecycle.This item makes achievement self-declared on each rune's schema so aggregate can derive the achieved set generically, the same open-world way SPEC-084 handles composability (knowledge lives with the party that has it).
Deferred granular follow-on to the bento collapse model (WORK-348). Once grid-level collapse + automatic progressive reduction are in place, the remaining need is per-cell responsive control — letting an individual tile declare its span per breakpoint.
Once cancelled / superseded exist, review the plan corpus for items that should be retired rather than left dangling. The main pool is the 13 pending work items, all sourced from SPEC-008 (unbuilt runes): stat, math, concept, exercise, glossary, objective, prerequisite, quiz, partner, job, album, artist, video. A reviewed, per-item judgment pass — not an automated flip.
Sweep the small set of non-terminal, non-ready work items for entries carrying the wrong status, independent of the new terminals. Human-judgment pass over a bounded list.
Build the core Vite plugin that intercepts .md files and emits JS modules with rendered HTML, frontmatter, SEO data, and serialized tree. This is the Level 1 (static, per-file) integration — no cross-page awareness.
Implement virtual:refrakt/styles module that imports theme tokens, per-rune CSS, and package CSS. Supports tree-shaking to include only CSS for runes actually used in content.
Implement the canonical field:value selector grammar from SPEC-070 as a single shared module in @refrakt-md/runes, consumed by collection, entityRoutes (SPEC-069), and backlog. The existing plugins/plan/src/filter.ts folds into it, gaining glob/regex, url resolution, and case-consistency while preserving backlog behavior.
Implement the deferBody mechanism SPEC-070's prototype validated: a catalog flag plus a pre-transform pass in the content loader that captures a rune's pristine body as a source string and empties it, so postProcess can re-parse and transform it per entity with a bound variable. Capture must happen before the page transform — by schema-transform time Markdoc has already resolved the body's $item interpolations to undefined.
Add the Plugin.contributePages hook and a contribution phase in the content loader (after file-page registration, before aggregation) that collects ContributedPage[] and runs them through the normal pipeline — the underlying primitive both the entityRoutes adapter and third-party plugins build on.
Lumina's CSS references several colour tokens that are never defined, so each paints a stale literal fallback (a sky-blue from an old default theme, or a cool Tailwind gray) that doesn't track light/dark. This is the real cause of the "out of place" blue (e.g. the typography specimen background) and the cold-gray muted text in dark mode. Fix the drift at the source, reconcile the vocabulary, and keep the configurable shapes (presets, generator, docs) in correspondence.
refrakt edit cannot launch in a multi-site project: EditOptions is just port/contentDir/devServer/noOpen, and resolveSite() throws when multiple sites are declared, telling the user to pass --content-dir — which bypasses config resolution entirely, losing plugins, tints, icons, and route rules. Refrakt's own repo (sites main + plan) hits this. Add a --site flag and an in-editor site switcher so the editor works first-class against multi-site configs.
In block mode, registry-resolved runes — collection, relationships, aggregate, xref, expand, and data-bound sandbox — render as unresolved sentinel shells with no explanation. They resolve in core postProcess against coreData.registry, which the client-side block renderer never runs; RUNTIME_ONLY_TYPES in block-renderer.ts only placeholders nav*. The server already holds the registry and resolvers (the full-page iframe preview uses them), so render these blocks server-side; where that's not possible, show an honest placeholder instead of an empty shell.
The MCP server and renderer config hard-coded their own copies of the status/severity vocabulary and have drifted from the canonical enums.ts — a regression of the drift SPEC-037 / WORK-127 fixed once. This is the quick, standalone fix that ships value before the larger consolidation work.
Make enums.ts the one place that defines status/severity/complexity/priority vocabularies, with derived lifecycle helpers, so consumers stop re-declaring the lists and drift becomes a build failure instead of a latent bug. This lands before the downstream status additions so they inherit the consolidated shape.
Implement the level: 'pipeline' mode that runs the full four-phase cross-page pipeline at build time, enabling breadcrumbs, nav, glossary auto-linking, and other entity-dependent features.
With WORK-110 through WORK-114 complete, convert the 5 postTransform uses identified in SPEC-033 to their declarative equivalents. Validate identical HTML output before and after each migration.
Register a small set of author-facing markdoc functions — currency, date, number, join — in @refrakt-md/runes as the shared value-formatting layer, usable anywhere markdoc transforms run: collection cells, body templates, and entityRoutes render strings. Keeps formatting out of fields and out of any bespoke projection DSL.
Generalize SPEC-066's sourceFile + extract into the embed() contract: an entity is embeddable if it has embed() or (sourceFile + extract). expand and the entityRoutes adapter accept either, so external plugins can make entities embeddable without a source file on disk.
Make dark-mode token coverage deliberate. Most "dark looks off" reports trace to the phantom tokens fixed in WORK-340 (a phantom can't have a dark value); this item closes the genuine remaining gaps and records the intentional shared-token decisions.
Capstone + real-world validation. Replace the current split-feature composability section on the site index (a juxtapose of two sandboxes) with a richer bento grid where each cell is a different live rune composition — the section demonstrates composability by being a composition. It doubles as the hero example atop the new Compositions docs category (WORK-346) and as the dogfood proof that the bento substrate works end to end.Now that the v0.20.0 surface model has shipped, the showcase can flex the new surface vocabulary too — so the grid demonstrates both composition axes (a guest in a media zone, and the surface treatment around it).
Accessibility polish across the theme. Today only ~5 of ~90 rune CSS files define :focus-visible, and only 2 honor prefers-reduced-motion — so keyboard focus is inconsistent and animations don't degrade for motion-sensitive users.
Implements SPEC-095: an explicit group-order attribute so authors can sequence groups over a non-enum field (e.g. category, plugin, edge kind), which today render in arbitrary insertion order.
editHints drive click-to-edit in the block editor; every rune without them is one where clicking a section silently does nothing. Coverage today is 93/130 runes (71.5%): business, design, docs, places, and storytelling are at 100%, but core is at 58% (35/60), plan at 45% (5/11), media at 60% (3/5), learning at 67% (2/3), and marketing at 80% (12/15). Close the gaps using the established SPEC-009 playbook (visible elements as refs/data-name, hints declared in the rune's config).
The engine grew a rich soft-lint system (posture demotion, escape-hatch lints, nesting validation, entity-id collisions) but the editor actively swallows it: runPreviewPostProcess in packages/editor/src/preview.ts collects PipelineWarnings into an array and drops it, and hook errors hit a bare catch {} ("degrade silently"). Authors only discover problems at build time. Pipe warnings through to the UI as a validation rail.This is the warning channel that SPEC-098's inline lints build on.
Execute ADR-019: move bento + bento-cell from @refrakt-md/marketing to core (@refrakt-md/runes + @refrakt-md/lumina) as Layout primitives, with a back-compat re-export shim from marketing. Not a blocker for WORK-350; target a future minor.
Deferred from WORK-409 (its final acceptance criterion). The harness runs end-to-end locally and in the pinned Playwright container; what's left is the CI automation, which needs a browser-backed runner to develop against — hence its own item, unassigned to a milestone until a browser CI environment is in place.
Implement SPEC-114: give plan work/bug dependencies a direction so the validator's cycle detection stops firing on prose cross-references. Today checkCircularDeps builds its graph from every {% ref %} in an entity (e.refs) with no direction, producing 88 false-positive circular-dependency errors across ~35 mostly-done items.
Export a thin initBehaviors() wrapper from @refrakt-md/vite/behaviors that frameworks can call after navigation to re-initialize interactive rune behaviors (accordion, tabs, datatable, etc.).
Internal-only cleanup that lands the rest of WORK-323 once WORK-331 has stopped emitting the dual-emit metas. Remove the now-dead legacy read/strip path so data-rune-fields is the engine's only field-data input. No external/contract benefit beyond Tier 1 — this is for a single internal representation and a smaller engine.
Build the Astro framework adapter — the first non-SvelteKit target. Astro is MPA-first and SSG-focused, making it the simplest adapter to build and validate.
The @refrakt-md/html scaffold (create-refrakt template-html) emits static HTML with no client JS — build.ts never bundles or references initPage() from @refrakt-md/html/client. So no interactive behavior runs in a scaffolded html site: tabs, accordion, search, and (since SPEC-073) the theme-toggle button are all inert. The adapter ships the client runtime (@refrakt-md/html/client + @refrakt-md/behaviors); the scaffold just never bundles and includes it.Discovered while finishing WORK-292: the html adapter now injects the no-flash pre-paint script (which works without JS), but the toggle can't cycle until the behaviors bundle loads. This is broader than the toggle — it's the html scaffold's general interactivity gap.
The composability investigation surfaced ~25 meaningful rune combinations — far more than fit in the authoring guide. Create a dedicated "Compositions" docs category, page-per-pattern: each page shows the Markdown you write, the rendered result (via preview), and a one-liner on which zone/mechanism makes it work. Start with Family A (a visual rune in a container's media zone), the set being made first-class this milestone.
The v0.20.0 surface model shipped with per-rune reference docs (card cover, recipe cover, bg, surfaces.md) but no single page that shows the vocabulary as a system. Build a dedicated showcase gallery that demonstrates the whole surface model on one page — the "wow" surface a visitor lands on to grasp what the model can do — organised by the model's own axes.
The follow-up WORK-489 explicitly deferred: convert the shared split.css beside→stack collapse from @media (global viewport) to @container (the rune's available width), and make the preview viewport frame a query container so the collapse is faithfully simulable in the responsive preview selector. Motivated by the feature doc page — its media-beside examples (media-position="start"/"end") couldn't carry a viewport selector because their collapse is @media-gated and the preview frame is width-only.
The tier-1 spine of SPEC-103: a preprocess-time data rune that reads a sandboxed external file and emits a Markdoc table AST node, the CSV/TSV adapter, and the shared projection + typing core (incl. data-value emission) and table emitter that every adapter reuses. JSON/NDJSON adapters (WORK-486), the datatable sort change (WORK-487), SQLite, and remote sources are out of scope. Proves the headline claim — chart and datatable consume the emitted <table> with no structural edits.
The foundation of SPEC-113: one synchronous ProjectFiles interface in @refrakt-md/types, with filesystem and in-memory providers, that replaces the four ad-hoc fs seams. Containment becomes an interface contract, so no consumer re-implements path-safety. Also lands the recordable-read wrapper that ADR-025 names as the one piece of groundwork for future incremental rebuild.
Move the sandbox example read seam (__sandboxReadFile family + preprocess sandbox hooks) onto the WORK-481 ProjectFiles provider, and route the sandbox src directory join through it so it inherits containment — closing the unguarded examplesDir + '/' + src path-traversal gap.
Close the main gap in SPEC-113: read-file.ts (and the snippet/expand/file-ref pipelines) call node:fs directly today, bypassing the injectable seam — so tree mode is not actually fs-free for snippets. Delegate the I/O to the WORK-481 provider, keeping line-slicing and diagnostics intact.
Finish the consumer migration and the virtual entry point: scan fileRoots and the plan plugin's configure scan through the provider, expose projectFiles + gitTimestamps on loadContentFromTree, and prove a full site builds from a pure in-memory map.
The JSON-family adapters for SPEC-103, on top of the WORK-417 adapter contract + projection core. JSON is not inherently tabular, so its adapter owns the three knobs CSV doesn't; NDJSON is line-delimited records. Both reduce to the shared { headers, rows } shape and are indistinguishable downstream.
Make the block editor surface the dropcap toggle by deriving it from the resolved reading register rather than a per-rune list. Per SPEC-108 §3 (editor consequence) + Work breakdown 4.
Document the ProjectFiles contract and the fetch-then-build materialization pattern for remote hosts, so plugin and adapter authors know the seam and how a hosted renderer feeds it.
The one host-side change SPEC-103 takes for typing: extend the datatable sort comparator to prefer a cell's data-value over its textContent, mirroring what chart already does (cell.dataset.value ?? textContent). This is what lets data's numeric typing produce correct sorts of human-formatted numbers (currency, thousands separators, units) — and it equally fixes hand-authored tables, so it is a general improvement, not a data-specific hack.
The author-facing documentation for SPEC-103: the data rune with CSV + JSON examples, the chart/datatable composition story, and the build-time-vs-runtime distinction so authors reach for the right layer.
The shared data-collapse responsive contract (WORK-469, WORK-473) is @media-based: beside→stack collapse (split.css), grid→1-column reflow (feature.css), and collapse-to-carousel (carousel.css) all key off the global viewport. Two consequences: