@amoree-code/ocean 0.0.0-stage → 1.1.0

package/dist/interfaces/cli/context-command.js

@@ -0,0 +1,172 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { DEFAULT_CONTEXT_BUDGET, measureContextCost, } from "@ocean/context/context/context-cost.js";
+import { BRAIN_RECORD_DIRS, oceanRoot, PERSONAL_DIR, PROJECTS_DIR, projectDir, SYSTEM_DIR, } from "@ocean/core/shared/paths.js";
+import { projectRules, projectVerify, readProjectManifest, resolveProject, } from "@ocean/core/shared/project-resolution.js";
+import { z } from "zod";
+import { oceanVersion } from "../../version.js";
+import { listTasks } from "./tasks-command.js";
+// The MEMORY.md files a session in this project reads: the personal index, then the project's.
+async function existingMemoryFiles(project) {
+    const candidates = [path.posix.join(PERSONAL_DIR, "MEMORY.md")];
+    if (project)
+        candidates.push(path.posix.join(projectDir(project), "MEMORY.md"));
+    const found = [];
+    for (const relative of candidates) {
+        try {
+            if ((await stat(path.join(oceanRoot(), relative))).isFile())
+                found.push(relative);
+        }
+        catch {
+            // Missing is normal.
+        }
+    }
+    return found;
+}
+export async function runContextCommand(json = false) {
+    const version = await oceanVersion();
+    const resolution = await resolveProject(process.cwd());
+    const project = resolution.status === "bound" ? resolution.projectId : null;
+    const tasks = project
+        ? (await listTasks(undefined, project)).filter((task) => task.state === "active" || task.state === "blocked")
+        : [];
+    // Unreadable rules are shown as such, never as an empty list.
+    const problems = [];
+    const manifest = project
+        ? await readProjectManifest(project).catch((error) => {
+            problems.push(error instanceof Error ? error.message : String(error));
+            return null;
+        })
+        : null;
+    const read = (load) => {
+        try {
+            return manifest ? load(manifest) : [];
+        }
+        catch (error) {
+            problems.push(error instanceof Error ? error.message : String(error));
+            return [];
+        }
+    };
+    const rules = read(projectRules);
+    const verify = read(projectVerify);
+    const context = {
+        project,
+        projectResolution: resolution,
+        rules,
+        verify,
+        ...(problems.length ? { problems } : {}),
+        version,
+        roots: [...BRAIN_RECORD_DIRS, PROJECTS_DIR, SYSTEM_DIR],
+        memory: await existingMemoryFiles(project),
+        tasks,
+    };
+    if (json) {
+        console.log(JSON.stringify(context, null, 2));
+        return;
+    }
+    console.log(`Ocean context\nversion: ${version}\nroots: ${[...BRAIN_RECORD_DIRS, PROJECTS_DIR, SYSTEM_DIR].join(", ")}`);
+    if (resolution.status !== "bound")
+        console.log(`project: ${resolution.status} — no Ocean binding for this directory; run 'ocean project bind <name> <path>'`);
+    else
+        console.log(`project: ${resolution.projectId} (confidence: ${resolution.confidence})`);
+    if (rules.length)
+        console.log(`rules:\n${rules.map((rule) => `- ${rule}`).join("\n")}`);
+    if (verify.length)
+        console.log(`verify:\n${verify.map((command) => `- ${command}`).join("\n")}`);
+    for (const problem of problems)
+        console.log(`unreadable: ${problem}`);
+    console.log(`memory: ${context.memory.join(", ") || "none"}`);
+    if (!tasks.length)
+        console.log("active tasks: none");
+    else
+        for (const task of tasks)
+            console.log(`${task.id} [${task.state}] ${task.title} — ${task.goal}`);
+}
+const costUsage = "Usage: ocean context cost [--json] [--budget <bytes>] [--project <dir>]";
+const budgetSchema = z.coerce.number().int().positive();
+function parseCostArgs(args) {
+    let json = false;
+    let budget = DEFAULT_CONTEXT_BUDGET;
+    let project = process.cwd();
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--budget" || arg === "--project") {
+            const value = args[index + 1];
+            if (value === undefined || value.startsWith("--"))
+                return null;
+            index += 1;
+            if (arg === "--project")
+                project = value;
+            else {
+                const parsed = budgetSchema.safeParse(value);
+                if (!parsed.success)
+                    return null;
+                budget = parsed.data;
+            }
+        }
+        else
+            return null;
+    }
+    return { json, budget, project: path.resolve(project) };
+}
+function costStatus(client) {
+    if (!client.skills.present &&
+        client.rules.every((file) => file.missing) &&
+        client.memory.every((file) => file.missing))
+        return "absent";
+    return client.overBudget ? "OVER" : "ok";
+}
+// `ocean context cost`: a read-only report of each client's always-on context bytes. Exits 0
+// even when a client is over budget — it is a report, not a gate.
+export async function runContextCostCommand(args) {
+    const options = parseCostArgs(args);
+    if (!options) {
+        console.error(costUsage);
+        process.exitCode = 1;
+        return;
+    }
+    const report = await measureContextCost({
+        projectDir: options.project,
+        budget: options.budget,
+    });
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    const sum = (files) => files.reduce((total, file) => total + file.bytes, 0);
+    const header = [
+        "client",
+        "rules",
+        "memory",
+        "skills",
+        "skill-fm",
+        "skill-body",
+        "always-on",
+        "status",
+    ];
+    const rows = report.clients.map((client) => [
+        client.shared ? `${client.client} (shared)` : client.client,
+        String(sum(client.rules)),
+        String(sum(client.memory)),
+        String(client.skills.count),
+        String(client.skills.frontmatterBytes),
+        String(client.skills.bodyBytes),
+        String(client.alwaysOnBytes),
+        costStatus(client),
+    ]);
+    const widths = header.map((title, column) => Math.max(title.length, ...rows.map((row) => row[column].length)));
+    const format = (cells) => cells.map((cell, column) => cell.padEnd(widths[column])).join("  ");
+    console.log(`Always-on context by client (budget ${report.budget} bytes)`);
+    console.log(format(header));
+    report.clients.forEach((client, index) => {
+        console.log(format(rows[index]));
+        for (const file of [...client.rules, ...client.memory, ...client.extras])
+            console.log(`  ${file.path} ${file.bytes}${file.via ? ` (via ${file.via})` : ""}${file.missing ? " missing" : ""}${file.unreadable ? " unreadable" : ""}`);
+        console.log(`  skills: ${client.skills.root}${client.skills.present ? "" : " absent"}${client.skills.hidden ? ` (${client.skills.hidden} hidden from the model, ${client.skills.hiddenFrontmatterBytes} bytes not loaded)` : ""}`);
+        for (const note of client.notes)
+            console.log(`  note: ${note}`);
+    });
+}
+//# sourceMappingURL=context-command.js.map

