Unified root-level refrakt config

Options Considered

1. Status quo — autodetection plus package.json scanning

Keep refrakt.config.json as a site-only file. MCP and discoverPlugins() scan package.json for @refrakt-md/* deps and attempt to load each one's cli-plugin.

Pros:

• Zero migration cost.
• Planning-only users stay zero-config.
• Already specified in SPEC-043.

Cons:

• Plugin list is heuristic — transitive deps and non-CLI packages can show up; opting out requires per-package metadata.
• Path overrides stay scattered across CLI flags forever.
• No single answer to "what is this refrakt project?" for tooling.
• The MCP server's "did you mean?" suggestions are only as good as the heuristic.

2. New root config alongside the site config

Add a fresh root file (refrakt.json or similar) that holds plugins/plan/site references. Leave site/refrakt.config.json alone.

Pros:

• Site config semantics are untouched.
• Clean separation between "project config" and "site config."

Cons:

• Two config files where there could be one. Authors have to learn which knob lives where.
• The existing packages field in the site config is conceptually a plugin reference too — duplicating it across files is worse than unifying.
• Naming collision risk (refrakt.json vs refrakt.config.json is a foot-gun).

3. Expand refrakt.config.json into a unified root config — chosen

Promote refrakt.config.json to be the project-level config, with explicit plugins, plan, and site sections. Keep the file optional so autodetection remains the fallback for zero-config repos. The current flat shape (contentDir, theme, target, packages, …) continues to work but is treated as shorthand for the site.* namespace.

Proposed shape (single site, common case):

{
  "plugins": [
    "@refrakt-md/plan",
    "@refrakt-md/marketing",
    "@refrakt-md/docs"
  ],
  "plan": {
    "dir": "plan"
  },
  "site": {
    "contentDir": "./content",
    "theme": "@refrakt-md/lumina",
    "target": "svelte",
    "packages": ["@refrakt-md/marketing", "@refrakt-md/docs"],
    "routeRules": [/* … */],
    "icons": {/* … */}
  }
}

Proposed shape (multiple sites in one repo):

{
  "plugins": ["@refrakt-md/plan", "@refrakt-md/marketing"],
  "plan": { "dir": "plan" },
  "sites": {
    "main": {
      "contentDir": "./site/content",
      "theme": "@refrakt-md/lumina",
      "target": "svelte",
      "packages": ["@refrakt-md/marketing"]
    },
    "blog": {
      "contentDir": "./blog/content",
      "theme": "@refrakt-md/lumina",
      "target": "svelte",
      "packages": ["@refrakt-md/marketing"]
    }
  }
}

site (singular) and sites (plural map) are mutually exclusive. The loader normalizes both into a single internal sites: Record<string, SiteConfig> shape — site becomes sites.default. Downstream consumers (SvelteKit plugin, MCP server, CLI commands) only ever see the normalized form.

Resolution rules:

• File absent → autodetect everything (current behavior preserved for planning-only repos).
• File present, only plan section → behaves like a planning-only project; site tools are unavailable.
• File present, only site (or flat shorthand) → single-site project; normalizes to sites.default.
• File present, only sites → multi-site project; CLI and SvelteKit plugin require a site identifier (or pick the only entry when there is exactly one).
• File present, both site and sites → configuration error; loader rejects with a clear message.
• File present, plan + site(s) → both contexts active; MCP exposes both tool groups.
• plugins is the canonical plugin list. If absent, fall back to scanning dependencies as today. If present, it is authoritative — the scanner does not look at package.json.
• site(s).*.packages and the top-level plugins array overlap intentionally: packages per site controls which rune packages are merged into that site's ThemeConfig (a SvelteKit-plugin concern); plugins controls which packages contribute CLI commands and MCP tools. Most users will list a package in both, but the split lets a CLI-only plugin (no runes) skip site merging, and lets two sites in the same repo merge different package subsets.

Pros:

• One file, one mental model. "Where do I tell refrakt about my plan?" has one answer.
• Plugin discovery becomes "read the array" for projects that opt in, eliminating heuristic ambiguity.
• Path overrides have a home — no more --dir on every plan invocation.
• Multi-site monorepos (docs + marketing, project + plan dashboard, multi-tenant) get a first-class story instead of needing separate repos or out-of-band orchestration.
• Backwards compatible via the flat-shape shorthand; no forced migration for existing sites.
• Sets up future sections (docs, editor, etc.) without further format churn.

Cons:

• Slight config tax for repos that want explicit control (mitigated: file is optional).
• Three ways to write site config (flat / site singular / sites plural) during the transition window — all collapse to the same normalized shape internally.
• The dual plugins / site(s).packages distinction needs documentation.
• Multi-site repos require a --site <name> flag on site-targeted CLI commands and a way for the SvelteKit plugin to be told which site it is building.

4. Autodetection-only, no config at all

Remove refrakt.config.json and infer everything from package.json and directory structure.

Pros:

• Maximum zero-config charm.

Cons:

• Site config is genuinely too rich to autodetect (routeRules, icons, backgrounds).
• No place for explicit overrides.
• Doesn't solve plugin discovery — same heuristic problem.