summer-engine 2.2.0 → 2.5.0

package/commands/gameskill.md

@@ -0,0 +1,103 @@
+You are capturing what we just learned in this game-development session into Summer Engine's skill library, so the next agent (and every Summer user) gets to start where we ended.
+
+This is the meta-skill: the loop that turns ad-hoc fixes into durable, reusable expertise.
+
+## What "Summer Engine" is, so you're grounded
+
+Three repos, one ecosystem:
+
+1. **`~/development/SummerEngine`** — the desktop engine (Godot fork in C++) + the canonical CLI. The engine source lives at `editor/`, `core/`, and the Summer-specific module at `modules/1summer_engine/`. The Summer CLI lives at `tools/summer-cli/`. It ships as `npm i -g summer-engine`. It does install/login/create/run for the engine, plus `summer skills install --as-claude-skill` which writes a curated subset of skills into `~/.claude/skills/` for any agent to auto-discover.
+2. **`~/development/PublicSummerEngine`** — the web app at summerengine.com. Has its own AI skill stores at `src/lib/ai/skills/bundled/` and `public/knowledge/summer/skills/` for the in-browser chat agent. ALSO has its own MCP-style consumers of the engine API (`src/lib/bridge/direct-executor.ts`, `src/lib/ai/tools/run-and-verify.ts`) which call the same engine endpoints the CLI does.
+3. **The active game project** — usually `~/development/<game-name>` (Godot 4.6) or whatever game we were just working on. Real working code in this repo is the gold standard for examples.
+
+The skill system is the value flywheel: every game we ship teaches lessons → the lessons become skills → the next user (or AI) starts smarter. Your job here is to close that loop for what we just did.
+
+## Cross-repo change awareness — read this before any non-trivial fix
+
+When the lesson is "the engine should expose more / behave differently," the change usually crosses repo boundaries. Map the layers before you edit:
+
+```
+[active game] → calls MCP / web app
+                       ↓
+[summer-cli MCP server (TypeScript)] → calls /api/ops + /api/state/* on the engine
+                       ↓
+[Summer Engine binary (C++ in SummerEngine repo)] — source of truth for what the API can return
+
+[PublicSummerEngine web app (TypeScript)] → also calls the same engine endpoints via direct-executor or Redis bridge
+```
+
+Implications:
+
+- **A C++ change in `SummerEngine/modules/1summer_engine/` or `SummerEngine/editor/` reaches everyone** (CLI MCP, web app, future tools). Most powerful, also highest blast radius.
+- **A TypeScript change in `tools/summer-cli/src/mcp/`** only changes what the CLI exposes. The web app has its own TypeScript layer in `PublicSummerEngine/src/lib/bridge/` — same engine endpoints, different glue. Don't assume your CLI tool change is web-app-aware.
+- **A skill update in `tools/summer-cli/skills/`** affects every agent that runs `summer skills install`. The web app's skill store is separate (`PublicSummerEngine/src/lib/ai/skills/bundled/`) and currently uses a different format (template wizards, not Markdown discipline guides). Don't try to mirror skills there blindly.
+
+When you change an engine endpoint's response shape (add fields, rename fields, change semantics):
+
+1. Grep both `tools/summer-cli/src/` and `PublicSummerEngine/src/lib/` for consumers of that endpoint.
+2. Confirm the change is **additive** (new fields, no removed/renamed) so existing consumers still work without modification.
+3. If the change is breaking, update both consumers in the same logical commit set.
+4. Note in TOOLING-TODO.md what's now possible that wasn't before.
+
+Engine binary changes ship via a rebuild + new release. The user has to pull the new engine for the change to take effect. CLI/web TypeScript changes ship via npm publish or web deploy. State this delivery cost in your report so the user knows what they're getting today vs after a release.
+
+## The four skill stores (probe each before doing anything)
+
+1. **Canonical source** — `~/development/SummerEngine/tools/summer-cli/skills/`
+   - Single source of truth. Domains: `ui-and-ux`, `gameplay-mechanics`, `character-controllers`, `scripting-patterns`, `visual-effects`, `debugging`, `rendering-and-lighting`, `scene-and-project`, `level-design`, `audio`, `ai-and-npcs`, `asset-pipeline`, `performance`, `deployment`, `multiplayer-and-networking`, plus `workflow` for process skills.
+   - The `skills:` array in `.claude-plugin/plugin.json` is the registry. Sibling shared docs live at top-level `references/`; test specs at top-level `tests/`.
+2. **Claude auto-discovery** — `~/.claude/skills/` (currently 7 skills, written here by `summer skills install --as-claude-skill`).
+3. **Web-app stores** — `~/development/PublicSummerEngine/src/lib/ai/skills/` and `public/knowledge/summer/skills/`. Mirror only if the learning applies to the web chat agent too — check what's there before assuming.
+4. **The active game** — read it as ground truth. Working code from the real project beats invented examples.
+
+## What to do, in order
+
+1. **One short sentence to the user.** "Capturing learnings from this session into the skill library." That's it. No plan dump.
+
+2. **Probe the stores.** Glob each path above. Note what exists and what's empty. Print a tight summary (one line per domain with skill count).
+
+3. **Recap the session.** Look back over the conversation. Pull out the learnings that are non-obvious AND general — things a future agent or user would benefit from but couldn't derive from reading the codebase. Examples that count:
+   - A working shader (the actual code) → `visual-effects`
+   - A GDScript idiom that beat the obvious approach → `scripting-patterns`
+   - A UI layout that survived the design pass → `ui-and-ux`
+   - A bug + root cause + fix that wasn't in any docs → `debugging`
+   - A Godot 4.6 quirk (type inference, `.keys()` weirdness, signal gotchas) → `scripting-patterns`
+   - A spawning/AI/enemy pattern that worked → `ai-and-npcs` or `gameplay-mechanics`
+   - A perf fix with measured before/after → `performance`
+   - An asset-creation workflow that beat alternatives → `asset-pipeline`
+
+   Examples that DON'T count:
+   - One-off code with no general lesson
+   - Stuff already documented in `CLAUDE.md` or an existing skill
+   - Personal preference with no reasoning behind it
+   - Anything you have to manufacture to fill space
+
+4. **Decide placement.** For each learning:
+   - **Update existing skill** — name the file, quote the section, draft the addition.
+   - **Create new skill** — pick the domain, name the file, draft the full skill markdown.
+   Match the format of existing skills in the same domain exactly. Read one if you're unsure.
+
+5. **One tight pause for the user.** Five-to-ten lines max: what files you'll touch, what each one captures, what gets left out. Wait for OK or redirect. Don't ask multiple questions.
+
+6. **Apply.**
+   - Write/edit `.md` files under `tools/summer-cli/skills/<domain>/`.
+   - Register a new skill in `.claude-plugin/plugin.json` (plus `.codex-plugin/`, `.cursor-plugin/`) AND in `src/lib/skills-registry.ts` `SKILL_REGISTRY`. Both are required.
+   - If the skill belongs in the curated Claude set, also write it to `~/.claude/skills/<name>/` so it's live in the current session — and tell the user to consider adding it to the CLI's default install set.
+   - If the learning applies to the web chat agent, mirror to `PublicSummerEngine` skill stores too.
+   - Run `git status` in `~/development/SummerEngine` (and `PublicSummerEngine` if touched) so the diff is visible.
+
+7. **Report.** One short message. Files changed, the future-agent payoff in one sentence per skill, and what (if anything) is still uncaptured.
+
+## Style rules — non-negotiable
+
+- **Tight. No slop. No glazing.** Mathias hates filler.
+- **Capture the why, not just the what.** "Use X" rots. "Use X because Y breaks under Z (we hit this in PRUT chest reveal, 2026-05)" survives. Always lead skill updates with the reason.
+- **Real working code from the active project beats invented examples.** Lift from PRUT or whatever we were in.
+- **VFX is code** — shaders + GDScript + node setup. Never image-generation pipelines or Meshy prompts.
+- **No em dashes** (—) in any user-facing copy you write into skills. Use periods or restructure the sentence.
+- **`[SUMMER]` markers on core Godot engine file edits** — but skill `.md` files don't need them.
+- **Verify before claiming.** If a skill says "Summer Engine does X" or "Stripe is configured Y way", verify in the actual code/DB before writing it down.
+
+## When there's nothing worth capturing
+
+It's totally fine to come back with "session was tactical, no durable learnings worth a skill update." Don't manufacture skills from thin air. Better to ship nothing into the skill library than ship noise.

