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.
The milestone's exit gate. The skeleton/skin extraction's goal is "theme #2 is a token file + layout + skin, not a fork" — but theme #2 is deferred (SPEC-094), so the extraction would otherwise ship with no consumer to prove it worked. The harness inert-proof only shows Lumina didn't regress; it does not show the skeleton is actually skin-agnostic. A thin proof skin closes that gap.
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.
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).
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.
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 tier-1 foundation of SPEC-103: a preprocess-time data rune that reads a sandboxed external file and emits a Markdoc table AST node, plus the CSV/TSV/JSON/NDJSON adapters and the shared projection/typing core. SQLite and any remote source are explicitly out of scope (later work items). Proves the headline claim — chart and datatable consume the emitted <table> with no edits.
The gate for SPEC-104: teach bg to host a live sandbox as a bare, presentational, full-bleed backdrop. Covers §1–§4 — the constrained body, the engine relocation that mirrors bg-video, the bare-surface guardrail, and boot-frame layering. Everything downstream (the preset, the showcase) builds on the data-bg-guest contract this establishes.
SPEC-104 §5: make a reusable sandbox backdrop applicable by name (bg="midnight-waves") like any other preset, by adding a sandbox descriptor to BgPresetDefinition — resolved at transform time (not the identity engine, which has no file access), expanding into the WORK-428 data-bg-guest body.
The gate for SPEC-105 (§1–§3): a shared, closed reveal modifier plus an orthogonal stagger modifier on section-level runes, emitting the generic data-* hooks and the per-child index the motion CSS and behaviour read. Pure intent → attributes; no look here.
SPEC-105 §4: a single dimensions/motion.css + motion tokens that render each reveal character — covering all section runes from one stylesheet, with the transform-composition and global-hook rules that keep it from becoming per-rune work.
SPEC-105 §5–§6: the timing trigger and the no-JS/SSR safety. A tiny IntersectionObserver behaviour flips data-in-view; enhancement gating guarantees the static page is always complete. JS = when, CSS = how.
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.
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.
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.
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 wholesale pass the WORK-410 spike sized: re-bucket Lumina's CSS into the two @layers per the spike's cut-line rule, so structure ships in @refrakt-md/skeleton and aesthetics stay in Lumina's skin. Mechanical and low-risk per declaration, but large (~114 files / ~6,058 declarations; the spike estimates ≈40% skeleton / 55% skin / 5% content).
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.
Add the variants field to RuneConfig — modifier-keyed config deltas — and validate at config load that every variant axis is a declared modifier. This is the foundational type + validation layer for engine config variants.
Infrastructure for SPEC-080. Adds blocks and layout to RuneConfig and the engine projection that composes a rune's transform tree with projected metadata blocks, placed explicitly into named containers. Built behind the new fields so the SPEC-079 path (zones / zoneLayouts / contentSlots / order / zoneHost / zoneHostPlacement) and the legacy slots / structure shim keep working untouched during the migration.
The rendering primitives SPEC-080 depends on: a single bar horizontal layout (merging split + chip-row), field shape decided intrinsically from metaType, a new code metaType, and the rename of the unreleased eyebrow rune to bar.
Re-migrate the plan family (work, spec, bug, decision, milestone) from the SPEC-079 metaFields + zones model (WORK-306, done) to the SPEC-080 blocks/layout model. The metaFields manifest is reused as-is; the zones / contentSlots / order / dispatcher reliance is replaced by transforms that build named-block trees plus blocks / layout config. This is the bulk of the SPEC-080 migration — the plan family leans hardest on the engine dispatcher.
Re-migrate recipe + howto from the SPEC-079 zones model (WORK-308 plus this branch's recipe/howto work) to the SPEC-080 blocks/layout model. These runes already build content + media trees and nest the metadata def-list via zoneHost / zoneHostPlacement, so they map almost directly.
Migrate the docs meta-bearing runes (Api, Symbol; Changelog untouched) straight to the SPEC-080 blocks/layout model. api is the deliberate proof point: method/auth render as chips and path renders as a bare <code> — all from metaType, in one flat bar — with no layout-specific or slot-specific logic.Supersedes WORK-309, which migrated docs to SPEC-079 zones (path as metaType: 'id' mono, method/path as split left/right). Skip the now-obsolete zones step and go directly to blocks/layout. api is still on the legacy structure path today, so this is its first real migration.
Step 1 of SPEC-082. Introduce the typed field-data channel: rune schemas write their field values to a single reserved attribute, data-rune-fields, holding a JSON-encoded object — produced by createComponentRenderable (properties populate it). Keep emitting the legacy <meta data-field> children in parallel (dual-emit) so behavior is unchanged. No engine changes in this step.
Step 2 of SPEC-082. The engine resolves modifierValues / metaFields from the parsed data-rune-fields first, falling back to the legacy <meta data-field> children when a key is absent. Parse the reserved attribute once per node. With both channels carrying the same data (after WORK-321), output is unchanged.
The engine primitive for SPEC-081. Generalize composeContainer into a recursive resolver over a name-keyed layout, so the config can create the structural skeleton (preamble / content / media wrappers) rather than only ordering containers the transform pre-built.
WORK-322 migrated the engine to read data-rune-fields, but the field metas have other readers that run on the pre-engine tree and still read field values from <meta data-field>. They must move to the bag before the metas can be dropped (WORK-323) — otherwise entity registration and SEO break.
Resolves SPEC-082 problem #4 (SEO double-booking) — the blocker for WORK-323. Some property metas are conflated: they carry both data-field (data, now in the bag via WORK-321 / WORK-322 / WORK-328) and property= from the schema map (e.g. recipe's prepTime / cookTime / servings). Split the two so the data channel (bag) and the schema.org channel (property= metas) are independent — only then can WORK-323 drop the data metas and remove the kebab set + meta-strip filter.
Resolve each variant axis per instance and merge matching deltas over the base config before layout assembly, reusing the existing mergeThemeConfig machinery.
Migrate card/bento-cell to the SPEC-081 flat-slot + base-layout model (prerequisite for the cover variant), migrate feature's grid/stack conditional out of its transform into a media-position variant, and document the variants primitive.
Add RuneConfig.frameTarget routing, the host-owned clip contract, the oversize opt-out, a shared frame CSS layer, and reconcile with bento's existing media vars.
Add the tint-tracking inset surface: a --rf-surface-inset-shift mix-amount token and a use-site color-mix recipe applied to media wells and chart/diagram.
SPEC-092 Layer 1 — the small first strike that proves the registry-authoring loop. Core registers every page as a page entity but copies only a fixed frontmatter subset (config.ts register hook). Merge the rest of the page's frontmatter onto the page entity's data so any field is queryable by the field-match grammar (which already normalises arrays).
SPEC-093 core — the build-time data channel from the registry into a sandbox. The registry's third render target (HTML via collection, SVG via aggregate, arbitrary client-side here). Independent of the SPEC-092 track: flat/tree shapes work over the page/pageTree data that exists today.
Extend the SPEC-048 TokenContract with a real typographic system. Today the contract carries only font.sans / font.mono — no scale, leading, weight, or tracking — so typographic identity (the primary differentiator for editorial/magazine themes) is not themeable. This is the gate for the SPEC-094 Tier 1 foundations.
Replace Lumina's hardcoded typography with the WORK-404 tokens. Today there are ~351 hardcoded font-size declarations against 5 tokenized — so an editorial theme wanting a different scale must override hundreds of declarations across 90 files. Tokenizing here is also what shrinks the WORK-410 skeleton/skin spike's classification surface.
A CLI command that emits a deterministic static rune gallery: every rune across its variant matrix, on one page, rendered through the HTML adapter. This is the AI-iteration surface and the deterministic subject the harness (WORK-409) photographs.
A shared Playwright harness that photographs the generated gallery + layout fixtures and diffs them against a baseline. This closes the AI iteration loop and — critically — gives the v0.23.0 skeleton/skin extraction its "diff must be empty" proof. No screenshot testing exists in the repo today; this is greenfield.Baselines are ephemeral, not committed. Fixtures and theme CSS churn constantly, so committed golden PNGs would mean endless binary diffs and a re-baseline commit on nearly every PR — noise that trains everyone to ignore the check, plus repo bloat. Instead the baseline is whatever you compare against in the moment (__screenshots__/ is gitignored): capture-then- compare locally, or compare-against-base in CI.
The gating spike for the v0.23.0 wholesale extraction. The skeleton/skin cut is a per-declaration design call (structure and aesthetics are braided inside single rules), so settle it empirically on a small slice before committing to the public contract every future theme depends on.
The foundation of SPEC-102: pin down the fixture format and unify the four fragmented stores into one source the CLI, gallery, editor, and reference all read. The WORK-407 gallery exposed the cost of the status quo — getFixture reads only cli/lib/fixtures.ts (13 runes), ignores RUNE_EXAMPLES (24), and 25 runes fall back to a naive stub that renders wrong (<p> inside an inline badge span).
With the format + loader in place (WORK-411), author a good fixture for every rune so the gallery, editor, and inspect render the whole catalogue correctly. The WORK-407 gallery surfaced ~25 runes with no real fixture (rendering the broken stub) and several child runes shown standalone.
Turn elevation into the universal chrome/depth axis from SPEC-107: an ordered semantic ladder emitted as data-elevation, superseding both §8's surface enum and today's shadow-only none/sm/md/lg scale. The foundation the rest of the milestone builds on.
Add the header-emphasis axis from SPEC-107: prominence scales a rune's page-section header (eyebrow / title / blurb / rhythm), selecting its typographic register. Unlike elevation it is not universal — it is available only to runes that carry the page-section header model.
The prerequisite the WORK-410 spike surfaced: a clean skeleton/skin split needs spacing to be tokenized, exactly as the type split needed WORK-404/WORK-405. Skeleton references spacing tokens by name; skin owns their values — but today Lumina hardcodes magnitudes (0.5rem, 0.375rem, 0.8125em, …), so the skin layer can't retune them without restating structure. The gate for the re-bucketing.
Stand up the packaging + cascade-layer infrastructure the WORK-410 spike settled, so skeleton and skin can ship and version separately. The structural home the re-bucketing fills.
With the generic aggregate rune in place (WORK-294), plan-progress becomes thin sugar over aggregate — same pattern as backlog / decision-log / plan-activity wrapping collection. plan-progress's current rendering (the progress bar + per-status badge row) is exactly the aggregate composition; we just need plan-specific defaults baked in so the call site stays {% plan-progress /%}.
Implements Phase 1 of SPEC-079 on the engine + theme side, without yet migrating the plan plugin (that lands in WORK-306). Three layout primitives, two composable runes, the universal chip primitive, the legacy slots + structure shim, and config-load validation.
Phase 1 proof case for SPEC-079. Migrates the plan plugin's entity runes (work, bug, spec, decision, milestone) from the legacy slots + structure config shape to the new metaFields + zones + sections model. Lands together with WORK-305 so v0.18 ships the spec end-to-end.
Phase 2 of SPEC-079. Migrates the storytelling plugin's meta-bearing runes (Character, Realm, Lore, Faction, Plot) from the legacy slots + structure config shape to the new metaFields + zones + contentSlots model. No visual change — Phase 1 already moved the chip look universally via Lumina's dimensions/metadata.css rewrite + the universal .rf-badge class. Phase 2 is purely config-shape cleanup.
Phase 2 of SPEC-079. Migrates the learning plugin's meta-bearing runes (HowTo, Recipe) from the legacy slots + structure config shape to the new metaFields + zones + contentSlots model.
Phase 2 of SPEC-079. Migrates the docs plugin's meta-bearing runes (Api, Symbol) from the legacy slots + structure config shape to the new metaFields + zones + contentSlots model.
Phase 2 of SPEC-079. Migrates the places plugin's meta-bearing rune (Event) from the legacy slots + structure config shape to the new metaFields + zones + contentSlots model.
Phase 2 of SPEC-079. Migrates the media plugin's meta-bearing runes (Track, Audio) from the legacy slots + structure config shape to the new metaFields + zones + contentSlots model.
Once api proves the model (WORK-318), migrate the remaining meta-bearing runes to SPEC-080 blocks/layout: storytelling (re-migrate faction / realm / character + lore / plot / others), marketing, business, places, media, design, and core runes (e.g. budget).Supersedes WORK-310 (places), WORK-311 (media), and WORK-312 (core budget) — those targeted SPEC-079 zones; migrate straight to blocks/layout instead. May be split into per-package sub-items during execution.
Once every rune is on blocks/layout (WORK-319), remove the superseded SPEC-079 placement surface from RuneConfig + engine and finalize the contract. Coordinate with WORK-313 (remove the legacy slots / structure shim) so only blocks/layout plus the projection / postTransform escape hatches remain.
Step 3 of SPEC-082 — the payoff. Stop emitting <meta data-field>; the engine reads only data-rune-fields (parse once, strip the reserved key before output). Delete the legacy meta-read path, the meta-strip filter, the kebab-matching set, and the unconsumed-meta leak filter. Genuine schema.org / SEO <meta property> tags are untouched.
Migrate the runes that hand-build structural skeletons in TypeScript to emit a flat bag of data-name slots (content interpretation only) and declare their preamble / content / media grouping via the recursive layout from WORK-324. Output stays identical; the grouping moves from imperative code to config.
Apply the SPEC-081 computation boundary: semantic derivation belongs in the rune transform, not the presentation postTransform. Budget's grand / per-category / per-day totals are the worked example — a theme-invariant fact about the content currently stranded in the engine's escape hatch.
Re-open the high-value slice of WORK-323 (descoped as a whole): stop emitting the dual-emit modifier/field <meta data-field> tags so the data-rune-fields bag is the only representation of field data in the rune tree. The risk being closed is that theme developers treat data-field metas as part of the output contract; this removes them from the pre-engine tree (they are already stripped from rendered output) without touching the engine input contract.
Land the SPEC-083 seam. Move chart onto the two-layer boundary: the data becomes a real <table> in the transform, and the rendering moves into an rf-chart web component that draws svg, full stop. No provider attribute, no registry, no selection — that abstraction is WORK-334, gated on a real second renderer. Chart stays in core; no new package.
Apply the SPEC-081 computation boundary to the five runes whose engine postTransform hand-builds deterministic, theme-invariant structure from self-emitted data — the same misplacement WORK-326 fixed for budget. (Chart is excluded — its rendering is a genuine variation point and gets its own design in SPEC-083.)
Review every declared contextModifiers entry across core and plugins, decide whether the pairing is meaningful, and either style it or remove it. The lone KNOWN_MISSING_SELECTORS context entry — Hero's feature → in-feature — is the first casualty: it has no sensible rendering, so the modifier comes out rather than getting CSS.
Turn RuneConfig.parent into a validated, self-declared requiresParent constraint (SPEC-084). A child rune that declares it must live inside a given parent, but appears outside it, surfaces a diagnostic instead of rendering silently-broken output. Crucially this is open-world: only a rune that self-declares a requirement is ever checked — the framework keeps no registry of allowed children, so third-party runes on either side just work.
The authoring-facing half of SPEC-084: a contract guide for rune authors plus a CLI audit. (The end-user catalog of concrete compositions lives separately in the "Compositions" docs category, WORK-346 — this item is the "how the contract works" reference, not the recipe book.)
Per SPEC-084's open-world styling rule, a container adapts its slot, not the specific guest. Containers that already expose a media zone (card, feature, hero, recipe) should size/clip any visual rune dropped into that zone — map today, chart/gallery/diagram/embed/sandbox next — via one name-agnostic selector, rather than per-pair styling. map-in-card is the proof case.
The plan sugars backlog, decision-log, and plan-activity lower to collection with bespoke card/table bodies that predate the bar rune. Rebuild their default bodies to compose from bar and give backlog a layout passthrough — while keeping the rollup faithful when the query mixes entity types.
Make {% bento-cell %} a first-class authoring path for full per-tile control (the dashboard use case), alongside the heading sugar. Today the bento-cell tag is registered but convertHeadings would swallow a hand-authored cell into the preceding heading's content, so explicit authoring doesn't actually work.
Land SPEC-085's sizing model and the placement/link affordances. One grid, one vocabulary: a 6-column default, proportional size presets, and precise cols/rows.
Close the one gap between "we have the data" and "we can chart it." Plan entities are already registered in the main site's registry, so {% aggregate type="work" group="status" %} returns real counts today — but aggregate can only render an inline integer or a body-zoned template, not a chart. Add a layout="chart" mode that renders the grouped counts as an SVG, reusing the rf-chart renderer from WORK-333. This is the SPEC-076 "chart layout" future extension, and the clean "data rune feeds viz rune" composition.
Today the rf-chart web component hardcodes its palette (a JS array of semantic token refs) and all geometry (bar width bw*0.75, point r:4, stroke/ font/ gridline sizes). A theme has no say over bar thickness, series colours, etc. Define a provider-agnostic theming contract — a --rf-chart-* custom-property surface — and make the built-in SVG renderer the reference implementation of it.
Implement the author-defined levels ladder for bento's heading-sugar path, per ADR-013. One attribute replaces the need for the removed sizing/span mode: a user who wants the old uniform-width grid writes levels="6,5,4,3,2,1".Queued deliberately — the design is settled in ADR-013; left to marinate before implementation.
The deferred half of WORK-296. plan-progress now lowers to an aggregate composition whose per-status badges render neutral — the badge rune keys colour off data-meta-sentiment, and aggregate does not project a per-group sentiment onto $item, so the body has nothing to feed it. This is SPEC-076's listed future extension — "per-group sentiment projected onto $item, derived from the rune's domain ordering when the group field has a sentiment-mapped enum." The status→sentiment maps already exist in the plan config (plugins/plan/src/config.ts metaFields.status.sentimentMap per type: work done→positive, bug fixed→positive, blocked→negative, …) but are invisible to the generic resolver.
Re-express showcase as frameTarget: 'self' consuming frame, with deprecated aliases for its old attributes (breakout bleed retained), and document the surface model.
Split the conflated overlay string into a structured flat-wash overlay and a structured scrim legibility facet, with a deprecation path for the raw-string passthrough.
sandbox is eager today: the iframe is created and its dependencies load on page render (it has a height knob but no deferral). That's fine for a small demo, but a heavy sandbox — a three.js scene (WORK-382), a large framework demo — on a perf-sensitive page like the site index costs a chunk of load time we deliberately avoided (WORK-350 and WORK-380 both limited live iframes "to keep the landing page fast").Add a deferred-activation capability so a heavy sandbox can headline a page without the load-time hit — useful for any heavy sandbox, not just three.js.
The compositions catalogue (WORK-346) shows visual guests in a media zone — images, charts, maps, diagrams. The ultimate flex is a running program: a sandbox runs arbitrary JS in an isolated iframe, so a live three.js scene drops into a card/bento media zone like any other guest. It makes the "the media zone holds anything" claim undeniable.sandbox already supports this with no new primitives: inline <script type="module"> importing three from a pinned CDN ESM URL, plus the existing height knob. The JS runs only in the browser, so the static build stays green.
SPEC-092 Layers 2 + 3 — let a page declare a registry type so collection/ aggregate can query it by domain (collection type="rune"), not just type:page.
The generated rune catalogue (WORK-386) needs every /runes/<name> page to carry category, plugin, and status frontmatter. Hand-editing ~100+ pages is a slog and drifts — so backfill it with a script.
The SPEC-092 showcase: the docs site's own rune catalogue, generated from the registry — the page about the runes built from the runes. The dogfood payoff of frontmatter-declared entities, and open-world (a third-party plugin's documented runes join with no change to refrakt).
The launch showcase for the data-bound sandbox — and the simplest, since the data already exists: the core pageTree. A data-shape="tree" sandbox renders the site as a navigable 3D map (three.js tree/force layout); nodes link to their URLs.
The second data-bound showcase — and a dogfood: the plan's own relationship graph. SPEC-072 edges are already live and populated (the plan plugin calls relate() for spec↔work↔decision↔milestone), so this needs no SPEC-092 work.
A generic, content-agnostic section rune: the shared page-section header (eyebrow → headline → blurb → image) followed by an arbitrary body. It exists so a preamble-less grid primitive like bento can be introduced with a title and intro — the role the feature "runes that work together" block plays on the site index today. Unblocks WORK-350 (the bento capstone), which replaces that feature section with a section + bento.
Long-standing leak in the density dimension, surfaced by the SPEC-101 hero-cover docs: sections.css scaled titles with a descendant selector ([data-density="compact"] [data-section="title"] { font-size: 1.25rem }), which punches through nested densities — a full-density hero inside a compact preview renders its headline at 1.25rem, wildly unrepresentative of the real rune. The existing "nested density scoping" resets in density.css covered descriptions and meta ranks but never the title, and a value-based reset can't work for titles (each rune sets its own size).
Make tokens.ts the single source for Lumina's token CSS. Today tokens/base.css and tokens/dark.css are hand-authored mirrors of luminaTokens, kept in lockstep by token-config-coverage.test.ts — the file header even notes "a future build script that regenerates this file." Wire generateThemeStylesheet into the build so the mirror and its coverage test retire and drift becomes impossible.
Extend the gallery generator (WORK-407) to a second subject class: layout fixtures — representative sample pages rendered through each LayoutConfig so page chrome (header, nav, sidebar, TOC, mobile panel, footer) is visually covered. Chrome carries as much of a theme's identity as runes, and the skeleton/skin extraction touches styles/layouts/*, so this is what lets the harness guarantee hold for chrome, not just content blocks.
ai/src/modes/write.ts hardcodes an "Example structure" in its prompt. Replace it with the unified fixtures — drawing each rune's rich/canonical fixture (with its notes) as in-context few-shot exemplars. No training pipeline; retrieval into the prompt only.
Guard the corpus: parse the frontmatter fields (the format established in WORK-411 strips the block; this work consumes it), validate them against the schema, support <rune>.<scenario>.md scenarios, and ensure every fixture parses + transforms. plugin-validate reports role coverage instead of only warning "no fixture".
The WORK-407 gallery renders the static pre-enhancement HTML, so custom-element / lifecycle runes render empty: diagram → <rf-diagram>, chart → <rf-chart>, nav → <rf-nav>, sandbox → <rf-sandbox>, map → ~nothing. Progressive-enhancement runes (accordion, details, tabs, …) render their no-JS fallback (all-expanded) rather than their real state. Including the behaviors client makes the lifecycle runes draw and the PE runes show their enhanced (representative) state.
The foundation for SPEC-106: recognise custom URL schemes in a Markdown image's src during the transform and resolve them to a renderable, before the generic <img> fallback. Custom schemes (placeholder:, icon:) already survive markdown-it's validateLink, so  arrives as an image node with src intact.
The inline icon shorthand discussed when the icon rune landed:  resolves to the named icon's inline SVG — the same source the {% icon %} rune uses.
 resolves to a generated, theme-tinted inline SVG placeholder sized to the named shape — deterministic, offline, screenshot-stable.
