create-booboo 0.2.0 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jessy Mariau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { mkdirSync, writeFileSync, existsSync, readdirSync } from "fs";
+import { mkdirSync, writeFileSync, existsSync, readdirSync, readFileSync } from "fs";
 import path from "path";
-var BOOBOO_VERSION = "^0.2.0";
+var BOOBOO_VERSION = "^0.5.0";
+var VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 var args = process.argv.slice(2);
 var flags = new Set(args.filter((a) => a.startsWith("--")));
 var dirArg = args.find((a) => !a.startsWith("--")) ?? "my-brain";
@@ -12,6 +13,17 @@ if (flags.has("--help") || flags.has("-h")) {
   console.log("usage: npx create-booboo <dir> [--force]\n  scaffolds a runnable Booboo brain (json starter + postgres upgrade path)");
   process.exit(0);
 }
+if (flags.has("--version") || flags.has("-v")) {
+  console.log(VERSION);
+  process.exit(0);
+}
+var KNOWN_FLAGS = /* @__PURE__ */ new Set(["--force", "--help", "-h", "--version", "-v"]);
+var unknownFlags = [...flags].filter((f) => !KNOWN_FLAGS.has(f));
+if (unknownFlags.length) {
+  console.error(`\u2717 unknown flag(s): ${unknownFlags.join(", ")}
+  usage: npx create-booboo <dir> [--force]`);
+  process.exit(1);
+}
 var dir = path.resolve(process.cwd(), dirArg);
 var name = path.basename(dir);
 var TITLE = name.replace(/[-_]/g, " ").toUpperCase();
@@ -33,6 +45,10 @@ layers:
 # Namespaces that must NEVER be emitted (filtered in the builder, before JSON/API/MCP).
 walls: [private, sealed]
 
+# Parse [[wikilinks]] in node text into first-class \`authored\` edges \u2014 the links
+# a writer CHOSE while understanding the source outrank any harvested relation.
+wikilinks: true
+
 sources:
   # 1) JSON starter \u2014 works immediately, no database. Edit data.booboo.json.
   - adapter: json