package/dist/bin/summer.js

@@ -10,6 +10,7 @@ import { openCommand } from "../commands/open.js";
 import { installCommand } from "../commands/install.js";
 import { createCommand } from "../commands/create.js";
 import { listCommand } from "../commands/list.js";
+import { memoryCommand } from "../commands/memory.js";
 import { skillsCommand } from "../commands/skills.js";
 import { orchestratorCommand } from "../commands/orchestrator.js";
 import { setupCommand } from "../commands/setup.js";
@@ -34,6 +35,7 @@ program.addCommand(runCommand);
 program.addCommand(openCommand);
 program.addCommand(createCommand);
 program.addCommand(listCommand);
+program.addCommand(memoryCommand);
 program.addCommand(skillsCommand);
 program.addCommand(mcpCommand);
 program.addCommand(setupCommand);
@@ -49,15 +51,21 @@ function printIntro(version) {
     console.log("");
     console.log(`     ${sym.arrow()} ${c.bold("Summer Engine")} ${c.dim("v" + version)}  ${c.dim("·")}  AI-native game engine`);
     console.log("");
-    console.log(`     ${c.bold("Get started")}`);
-    console.log(`     ${c.dim("$")} summer setup claude-code      ${c.dim("Configure Claude Code (or codex/cursor/windsurf)")}`);
-    console.log(`     ${c.dim("$")} summer create 3d-basic my-game ${c.dim("Start a project")}`);
-    console.log(`     ${c.dim("$")} summer doctor                  ${c.dim("Check setup")}`);
+    console.log(`     ${c.bold("Setup wizard")}`);
+    console.log(`     Open Claude Code, Cursor, Codex, Copilot, Windsurf, or another supported agent and paste:`);
+    console.log(`     ${c.brand("\"Install Summer Engine and let's make a game.\"")}`);
+    console.log("");
+    console.log(`     ${c.bold("Manual commands")}`);
+    console.log(`     ${c.dim("$")} npx -y summer-engine@latest setup claude-code --yes`);
+    console.log(`     ${c.dim("$")} npx -y summer-engine@latest create 3d-basic my-game`);
+    console.log(`     ${c.dim("$")} npx -y summer-engine@latest memory`);
+    console.log(`     ${c.dim("$")} npx -y summer-engine@latest doctor`);
     console.log("");
     console.log(`     ${c.bold("Slash commands")} ${c.dim("(in your AI agent)")}`);
     console.log(`     ${c.brand("/debug")}   ${c.dim("Triage and fix a bug end-to-end")}`);
     console.log(`     ${c.brand("/play")}    ${c.dim("Run the game and report state")}`);
     console.log("");
     console.log(`     ${c.dim("Docs:")} https://summerengine.com/docs`);
+    console.log(`     ${c.dim("Source:")} https://github.com/SummerEngine/summer`);
     console.log("");
 }

