@fusionkit/cli 0.1.6 → 0.1.7

package/README.md

@@ -44,23 +44,25 @@ cloud panel (skip with `--yes`). Use `--local` for the on-device MLX panel, or
 
 ## Per-repo config
 
-Tired of long flag lines? Scaffold a committed `fusionkit.json`:
+Tired of long flag lines? Scaffold a committed `.fusionkit/` folder:
 
 ```bash
 fusionkit init
 ```
 
-It records the panel, judge, default tool, and run defaults so the whole team
-can just run `fusionkit codex`. Only env-var *names* for keys are stored, never
-secrets. Explicit CLI flags always override the file. Inspect the effective
-config and a dry-run preview with `fusionkit status`.
+It writes `.fusionkit/fusion.json` (the panel, judge, default tool, and run
+defaults) plus editable system-prompt overrides in `.fusionkit/prompts/*.md`, so
+the whole team can just run `fusionkit codex`. Only env-var *names* for keys are
+stored, never secrets. Explicit CLI flags always override the folder. A legacy
+`fusionkit.json` is auto-migrated on first run. Inspect the effective config and
+a dry-run preview with `fusionkit status`.
 
 ## Commands
 
 - `fusionkit codex | claude | cursor` — launch that agent backed by the panel.
 - `fusionkit serve` — just run the gateway and print setup snippets for any tool.
 - `fusionkit fusion [tool]` — the generic launcher (interactive picker on a TTY).
-- `fusionkit init` — scaffold `fusionkit.json` for this repo.
+- `fusionkit init` — scaffold the committed `.fusionkit/` folder for this repo.
 - `fusionkit doctor` — check prerequisites with fix hints.
 - `fusionkit status` — show the effective config and what a run will do.
 

package/dist/commands/doctor.js