With the placeholder: resolver in place, swap the SPEC-102 fixtures' base64-PNG image blobs for clean  references, and confirm the image-consuming runes render the resolved SVG.
Close the loop on the use case that motivated SPEC-107: the same content rune reading as a contained card and as a full-width hero, by composing the axes — no rune fork.
The "content, not CSS" finding from the WORK-410 spike (SPEC-094 §8's icon-from-config): rune CSS embeds glyph shapes as data:image/svg+xml mask-images. Move them to the theme icon registry so a theme swaps glyph sets without touching CSS.
Phase 2 of SPEC-079. Migrates the core {% budget %} rune (the only core rune using meta-projection — currency, duration meta fields) from the legacy slots + structure config shape to the new metaFields + zones + contentSlots model.
Phase 3 of SPEC-079. Removes the backwards-compat path in packages/transform/src/engine.ts that lets legacy slots: [...] + structure: {...} configs continue to render. Lands once all first-party plugins have migrated (WORK-306 through WORK-312 done) and the deprecation warning has been visible across at least one minor release.
Finish SPEC-081: teach the contract generator about declaratively-grouped skeletons, and retire the projection operations now subsumed by recursive layout.
packages/content/test/plan-site-dogfood-real.test.ts ("builds a browsable plan site from refrakt's real plan/ via entityRoutes + collection") flakes under full-suite parallel load — it failed on most npm test runs across the SPEC-082 work, yet passes reliably in isolation (~5–6s). It is a heavy, real-file pipeline build (reads the whole plan/ tree, runs the full content pipeline), so under vitest's parallel worker pool it appears to hit a timeout or a shared-resource race rather than a genuine assertion failure.This is pre-existing and unrelated to any one change — it just became visible because every SPEC-082 step ran the full suite.
When collection groups results, the per-item template can't see which group it belongs to or that group's size — so authors drop to aggregate for anything group-aware. Expose the group key (and count) on $item so grouped collections can render group context inline.
Promote BgPresetDefinition.style to a documented, intentional last-resort escape hatch and confirm the project-config backgrounds home with merge-over-theme semantics.
Frontmatter-driven catalogues can drift from code — add a defineRune without a doc page and it silently vanishes from the generated catalogue. Turn that into a build signal. Fast-follow to the catalogue work.
Document the fixture format, frontmatter fields, the role (coverage-vs-exemplar) split, and the <rune>.<scenario>.md convention under the plugin/theme authoring section.