package/dist/commands/create.js

@@ -42,6 +42,7 @@ export const createCommand = new Command("create")
         console.log(`\nProject created at ${fullPath}`);
         console.log("\nNext steps:");
         console.log(`  summer run ${dirName}`);
+        console.log("  Ask your agent to run summer:brainstorm-game to create .summer/GameSoul.md");
         return;
     }
     // Fall back to remote template lookup
@@ -86,6 +87,7 @@ export const createCommand = new Command("create")
     console.log("Source: " + remote.url);
     console.log("\nNext steps:");
     console.log(`  summer run ${dirName}`);
+    console.log("  Ask your agent to run summer:brainstorm-game to create .summer/GameSoul.md");
 });
 function projectGodot(name, mainScene) {
     return `; Summer Engine Project

package/dist/commands/doctor.js

@@ -6,6 +6,8 @@ import { Command } from "commander";
 import { getAuthToken, getUserInfo } from "../lib/auth.js";
 import { checkEngineHealth, getApiPort, getApiToken } from "../lib/engine.js";
 import { brandLine, c, pad, sym, tildeify } from "../lib/format.js";
+import { getProjectMemorySummary } from "../lib/project-memory.js";
+import { buildCliVersionCheck, buildSkillsVersionCheck, defaultSkillMarkerCandidates, fetchLatestRegistryVersion, } from "../lib/version-check.js";
 const require = createRequire(import.meta.url);
 const { version } = require("../../package.json");
 const MAC_ENGINE_PATHS = [
@@ -18,7 +20,7 @@ const WIN_ENGINE_PATHS = [
     `${process.env.PROGRAMFILES}\\Summer Engine\\Summer.exe`,
 ];
 export const doctorCommand = new Command("doctor")
-    .description("Diagnose Node, login, engine, local API, and MCP boot")
+    .description("Diagnose Node, login, engine, project memory, local API, and MCP boot")
     .option("--json", "Print diagnostics as JSON")
     .action(async (opts) => {
     if (!opts.json) {
@@ -42,9 +44,12 @@ export async function runDoctor(options = {}) {
         status: "ok",
         message: `v${version}`,
     });
+    checks.push(await checkCliVersionCurrent());
+    checks.push(checkSkillsVersion());
     checks.push(await checkLogin());
     checks.push(checkEngineInstall());
     checks.push(await checkLocalApi());
+    checks.push(await checkProjectMemory());
     checks.push(await checkMcpBoot());
     const result = summarizeChecks(checks);
     if (!options.quiet) {
@@ -74,6 +79,33 @@ function checkNodeVersion() {
         message: `${process.version} (need 18+)`,
     };
 }
+async function checkCliVersionCurrent() {
+    const registry = await fetchLatestRegistryVersion();
+    const result = buildCliVersionCheck({
+        installedVersion: version,
+        registry,
+    });
+    return {
+        id: "cli-version-current",
+        label: "CLI up to date",
+        status: result.status,
+        message: result.message,
+        details: result.details,
+    };
+}
+function checkSkillsVersion() {
+    const result = buildSkillsVersionCheck({
+        installedCliVersion: version,
+        candidates: defaultSkillMarkerCandidates(),
+    });
+    return {
+        id: "skills-version-stale",
+        label: "Skills up to date",
+        status: result.status,
+        message: result.message,
+        details: result.details,
+    };
+}
 async function checkLogin() {
     const token = await getAuthToken();
     const user = await getUserInfo();
@@ -147,6 +179,44 @@ async function checkLocalApi() {
         },
     };
 }
+async function checkProjectMemory() {
+    const port = await getApiPort();
+    const health = await checkEngineHealth(port);
+    if (!health?.project_path) {
+        return {
+            id: "project-memory",
+            label: "Project Memory",
+            status: "ok",
+            message: "no project open",
+        };
+    }
+    const summary = getProjectMemorySummary(health.project_path);
+    if (!summary.present) {
+        return {
+            id: "project-memory",
+            label: "Project Memory",
+            status: "warning",
+            message: ".summer not created yet",
+            details: {
+                projectPath: health.project_path,
+                reason: summary.reason,
+                recommendedAction: "Ask your agent to run summer:brainstorm-game.",
+            },
+        };
+    }
+    return {
+        id: "project-memory",
+        label: "Project Memory",
+        status: "ok",
+        message: `${summary.files.length} files, ${summary.structured.fileCount} memory, ${summary.structured.lockedCount} locked`,
+        details: {
+            projectPath: health.project_path,
+            files: summary.files.length,
+            memoryFiles: summary.structured.fileCount,
+            locked: summary.structured.lockedCount,
+        },
+    };
+}
 async function checkMcpBoot() {
     const cliPath = process.argv[1];
     if (!cliPath) {

package/dist/commands/install.d.ts

@@ -1,2 +1,19 @@
 import { Command } from "commander";
+/** Guard a download URL from the releases endpoint. A missing/empty URL (an
+ *  outdated or misconfigured endpoint) otherwise becomes a cryptic
+ *  fetch(undefined) failure — surface it clearly with a manual fallback. */
+export declare function requireDownloadUrl(value: string | undefined, label: string): string;
+/** Verify a downloaded file's sha256 against the expected hash from the releases
+ *  endpoint. Skipped when no expected hash is published. Catches a truncated or
+ *  corrupted download (a ~1GB install over a flaky network) before it becomes a
+ *  confusing DMG-mount / installer failure downstream. */
+export declare function verifyChecksum(actual: string, expected: string | undefined, label: string): void;
+/** Velopack Setup.exe install args. Velopack is NOT NSIS: silent install is
+ *  `--silent` and a custom directory is `--installto <dir>` (per Velopack's
+ *  setup.exe CLI). The old NSIS flags (/S, /D=) are rejected by the Velopack
+ *  installer with "unexpected argument '/S' found" — this is the wizard bug. */
+export declare function windowsInstallerArgs(customPath?: string): string;
 export declare const installCommand: Command;
+export declare function downloadFile(url: string, dest: string): Promise<{
+    sha256: string;
+}>;

package/dist/commands/install.js

@@ -1,11 +1,41 @@
 import { Command } from "commander";
 import { execSync } from "child_process";
+import { createHash } from "crypto";
 import { createWriteStream, existsSync, mkdirSync } from "fs";
 import { pipeline } from "stream/promises";
 import { Readable } from "stream";
 import { tmpdir, platform } from "os";
 import { join } from "path";
 const RELEASES_URL = "https://www.summerengine.com/api/desktop/releases";
+/** Guard a download URL from the releases endpoint. A missing/empty URL (an
+ *  outdated or misconfigured endpoint) otherwise becomes a cryptic
+ *  fetch(undefined) failure — surface it clearly with a manual fallback. */
+export function requireDownloadUrl(value, label) {
+    if (!value || value.trim().length === 0) {
+        throw new Error(`Release info is missing the ${label} download URL — the releases endpoint may be ` +
+            `outdated. Download manually from https://summerengine.com/download`);
+    }
+    return value;
+}
+/** Verify a downloaded file's sha256 against the expected hash from the releases
+ *  endpoint. Skipped when no expected hash is published. Catches a truncated or
+ *  corrupted download (a ~1GB install over a flaky network) before it becomes a
+ *  confusing DMG-mount / installer failure downstream. */
+export function verifyChecksum(actual, expected, label) {
+    if (!expected || expected.trim().length === 0)
+        return; // nothing published to verify against
+    if (actual.toLowerCase() !== expected.toLowerCase()) {
+        throw new Error(`${label} checksum mismatch — the download was corrupted or incomplete ` +
+            `(expected ${expected.slice(0, 12)}…, got ${actual.slice(0, 12)}…). Re-run \`summer install\`.`);
+    }
+}
+/** Velopack Setup.exe install args. Velopack is NOT NSIS: silent install is
+ *  `--silent` and a custom directory is `--installto <dir>` (per Velopack's
+ *  setup.exe CLI). The old NSIS flags (/S, /D=) are rejected by the Velopack
+ *  installer with "unexpected argument '/S' found" — this is the wizard bug. */
+export function windowsInstallerArgs(customPath) {
+    return customPath ? `--silent --installto "${customPath}"` : "--silent";
+}
 export const installCommand = new Command("install")
     .description("Download and install Summer Engine")
     .option("--path <dir>", "Custom install directory")
