@kl-c/matrixos 0.3.51 → 0.3.53

package/dist/cli/index.js

@@ -2163,7 +2163,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@kl-c/matrixos",
-    version: "0.3.51",
+    version: "0.3.53",
     description: "MaTrixOS \u2014 Agentic OS for OpenCode. Personalizable, communicating, self-improving, resilient.",
     main: "./dist/index.js",
     types: "dist/index.d.ts",
@@ -168395,46 +168395,278 @@ function executeRgpdConsentCommand(args) {
   }
 }
 
+// packages/omo-opencode/src/cli/prepare.ts
+var exports_prepare = {};
+__export(exports_prepare, {
+  submitPr: () => submitPr,
+  preparePr: () => preparePr
+});
+import { execSync as execSync3 } from "child_process";
+function sh(cmd) {
+  return execSync3(cmd, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+function shOk(cmd) {
+  try {
+    execSync3(cmd, { encoding: "utf-8", stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function preparePr(options) {
+  const apply = options.apply ?? false;
+  const draft = options.draft ?? true;
+  const base = options.base ?? "main";
+  const steps = [];
+  const run5 = (cmd, label) => {
+    steps.push(`${label}: ${cmd}`);
+    if (!apply)
+      return "";
+    try {
+      return sh(cmd);
+    } catch (e) {
+      console.error(`[prepare] FAILED at: ${label}
+${e instanceof Error ? e.message : String(e)}`);
+      process.exit(1);
+    }
+  };
+  if (!shOk("git rev-parse --is-inside-work-tree")) {
+    console.error("[prepare] not a git repository");
+    return 1;
+  }
+  const status2 = sh("git status --porcelain");
+  if (!status2 && !apply) {}
+  if (apply && !status2) {
+    console.error("[prepare] nothing to commit (working tree clean)");
+    return 1;
+  }
+  const branch = `feat/matrixos-${Date.now().toString(36)}`;
+  const title = options.title ?? (apply ? sh("git log -1 --pretty=%s") : "Prepared change");
+  const body = options.body ?? "Prepared by matrixos prepare (draft, not yet submitted).";
+  run5(`git checkout -b ${branch}`, "create branch");
+  run5(`git add -A`, "stage");
+  run5(`git commit -m "${title.replace(/"/g, "\\\"")}"`, "commit");
+  run5(`git push -u origin ${branch}`, "push");
+  const prFlags = draft ? "--fill --draft" : "--fill";
+  const prOut = run5(`gh pr create ${prFlags} --base ${base} --title "${title.replace(/"/g, "\\\"")}" --body "${body.replace(/"/g, "\\\"")}"`, "open PR");
+  if (!apply) {
+    console.log(`[dry-run] would execute:
+` + steps.join(`
+`));
+    console.log(`
+[dry-run] would open ${draft ? "DRAFT" : ""} PR on base '${base}' with title: ${title}`);
+    console.log("[dry-run] re-run with --apply to actually create the PR.");
+    return 0;
+  }
+  console.log(`[prepare] PR created: ${prOut}`);
+  console.log(`[prepare] Draft PR is NOT submitted. Run 'matrixos submit <pr-url>' to mark ready.`);
+  return 0;
+}
+function submitPr(options) {
+  const pr = options.pr;
+  if (!pr) {
+    console.error("[submit] PR identifier required (URL or number)");
+    return 1;
+  }
+  const prRef = pr.includes("/") || /^\d+$/.test(pr) ? pr : `#${pr}`;
+  try {
+    sh(`gh pr ready ${prRef}`);
+    console.log(`[submit] PR ${prRef} marked ready.`);
+    return 0;
+  } catch (e) {
+    console.error(`[submit] failed: ${e instanceof Error ? e.message : String(e)}`);
+    return 1;
+  }
+}
+var init_prepare = () => {};
+
+// packages/omo-opencode/src/cli/project-init.ts
+var exports_project_init = {};
+__export(exports_project_init, {
+  projectInit: () => projectInit
+});
+import * as fs24 from "fs";
+import * as path29 from "path";
+function projectInit(options) {
+  const target = path29.resolve(options.path ?? process.cwd(), options.name);
+  const apply = options.apply ?? false;
+  if (fs24.existsSync(target) && fs24.readdirSync(target).length > 0) {
+    console.error(`[project] target exists and is not empty: ${target}`);
+    return 1;
+  }
+  const files = Object.entries(TEMPLATES).map(([rel, fn]) => ({ rel, content: fn(options.name) }));
+  if (!apply) {
+    console.log(`[dry-run] would create project '${options.name}' at:
+${target}
+`);
+    console.log("Files:");
+    for (const f2 of files) {
+      console.log(`  ${f2.rel}`);
+    }
+    console.log(`
+[dry-run] re-run with --apply to write the files.`);
+    return 0;
+  }
+  fs24.mkdirSync(path29.join(target, "src"), { recursive: true });
+  for (const f2 of files) {
+    const full = path29.join(target, f2.rel);
+    fs24.mkdirSync(path29.dirname(full), { recursive: true });
+    fs24.writeFileSync(full, f2.content);
+    console.log(`[project] wrote ${f2.rel}`);
+  }
+  console.log(`
+[project] '${options.name}' initialized at ${target}`);
+  console.log(`[project] Next: cd ${target} && matrixos run --agent Architect 'refine the plan.md'`);
+  return 0;
+}
+var TEMPLATES;
+var init_project_init = __esm(() => {
+  TEMPLATES = {
+    "AGENTS.md": (name2) => `# ${name2}
+
+> Project context for AI agents. Keep this file accurate \u2014 agents read it first.
+
+## OVERVIEW
+
+One-paragraph description of what this project is and who uses it.
+
+## CONVENTIONS
+
+- Code style: TBD
+- Tests: TBD
+- Commits: conventional commits
+
+## STRUCTURE
+
+\`\`\`
+${name2}/
+\u251C\u2500\u2500 README.md
+\u251C\u2500\u2500 PROJECT.md   # project state / roadmap
+\u251C\u2500\u2500 plan.md      # current plan
+\u2514\u2500\u2500 src/
+\`\`\`
+
+## NOTES
+
+- Link the relevant MaTrixOS Goal/Kanban board for tracking.
+`,
+    "README.md": (name2) => `# ${name2}
+
+## Install
+
+\`\`\`bash
+# add your install steps
+\`\`\`
+
+## Usage
+
+\`\`\`bash
+# add your usage steps
+\`\`\`
+
+## Development
+
+See AGENTS.md for agent context.
+`,
+    ".gitignore": () => `# Dependencies
+node_modules/
+.venv/
+__pycache__/
+
+# Build
+/dist/
+build/
+
+# Env / secrets
+.env
+.env.local
+*.secret
+
+# OS
+.DS_Store
+
+# MaTrixOS
+.omo/
+`,
+    "PROJECT.md": (name2) => `# ${name2} \u2014 Project State
+
+## STATUS
+
+| Item | State |
+|------|-------|
+| Scope | defined / wip / done |
+| Health | green / yellow / red |
+
+## ROADMAP
+
+- [ ] Milestone 1
+- [ ] Milestone 2
+
+## LINKS
+
+- MaTrixOS Goal: (create via dashboard)
+- Kanban: (link board)
+`,
+    "plan.md": () => `# Plan
+
+## Goal
+
+What are we trying to achieve?
+
+## Steps
+
+1. 
+2. 
+3. 
+
+## Open Questions
+
+- 
+`,
+    "src/.gitkeep": () => ""
+  };
+});
+
 // packages/omo-opencode/src/cli/service.ts
 var exports_service = {};
 __export(exports_service, {
   serviceInstallCommand: () => serviceInstallCommand
 });
 import * as os15 from "os";
-import * as fs24 from "fs";
-import * as path29 from "path";
-import { execSync as execSync3 } from "child_process";
+import * as fs25 from "fs";
+import * as path30 from "path";
+import { execSync as execSync4 } from "child_process";
 function resolveMatrixosBin2() {
   try {
-    const p2 = execSync3("command -v matrixos", { encoding: "utf-8" }).trim();
+    const p2 = execSync4("command -v matrixos", { encoding: "utf-8" }).trim();
     if (p2)
       return p2;
   } catch {}
-  for (const cand of ["/usr/local/bin/matrixos", "/usr/bin/matrixos", path29.join(os15.homedir(), ".bun/bin/matrixos")]) {
-    if (fs24.existsSync(cand))
+  for (const cand of ["/usr/local/bin/matrixos", "/usr/bin/matrixos", path30.join(os15.homedir(), ".bun/bin/matrixos")]) {
+    if (fs25.existsSync(cand))
       return cand;
   }
   return "matrixos";
 }
 function resolveBunBin() {
   try {
-    const p2 = execSync3("command -v bun", { encoding: "utf-8" }).trim();
+    const p2 = execSync4("command -v bun", { encoding: "utf-8" }).trim();
     if (p2)
       return p2;
   } catch {}
   return "/usr/bin/bun";
 }
 function writeFileEnsureDir(filePath, content) {
-  fs24.mkdirSync(path29.dirname(filePath), { recursive: true });
-  fs24.writeFileSync(filePath, content, "utf-8");
+  fs25.mkdirSync(path30.dirname(filePath), { recursive: true });
+  fs25.writeFileSync(filePath, content, "utf-8");
   console.log(`[service] written: ${filePath}`);
 }
 function installSystemd(opts) {
   const bin = resolveMatrixosBin2();
   const bun = resolveBunBin();
   const scope = opts.user ? "--user" : "";
-  const unitDir = opts.user ? path29.join(os15.homedir(), ".config", "systemd", "user") : "/etc/systemd/system";
-  const envPath = `/usr/local/bin:/usr/bin:/bin:${path29.dirname(bun)}`;
+  const unitDir = opts.user ? path30.join(os15.homedir(), ".config", "systemd", "user") : "/etc/systemd/system";
+  const envPath = `/usr/local/bin:/usr/bin:/bin:${path30.dirname(bun)}`;
   if (opts.dashboard !== false) {
     const unit = `[Unit]
 Description=MaTrixOS Dashboard
@@ -168453,7 +168685,7 @@ RestartSec=5
 [Install]
 WantedBy=${opts.user ? "default.target" : "multi-user.target"}
 `;
-    writeFileEnsureDir(path29.join(unitDir, "matrixos-dashboard.service"), unit);
+    writeFileEnsureDir(path30.join(unitDir, "matrixos-dashboard.service"), unit);
   }
   if (opts.gateway !== false) {
     const unit = `[Unit]
@@ -168473,7 +168705,7 @@ RestartSec=5
 [Install]
 WantedBy=${opts.user ? "default.target" : "multi-user.target"}
 `;
-    writeFileEnsureDir(path29.join(unitDir, "matrixos-gateway.service"), unit);
+    writeFileEnsureDir(path30.join(unitDir, "matrixos-gateway.service"), unit);
   }
   if (opts.cron !== false) {
     const unit = `[Unit]
@@ -168493,45 +168725,45 @@ RestartSec=5
 [Install]
 WantedBy=${opts.user ? "default.target" : "multi-user.target"}
 `;
-    writeFileEnsureDir(path29.join(unitDir, "matrixos-cron.service"), unit);
+    writeFileEnsureDir(path30.join(unitDir, "matrixos-cron.service"), unit);
   }
   console.log("[service] reloading systemd...");
   if (scope) {
-    execSync3(`${scope} systemctl --user daemon-reload`, { stdio: "inherit" });
+    execSync4(`${scope} systemctl --user daemon-reload`, { stdio: "inherit" });
     if (opts.dashboard !== false)
-      execSync3(`${scope} systemctl --user enable matrixos-dashboard.service`, { stdio: "inherit" });
+      execSync4(`${scope} systemctl --user enable matrixos-dashboard.service`, { stdio: "inherit" });
     if (opts.gateway !== false)
-      execSync3(`${scope} systemctl --user enable matrixos-gateway.service`, { stdio: "inherit" });
+      execSync4(`${scope} systemctl --user enable matrixos-gateway.service`, { stdio: "inherit" });
     if (opts.cron !== false)
-      execSync3(`${scope} systemctl --user enable matrixos-cron.service`, { stdio: "inherit" });
+      execSync4(`${scope} systemctl --user enable matrixos-cron.service`, { stdio: "inherit" });
     if (opts.dashboard !== false)
-      execSync3(`${scope} systemctl --user start matrixos-dashboard.service`, { stdio: "inherit" });
+      execSync4(`${scope} systemctl --user start matrixos-dashboard.service`, { stdio: "inherit" });
     if (opts.gateway !== false)
-      execSync3(`${scope} systemctl --user start matrixos-gateway.service`, { stdio: "inherit" });
+      execSync4(`${scope} systemctl --user start matrixos-gateway.service`, { stdio: "inherit" });
     if (opts.cron !== false)
-      execSync3(`${scope} systemctl --user start matrixos-cron.service`, { stdio: "inherit" });
+      execSync4(`${scope} systemctl --user start matrixos-cron.service`, { stdio: "inherit" });
   } else {
-    execSync3("systemctl daemon-reload", { stdio: "inherit" });
+    execSync4("systemctl daemon-reload", { stdio: "inherit" });
     if (opts.dashboard !== false)
-      execSync3("systemctl enable matrixos-dashboard.service", { stdio: "inherit" });
+      execSync4("systemctl enable matrixos-dashboard.service", { stdio: "inherit" });
     if (opts.gateway !== false)
-      execSync3("systemctl enable matrixos-gateway.service", { stdio: "inherit" });
+      execSync4("systemctl enable matrixos-gateway.service", { stdio: "inherit" });
     if (opts.cron !== false)
-      execSync3("systemctl enable matrixos-cron.service", { stdio: "inherit" });
+      execSync4("systemctl enable matrixos-cron.service", { stdio: "inherit" });
     if (opts.dashboard !== false)
-      execSync3("systemctl start matrixos-dashboard.service", { stdio: "inherit" });
+      execSync4("systemctl start matrixos-dashboard.service", { stdio: "inherit" });
     if (opts.gateway !== false)
-      execSync3("systemctl start matrixos-gateway.service", { stdio: "inherit" });
+      execSync4("systemctl start matrixos-gateway.service", { stdio: "inherit" });
     if (opts.cron !== false)
-      execSync3("systemctl start matrixos-cron.service", { stdio: "inherit" });
+      execSync4("systemctl start matrixos-cron.service", { stdio: "inherit" });
   }
   console.log("[service] systemd units installed and started.");
 }
 function installLaunchd(opts) {
   const bin = resolveMatrixosBin2();
   const bun = resolveBunBin();
-  const launchDir = path29.join(os15.homedir(), "Library", "LaunchAgents");
-  const envPath = `/usr/local/bin:/usr/bin:/bin:${path29.dirname(bun)}`;
+  const launchDir = path30.join(os15.homedir(), "Library", "LaunchAgents");
+  const envPath = `/usr/local/bin:/usr/bin:/bin:${path30.dirname(bun)}`;
   if (opts.dashboard !== false) {
     const label = "com.klc.matrixos.dashboard";
     const plist = `<?xml version="1.0" encoding="UTF-8"?>
@@ -168568,8 +168800,8 @@ function installLaunchd(opts) {
 </dict>
 </plist>
 `;
-    writeFileEnsureDir(path29.join(launchDir, `${label}.plist`), plist);
-    execSync3(`launchctl load ${path29.join(launchDir, `${label}.plist`)}`, { stdio: "inherit" });
+    writeFileEnsureDir(path30.join(launchDir, `${label}.plist`), plist);
+    execSync4(`launchctl load ${path30.join(launchDir, `${label}.plist`)}`, { stdio: "inherit" });
   }
   if (opts.gateway !== false) {
     const label = "com.klc.matrixos.gateway";
@@ -168607,8 +168839,8 @@ function installLaunchd(opts) {
 </dict>
 </plist>
 `;
-    writeFileEnsureDir(path29.join(launchDir, `${label}.plist`), plist);
-    execSync3(`launchctl load ${path29.join(launchDir, `${label}.plist`)}`, { stdio: "inherit" });
+    writeFileEnsureDir(path30.join(launchDir, `${label}.plist`), plist);
+    execSync4(`launchctl load ${path30.join(launchDir, `${label}.plist`)}`, { stdio: "inherit" });
   }
   console.log("[service] launchd agents installed and loaded.");
 }
@@ -168622,7 +168854,7 @@ async function serviceInstallCommand(options) {
   const platform2 = process.platform;
   console.log(`[service] detected platform: ${platform2}`);
   if (platform2 === "linux") {
-    if (!fs24.existsSync("/run/systemd/system") && !fs24.existsSync("/etc/systemd/system")) {
+    if (!fs25.existsSync("/run/systemd/system") && !fs25.existsSync("/etc/systemd/system")) {
       console.error("[service] systemd not detected \u2014 cannot install service automatically.");
       console.error("  Start manually: matrixos dashboard --host 0.0.0.0 --daemon");
       return 1;
@@ -190329,6 +190561,43 @@ Examples:
   process.stdout.write(result.stdout);
   process.exit(result.exitCode);
 });
+var prepare = program2.command("prepare").description("Prepare a pull request WITHOUT submitting (draft by default; --apply to create)").option("-t, --title <text>", "PR title").option("-b, --body <text>", "PR body").option("--base <branch>", "Base branch", "main").option("--no-draft", "Open as ready PR (default is draft)").option("--apply", "Actually create the branch/commit/PR (default dry-run)").option("--json", "Output as JSON").addHelpText("after", `
+Examples:
+  $ matrixos prepare                       # dry-run: show what would happen
+  $ matrixos prepare --apply               # create draft PR on main
+  $ matrixos prepare --apply --title "Fix X" --no-draft
+`).action(async (options) => {
+  const { preparePr: preparePr2 } = await Promise.resolve().then(() => (init_prepare(), exports_prepare));
+  const code = preparePr2({
+    title: options.title,
+    body: options.body,
+    base: options.base,
+    draft: options.draft ?? true,
+    apply: options.apply ?? false,
+    json: options.json ?? false
+  });
+  process.exit(code);
+});
+prepare.command("submit <pr>").description("Mark a prepared PR as ready (human validation gate)").option("--json", "Output as JSON").action(async (pr, options) => {
+  const { submitPr: submitPr2 } = await Promise.resolve().then(() => (init_prepare(), exports_prepare));
+  const code = submitPr2({ pr, json: options.json ?? false });
+  process.exit(code);
+});
+var projectCmd = program2.command("project").description("Project lifecycle helpers (generic scaffolding)");
+projectCmd.command("init <name>").description("Scaffold a generic project (AGENTS.md, README, .gitignore, PROJECT.md, plan.md)").option("-p, --path <dir>", "Target directory (default: cwd)").option("--apply", "Actually write the files (default dry-run)").option("--json", "Output as JSON").addHelpText("after", `
+Examples:
+  $ matrixos project init my-app            # dry-run
+  $ matrixos project init my-app --apply    # write files
+`).action(async (name2, options) => {
+  const { projectInit: projectInit2 } = await Promise.resolve().then(() => (init_project_init(), exports_project_init));
+  const code = projectInit2({
+    name: name2,
+    path: options.path,
+    apply: options.apply ?? false,
+    json: options.json ?? false
+  });
+  process.exit(code);
+});
 program2.command("service").description("Install MaTrixOS as a persistent OS service (dashboard + gateway)").argument("<action>", "install | uninstall").option("--no-dashboard", "Skip dashboard service").option("--no-gateway", "Skip gateway service").option("--no-cron", "Skip cron scheduler service").option("--user", "Install as current user (systemd --user / launchd user agent)").action(async (action, options) => {
   if (action !== "install" && action !== "uninstall") {
     console.error(`[service] unknown action: ${action}. Use 'install' or 'uninstall'.`);

package/dist/cli/prepare.d.ts

@@ -0,0 +1,14 @@
+export interface PrepareOptions {
+    title?: string;
+    body?: string;
+    base?: string;
+    draft?: boolean;
+    apply?: boolean;
+    json?: boolean;
+}
+export interface SubmitOptions {
+    pr?: string;
+    json?: boolean;
+}
+export declare function preparePr(options: PrepareOptions): number;
+export declare function submitPr(options: SubmitOptions): number;

package/dist/cli/project-init.d.ts

@@ -0,0 +1,7 @@
+export interface ProjectInitOptions {
+    name: string;
+    path?: string;
+    apply?: boolean;
+    json?: boolean;
+}
+export declare function projectInit(options: ProjectInitOptions): number;

package/dist/cli-node/index.js

@@ -2163,7 +2163,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@kl-c/matrixos",
-    version: "0.3.51",
+    version: "0.3.53",
     description: "MaTrixOS \u2014 Agentic OS for OpenCode. Personalizable, communicating, self-improving, resilient.",
     main: "./dist/index.js",
     types: "dist/index.d.ts",
@@ -168450,46 +168450,278 @@ function executeRgpdConsentCommand(args) {
   }
 }
 
+// packages/omo-opencode/src/cli/prepare.ts
+var exports_prepare = {};
+__export(exports_prepare, {
+  submitPr: () => submitPr,
+  preparePr: () => preparePr
+});
+import { execSync as execSync3 } from "child_process";
+function sh(cmd) {
+  return execSync3(cmd, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+function shOk(cmd) {
+  try {
+    execSync3(cmd, { encoding: "utf-8", stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function preparePr(options) {
+  const apply = options.apply ?? false;
+  const draft = options.draft ?? true;
+  const base = options.base ?? "main";
+  const steps = [];
+  const run5 = (cmd, label) => {
+    steps.push(`${label}: ${cmd}`);
+    if (!apply)
+      return "";
+    try {
+      return sh(cmd);
+    } catch (e) {
+      console.error(`[prepare] FAILED at: ${label}
+${e instanceof Error ? e.message : String(e)}`);
+      process.exit(1);
+    }
+  };
+  if (!shOk("git rev-parse --is-inside-work-tree")) {
+    console.error("[prepare] not a git repository");
+    return 1;
+  }
+  const status2 = sh("git status --porcelain");
+  if (!status2 && !apply) {}
+  if (apply && !status2) {
+    console.error("[prepare] nothing to commit (working tree clean)");
+    return 1;
+  }
+  const branch = `feat/matrixos-${Date.now().toString(36)}`;
+  const title = options.title ?? (apply ? sh("git log -1 --pretty=%s") : "Prepared change");
+  const body = options.body ?? "Prepared by matrixos prepare (draft, not yet submitted).";
+  run5(`git checkout -b ${branch}`, "create branch");
+  run5(`git add -A`, "stage");
+  run5(`git commit -m "${title.replace(/"/g, "\\\"")}"`, "commit");
+  run5(`git push -u origin ${branch}`, "push");
+  const prFlags = draft ? "--fill --draft" : "--fill";
+  const prOut = run5(`gh pr create ${prFlags} --base ${base} --title "${title.replace(/"/g, "\\\"")}" --body "${body.replace(/"/g, "\\\"")}"`, "open PR");
+  if (!apply) {
+    console.log(`[dry-run] would execute:
+` + steps.join(`
+`));
+    console.log(`
+[dry-run] would open ${draft ? "DRAFT" : ""} PR on base '${base}' with title: ${title}`);
+    console.log("[dry-run] re-run with --apply to actually create the PR.");
+    return 0;
+  }
+  console.log(`[prepare] PR created: ${prOut}`);
+  console.log(`[prepare] Draft PR is NOT submitted. Run 'matrixos submit <pr-url>' to mark ready.`);
+  return 0;
+}
+function submitPr(options) {
+  const pr = options.pr;
+  if (!pr) {
+    console.error("[submit] PR identifier required (URL or number)");
+    return 1;
+  }
+  const prRef = pr.includes("/") || /^\d+$/.test(pr) ? pr : `#${pr}`;
+  try {
+    sh(`gh pr ready ${prRef}`);
+    console.log(`[submit] PR ${prRef} marked ready.`);
+    return 0;
+  } catch (e) {
+    console.error(`[submit] failed: ${e instanceof Error ? e.message : String(e)}`);
+    return 1;
+  }
+}
+var init_prepare = () => {};
+
+// packages/omo-opencode/src/cli/project-init.ts
+var exports_project_init = {};
+__export(exports_project_init, {
+  projectInit: () => projectInit
+});
+import * as fs24 from "fs";
+import * as path29 from "path";
+function projectInit(options) {
+  const target = path29.resolve(options.path ?? process.cwd(), options.name);
+  const apply = options.apply ?? false;
+  if (fs24.existsSync(target) && fs24.readdirSync(target).length > 0) {
+    console.error(`[project] target exists and is not empty: ${target}`);
+    return 1;
+  }
+  const files = Object.entries(TEMPLATES).map(([rel, fn]) => ({ rel, content: fn(options.name) }));
+  if (!apply) {
+    console.log(`[dry-run] would create project '${options.name}' at:
+${target}
+`);
+    console.log("Files:");
+    for (const f2 of files) {
+      console.log(`  ${f2.rel}`);
+    }
+    console.log(`
+[dry-run] re-run with --apply to write the files.`);
+    return 0;
+  }
+  fs24.mkdirSync(path29.join(target, "src"), { recursive: true });
+  for (const f2 of files) {
+    const full = path29.join(target, f2.rel);
+    fs24.mkdirSync(path29.dirname(full), { recursive: true });
+    fs24.writeFileSync(full, f2.content);
+    console.log(`[project] wrote ${f2.rel}`);
+  }
+  console.log(`
+[project] '${options.name}' initialized at ${target}`);
+  console.log(`[project] Next: cd ${target} && matrixos run --agent Architect 'refine the plan.md'`);
+  return 0;
+}
+var TEMPLATES;
+var init_project_init = __esm(() => {
+  TEMPLATES = {
+    "AGENTS.md": (name2) => `# ${name2}
+
+> Project context for AI agents. Keep this file accurate \u2014 agents read it first.
+
+## OVERVIEW
+
+One-paragraph description of what this project is and who uses it.
+
+## CONVENTIONS
+
+- Code style: TBD
+- Tests: TBD
+- Commits: conventional commits
+
+## STRUCTURE
+
+\`\`\`
+${name2}/
+\u251C\u2500\u2500 README.md
+\u251C\u2500\u2500 PROJECT.md   # project state / roadmap
+\u251C\u2500\u2500 plan.md      # current plan
+\u2514\u2500\u2500 src/
+\`\`\`
+
+## NOTES
+
+- Link the relevant MaTrixOS Goal/Kanban board for tracking.
+`,
+    "README.md": (name2) => `# ${name2}
+
+## Install
+
+\`\`\`bash
+# add your install steps
+\`\`\`
+
+## Usage
+
+\`\`\`bash
+# add your usage steps
+\`\`\`
+
+## Development
+
+See AGENTS.md for agent context.
+`,
+    ".gitignore": () => `# Dependencies
+node_modules/
+.venv/
+__pycache__/
+
+# Build
+/dist/
+build/
+
+# Env / secrets
+.env
+.env.local
+*.secret
+
+# OS
+.DS_Store
+
+# MaTrixOS
+.omo/
+`,
+    "PROJECT.md": (name2) => `# ${name2} \u2014 Project State
+
+## STATUS
+
+| Item | State |
+|------|-------|
+| Scope | defined / wip / done |
+| Health | green / yellow / red |
+
+## ROADMAP
+
+- [ ] Milestone 1
+- [ ] Milestone 2
+
+## LINKS
+
+- MaTrixOS Goal: (create via dashboard)
+- Kanban: (link board)
+`,
+    "plan.md": () => `# Plan
+
+## Goal
+
+What are we trying to achieve?
+
+## Steps
+
+1. 
+2. 
+3. 
+
+## Open Questions
+
+- 
+`,
+    "src/.gitkeep": () => ""
+  };
+});
+
 // packages/omo-opencode/src/cli/service.ts
 var exports_service = {};
 __export(exports_service, {
   serviceInstallCommand: () => serviceInstallCommand
 });
 import * as os15 from "os";
-import * as fs24 from "fs";
-import * as path29 from "path";
-import { execSync as execSync3 } from "child_process";
+import * as fs25 from "fs";
+import * as path30 from "path";
+import { execSync as execSync4 } from "child_process";
 function resolveMatrixosBin2() {
   try {
-    const p2 = execSync3("command -v matrixos", { encoding: "utf-8" }).trim();
+    const p2 = execSync4("command -v matrixos", { encoding: "utf-8" }).trim();
     if (p2)
       return p2;
   } catch {}
-  for (const cand of ["/usr/local/bin/matrixos", "/usr/bin/matrixos", path29.join(os15.homedir(), ".bun/bin/matrixos")]) {
-    if (fs24.existsSync(cand))
+  for (const cand of ["/usr/local/bin/matrixos", "/usr/bin/matrixos", path30.join(os15.homedir(), ".bun/bin/matrixos")]) {
+    if (fs25.existsSync(cand))
       return cand;
   }
   return "matrixos";
 }
 function resolveBunBin() {
   try {
-    const p2 = execSync3("command -v bun", { encoding: "utf-8" }).trim();
+    const p2 = execSync4("command -v bun", { encoding: "utf-8" }).trim();
     if (p2)
       return p2;
   } catch {}
   return "/usr/bin/bun";
 }
 function writeFileEnsureDir(filePath, content) {
-  fs24.mkdirSync(path29.dirname(filePath), { recursive: true });
-  fs24.writeFileSync(filePath, content, "utf-8");
+  fs25.mkdirSync(path30.dirname(filePath), { recursive: true });
+  fs25.writeFileSync(filePath, content, "utf-8");
   console.log(`[service] written: ${filePath}`);
 }
 function installSystemd(opts) {
   const bin = resolveMatrixosBin2();
   const bun = resolveBunBin();
   const scope = opts.user ? "--user" : "";
-  const unitDir = opts.user ? path29.join(os15.homedir(), ".config", "systemd", "user") : "/etc/systemd/system";
-  const envPath = `/usr/local/bin:/usr/bin:/bin:${path29.dirname(bun)}`;
+  const unitDir = opts.user ? path30.join(os15.homedir(), ".config", "systemd", "user") : "/etc/systemd/system";
+  const envPath = `/usr/local/bin:/usr/bin:/bin:${path30.dirname(bun)}`;
   if (opts.dashboard !== false) {
     const unit = `[Unit]
 Description=MaTrixOS Dashboard
@@ -168508,7 +168740,7 @@ RestartSec=5
 [Install]
 WantedBy=${opts.user ? "default.target" : "multi-user.target"}
 `;
-    writeFileEnsureDir(path29.join(unitDir, "matrixos-dashboard.service"), unit);
+    writeFileEnsureDir(path30.join(unitDir, "matrixos-dashboard.service"), unit);
   }
   if (opts.gateway !== false) {
     const unit = `[Unit]
@@ -168528,7 +168760,7 @@ RestartSec=5
 [Install]
 WantedBy=${opts.user ? "default.target" : "multi-user.target"}
 `;
-    writeFileEnsureDir(path29.join(unitDir, "matrixos-gateway.service"), unit);
+    writeFileEnsureDir(path30.join(unitDir, "matrixos-gateway.service"), unit);
   }
   if (opts.cron !== false) {
     const unit = `[Unit]
@@ -168548,45 +168780,45 @@ RestartSec=5
 [Install]
 WantedBy=${opts.user ? "default.target" : "multi-user.target"}
 `;
-    writeFileEnsureDir(path29.join(unitDir, "matrixos-cron.service"), unit);
+    writeFileEnsureDir(path30.join(unitDir, "matrixos-cron.service"), unit);
   }
   console.log("[service] reloading systemd...");
   if (scope) {
-    execSync3(`${scope} systemctl --user daemon-reload`, { stdio: "inherit" });
+    execSync4(`${scope} systemctl --user daemon-reload`, { stdio: "inherit" });
     if (opts.dashboard !== false)
-      execSync3(`${scope} systemctl --user enable matrixos-dashboard.service`, { stdio: "inherit" });
+      execSync4(`${scope} systemctl --user enable matrixos-dashboard.service`, { stdio: "inherit" });
     if (opts.gateway !== false)
-      execSync3(`${scope} systemctl --user enable matrixos-gateway.service`, { stdio: "inherit" });
+      execSync4(`${scope} systemctl --user enable matrixos-gateway.service`, { stdio: "inherit" });
     if (opts.cron !== false)
-      execSync3(`${scope} systemctl --user enable matrixos-cron.service`, { stdio: "inherit" });
+      execSync4(`${scope} systemctl --user enable matrixos-cron.service`, { stdio: "inherit" });
     if (opts.dashboard !== false)
-      execSync3(`${scope} systemctl --user start matrixos-dashboard.service`, { stdio: "inherit" });
+      execSync4(`${scope} systemctl --user start matrixos-dashboard.service`, { stdio: "inherit" });
     if (opts.gateway !== false)
-      execSync3(`${scope} systemctl --user start matrixos-gateway.service`, { stdio: "inherit" });
+      execSync4(`${scope} systemctl --user start matrixos-gateway.service`, { stdio: "inherit" });
     if (opts.cron !== false)
-      execSync3(`${scope} systemctl --user start matrixos-cron.service`, { stdio: "inherit" });
+      execSync4(`${scope} systemctl --user start matrixos-cron.service`, { stdio: "inherit" });
   } else {
-    execSync3("systemctl daemon-reload", { stdio: "inherit" });
+    execSync4("systemctl daemon-reload", { stdio: "inherit" });
     if (opts.dashboard !== false)
-      execSync3("systemctl enable matrixos-dashboard.service", { stdio: "inherit" });
+      execSync4("systemctl enable matrixos-dashboard.service", { stdio: "inherit" });
     if (opts.gateway !== false)
-      execSync3("systemctl enable matrixos-gateway.service", { stdio: "inherit" });
+      execSync4("systemctl enable matrixos-gateway.service", { stdio: "inherit" });
     if (opts.cron !== false)
-      execSync3("systemctl enable matrixos-cron.service", { stdio: "inherit" });
+      execSync4("systemctl enable matrixos-cron.service", { stdio: "inherit" });
     if (opts.dashboard !== false)
-      execSync3("systemctl start matrixos-dashboard.service", { stdio: "inherit" });
+      execSync4("systemctl start matrixos-dashboard.service", { stdio: "inherit" });
     if (opts.gateway !== false)
-      execSync3("systemctl start matrixos-gateway.service", { stdio: "inherit" });
+      execSync4("systemctl start matrixos-gateway.service", { stdio: "inherit" });
     if (opts.cron !== false)
-      execSync3("systemctl start matrixos-cron.service", { stdio: "inherit" });
+      execSync4("systemctl start matrixos-cron.service", { stdio: "inherit" });
   }
   console.log("[service] systemd units installed and started.");
 }
 function installLaunchd(opts) {
   const bin = resolveMatrixosBin2();
   const bun = resolveBunBin();
-  const launchDir = path29.join(os15.homedir(), "Library", "LaunchAgents");
-  const envPath = `/usr/local/bin:/usr/bin:/bin:${path29.dirname(bun)}`;
+  const launchDir = path30.join(os15.homedir(), "Library", "LaunchAgents");
+  const envPath = `/usr/local/bin:/usr/bin:/bin:${path30.dirname(bun)}`;
   if (opts.dashboard !== false) {
     const label = "com.klc.matrixos.dashboard";
     const plist = `<?xml version="1.0" encoding="UTF-8"?>
@@ -168623,8 +168855,8 @@ function installLaunchd(opts) {
 </dict>
 </plist>
 `;
-    writeFileEnsureDir(path29.join(launchDir, `${label}.plist`), plist);
-    execSync3(`launchctl load ${path29.join(launchDir, `${label}.plist`)}`, { stdio: "inherit" });
+    writeFileEnsureDir(path30.join(launchDir, `${label}.plist`), plist);
+    execSync4(`launchctl load ${path30.join(launchDir, `${label}.plist`)}`, { stdio: "inherit" });
   }
   if (opts.gateway !== false) {
     const label = "com.klc.matrixos.gateway";
@@ -168662,8 +168894,8 @@ function installLaunchd(opts) {
 </dict>
 </plist>
 `;
-    writeFileEnsureDir(path29.join(launchDir, `${label}.plist`), plist);
-    execSync3(`launchctl load ${path29.join(launchDir, `${label}.plist`)}`, { stdio: "inherit" });
+    writeFileEnsureDir(path30.join(launchDir, `${label}.plist`), plist);
+    execSync4(`launchctl load ${path30.join(launchDir, `${label}.plist`)}`, { stdio: "inherit" });
   }
   console.log("[service] launchd agents installed and loaded.");
 }
@@ -168677,7 +168909,7 @@ async function serviceInstallCommand(options) {
   const platform2 = process.platform;
   console.log(`[service] detected platform: ${platform2}`);
   if (platform2 === "linux") {
-    if (!fs24.existsSync("/run/systemd/system") && !fs24.existsSync("/etc/systemd/system")) {
+    if (!fs25.existsSync("/run/systemd/system") && !fs25.existsSync("/etc/systemd/system")) {
       console.error("[service] systemd not detected \u2014 cannot install service automatically.");
       console.error("  Start manually: matrixos dashboard --host 0.0.0.0 --daemon");
       return 1;
@@ -190384,6 +190616,43 @@ Examples:
   process.stdout.write(result.stdout);
   process.exit(result.exitCode);
 });
+var prepare = program2.command("prepare").description("Prepare a pull request WITHOUT submitting (draft by default; --apply to create)").option("-t, --title <text>", "PR title").option("-b, --body <text>", "PR body").option("--base <branch>", "Base branch", "main").option("--no-draft", "Open as ready PR (default is draft)").option("--apply", "Actually create the branch/commit/PR (default dry-run)").option("--json", "Output as JSON").addHelpText("after", `
+Examples:
+  $ matrixos prepare                       # dry-run: show what would happen
+  $ matrixos prepare --apply               # create draft PR on main
+  $ matrixos prepare --apply --title "Fix X" --no-draft
+`).action(async (options) => {
+  const { preparePr: preparePr2 } = await Promise.resolve().then(() => (init_prepare(), exports_prepare));
+  const code = preparePr2({
+    title: options.title,
+    body: options.body,
+    base: options.base,
+    draft: options.draft ?? true,
+    apply: options.apply ?? false,
+    json: options.json ?? false
+  });
+  process.exit(code);
+});
+prepare.command("submit <pr>").description("Mark a prepared PR as ready (human validation gate)").option("--json", "Output as JSON").action(async (pr, options) => {
+  const { submitPr: submitPr2 } = await Promise.resolve().then(() => (init_prepare(), exports_prepare));
+  const code = submitPr2({ pr, json: options.json ?? false });
+  process.exit(code);
+});
+var projectCmd = program2.command("project").description("Project lifecycle helpers (generic scaffolding)");
+projectCmd.command("init <name>").description("Scaffold a generic project (AGENTS.md, README, .gitignore, PROJECT.md, plan.md)").option("-p, --path <dir>", "Target directory (default: cwd)").option("--apply", "Actually write the files (default dry-run)").option("--json", "Output as JSON").addHelpText("after", `
+Examples:
+  $ matrixos project init my-app            # dry-run
+  $ matrixos project init my-app --apply    # write files
+`).action(async (name2, options) => {
+  const { projectInit: projectInit2 } = await Promise.resolve().then(() => (init_project_init(), exports_project_init));
+  const code = projectInit2({
+    name: name2,
+    path: options.path,
+    apply: options.apply ?? false,
+    json: options.json ?? false
+  });
+  process.exit(code);
+});
 program2.command("service").description("Install MaTrixOS as a persistent OS service (dashboard + gateway)").argument("<action>", "install | uninstall").option("--no-dashboard", "Skip dashboard service").option("--no-gateway", "Skip gateway service").option("--no-cron", "Skip cron scheduler service").option("--user", "Install as current user (systemd --user / launchd user agent)").action(async (action, options) => {
   if (action !== "install" && action !== "uninstall") {
     console.error(`[service] unknown action: ${action}. Use 'install' or 'uninstall'.`);

package/dist/index.js

@@ -368086,7 +368086,7 @@ function getCachedVersion(options = {}) {
 // package.json
 var package_default = {
   name: "@kl-c/matrixos",
-  version: "0.3.51",
+  version: "0.3.53",
   description: "MaTrixOS \u2014 Agentic OS for OpenCode. Personalizable, communicating, self-improving, resilient.",
   main: "./dist/index.js",
   types: "dist/index.d.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kl-c/matrixos",
-  "version": "0.3.51",
+  "version": "0.3.53",
   "description": "MaTrixOS \u2014 Agentic OS for OpenCode. Personalizable, communicating, self-improving, resilient.",
   "main": "./dist/index.js",
   "types": "dist/index.d.ts",