package/dist/interfaces/cli/daily-command.js

@@ -0,0 +1,131 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+import { listLessons, setLessonStatus } from "@ocean/brain/memory/lessons.js";
+import { withFileLock } from "@ocean/core/shared/fs-utils.js";
+import { localDate } from "@ocean/core/shared/local-date.js";
+import { DAILY_DIR, oceanPath } from "@ocean/core/shared/paths.js";
+import { openSessionStore } from "@ocean/loop/infrastructure/persistence/session-store.js";
+import { listTasks } from "./tasks-command.js";
+/**
+ * Interactive human-in-the-loop gate for candidate lessons (see lessons.ts). Only runs on a
+ * real TTY, so headless and scheduled invocations of `ocean daily start` never block on input.
+ */
+const lessonGateLimit = 5;
+async function runLessonGate() {
+    if (!(process.stdin.isTTY && process.stdout.isTTY))
+        return;
+    const allPending = await listLessons({ status: "candidate" });
+    if (!allPending.length)
+        return;
+    const pending = allPending.slice(-lessonGateLimit);
+    const prompt = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        console.log(allPending.length > pending.length
+            ? `\n🤖 Ocean: ${pending.length} most recent of ${allPending.length} candidate lesson(s) awaiting review.`
+            : `\n🤖 Ocean: ${pending.length} candidate lesson(s) awaiting review.`);
+        for (const lesson of pending) {
+            console.log(`\n[${lesson.hits} verified hit(s)] ${lesson.title}`);
+            const answer = (await prompt.question("Activate this lesson? (y = activate, n = retire, Enter = later): "))
+                .trim()
+                .toLowerCase();
+            // Only an explicit answer changes anything: Enter or EOF leaves it a candidate.
+            if (answer !== "y" && answer !== "n") {
+                console.log("→ left as candidate");
+                continue;
+            }
+            await setLessonStatus(lesson.id, answer === "y" ? "active" : "retired");
+            console.log(answer === "y" ? "→ active" : "→ retired");
+        }
+    }
+    finally {
+        prompt.close();
+    }
+}
+export async function runDailyCommand(action, args) {
+    if (action !== "start") {
+        console.error("Usage: ocean daily start [--apply] [--news <bounded-news-summary>]");
+        process.exitCode = 1;
+        return;
+    }
+    await runLessonGate();
+    const apply = args.includes("--apply");
+    const newsIndex = args.indexOf("--news");
+    const news = newsIndex >= 0
+        ? args
+            .slice(newsIndex + 1)
+            .join(" ")
+            .slice(0, 4_000)
+        : "";
+    const tasks = await listTasks();
+    const store = await openSessionStore();
+    let sessions;
+    try {
+        sessions = store
+            .list()
+            .slice(0, 5)
+            .map((session) => ({
+            sessionId: session.sessionId,
+            title: session.title,
+            provider: session.provider,
+            status: session.status,
+            nextAction: session.nextAction,
+        }));
+    }
+    finally {
+        store.close();
+    }
+    const date = localDate();
+    const file = oceanPath(DAILY_DIR, `${date}.md`);
+    const content = `${[
+        `# Daily brief — ${date}`,
+        "",
+        "## Brief",
+        "",
+        tasks.length
+            ? tasks
+                .map((task) => `- ${task.id}: ${task.title} — ${task.goal}`)
+                .join("\n")
+            : "- No active tasks.",
+        "",
+        "## Check-in",
+        "",
+        sessions.length
+            ? sessions
+                .map((session) => `- ${session.sessionId}: ${session.title || session.provider} — ${session.status}${session.nextAction ? `; next: ${session.nextAction}` : ""}`)
+                .join("\n")
+            : "- No recent sessions.",
+        "",
+        "## News",
+        "",
+        news ||
+            "- No news supplied. The active AI client may research only the requested topics and pass a bounded summary with `--news`.",
+    ]
+        .join("\n")
+        .slice(0, 12_000)}\n`;
+    if (apply) {
+        await mkdir(path.dirname(file), { recursive: true });
+        // Same lock as the session-closeout writers: a closeout landing between the check and
+        // the write would otherwise be overwritten (T-257).
+        await withFileLock(file, async () => {
+            const existing = await readFile(file, "utf8").catch(() => "");
+            if (existing.trim())
+                throw new Error(`Daily file already has content: ${file}`);
+            await writeFile(file, content, "utf8");
+        });
+    }
+    console.log(JSON.stringify({
+        apply,
+        date,
+        file,
+        bytes: Buffer.byteLength(content),
+        tasks: tasks.length,
+        sessions: sessions.length,
+        news: Boolean(news),
+        content,
+    }, null, 2));
+}
+//# sourceMappingURL=daily-command.js.map

package/dist/interfaces/cli/governance-command.js

@@ -0,0 +1,55 @@
+import { readdir, readFile } from "node:fs/promises";
+import { CHARTER_DIR, oceanPath, POLICIES_DIR, resolveWithin, } from "@ocean/core/shared/paths.js";
+const policyRoot = () => oceanPath(POLICIES_DIR);
+const rulesFile = () => oceanPath(CHARTER_DIR, "core.md");
+async function policyNames() {
+    return (await readdir(policyRoot(), { withFileTypes: true }))
+        .filter((entry) => entry.isFile() &&
+        entry.name.endsWith(".md") &&
+        entry.name !== "README.md")
+        .map((entry) => entry.name.slice(0, -3))
+        .sort();
+}
+export async function runPolicyCommand(name = "list") {
+    const names = await policyNames();
+    if (name === "list") {
+        console.log(JSON.stringify({ policies: names }, null, 2));
+        return;
+    }
+    if (name === "doctor") {
+        const core = await readFile(rulesFile(), "utf8");
+        const referenced = new Set([...core.matchAll(/ocean policy ([a-z-]+)/g)]
+            .map((match) => match[1])
+            .filter((item) => item !== "list"));
+        const missing = [...referenced].filter((item) => !names.includes(item));
+        console.log(JSON.stringify({ ok: missing.length === 0, policies: names.length, missing }, null, 2));
+        if (missing.length)
+            process.exitCode = 1;
+        return;
+    }
+    if (!/^[a-z][a-z-]*$/.test(name) || !names.includes(name))
+        throw new Error(`Unknown policy: ${name}`);
+    process.stdout.write(await readFile(resolveWithin(policyRoot(), `${name}.md`), "utf8"));
+}
+export async function runLifecycleCommand(args) {
+    const taskIndex = args.indexOf("--task");
+    const taskId = taskIndex >= 0 ? args[taskIndex + 1] : undefined;
+    const verificationIndex = args.indexOf("--verification");
+    const verification = verificationIndex >= 0 ? args[verificationIndex + 1] : undefined;
+    const complete = args.includes("--complete");
+    const decision = complete && verification === "passed" ? "CHECKPOINT" : "CONTINUE";
+    const result = {
+        decision,
+        taskId: taskId ?? null,
+        complete,
+        verification: verification ?? "unknown",
+        reason: decision === "CHECKPOINT"
+            ? "completed work with passing verification must be persisted"
+            : "no verified completion boundary was supplied",
+    };
+    if (args.includes("--json"))
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(`${result.decision}: ${result.reason}`);
+}
+//# sourceMappingURL=governance-command.js.map

package/dist/interfaces/cli/handoff-command.js

@@ -0,0 +1,35 @@
+import { createHandoff, getHandoff, listHandoffs, } from "@ocean/loop/handoff/handoff-service.js";
+import { defaultSessionStoreFactory } from "../../composition/runtime.js";
+export async function runHandoffCommand(action, args) {
+    if (action === "create") {
+        const taskIndex = args.indexOf("--task");
+        const sessionIndex = args.indexOf("--session");
+        const nextIndex = args.indexOf("--next");
+        const providerIndex = args.indexOf("--provider");
+        const handoff = await createHandoff({
+            taskId: taskIndex >= 0 ? args[taskIndex + 1] : undefined,
+            sessionId: sessionIndex >= 0 ? args[sessionIndex + 1] : undefined,
+            nextAction: nextIndex >= 0 ? args.slice(nextIndex + 1).join(" ") : undefined,
+            provider: providerIndex >= 0 ? args[providerIndex + 1] : undefined,
+        }, defaultSessionStoreFactory);
+        console.log(JSON.stringify(handoff, null, 2));
+        return;
+    }
+    if (action === "show" || action === "context") {
+        const id = args[0];
+        if (!id)
+            throw new Error(`Usage: ocean handoff ${action} <handoff-id>`);
+        const handoff = await getHandoff(id, defaultSessionStoreFactory, action === "context" ? 8_000 : 16_000);
+        console.log(JSON.stringify(handoff, null, 2));
+        return;
+    }
+    if (action === "list") {
+        const taskIndex = args.indexOf("--task");
+        const projectIndex = args.indexOf("--project");
+        console.log(JSON.stringify(await listHandoffs(defaultSessionStoreFactory, taskIndex >= 0 ? args[taskIndex + 1] : undefined, projectIndex >= 0 ? args[projectIndex + 1] : undefined), null, 2));
+        return;
+    }
+    console.error("Usage: ocean handoff create [--task <id>] [--session <id>] [--next <action>]|show <id>|context <id>|list [--task <id>] [--project <id>]");
+    process.exitCode = 1;
+}
+//# sourceMappingURL=handoff-command.js.map

package/dist/interfaces/cli/help-command.js

@@ -0,0 +1,207 @@
+const commandGroups = [
+    [
+        "Workspace",
+        "setup, onboard, context, project, tasks, loop, policy, lifecycle, doctor, repair",
+    ],
+    [
+        "Execution",
+        "run, profiles, session, service, intercept, operate, intent, gateway, schedule",
+    ],
+    [
+        "Providers",
+        "client, clients, install, update, remove, auth, mcp, market, browser",
+    ],
+    [
+        "Knowledge",
+        "memory, pull, observe, capture, handoff, idea, daily, skill, catalog",
+    ],
+    ["Integrations", "obsidian, hook, migrate, layout, env"],
+];
+export function renderHelp() {
+    const groups = commandGroups
+        .map(([label, commands]) => `  ${label.padEnd(12)} ${commands}`)
+        .join("\n");
+    return `Usage: ocean <command> [options]\n\nCommands:\n${groups}\n\nGlobal options:\n  -h, --help     Show this help\n  -v, --version  Show the installed version\n\nRun \`ocean <command> --help\` for one command's usage.`;
+}
+// One entry per command in commandRegistry (a test keeps the two in step): what it does, and
+// its usage line as the command itself prints it on a bad argument.
+export const commandHelp = {
+    setup: [
+        "Create the private workspace, the AI CLI shims, the shell profile entry and the login service.",
+        "ocean setup [--obsidian <vault-path>] [--read-write]",
+    ],
+    onboard: [
+        "Run the pending first-run steps; --status only shows them.",
+        "ocean onboard [--yes] [--status] [--reset <step>]",
+    ],
+    context: [
+        "Print the workspace context for the current folder, or each client's always-on context cost.",
+        "ocean context [--json] | cost [--json] [--budget <bytes>] [--project <dir>]",
+    ],
+    project: [
+        "Resolve, bind, register, rename and index projects.",
+        "ocean project resolve [path]|bind <name> <path> [--add]|register [path]|unbind <path>|rename <id> <new-id>|list|migrate [--write]|index [--write]",
+    ],
+    tasks: [
+        "List, create, claim, checkpoint, verify and complete tasks.",
+        "ocean tasks list [state] [--project <id>] [--pretty]|new <title> [--project <id>]|doctor [--all]|index [--write]|checkpoint <id> --note <text> [--next <text>]|verify <id>|complete <id>|claim <id> --by <name> [--paths a,b] [--force]|release <id> [--by <name>] [--force]|archive [--apply|--auto]|renumber --project <id> --prefix <PREFIX> [--write]",
+    ],
+    loop: [
+        "Start, inspect and stop task loops (repeated agent runs on one task).",
+        "ocean loop start <task-id> <profile> --prompt <text> --approve [--max-iterations N] [--interval-ms N] [--max-attempts N]|status|stop <loop-id>|worker-once|worker",
+    ],
+    policy: [
+        "List the charter's policies, check them, or print one.",
+        "ocean policy [list|doctor|<name>]",
+    ],
+    lifecycle: [
+        "Decide whether a unit of work should checkpoint now.",
+        "ocean lifecycle [--task <id>] [--verification <result>] [--complete] [--json]",
+    ],
+    doctor: [
+        "Check the workspace, clients and integrations; exits 1 on any FAIL.",
+        "ocean doctor [--json]",
+    ],
+    repair: [
+        "Show what doctor can fix; --apply fixes it.",
+        "ocean repair [--apply]",
+    ],
+    run: [
+        "Run a headless agent with a profile and record the session.",
+        "ocean run --profile <name> [--client <client>] [--task <id>] [--handoff <id>] --prompt <text>",
+    ],
+    profiles: [
+        "Validate, upgrade or suggest agent profiles.",
+        "ocean profiles validate | upgrade --check | --apply | --rollback | suggest --task <id> [--profile <name>]",
+    ],
+    session: [
+        "List, show, resume, promote and compact recorded sessions.",
+        "ocean session list|show <session-id>|summary <session-id>|events <session-id>|resume <session-id> <prompt>|promote <session-id> [knowledge/<kind>] --approve|doctor [hours] [--apply]|compact [--keep-days N] [--simulate]|compact --apply --before <iso> --plan <fingerprint>",
+    ],
+    service: [
+        "Run the background service in the foreground (setup's login entry starts it).",
+        "ocean service",
+    ],
+    intercept: [
+        "Run an AI CLI through Ocean's session capture (the shims call this).",
+        "ocean intercept --client <provider> -- [args]",
+    ],
+    operate: [
+        "Classify a plain-language request and run the matching Ocean operation.",
+        "ocean operate <text> | -- <text containing -h>",
+    ],
+    intent: [
+        "Classify a plain-language request without running anything.",
+        "ocean intent classify <text>",
+    ],
+    gateway: [
+        "Serve the local webhook gateway on 127.0.0.1 (needs OCEAN_GATEWAY_TOKEN).",
+        "ocean gateway",
+    ],
+    schedule: [
+        "Add, list and run scheduled agent runs.",
+        "ocean schedule list|add <id> <profile> <interval-ms> <prompt>|enable|disable|run-due|run-now|worker-once|worker",
+    ],
+    client: [
+        "Inspect, open, register and sync AI clients.",
+        "ocean client list|status|test [provider] [--json]|open <provider> [provider-args] [-- provider-args]|vscode-wrapper [--settings <path>] [--apply]|sync|register <id> [command]|enable <id>|disable <id>|manage|doctor [absolute-provider-path]",
+    ],
+    clients: [
+        "Connect installed AI clients to Ocean's MCP server and hooks; apply shows the plan until --yes.",
+        "ocean clients detect|plan [--json] | apply [--client <id>…] [--yes] | verify [<id>…] | confirm <id>… --label in-app|headless|connected|blocked [--via <evidence>] [--reason <why>] | ledger | repair | restore [--batch <id>]",
+    ],
+    install: [
+        "Install a supported AI client CLI.",
+        "ocean install <client> [--yes]",
+    ],
+    update: ["Update an installed AI client CLI.", "ocean update <client> --yes"],
+    remove: ["Remove an installed AI client CLI.", "ocean remove <client> --yes"],
+    auth: [
+        "Show or start an AI client's login.",
+        "ocean auth status|login <client>",
+    ],
+    mcp: [
+        "Print MCP client configs, or serve Ocean's MCP server and gateway.",
+        "ocean mcp config|playwright-config|gateway-config|browser-config|browser-bridge|browser-service install|uninstall|serve|gateway",
+    ],
+    market: [
+        "List, install, update and run marketplace packages; permissions need --yes.",
+        "ocean market list|install <name> [--version <v>]|update <name>|uninstall <name>|exec <name> [--index <file>]... [--yes] [--accept-flagged]",
+    ],
+    browser: [
+        "Drive a browser session; uploads and submits need --approve.",
+        "ocean browser detect|open|show|events|close|approve|navigate|read|observe|extract|click|type|replace-text|select|scroll|wait|upload|download|submit|run",
+    ],
+    memory: [
+        "Search, read, review and maintain memory records and the brain index.",
+        "ocean memory doctor|sync [--apply]|review [list|approve <id> [--to <path>]|reject <id>]|eval <questions.json> [--k N] [--min R]|digest|harvest [--source <id>] [--yes]|import-claude <export-dir> [--yes]|history [path] [--limit N]|restore <id> [--hash <sha256>]|delete <path> --hash <sha256>|purge [--days N] [--yes]|facts <profile> [key] [value]|facts <profile> delete <key>|reindex [--no-vectors]|search <q> [--project <id>|--all] [--json]|read <id|path>|neighbors <id|path> [--depth N] [--project <id>|--all]",
+    ],
+    pull: [
+        "Pull what AI clients hold into Ocean as review candidates; a dry run until --yes.",
+        "ocean pull [--yes] [--daily] | search [words…] [--project <id>] [--client <id>] [--limit N] [--json] | report",
+    ],
+    observe: [
+        "Run a command and record its output, or show a recording.",
+        "ocean observe -- <command> [args] | show <id> [--grep <pattern>]",
+    ],
+    capture: [
+        "Capture ideas and promote or discard them.",
+        "ocean capture add <idea>|scan [session-id]|list [status]|promote <id> <target>|discard <id>",
+    ],
+    handoff: [
+        "Create, show and list handoffs between sessions.",
+        "ocean handoff create [--task <id>] [--session <id>] [--next <action>]|show <id>|context <id>|list [--task <id>] [--project <id>]",
+    ],
+    idea: [
+        "Save, list, classify and discard ideas.",
+        "ocean idea save <title> <content> [--session <id>]|list [status]|classify <id> <target>|discard <id>",
+    ],
+    daily: [
+        "Prepare today's daily note; --apply writes it.",
+        "ocean daily start [--apply] [--news <bounded-news-summary>]",
+    ],
+    skill: [
+        "Sync, list, add, review and learn skills.",
+        "ocean skill sync|doctor|list [status|id]|observe [session-id]|add <id> <name> <instructions>|review <id> promoted|rejected|learn <session-id>|migrate",
+    ],
+    catalog: [
+        "List the AI clients Ocean can install, with their installers.",
+        "ocean catalog",
+    ],
+    obsidian: [
+        "Connect, sync and write to an Obsidian vault (read-only unless --read-write).",
+        "ocean obsidian connect <vault-path> [--read-write]|discover|sync|watch|inbox|write|conflicts resolve <id> --keep=vault|ocean",
+    ],
+    hook: [
+        "Session hooks the AI clients call; session-end reads its payload from stdin.",
+        "ocean hook session-start [--client <client>] [--repair] | session-end [--client <client>]",
+    ],
+    migrate: [
+        "Migrate the session store; a dry run until --apply.",
+        "ocean migrate [--apply]",
+    ],
+    layout: [
+        "Plan, apply or roll back the workspace layout move.",
+        "ocean layout plan | apply --yes | rollback --yes",
+    ],
+    env: [
+        "Print the shell line that puts Ocean's shim folder on PATH; writes nothing.",
+        "ocean env",
+    ],
+};
+const HELP_FLAGS = new Set(["--help", "-h"]);
+// A help flag anywhere before `--` is Ocean's, for every command: `client sync --help` once ran the
+// sync. Arguments after `--` belong to the wrapped program or the free text, so
+// `ocean client open claude -- --help` reaches Claude.
+export function wantsCommandHelp(args) {
+    const end = args.indexOf("--");
+    return (end < 0 ? args : args.slice(0, end)).some((arg) => HELP_FLAGS.has(arg));
+}
+export function renderCommandHelp(command) {
+    const [summary, usage] = commandHelp[command] ?? [
+        "",
+        `ocean ${command} [options]`,
+    ];
+    return `Usage: ${usage}\n\n${summary}`.trimEnd();
+}
+//# sourceMappingURL=help-command.js.map