@@ -42,6 +72,7 @@ async function installMac(releases, customPath) {
         console.error("No macOS release found.");
         process.exit(1);
     }
+    const dmgUrl = requireDownloadUrl(info.dmg_url, "macOS DMG");
     console.log(`Latest version: ${info.version}`);
     const destApp = customPath || "/Applications/Summer.app";
     if (existsSync(destApp)) {
@@ -50,7 +81,18 @@ async function installMac(releases, customPath) {
     }
     const dmgPath = join(tmpdir(), `Summer-v${info.version}.dmg`);
     console.log(`Downloading Summer Engine v${info.version} (~1 GB, includes bundled Git + runtime)...`);
-    await downloadFile(info.dmg_url, dmgPath);
+    try {
+        const { sha256 } = await downloadFile(dmgUrl, dmgPath);
+        verifyChecksum(sha256, info.dmg_sha256, "DMG");
+    }
+    catch (err) {
+        try {
+            execSync(`rm -f "${dmgPath}"`, { stdio: "ignore" });
+        }
+        catch { /* best effort */ }
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
     console.log("Mounting DMG...");
     const mountOutput = execSync(`hdiutil attach "${dmgPath}" -nobrowse -noverify -noautoopen`, {
         encoding: "utf-8",
@@ -88,13 +130,25 @@ async function installWindows(releases, customPath) {
         console.error("No Windows release found.");
         process.exit(1);
     }
+    const exeUrl = requireDownloadUrl(info.url, "Windows installer");
     console.log(`Latest version: ${info.version}`);
     const exePath = join(tmpdir(), `Summer-v${info.version}.exe`);
     console.log(`Downloading Summer Engine v${info.version} (~1 GB, includes bundled Git + runtime)...`);
-    await downloadFile(info.url, exePath);
+    try {
+        const { sha256 } = await downloadFile(exeUrl, exePath);
+        verifyChecksum(sha256, info.sha256, "installer");
+    }
+    catch (err) {
+        try {
+            execSync(`del "${exePath}"`, { stdio: "ignore" });
+        }
+        catch { /* best effort */ }
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
     console.log("Running installer...");
     try {
-        execSync(`"${exePath}" /S${customPath ? ` /D=${customPath}` : ""}`, {
+        execSync(`"${exePath}" ${windowsInstallerArgs(customPath)}`, {
             stdio: "inherit",
         });
     }
@@ -111,7 +165,7 @@ async function installWindows(releases, customPath) {
     console.log("  summer login    # Sign in to your account");
     console.log("  summer run      # Launch the engine");
 }
-async function downloadFile(url, dest) {
+export async function downloadFile(url, dest) {
     const res = await fetch(url);
     if (!res.ok || !res.body) {
         throw new Error(`Download failed: HTTP ${res.status}`);
@@ -121,9 +175,13 @@ async function downloadFile(url, dest) {
         mkdirSync(dir, { recursive: true });
     const fileStream = createWriteStream(dest);
     const readable = Readable.fromWeb(res.body);
+    // Hash while streaming (the 'data' listener and the pipe both see every chunk
+    // in flowing mode), so we get integrity for free without a second read pass.
+    const hash = createHash("sha256");
     let downloaded = 0;
     const total = parseInt(res.headers.get("content-length") || "0", 10);
     readable.on("data", (chunk) => {
+        hash.update(chunk);
         downloaded += chunk.length;
         if (total > 0) {
             const pct = Math.round((downloaded / total) * 100);
@@ -132,4 +190,5 @@ async function downloadFile(url, dest) {
     });
     await pipeline(readable, fileStream);
     process.stdout.write("\n");
+    return { sha256: hash.digest("hex") };
 }

package/dist/commands/memory.d.ts

@@ -0,0 +1,14 @@
+import { Command } from "commander";
+import { type ProjectMemorySummary } from "../lib/project-memory.js";
+interface ResolvedMemoryProject {
+    projectPath: string | null;
+    source: "option" | "engine" | "cwd" | "none";
+    reason?: string;
+}
+export declare const memoryCommand: Command;
+export declare function resolveMemoryProject(projectOption?: string): Promise<ResolvedMemoryProject>;
+export declare function findProjectRoot(startDir: string): string | null;
+export declare function resolveMemoryFilePath(projectPath: string, requested: string): string;
+export declare function formatMemorySummary(projectPath: string, summary: ProjectMemorySummary): string;
+export declare function formatStatusMemoryLine(summary: ProjectMemorySummary): string;
+export {};

package/dist/commands/memory.js

@@ -0,0 +1,196 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { Command } from "commander";
+import { checkEngineHealth, getApiPort } from "../lib/engine.js";
+import { getProjectMemorySummary, } from "../lib/project-memory.js";
+import { c, pad, tildeify } from "../lib/format.js";
+export const memoryCommand = new Command("memory")
+    .description("Inspect project memory in .summer")
+    .option("--project <path>", "Project directory to inspect")
+    .option("--json", "Print memory summary as JSON")
+    .action(async (opts) => {
+    const resolvedProject = await resolveMemoryProject(opts.project);
+    if (!resolvedProject.projectPath) {
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: false, ...resolvedProject }, null, 2));
+        }
+        else {
+            console.error(resolvedProject.reason ?? "Could not find a Summer project.");
+            console.error("Run from a project directory, pass --project <path>, or start Summer Engine.");
+        }
+        process.exit(1);
+    }
+    const summary = getProjectMemorySummary(resolvedProject.projectPath);
+    if (opts.json) {
+        console.log(JSON.stringify({
+            ok: true,
+            projectPath: resolvedProject.projectPath,
+            source: resolvedProject.source,
+            memory: summary,
+        }, null, 2));
+        return;
+    }
+    console.log(formatMemorySummary(resolvedProject.projectPath, summary));
+});
+memoryCommand
+    .command("show <file>")
+    .description("Print a .summer memory Markdown file")
+    .option("--project <path>", "Project directory to inspect")
+    .action(async (file, opts) => {
+    const resolvedProject = await resolveMemoryProject(opts.project);
+    if (!resolvedProject.projectPath) {
+        console.error(resolvedProject.reason ?? "Could not find a Summer project.");
+        console.error("Run from a project directory, pass --project <path>, or start Summer Engine.");
+        process.exit(1);
+    }
+    const filePath = resolveMemoryFilePath(resolvedProject.projectPath, file);
+    console.log(readFileSync(filePath, "utf-8"));
+});
+memoryCommand
+    .command("path")
+    .description("Print the .summer directory path for the current project")
+    .option("--project <path>", "Project directory to inspect")
+    .action(async (opts) => {
+    const resolvedProject = await resolveMemoryProject(opts.project);
+    if (!resolvedProject.projectPath) {
+        console.error(resolvedProject.reason ?? "Could not find a Summer project.");
+        console.error("Run from a project directory, pass --project <path>, or start Summer Engine.");
+        process.exit(1);
+    }
+    console.log(join(resolvedProject.projectPath, ".summer"));
+});
+export async function resolveMemoryProject(projectOption) {
+    if (projectOption) {
+        const projectPath = resolve(projectOption);
+        if (!existsSync(projectPath)) {
+            return {
+                projectPath: null,
+                source: "option",
+                reason: `Project directory not found: ${projectPath}`,
+            };
+        }
+        if (!existsSync(join(projectPath, "project.godot"))) {
+            return {
+                projectPath: null,
+                source: "option",
+                reason: `No project.godot found in ${projectPath}.`,
+            };
+        }
+        return { projectPath, source: "option" };
+    }
+    const cwdProject = findProjectRoot(process.cwd());
+    if (cwdProject)
+        return { projectPath: cwdProject, source: "cwd" };
+    const port = await getApiPort();
+    const health = await checkEngineHealth(port);
+    if (health?.project_path && existsSync(join(health.project_path, "project.godot"))) {
+        return { projectPath: health.project_path, source: "engine" };
+    }
+    return {
+        projectPath: null,
+        source: "none",
+        reason: "No Summer project found from engine state or current directory.",
+    };
+}
+export function findProjectRoot(startDir) {
+    let current = resolve(startDir);
+    while (true) {
+        if (existsSync(join(current, "project.godot")))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+export function resolveMemoryFilePath(projectPath, requested) {
+    const summerDir = resolve(projectPath, ".summer");
+    const rawPath = requested.startsWith(".summer/")
+        ? resolve(projectPath, requested)
+        : resolve(summerDir, requested);
+    const withinSummer = isPathInside(summerDir, rawPath);
+    if (!withinSummer) {
+        throw new Error("Memory files must be inside the project's .summer directory.");
+    }
+    if (!existsSync(rawPath)) {
+        throw new Error(`Memory file not found: ${requested}`);
+    }
+    if (!statSync(rawPath).isFile()) {
+        throw new Error(`Memory path is not a file: ${requested}`);
+    }
+    return rawPath;
+}
+export function formatMemorySummary(projectPath, summary) {
+    const lines = [];
+    lines.push(c.bold("Project Memory"));
+    lines.push("");
+    lines.push(`  Project: ${tildeify(projectPath)}`);
+    lines.push(`  Folder:  ${tildeify(join(projectPath, ".summer"))}`);
+    lines.push("");
+    if (!summary.present) {
+        lines.push(`  ${summary.reason ?? "No .summer memory found yet."}`);
+        lines.push("");
+        lines.push("  Agents create this through Summer skills.");
+        lines.push("  Start with .summer/GameSoul.md for the project brief.");
+        lines.push("  Use .summer/memory/ for locked facts like voice IDs and world canon.");
+        return lines.join("\n");
+    }
+    const totalFiles = summary.files.length;
+    const structured = summary.structured;
+    lines.push(`  Status:  ${totalFiles} .summer Markdown file${totalFiles === 1 ? "" : "s"}, ` +
+        `${structured.fileCount} structured memory file${structured.fileCount === 1 ? "" : "s"}, ` +
+        `${structured.lockedCount} locked`);
+    lines.push("");
+    const canonicalRows = canonicalRowsFromSummary(summary);
+    if (canonicalRows.length > 0) {
+        lines.push(c.bold("Canonical"));
+        for (const [label, file] of canonicalRows) {
+            lines.push(formatMemoryFileLine(label, file));
+        }
+        lines.push("");
+    }
+    if (structured.files.length > 0) {
+        lines.push(c.bold("Structured"));
+        for (const file of structured.files) {
+            lines.push(formatMemoryFileLine(file.kind, file));
+        }
+        if (structured.truncated) {
+            lines.push("  ...more files omitted from summary");
+        }
+        lines.push("");
+    }
+    lines.push("Read a file:");
+    lines.push("  summer memory show .summer/memory/casting/voices.md");
+    lines.push("");
+    lines.push("Rule:");
+    lines.push("  Markdown is canonical. Changing priority: locked memory requires explicit user confirmation.");
+    return lines.join("\n");
+}
+export function formatStatusMemoryLine(summary) {
+    if (!summary.present)
+        return "Memory: No .summer folder yet";
+    const fileCount = summary.files.length;
+    const structuredCount = summary.structured.fileCount;
+    const lockedCount = summary.structured.lockedCount;
+    return `Memory: ${fileCount} .summer file${fileCount === 1 ? "" : "s"}, ${structuredCount} memory file${structuredCount === 1 ? "" : "s"}, ${lockedCount} locked`;
+}
+function canonicalRowsFromSummary(summary) {
+    const rows = [
+        ["brief", summary.canonical.gameSoul],
+        ["art", summary.canonical.artBible],
+        ["audio", summary.canonical.audioBible],
+        ["build", summary.canonical.buildPlan],
+        ["legacy-casting", summary.canonical.legacyVoiceCast],
+    ];
+    return rows.filter((row) => row[1] !== null);
+}
+function formatMemoryFileLine(label, file) {
+    const lock = file.locked ? "locked" : "";
+    const title = file.title ? ` - ${file.title}` : "";
+    return `  ${pad(label, 15)} ${pad(file.path, 42)} ${lock}${title}`;
+}
+function isPathInside(parent, child) {
+    const relativePath = relative(parent, child);
+    return (relativePath === "" ||
+        (!relativePath.startsWith("..") && !isAbsolute(relativePath)));
+}