WORK-680
ID:WORK-680Status:done

A staging site renders the docs with staged runes in place of plugin runes

A second site, staging, renders site/content with the project runes in site/staged-runes/ preferred over the plugin runes they replace (SPEC-181 D1). It uses only existing configuration: runes.dir and runes.prefer (__project__).

Priority:highComplexity:simpleMilestone:v0.44.0Source:SPEC-181
main View source

Criteria completion

Criteria completion: 6 of 6 (100%) checked; tracking started on Oct 29, no incremental history yet0%25%50%75%100%Oct 29Nov 4

Tracking started Oct 29 — check back for trends.

Relationships

Implements 1
Related 3
Branches 3
main current done
claude/milestone-v0-44-0-ism7ni donemain doneclaude/rune-compositions-staging-f9ouim ready

Acceptance Criteria

  • refrakt.config.json declares a staging site with main's contentDir, theme, tints, plugins, route rules and icons, plus runes.dir: "site/staged-runes"
  • A test fails when staging differs from main in any field other than runes (SPEC-181 D3)
  • site/vite.config.ts reads the site from REFRAKT_SITE, defaulting to main; npm run dev:staging serves the staging site on its own port and npm run build:staging builds it into its own output directory
  • A test with a staged rune that shadows a plugin rune shows that the staged schema, generated config and aliases replace the plugin's, and that the plugin's hand-written theme entry for it is not applied
  • main's build output, contracts --check and seo:baseline:check are unchanged with runes staged
  • Every other site-scoped command that defaults to a single site (refrakt validate, inspect, contracts) still resolves main here, or is pointed at it explicitly where it would now be ambiguous

Approach

  • resolveSite errors when several sites are declared and none is requested. Check each script and CI job that relied on the default before staging was added; plan was already a second site, so most should already name main.
  • Dev rebuild on a rune edit is SPEC-153 D10. If editing site/staged-runes/*.md does not refresh the dev server, note it, and either fix it here if it is small or file a bug.

Blocks

  • WORK-681

References

  • SPEC-181: D1, D3.
  • SPEC-153: D4, D8, D10.

Resolution

Completed: 2026-10-30

Branch: claude/milestone-v0-44-0-ism7ni

What was done

  • refrakt.config.json: a staging site that copies main field for field and adds runes: { dir: "site/staged-runes" }. It was inserted as text, so main is untouched.
  • site/vite.config.ts reads the site from REFRAKT_SITE (default main). site/svelte.config.js writes build-staging/ for it, which is gitignored.
  • npm run dev:staging (port 5174) and npm run build:staging are available at the root and in site.
  • packages/content/test/staging-site.test.ts:
    • staging equals main apart from runes (SPEC-181 D3);
    • a staged rune preferred with __project__ replaces the plugin's schema, its generated config replaces the hand-written Hero entry entirely, and its aliases replace the plugin's (call-to-action is dropped with a staged cta).
  • scripts/generate-rune-attributes.mjs leaves staging out, since the reference pages document what ships.

Notes

  • Site-scoped commands needed no change. inspect / contracts / reference already required --site because plan was a second site, and every script names main. refrakt validate validates every site, so CI now validates staging too.
  • Dev rebuild on a staged rune edit uses SPEC-153 D10's watch on runes.dir, which the plugin already resolves per site.