package/dist/interfaces/cli/idea-command.js

@@ -0,0 +1,47 @@
+import { randomUUID } from "node:crypto";
+import { openSessionStore } from "@ocean/loop/infrastructure/persistence/session-store.js";
+export async function runIdeaCommand(action, args) {
+    const store = await openSessionStore();
+    try {
+        if (action === "save") {
+            const title = args[0];
+            const sessionIndex = args.indexOf("--session");
+            const content = args
+                .slice(1, sessionIndex >= 0 ? sessionIndex : undefined)
+                .join(" ")
+                .trim();
+            if (!title || !content)
+                throw new Error("Usage: ocean idea save <title> <content> [--session <session-id>]");
+            store.saveIdea({
+                ideaId: `idea-${randomUUID()}`,
+                title,
+                content,
+                sourceSessionId: sessionIndex >= 0 ? args[sessionIndex + 1] : null,
+            });
+            console.log(JSON.stringify({ saved: true, status: "raw", title }, null, 2));
+            return;
+        }
+        if (action === "list") {
+            console.log(JSON.stringify(store.listIdeas(args[0]), null, 2));
+            return;
+        }
+        if (action === "classify" || action === "discard") {
+            const id = args[0];
+            if (!id)
+                throw new Error(`Usage: ocean idea ${action} <idea-id> [target]`);
+            store.updateIdea(id, action === "discard" ? "discarded" : "classified", action === "classify" ? args[1] : undefined);
+            console.log(JSON.stringify({
+                ideaId: id,
+                status: action === "discard" ? "discarded" : "classified",
+                target: args[1] ?? null,
+            }, null, 2));
+            return;
+        }
+        console.error("Usage: ocean idea save <title> <content> [--session <id>]|list [status]|classify <id> <target>|discard <id>");
+        process.exitCode = 1;
+    }
+    finally {
+        store.close();
+    }
+}
+//# sourceMappingURL=idea-command.js.map