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; history from Oct 29 to Oct 300%25%50%75%100%Oct 29Oct 30

Relationships

Implements 1
Related 3
Branches 2
main current done
claude/milestone-v0-44-0-ism7ni doneclaude/rune-compositions-staging-f9ouim ready
History 5
  1. c72d96f
    • ☑ `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
    by bjornolofandersson
  2. 4563e37
    Content editedby Claude
    plan: WORK-680, WORK-684, WORK-685 done
  3. 989c350
    Content editedby Claude
    v0.44.0 batch 5: staging site; hero and testimonial accept the composed
  4. bbcfb94
    Created (ready)by bjornolofandersson
  5. d14882c
    Content editedby Claude
    plan: SPEC-181 uses a staging site and settles the rollout

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.