@@ -56,13 +56,15 @@ function runDoctor() {
         console.log("");
         console.log(bold("repo config"));
         try {
-            const config = loadFusionConfig(repoRoot);
+            const config = loadFusionConfig(repoRoot, (message) => console.log(`  ${gray(glyph.bullet())} ${dim(message)}`));
             if (config === undefined) {
-                console.log(`  ${gray(glyph.bullet())} no ${cyan("fusionkit.json")} yet — run ${bold("fusionkit fusion init")}`);
+                console.log(`  ${gray(glyph.bullet())} no ${cyan(".fusionkit/")} yet — run ${bold("fusionkit fusion init")}`);
             }
             else {
+                const overrides = Object.keys(config.prompts ?? {});
                 console.log(`  ${green(glyph.tick())} ${cyan(fusionConfigPath(repoRoot))}`);
                 console.log(`    ${dim(`tool: ${config.tool ?? "(unset)"}  panel: ${(config.panel ?? []).map((s) => s.id).join(", ") || "(unset)"}`)}`);
+                console.log(`    ${dim(`prompt overrides: ${overrides.length > 0 ? overrides.join(", ") : "(none — built-in defaults)"}`)}`);
             }
         }
         catch (error) {
@@ -94,7 +96,7 @@ function runStatus() {
     }
     let config;
     try {
-        config = loadFusionConfig(repoRoot);
+        config = loadFusionConfig(repoRoot, (message) => console.log(dim(message)));
     }
     catch (error) {
         console.log(`${red("config error:")} ${error instanceof Error ? error.message : String(error)}`);
@@ -110,6 +112,8 @@ function runStatus() {
     console.log(`${dim("tool:")}   ${bold(tool)}`);
     console.log(`${dim("judge:")}  ${judge}`);
     console.log(`${dim("observe:")} ${config?.observe === true ? "on" : "off"}`);
+    const overrides = Object.keys(config?.prompts ?? {});
+    console.log(`${dim("prompts:")} ${overrides.length > 0 ? overrides.join(", ") : dim("(built-in defaults)")}`);
     console.log(bold("\npanel"));
     for (const spec of panel)
         console.log(`  ${glyph.bullet()} ${panelLabel(spec)}`);

package/dist/commands/fusion.js

@@ -17,9 +17,9 @@ function applyFusionOptions(command) {
         .option("--fusionkit-dir <dir>", "local FusionKit checkout (dev override for the uvx synthesizer)")
         .option("--repo <dir>", "coding workspace the panel fuses over")
         .option("--local", "use the local MLX panel trio instead of the default cloud panel")
-        .option("--no-local", "override a fusionkit.json default of local=true")
+        .option("--no-local", "override a .fusionkit default of local=true")
         .option("--observe", "boot the local scope dashboard and stream live trace events")
-        .option("--no-observe", "override a fusionkit.json default of observe=true")
+        .option("--no-observe", "override a .fusionkit default of observe=true")
         .option("--yes", "skip the interactive cloud-panel cost confirmation")
         .option("--auth-token <token>", "require a bearer token on the gateway")
         .option("--port <n>", "gateway port (default: ephemeral)")
@@ -98,6 +98,8 @@ function mergeConfig(options, config) {
         options.portless = config.portless;
     if (options.port === undefined && config.port != null)
         options.port = config.port;
+    if (options.prompts === undefined && config.prompts !== undefined)
+        options.prompts = config.prompts;
 }
 /** The repo root used for config lookup: --repo if given, else the cwd's git root. */
 function configRepoRoot(options) {
@@ -124,15 +126,21 @@ function resolveContext(opts) {
     return { options, ...(config?.tool !== undefined ? { configTool: config.tool } : {}) };
 }
 export function registerFusion(program) {
-    // Top-level `init` — scaffold a committed fusionkit.json for this repo.
+    // Top-level `init` — scaffold a committed .fusionkit/ folder for this repo.
     program
         .command("init")
-        .description("scaffold a committed fusionkit.json for this repo")
+        .description("scaffold a committed .fusionkit/ folder for this repo")
         .option("--repo <dir>", "coding workspace the panel fuses over")
-        .option("--force", "overwrite an existing fusionkit.json")
+        .option("--fusionkit-dir <dir>", "local FusionKit checkout (dev override for default prompts)")
+        .option("--force", "overwrite an existing .fusionkit/ config and prompts")
         .action(async (opts) => {
-        const repoRoot = configRepoRoot(resolveOptions(opts));
-        const code = await runFusionInit({ repoRoot, force: opts.force === true });
+        const options = resolveOptions(opts);
+        const repoRoot = configRepoRoot(options);
+        const code = await runFusionInit({
+            repoRoot,
+            force: opts.force === true,
+            ...(options.fusionkitDir !== undefined ? { fusionkitDir: options.fusionkitDir } : {})
+        });
         process.exit(code);
     });
     // Generic `fusion [tool]` — keeps the original surface and interactive pick.
@@ -143,7 +151,7 @@ export function registerFusion(program) {
         .argument("[args...]", "arguments forwarded to the tool")
         .option("--tool <tool>", `coding agent to launch (${FUSION_TOOLS.join(" | ")})`))
         .addHelpText("after", "\nfusionkit's own flags must precede the tool name; everything after the tool is forwarded to it." +
-        "\nRun `fusionkit init` to scaffold a committed fusionkit.json for this repo." +
+        "\nRun `fusionkit init` to scaffold a committed .fusionkit/ folder for this repo." +
         "\nRun `fusionkit fusion stop` to reap portless singleton services (router, dashboard, ...).")
         .action(async (positionalTool, args, opts) => {
         // `fusion stop` reaps persistent portless singletons left running by prior

package/dist/fusion/env.d.ts

@@ -1,3 +1,4 @@
+import type { PromptOverrides } from "../fusion-config.js";
 /** A launchable tool id from the registry, or the `serve` pseudo-tool. */
 export type FusionTool = string;
 export type PanelProvider = "mlx" | "openai" | "anthropic" | "google" | "openai-compatible";
@@ -32,6 +33,8 @@ export type RunFusionOptions = {
     yes?: boolean;
     /** Route services through portless (stable named URLs + singletons). Default on. */
     portless?: boolean;
+    /** System-prompt overrides forwarded to the synthesizer's router config. */
+    prompts?: PromptOverrides;
     log?: (line: string) => void;
 };
 /**
@@ -77,7 +80,7 @@ export type StackReporter = (event: StackEvent) => void;
  * synthesizer (`fusionkit serve`) and the single-model OpenAI shim
  * (`fusionkit serve-endpoint`). Pinned so `uvx` resolves a reproducible build.
  */
-export declare const FUSIONKIT_PYPI_VERSION = "0.2.0";
+export declare const FUSIONKIT_PYPI_VERSION = "0.3.0";
 /**
  * Default cloud panel — works cross-platform with only `OPENAI_API_KEY` and
  * `ANTHROPIC_API_KEY` set. The judge defaults to the first entry.

package/dist/fusion/env.js

@@ -10,7 +10,7 @@ import { existsSync, readFileSync } from "node:fs";
  * synthesizer (`fusionkit serve`) and the single-model OpenAI shim
  * (`fusionkit serve-endpoint`). Pinned so `uvx` resolves a reproducible build.
  */
-export const FUSIONKIT_PYPI_VERSION = "0.2.0";
+export const FUSIONKIT_PYPI_VERSION = "0.3.0";
 /**
  * Default cloud panel — works cross-platform with only `OPENAI_API_KEY` and
  * `ANTHROPIC_API_KEY` set. The judge defaults to the first entry.

package/dist/fusion/stack.d.ts

@@ -1,5 +1,6 @@
 import type { EnsembleModel } from "@fusionkit/ensemble";
 import type { PortlessSession } from "../shared/portless.js";
+import type { PromptOverrides } from "../fusion-config.js";
 import type { PanelModelSpec, StackReporter } from "./env.js";
 /**
  * The single `fusionkit serve` router: one process that fronts every panel
@@ -31,6 +32,7 @@ export declare function startRouter(options: {
     specs: PanelModelSpec[];
     judgeModel?: string;
     fusionkitDir?: string;
+    prompts?: PromptOverrides;
     logsDir?: string;
     report?: StackReporter;
     log: (line: string) => void;
@@ -46,6 +48,8 @@ export type StartFusionStackOptions = {
     models: PanelModelSpec[];
     endpoints?: Record<string, string>;
     fusionkitDir?: string;
+    /** System-prompt overrides emitted into the router's synthesizer config. */
+    prompts?: PromptOverrides;
     judgeModel?: string;
     /** Pre-running fusionkit serve URL for trajectory synthesis (skips spawn). */
     synthesisUrl?: string;

package/dist/fusion/stack.js

@@ -10,6 +10,7 @@ import { MlxBackend, startGateway } from "@fusionkit/model-gateway";
 import { startFusionStepGateway } from "../gateway.js";
 import { createPortlessSession } from "../shared/portless.js";
 import { freePort, spawnLogged, terminate, waitForHttp } from "../shared/proc.js";
+import { PROMPT_CONFIG_KEY, PROMPT_IDS } from "../fusion-config.js";
 import { defaultKeyEnv, fusionkitPyCommand, loadEnvFileInto } from "./env.js";
 /**
  * Heuristic: does the captured output indicate a permanent failure (bad key,
@@ -85,6 +86,19 @@ function routerConfigYaml(input) {
     // Generous budget: reasoning models (gpt-5.x) spend tokens on reasoning before
     // producing content, so a small cap can yield an empty answer.
     lines.push("sampling: {temperature: 0.2, top_p: 0.9, max_tokens: 8192}");
+    // Committed `.fusionkit/prompts/*.md` overrides flow into the synthesizer's
+    // PromptOverrides here. JSON.stringify yields a valid YAML double-quoted
+    // scalar, so multi-line prompts are escaped safely.
+    const promptEntries = PROMPT_IDS.flatMap((id) => {
+        const value = input.prompts?.[id];
+        return value !== undefined ? [[PROMPT_CONFIG_KEY[id], value]] : [];
+    });
+    if (promptEntries.length > 0) {
+        lines.push("prompts:");
+        for (const [key, value] of promptEntries) {
+            lines.push(`  ${key}: ${JSON.stringify(value)}`);
+        }
+    }
     lines.push("");
     return lines.join("\n");
 }
@@ -142,7 +156,12 @@ export async function startRouter(options) {
             gateways.push(gateway);
             mlxUrls[spec.id] = gateway.url();
         }
-        const config = routerConfigYaml({ specs, mlxUrls, judgeId: judgeSpec.id });
+        const config = routerConfigYaml({
+            specs,
+            mlxUrls,
+            judgeId: judgeSpec.id,
+            ...(options.prompts !== undefined ? { prompts: options.prompts } : {})
+        });
         const configDir = mkdtempSync(join(tmpdir(), "fusion-router-"));
         const configPath = join(configDir, "router.yaml");
         writeFileSync(configPath, config);
@@ -235,6 +254,7 @@ export async function startFusionStack(options) {
                     specs: options.models,
                     ...(options.judgeModel !== undefined ? { judgeModel: options.judgeModel } : {}),
                     ...(options.fusionkitDir !== undefined ? { fusionkitDir: options.fusionkitDir } : {}),
+                    ...(options.prompts !== undefined ? { prompts: options.prompts } : {}),
                     ...(options.logsDir !== undefined ? { logsDir: options.logsDir } : {}),
                     ...(report !== undefined ? { report } : {}),
                     log: options.log

package/dist/fusion-config.d.ts

@@ -1,6 +1,20 @@
 import type { FusionTool, PanelModelSpec } from "./fusion-quickstart.js";
+export declare const FUSION_CONFIG_DIRNAME = ".fusionkit";
+export declare const FUSION_CONFIG_BASENAME = "fusion.json";
+export declare const FUSION_PROMPTS_DIRNAME = "prompts";
+/** Legacy single-file config at the repo root (pre-`.fusionkit/`). */
 export declare const FUSION_CONFIG_FILENAME = "fusionkit.json";
-export declare const FUSION_CONFIG_VERSION = "fusionkit.fusion.v1";
+export declare const FUSION_CONFIG_VERSION = "fusionkit.fusion.v2";
+/**
+ * The committable system-prompt override ids. Each maps to a
+ * `.fusionkit/prompts/<id>.md` file and to a `FusionConfig.prompts` key in the
+ * Python synthesizer (see {@link PROMPT_CONFIG_KEY}).
+ */
+export declare const PROMPT_IDS: readonly ["judge", "synthesizer", "trajectory-synthesizer", "trajectory-step", "verifier", "panel"];
+export type PromptId = (typeof PROMPT_IDS)[number];
+/** Map each prompt override id to the `prompts:` key fusionkit's config expects. */
+export declare const PROMPT_CONFIG_KEY: Record<PromptId, string>;
+export type PromptOverrides = Partial<Record<PromptId, string>>;
 export type FusionConfig = {
     version: typeof FUSION_CONFIG_VERSION;
     tool?: FusionTool;
@@ -10,19 +24,57 @@ export type FusionConfig = {
     observe?: boolean;
     portless?: boolean;
     port?: number | null;
+    /**
+     * System-prompt overrides, loaded from `.fusionkit/prompts/*.md`. Not stored
+     * inline in `config.json` — it is hydrated from the prompt files on load.
+     */
+    prompts?: PromptOverrides;
 };
 export declare class FusionConfigError extends Error {
     constructor(message: string);
 }
+/** The `.fusionkit/` directory at the repo root. */
+export declare function fusionConfigDir(repoRoot: string): string;
+/** The `.fusionkit/fusion.json` settings file. */
 export declare function fusionConfigPath(repoRoot: string): string;
-/** Validate a parsed object as a {@link FusionConfig}, throwing on any problem. */
+/** The legacy `fusionkit.json` at the repo root (pre-`.fusionkit/`). */
+export declare function legacyFusionConfigPath(repoRoot: string): string;
+/** The `.fusionkit/prompts/` directory holding the override files. */
+export declare function fusionPromptsDir(repoRoot: string): string;
+/** The `.fusionkit/prompts/<id>.md` file for a single prompt override. */
+export declare function fusionPromptPath(repoRoot: string, id: PromptId): string;
+/**
+ * Validate a parsed settings object as a {@link FusionConfig}, throwing on any
+ * problem. Prompt overrides are loaded separately from `.fusionkit/prompts/`,
+ * not from this object. A `v1` version is accepted and upgraded to `v2`.
+ */
 export declare function parseFusionConfig(raw: unknown, source: string): FusionConfig;
 /**
- * Load `<repoRoot>/fusionkit.json` if present. Returns `undefined` when the file
- * does not exist; throws {@link FusionConfigError} on malformed content.
+ * Read the committed prompt overrides from `.fusionkit/prompts/*.md`. Only files
+ * that exist and are non-empty (after trimming) become overrides.
+ */
+export declare function readFusionPrompts(repoRoot: string): PromptOverrides;
+/**
+ * Load the per-repo config. Prefers `.fusionkit/config.json`; if it is absent
+ * but a legacy `fusionkit.json` exists, auto-migrates it into the folder (the
+ * original is left intact) and loads from there. Returns `undefined` when no
+ * config exists; throws {@link FusionConfigError} on malformed content.
+ *
+ * `onNotice` receives a one-line message when a migration happens.
+ */
+export declare function loadFusionConfig(repoRoot: string, onNotice?: (message: string) => void): FusionConfig | undefined;
+/**
+ * Write `.fusionkit/config.json` (creating the folder), refusing to clobber
+ * unless `force`. Prompt overrides are stored as files, not inline, so any
+ * `prompts` on the config object is omitted here.
  */
-export declare function loadFusionConfig(repoRoot: string): FusionConfig | undefined;
-/** Write `fusionkit.json` at the repo root, refusing to clobber unless `force`. */
 export declare function writeFusionConfig(repoRoot: string, config: FusionConfig, options?: {
     force?: boolean;
 }): string;
+/**
+ * Write prompt override files into `.fusionkit/prompts/`. Existing files are
+ * left untouched unless `force`. Returns the paths actually written.
+ */
+export declare function writeFusionPrompts(repoRoot: string, prompts: PromptOverrides, options?: {
+    force?: boolean;
+}): string[];

package/dist/fusion-config.js

@@ -1,29 +1,85 @@
 /**
- * Per-repo fusion configuration (`fusionkit.json`, committed at the repo root).
+ * Per-repo fusion configuration, stored in a committed `.fusionkit/` folder at
+ * the repo root:
  *
- * Captures the panel, judge, default tool, and run defaults so a contributor can
- * just run `fusionkit codex` instead of retyping a long flag line. The file is
- * safe to commit: it stores only the env-var *names* that hold API keys
- * (`keyEnv`), never the secret values.
+ *   .fusionkit/
+ *     fusion.json        - all settings (panel, judge, default tool, run defaults)
+ *     prompts/<id>.md    - optional system-prompt overrides (one file per prompt)
  *
- * Precedence at run time is: explicit CLI flags > fusionkit.json > built-in
- * defaults. CLI flags always win, so the file is a default layer, not a lock.
+ * The folder is safe to commit: it stores only the env-var *names* that hold API
+ * keys (`keyEnv`), never the secret values. A prompt file that exists and is
+ * non-empty overrides the matching built-in synthesizer prompt; absent/empty
+ * falls back to the built-in default.
+ *
+ * Precedence at run time is: explicit CLI flags > .fusionkit > built-in
+ * defaults. CLI flags always win, so the folder is a default layer, not a lock.
+ *
+ * Legacy `fusionkit.json` files at the repo root are auto-migrated into
+ * `.fusionkit/fusion.json` on first load (the original is left intact as a
+ * back-compat fallback).
  */
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { FUSION_TOOLS } from "./fusion-quickstart.js";
 import { PANEL_PROVIDERS } from "./shared/options.js";
+export const FUSION_CONFIG_DIRNAME = ".fusionkit";
+// `fusion.json` (not `config.json`) so the fusion settings never collide with
+// the plane home's `.fusionkit/config.json` (`warrant.config.v2`).
+export const FUSION_CONFIG_BASENAME = "fusion.json";
+export const FUSION_PROMPTS_DIRNAME = "prompts";
+/** Legacy single-file config at the repo root (pre-`.fusionkit/`). */
 export const FUSION_CONFIG_FILENAME = "fusionkit.json";
-export const FUSION_CONFIG_VERSION = "fusionkit.fusion.v1";
+export const FUSION_CONFIG_VERSION = "fusionkit.fusion.v2";
+/** Versions `parseFusionConfig` will load; `v1` is upgraded to `v2` in memory. */
+const SUPPORTED_CONFIG_VERSIONS = ["fusionkit.fusion.v1", "fusionkit.fusion.v2"];
+/**
+ * The committable system-prompt override ids. Each maps to a
+ * `.fusionkit/prompts/<id>.md` file and to a `FusionConfig.prompts` key in the
+ * Python synthesizer (see {@link PROMPT_CONFIG_KEY}).
+ */
+export const PROMPT_IDS = [
+    "judge",
+    "synthesizer",
+    "trajectory-synthesizer",
+    "trajectory-step",
+    "verifier",
+    "panel"
+];
+/** Map each prompt override id to the `prompts:` key fusionkit's config expects. */
+export const PROMPT_CONFIG_KEY = {
+    judge: "judge_system",
+    synthesizer: "synthesizer_system",
+    "trajectory-synthesizer": "trajectory_synthesizer_system",
+    "trajectory-step": "trajectory_step_system",
+    verifier: "verifier_system",
+    panel: "panel_system"
+};
 export class FusionConfigError extends Error {
     constructor(message) {
         super(message);
         this.name = "FusionConfigError";
     }
 }
+/** The `.fusionkit/` directory at the repo root. */
+export function fusionConfigDir(repoRoot) {
+    return join(repoRoot, FUSION_CONFIG_DIRNAME);
+}
+/** The `.fusionkit/fusion.json` settings file. */
 export function fusionConfigPath(repoRoot) {
+    return join(fusionConfigDir(repoRoot), FUSION_CONFIG_BASENAME);
+}
+/** The legacy `fusionkit.json` at the repo root (pre-`.fusionkit/`). */
+export function legacyFusionConfigPath(repoRoot) {
     return join(repoRoot, FUSION_CONFIG_FILENAME);
 }
+/** The `.fusionkit/prompts/` directory holding the override files. */
+export function fusionPromptsDir(repoRoot) {
+    return join(fusionConfigDir(repoRoot), FUSION_PROMPTS_DIRNAME);
+}
+/** The `.fusionkit/prompts/<id>.md` file for a single prompt override. */
+export function fusionPromptPath(repoRoot, id) {
+    return join(fusionPromptsDir(repoRoot), `${id}.md`);
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -57,12 +113,16 @@ function validatePanelEntry(entry, index) {
     }
     return spec;
 }
-/** Validate a parsed object as a {@link FusionConfig}, throwing on any problem. */
+/**
+ * Validate a parsed settings object as a {@link FusionConfig}, throwing on any
+ * problem. Prompt overrides are loaded separately from `.fusionkit/prompts/`,
+ * not from this object. A `v1` version is accepted and upgraded to `v2`.
+ */
 export function parseFusionConfig(raw, source) {
     if (!isRecord(raw))
         throw new FusionConfigError(`${source}: must be a JSON object`);
-    if (raw.version !== FUSION_CONFIG_VERSION) {
-        throw new FusionConfigError(`${source}: unsupported version ${JSON.stringify(raw.version)} (expected "${FUSION_CONFIG_VERSION}")`);
+    if (typeof raw.version !== "string" || !SUPPORTED_CONFIG_VERSIONS.includes(raw.version)) {
+        throw new FusionConfigError(`${source}: unsupported version ${JSON.stringify(raw.version)} (expected one of ${SUPPORTED_CONFIG_VERSIONS.join(", ")})`);
     }
     const config = { version: FUSION_CONFIG_VERSION };
     if (raw.tool !== undefined) {
@@ -104,14 +164,7 @@ export function parseFusionConfig(raw, source) {
     }
     return config;
 }
-/**
- * Load `<repoRoot>/fusionkit.json` if present. Returns `undefined` when the file
- * does not exist; throws {@link FusionConfigError} on malformed content.
- */
-export function loadFusionConfig(repoRoot) {
-    const path = fusionConfigPath(repoRoot);
-    if (!existsSync(path))
-        return undefined;
+function readAndParse(path) {
     let raw;
     try {
         raw = JSON.parse(readFileSync(path, "utf8"));
@@ -121,12 +174,89 @@ export function loadFusionConfig(repoRoot) {
     }
     return parseFusionConfig(raw, path);
 }
-/** Write `fusionkit.json` at the repo root, refusing to clobber unless `force`. */
+/**
+ * Read the committed prompt overrides from `.fusionkit/prompts/*.md`. Only files
+ * that exist and are non-empty (after trimming) become overrides.
+ */
+export function readFusionPrompts(repoRoot) {
+    const dir = fusionPromptsDir(repoRoot);
+    const prompts = {};
+    if (!existsSync(dir))
+        return prompts;
+    for (const id of PROMPT_IDS) {
+        const path = fusionPromptPath(repoRoot, id);
+        if (!existsSync(path))
+            continue;
+        const text = readFileSync(path, "utf8").trim();
+        if (text.length > 0)
+            prompts[id] = text;
+    }
+    return prompts;
+}
+function withPrompts(repoRoot, config) {
+    const prompts = readFusionPrompts(repoRoot);
+    if (Object.keys(prompts).length === 0)
+        return config;
+    return { ...config, prompts };
+}
+/**
+ * Load the per-repo config. Prefers `.fusionkit/config.json`; if it is absent
+ * but a legacy `fusionkit.json` exists, auto-migrates it into the folder (the
+ * original is left intact) and loads from there. Returns `undefined` when no
+ * config exists; throws {@link FusionConfigError} on malformed content.
+ *
+ * `onNotice` receives a one-line message when a migration happens.
+ */
+export function loadFusionConfig(repoRoot, onNotice) {
+    const newPath = fusionConfigPath(repoRoot);
+    if (existsSync(newPath)) {
+        return withPrompts(repoRoot, readAndParse(newPath));
+    }
+    const legacyPath = legacyFusionConfigPath(repoRoot);
+    if (!existsSync(legacyPath))
+        return undefined;
+    const config = readAndParse(legacyPath);
+    try {
+        writeFusionConfig(repoRoot, config);
+        onNotice?.(`migrated ${legacyPath} into ${newPath}`);
+    }
+    catch {
+        // Could not write the migrated copy (e.g. read-only FS); use the legacy
+        // file in place for this run rather than failing.
+    }
+    return withPrompts(repoRoot, config);
+}
+/**
+ * Write `.fusionkit/config.json` (creating the folder), refusing to clobber
+ * unless `force`. Prompt overrides are stored as files, not inline, so any
+ * `prompts` on the config object is omitted here.
+ */
 export function writeFusionConfig(repoRoot, config, options = {}) {
     const path = fusionConfigPath(repoRoot);
     if (existsSync(path) && options.force !== true) {
         throw new FusionConfigError(`${path} already exists (pass --force to overwrite)`);
     }
-    writeFileSync(path, JSON.stringify(config, null, 2) + "\n");
+    mkdirSync(fusionConfigDir(repoRoot), { recursive: true });
+    const { prompts: _prompts, ...persisted } = config;
+    writeFileSync(path, JSON.stringify(persisted, null, 2) + "\n");
     return path;
 }
+/**
+ * Write prompt override files into `.fusionkit/prompts/`. Existing files are
+ * left untouched unless `force`. Returns the paths actually written.
+ */
+export function writeFusionPrompts(repoRoot, prompts, options = {}) {
+    mkdirSync(fusionPromptsDir(repoRoot), { recursive: true });
+    const written = [];
+    for (const id of PROMPT_IDS) {
+        const text = prompts[id];
+        if (text === undefined)
+            continue;
+        const path = fusionPromptPath(repoRoot, id);
+        if (existsSync(path) && options.force !== true)
+            continue;
+        writeFileSync(path, text.endsWith("\n") ? text : `${text}\n`);
+        written.push(path);
+    }
+    return written;
+}

package/dist/fusion-init.d.ts

@@ -1,4 +1,5 @@
 export declare function runFusionInit(input: {
     repoRoot?: string;
     force?: boolean;
+    fusionkitDir?: string;
 }): Promise<number>;

package/dist/fusion-init.js

@@ -3,8 +3,9 @@
  * per-repo `fusionkit.json`. On a non-interactive stdin the prompts fall back to
  * their defaults, so `fusion init` still produces a sensible config in CI.
  */
-import { DEFAULT_CLOUD_PANEL, DEFAULT_TRIO, defaultKeyEnv } from "./fusion-quickstart.js";
-import { FUSION_CONFIG_VERSION, FusionConfigError, fusionConfigPath, writeFusionConfig } from "./fusion-config.js";
+import { execFileSync } from "node:child_process";
+import { DEFAULT_CLOUD_PANEL, DEFAULT_TRIO, defaultKeyEnv, fusionkitPyCommand } from "./fusion-quickstart.js";
+import { FUSION_CONFIG_VERSION, FusionConfigError, fusionConfigPath, fusionPromptsDir, PROMPT_IDS, writeFusionConfig, writeFusionPrompts } from "./fusion-config.js";
 import { parsePanelModelSpec } from "./shared/options.js";
 import { confirm, done, note, select, text } from "./ui/prompt.js";
 import { uiStream } from "./ui/runtime.js";
@@ -18,6 +19,35 @@ function withKeyEnv(spec) {
     const keyEnv = defaultKeyEnv(provider);
     return keyEnv !== undefined ? { ...spec, keyEnv } : { ...spec };
 }
+/**
+ * Pull the built-in default prompts from the Python `fusionkit` CLI
+ * (`fusionkit prompts dump`) so the scaffolded `.fusionkit/prompts/*.md` files
+ * match the synthesizer's source of truth. Returns `undefined` if the CLI is
+ * unreachable (e.g. offline) — callers fall back to leaving prompts unset, in
+ * which case the built-in defaults are used at run time.
+ */
+function fetchDefaultPrompts(fusionkitDir) {
+    const runner = fusionkitPyCommand(fusionkitDir);
+    try {
+        const stdout = execFileSync(runner.command, [...runner.prefix, "prompts", "dump"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 120_000,
+            ...(runner.cwd !== undefined ? { cwd: runner.cwd } : {})
+        });
+        const parsed = JSON.parse(stdout);
+        const prompts = {};
+        for (const id of PROMPT_IDS) {
+            const value = parsed[id];
+            if (typeof value === "string" && value.length > 0)
+                prompts[id] = value;
+        }
+        return Object.keys(prompts).length > 0 ? prompts : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 async function buildCustomPanel() {
     out.write(dim("Add panel models as ID=PROVIDER:MODEL (e.g. gpt=openai:gpt-5.5). Blank line to finish.\n"));
     const specs = [];
@@ -42,7 +72,7 @@ async function buildCustomPanel() {
 export async function runFusionInit(input) {
     if (input.repoRoot === undefined) {
         out.write(`${red("error:")} not inside a git repository.\n` +
-            "  cd into your project (or run from a repo) so fusionkit.json lands at the repo root.\n");
+            "  cd into your project (or run from a repo) so .fusionkit/ lands at the repo root.\n");
         return 1;
     }
     out.write(`\n${brandHeader("let's set up model fusion for this repo")}\n\n`);
@@ -103,8 +133,22 @@ export async function runFusionInit(input) {
         }
         throw error;
     }
+    // Scaffold editable prompt overrides from the synthesizer's built-in defaults.
+    // If the Python CLI is unreachable, skip silently — unset prompts use the
+    // built-in defaults at run time, and the user can eject them later with
+    // `fusionkit prompts dump --dir .fusionkit/prompts`.
+    const defaultPrompts = fetchDefaultPrompts(input.fusionkitDir);
+    const wrotePrompts = defaultPrompts !== undefined
+        ? writeFusionPrompts(input.repoRoot, defaultPrompts, { force: input.force === true })
+        : [];
     out.write("\n");
     done(`wrote ${cyan(fusionConfigPath(input.repoRoot))}`);
-    note(`commit it, then just run: ${bold(`fusionkit ${tool === "serve" ? "serve" : tool}`)}`);
+    if (wrotePrompts.length > 0) {
+        note(`editable prompts in ${cyan(fusionPromptsDir(input.repoRoot))} (empty file = built-in default)`);
+    }
+    else if (defaultPrompts === undefined) {
+        note(`prompts use built-in defaults; run ${bold("fusionkit prompts dump --dir .fusionkit/prompts")} to customize`);
+    }
+    note(`commit ${cyan(".fusionkit/")}, then just run: ${bold(`fusionkit ${tool === "serve" ? "serve" : tool}`)}`);
     return 0;
 }

package/dist/fusion-quickstart.js

@@ -201,6 +201,7 @@ export async function runFusion(tool, toolArgs, options = {}) {
             ...(report !== undefined ? { report } : {}),
             ...(options.endpoints !== undefined ? { endpoints: options.endpoints } : {}),
             ...(options.fusionkitDir !== undefined ? { fusionkitDir: options.fusionkitDir } : {}),
+            ...(options.prompts !== undefined ? { prompts: options.prompts } : {}),
             ...(options.judgeModel !== undefined ? { judgeModel: options.judgeModel } : {}),
             ...(options.synthesisUrl !== undefined ? { synthesisUrl: options.synthesisUrl } : {}),
             ...(options.authToken !== undefined ? { authToken: options.authToken } : {}),