@@ -69,8 +85,8 @@ var dataJson = JSON.stringify(
       { id: "agent:researcher", type: "agent", layer: "agents", label: "Researcher", weight: 0.6, tier: 1, parent: "core", icon: "\u{1F50E}", data: { role: "gathers sources" } },
       { id: "kb:spec", type: "entity", layer: "knowledge", label: "Spec", weight: 0.4, tier: 2, parent: "core" },
       { id: "kb:brand", type: "entity", layer: "knowledge", label: "Brand", weight: 0.4, tier: 2, parent: "core" },
-      { id: "mem:1", type: "memory", layer: "memory", label: "shipped v1", weight: 0.2, tier: 3, parent: "agent:writer" },
-      { id: "mem:2", type: "memory", layer: "memory", label: "found source", weight: 0.2, tier: 3, parent: "agent:researcher" }
+      { id: "mem:1", type: "memory", layer: "memory", label: "shipped v1", weight: 0.2, tier: 3, parent: "agent:writer", data: { text: "v1 shipped against [[kb:spec]] \u2014 the launch note the Writer drafted." } },
+      { id: "mem:2", type: "memory", layer: "memory", label: "found source", weight: 0.2, tier: 3, parent: "agent:researcher", data: { text: "primary source located; informs [[kb:brand]]." } }
     ],
     links: [
       { source: "agent:writer", target: "kb:spec", type: "uses" },
@@ -105,7 +121,8 @@ var pkgJson = JSON.stringify(
       serve: "booboo serve --snapshot brain.json --port 8787",
       mcp: "booboo mcp --snapshot brain.json --org org.booboo.json",
       view: "booboo view --snapshot brain.json",
-      panel: "booboo panel --org org.booboo.json --snapshot brain.json"
+      panel: "booboo panel --org org.booboo.json --snapshot brain.json",
+      vault: "booboo vault --snapshot brain.json --org org.booboo.json --out vault"
     },
     dependencies: {
       "@booboo-brain/cli": BOOBOO_VERSION
@@ -146,23 +163,82 @@ latest reports. This file is a **source** (commit it) \u2014 the snapshot is der
 
 > **Privacy:** anything whose \`cluster\` is in \`walls:\` is filtered *before* emit \u2014 sealed data never reaches the snapshot, API, or MCP.
 
+## The vault \u2014 your brain as plain markdown
+
+\`npm run vault\` emits the whole brain as a wiki-linked markdown vault (\`vault/\`):
+one page per node, index pages per layer/cluster, an agent dossier per org member.
+Open it as an Obsidian vault, read it on a couch, or hand it to ANY agent \u2014 plain
+files survive every provider. It is derived: regenerate, never hand-edit.
+
+## The agent contract
+
+**AGENTS.md** (imported by CLAUDE.md) is the operating doctrine an AI agent working
+this folder reads first: boot from the org, author \`[[wikilinks]]\`, one atomic fact
+per note, corrections replace, respect the walls, watch the quality gate. Edit it as
+your conventions evolve \u2014 it IS your system's constitution.
+
 ## MCP
 
 \`npm run mcp\` exposes \`booboo_stats \xB7 booboo_search \xB7 booboo_node \xB7 booboo_neighbors \xB7 booboo_path\`
-so an AI client can query the brain. See the Booboo repo for client config.
+(+ \`booboo_boot \xB7 booboo_org\` with \`--org\`) so an AI client can query the brain, plus the LIVE
+memory verbs \`booboo_remember\` and \`booboo_report\` \u2014 durable writes that append to the journal
+beside the snapshot and are queryable the same session (pass \`--no-write\` for a read-only server).
+See the Booboo repo for client config.
 `;
 var gitignore = `node_modules/
 # the built snapshot can contain real/private data \u2014 don't commit it
 brain.json
+# the LIVE MEMORY journal \u2014 durable agent writes (remember/report). Private,
+# and NOT regenerated by build, so it's never deleted \u2014 just don't commit it.
+*.journal.jsonl
+# the vault is derived from the snapshot \u2014 regenerate, never commit
+vault/
 *.log
 `;
+var agentsMd = `# ${TITLE} \u2014 the agent contract
+*Any AI agent working in this folder reads this first, every session. It is the
+operating doctrine for this brain \u2014 the conventions match the setup.*
+
+## What this folder is
+- \`booboo.config.yaml\` \u2014 build config (layers \xB7 sources \xB7 walls \xB7 wikilinks). Edit to shape the brain.
+- \`org.booboo.json\` \u2014 **SOURCE**: the agent organigram you boot from. Versioned, validated, edited via the panel or a reviewed change \u2014 never ad-hoc.
+- \`brain.json\` \u2014 **DERIVED** snapshot. Regenerate with \`npm run build\`; never hand-edit.
+- \`vault/\` \u2014 **DERIVED** markdown mirror of the brain (Obsidian-compatible). Regenerate with \`npm run vault\`; never hand-edit.
+
+## The loop (every non-trivial task)
+1. **ORIENT** \u2014 never assume what the brain knows: boot as your agent (\`booboo_boot('<agent-id>')\` over MCP) for your identity, inherited rules and buckets; then \`booboo_search\`/\`booboo_neighbors\` for the facts you need. *Assumption is not recall.*
+2. **ACT** \u2014 the smallest correct change.
+3. **VERIFY against reality** \u2014 \`npm run build\` and read the \`quality\` line; open \`npm run view\` or \`npm run panel\` when the change is visual. Introspection is not verification.
+4. **RECORD** \u2014 write what you learned: call \`booboo_remember\` (a durable memory) and \`booboo_report\` (what you closed) over MCP. These are LIVE \u2014 they append to the journal beside the snapshot and are queryable the same session; no rebuild needed. Close every substantial task with a \`booboo_report\`.
+
+## Writing memories (the conventions that keep the brain curated)
+- **Use \`booboo_remember\`** \u2014 pass \`agent\` (who it belongs to), \`text\` (the fact), and optionally \`kind\` / \`bucket\`. It writes to the durable journal (survives every rebuild) and is instantly searchable. \`booboo_report\` files what you closed; it lands on the panel's Reports timeline.
+- **One atomic fact per note**, written for the future reader. Never dump a transcript \u2014 the quality gate counts \`dump-suspects\` and they are a smell.
+- **Author your links**: put \`[[node-id]]\` (or \`[[exact label]]\`) refs in the note text where you KNOW the connection. \`wikilinks: true\` turns them into first-class \`authored\` edges that outrank any harvested relation.
+- **Corrections replace**: when a note corrects an earlier fact, remove or supersede the old one in the same act. A brain that only accumulates is not curated \u2014 stale truth next to live truth is worse than either.
+- **Respect the walls**: anything in a \`walls:\` cluster never leaves the builder. Never move data out of a walled cluster; never widen the walls without the human.
+
+## The org is law
+Rules in \`org.booboo.json\` inherit top-down \u2014 \`booboo_boot\` returns yours; obey them. Reorganising the fleet (reparenting, new agents, rule changes) goes through the panel (\`npm run panel\`) or a reviewed edit so the change is validated and diffable.
+
+## Quality gate (read it every build)
+\`npm run build\` prints \`quality \xB7 authored:N \xB7 orphans:N \xB7 dump-suspects:N\`.
+Authored should grow; orphans and dumps should not. Rising orphans/dumps = accumulating, not curating \u2014 fix the notes before adding more.
+
+## Honest close
+End substantial work by reporting plainly: what changed, what you verified against the running thing, what you couldn't verify, and any note you superseded.
+`;
+var claudeMd = `@AGENTS.md
+`;
 var files = {
   "booboo.config.yaml": configYaml,
   "data.booboo.json": dataJson,
   "org.booboo.json": orgJson,
   "package.json": pkgJson,
   "README.md": readme,
-  ".gitignore": gitignore
+  ".gitignore": gitignore,
+  "AGENTS.md": agentsMd,
+  "CLAUDE.md": claudeMd
 };
 for (const [f, content] of Object.entries(files)) writeFileSync(path.join(dir, f), content, "utf8");
 console.log(`
@@ -175,5 +251,8 @@ console.log("  npm run build      # build the graph snapshot");
 console.log("  npm run serve      # REST API on http://localhost:8787");
 console.log("  npm run mcp        # MCP over stdio (Claude / Cursor / Claude Code)");
 console.log("  npm run view       # see your brain in 3D (opens your browser)");
-console.log("  npm run panel      # the organigram \u2014 run your agents like a company\n");
+console.log("  npm run panel      # the organigram \u2014 run your agents like a company");
+console.log("  npm run vault      # the brain as a wiki-linked markdown vault (Obsidian-ready)\n");
+console.log("Your agent's contract is AGENTS.md (CLAUDE.md imports it) \u2014 Claude/Codex read it");
+console.log("automatically in this folder and will follow the brain's conventions.\n");
 console.log("Then edit booboo.config.yaml to point at your own data \u2014 a postgres example is included.\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-booboo",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Scaffold a new Booboo brain — `npx create-booboo my-brain`. Zero deps.",
   "license": "MIT",
   "repository": {
@@ -19,9 +19,6 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "tsup src/cli.ts --format esm --clean"
-  },
   "devDependencies": {
     "tsup": "^8",
     "typescript": "^5"
@@ -32,5 +29,8 @@
     "create",
     "knowledge-graph",
     "mcp"
-  ]
-}
+  ],
+  "scripts": {
+    "build": "tsup src/cli.ts --format esm --clean"
+  }
+}