@arkhera30/cli 0.3.15 → 0.4.0

package/compose/docker-compose.yml

@@ -60,7 +60,7 @@ services:
       - "${VAULT_PORT:-8000}:8000"
     volumes:
       # Knowledge-base repo — read/write; Vault clones on first boot if empty
-      - ${HORUS_DATA_PATH}/knowledge-base:/data/knowledge-repo:rw
+      - ${HORUS_DATA_PATH}/vaults/default:/data/knowledge-repo:rw
       # Write-path workspace: staging area for draft pages before PR
       - vault-workspace:/data/workspace
     environment:

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command11 } from "commander";
-import chalk11 from "chalk";
+import { Command as Command13 } from "commander";
+import chalk13 from "chalk";
 
 // src/commands/setup.ts
 import { Command as Command2 } from "commander";
@@ -139,6 +139,7 @@ function buildConfigFromParsed(parsed) {
       vault_rest: parsedPorts?.vault_rest ?? defaults.ports.vault_rest,
       vault_mcp: parsedPorts?.vault_mcp ?? defaults.ports.vault_mcp,
       vault_router: parsedPorts?.vault_router ?? defaults.ports.vault_router,
+      ui: parsedPorts?.ui ?? defaults.ports.ui,
       forge: parsedPorts?.forge ?? defaults.ports.forge,
       typesense: parsedPorts?.typesense ?? defaults.ports.typesense,
       neo4j_http: parsedPorts?.neo4j_http ?? defaults.ports.neo4j_http,
@@ -672,6 +673,11 @@ var FORGE_SERVICE = `  # \u2500\u2500 Forge \u2500\u2500\u2500\u2500\u2500\u2500
       - FORGE_SCAN_PATHS=\${FORGE_SCAN_PATHS:-/data/repos}
       - FORGE_SESSION_TTL_MS=\${FORGE_SESSION_TTL_MS:-1800000}
       - GITHUB_TOKEN=\${GITHUB_TOKEN:-}
+      # Fix git "dubious ownership" on bind-mounted repos (bug 4a32728f).
+      # Container UID differs from host UID that owns mounted repos.
+      - GIT_CONFIG_COUNT=1
+      - GIT_CONFIG_KEY_0=safe.directory
+      - GIT_CONFIG_VALUE_0=*
       - TYPESENSE_HOST=typesense
       - TYPESENSE_PORT=8108
       - TYPESENSE_API_KEY=\${TYPESENSE_API_KEY:-horus-local-key}
@@ -1083,6 +1089,25 @@ function mergeAndWriteConfig(configPath, mcpServers) {
   mkdirSync2(dir, { recursive: true });
   writeFileSync3(configPath, JSON.stringify(existing, null, 2) + "\n", "utf-8");
 }
+function detectNpxPath() {
+  const candidates = ["/opt/homebrew/bin/npx", "/usr/local/bin/npx"];
+  for (const candidate of candidates) {
+    if (existsSync4(candidate)) {
+      return candidate;
+    }
+  }
+  return "npx";
+}
+function buildClaudeDesktopServers(config, host) {
+  const npxPath = detectNpxPath();
+  const npxDir = npxPath === "npx" ? "/usr/local/bin" : npxPath.substring(0, npxPath.lastIndexOf("/"));
+  const envPath = `${npxDir}:/usr/local/bin:/usr/bin:/bin`;
+  return {
+    anvil: { command: npxPath, args: ["mcp-remote", `http://${host}:${config.ports.anvil}/mcp`], env: { PATH: envPath } },
+    vault: { command: npxPath, args: ["mcp-remote", `http://${host}:${config.ports.vault_mcp}/mcp`], env: { PATH: envPath } },
+    forge: { command: npxPath, args: ["mcp-remote", `http://${host}:${config.ports.forge}/mcp`], env: { PATH: envPath } }
+  };
+}
 async function isClaudeCliAvailable() {
   try {
     const result = await execa2("claude", ["--version"], { reject: false });
@@ -1181,7 +1206,8 @@ async function runConnect(config, runtime, targets, host = "localhost") {
       const desktopSpinner = ora(`Configuring ${chalk.cyan("claude-desktop")}...`).start();
       try {
         const configPath = getConfigPath(target);
-        mergeAndWriteConfig(configPath, httpServers);
+        const desktopServers = buildClaudeDesktopServers(config, host);
+        mergeAndWriteConfig(configPath, desktopServers);
         desktopSpinner.succeed(`Configured ${chalk.cyan("claude-desktop")} \u2014 ${chalk.dim(configPath)}`);
         configured.push(target);
       } catch (error) {
@@ -1333,7 +1359,7 @@ function extractHostname(url) {
     return "github.com";
   }
 }
-var setupCommand = new Command2("setup").description("Interactive first-run setup for Horus").option("-y, --yes", "Non-interactive mode (use defaults + env vars)").option("--runtime <runtime>", "Container runtime to use: docker or podman (non-interactive only)").option("--data-dir <path>", "Data directory path").option("--repos-path <path>", "Host repos path for Forge scanning").option("--anvil-repo <url>", "Anvil notes repository URL").option("--vault-name <name>", "Vault name (can be specified multiple times)").option("--vault-repo <url>", "Vault knowledge-base repository URL (matches positionally with --vault-name)").option("--forge-repo <url>", "Forge registry repository URL").option("--github-token <token>", "GitHub personal access token for private repos (primary host)").action(async (opts) => {
+var setupCommand = new Command2("setup").description("Interactive first-run setup for Horus").option("-y, --yes", "Non-interactive mode (use defaults + env vars)").option("--runtime <runtime>", "Container runtime to use: docker or podman (non-interactive only)").option("--data-dir <path>", "Data directory path").option("--repos-path <path>", "Host repos path for Forge scanning").option("--anvil-repo <url>", "Anvil notes repository URL").option("--vault-name <name>", "Vault name (can be specified multiple times)").option("--vault-repo <url>", "Vault knowledge-base repository URL (matches positionally with --vault-name)").option("--forge-repo <url>", "Forge registry repository URL").option("--github-token <token>", "GitHub personal access token for private repos (primary host)").option("--claude-desktop", "Configure Claude Desktop MCP servers during setup (non-interactive opt-in)").action(async (opts) => {
   console.log("");
   console.log(chalk2.bold("Horus Setup"));
   console.log(chalk2.dim("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
@@ -1478,6 +1504,7 @@ var setupCommand = new Command2("setup").description("Interactive first-run setu
         vault_rest: vault_rest ?? DEFAULT_PORTS.vault_rest,
         vault_mcp: vault_mcp ?? DEFAULT_PORTS.vault_mcp,
         vault_router: vault_router ?? DEFAULT_PORTS.vault_router,
+        ui: DEFAULT_PORTS.ui,
         forge: forge ?? DEFAULT_PORTS.forge,
         typesense: DEFAULT_PORTS.typesense,
         neo4j_http: DEFAULT_PORTS.neo4j_http,
@@ -1731,11 +1758,28 @@ ${example(`${vaultName.trim()}-knowledge`)}
   const detectedClients = detectInstalledClients();
   if (detectedClients.length > 0) {
     console.log(chalk2.bold("Configuring AI clients..."));
-    try {
-      await runConnect(config, runtime, detectedClients, "localhost");
-    } catch (error) {
-      console.log(chalk2.yellow("Could not configure AI clients automatically."));
-      console.log(chalk2.dim(`Run ${chalk2.cyan("horus connect")} to configure them manually.`));
+    let clientsToConnect = [...detectedClients];
+    if (clientsToConnect.includes("claude-desktop")) {
+      let configureDesktop;
+      if (opts.yes) {
+        configureDesktop = opts.claudeDesktop === true;
+        if (!configureDesktop) {
+          console.log(chalk2.dim("Skipping Claude Desktop (pass --claude-desktop to configure it)."));
+        }
+      } else {
+        configureDesktop = opts.claudeDesktop === false ? false : await confirm({ message: "Setup for Claude Desktop?", default: true });
+      }
+      if (!configureDesktop) {
+        clientsToConnect = clientsToConnect.filter((c) => c !== "claude-desktop");
+      }
+    }
+    if (clientsToConnect.length > 0) {
+      try {
+        await runConnect(config, runtime, clientsToConnect, "localhost");
+      } catch (error) {
+        console.log(chalk2.yellow("Could not configure AI clients automatically."));
+        console.log(chalk2.dim(`Run ${chalk2.cyan("horus connect")} to configure them manually.`));
+      }
     }
   } else {
     console.log(chalk2.dim(`No AI clients detected. Run ${chalk2.cyan("horus connect")} after installing Claude Desktop, Claude Code, or Cursor.`));
@@ -2461,6 +2505,16 @@ function checkDataDir(dataDir) {
     };
   }
 }
+function checkGhostDataDir() {
+  const ghostDir = join5(HORUS_DIR, "horus-data");
+  if (!existsSync7(ghostDir)) return null;
+  return {
+    status: "warn",
+    label: "Ghost data directory",
+    message: `Legacy directory ~/Horus/horus-data/ exists \u2014 this is not used by Horus`,
+    hint: `Delete it: rm -rf "${ghostDir}"`
+  };
+}
 function checkDiskSpace(dataDir) {
   const checkDir = existsSync7(dataDir) ? dataDir : join5(dataDir, "..");
   try {
@@ -2585,6 +2639,8 @@ var doctorCommand = new Command8("doctor").description("Diagnose common Horus is
   allResults.push(checkPort(ports.forge, "Forge"));
   allResults.push(checkDataDir(dataDir));
   allResults.push(checkDiskSpace(dataDir));
+  const ghostCheck = checkGhostDataDir();
+  if (ghostCheck) allResults.push(ghostCheck);
   const runtimeOk = allResults[0].status !== "fail";
   const composeOk = allResults[1].status !== "fail";
   if (runtimeOk && composeOk) {
@@ -3359,8 +3415,357 @@ testEnvCommand.command("seed").description("Populate a slot with test fixtures (
   console.log(chalk10.dim("Services will re-index automatically. Allow ~10s before running tests."));
 });
 
+// src/commands/help.ts
+import { Command as Command11 } from "commander";
+import chalk11 from "chalk";
+import { readFileSync as readFileSync7, existsSync as existsSync10 } from "fs";
+import { join as join9, dirname as dirname3 } from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
+
+// src/lib/guide-retrieval.ts
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "the",
+  "a",
+  "an",
+  "and",
+  "or",
+  "but",
+  "if",
+  "then",
+  "else",
+  "when",
+  "while",
+  "of",
+  "in",
+  "on",
+  "at",
+  "to",
+  "from",
+  "for",
+  "with",
+  "by",
+  "as",
+  "about",
+  "this",
+  "that",
+  "these",
+  "those",
+  "it",
+  "its",
+  "they",
+  "them",
+  "their",
+  "he",
+  "she",
+  "we",
+  "you",
+  "your",
+  "our",
+  "my",
+  "me",
+  "us",
+  "his",
+  "her",
+  "him",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "being",
+  "am",
+  "have",
+  "has",
+  "had",
+  "having",
+  "do",
+  "does",
+  "did",
+  "doing",
+  "will",
+  "would",
+  "could",
+  "should",
+  "can",
+  "may",
+  "might",
+  "must",
+  "shall",
+  "not",
+  "no",
+  "yes",
+  "so",
+  "too",
+  "very",
+  "just",
+  "only",
+  "also",
+  "all",
+  "any",
+  "some",
+  "each",
+  "every",
+  "more",
+  "most",
+  "much",
+  "many",
+  "one",
+  "two",
+  "three",
+  "here",
+  "there",
+  "where",
+  "how",
+  "why",
+  "what",
+  "who",
+  "which"
+]);
+function tokenizeQuery(text) {
+  return text.toLowerCase().replace(/```[\s\S]*?```/g, " ").replace(/`[^`]*`/g, " ").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter((t) => t.length >= 2 && !STOP_WORDS.has(t));
+}
+var K1 = 1.5;
+var B = 0.75;
+function termFreq(token, tokens) {
+  let n = 0;
+  for (const t of tokens) if (t === token) n++;
+  return n;
+}
+function docFreq(token, guides) {
+  let n = 0;
+  for (const g of guides) {
+    if (g.tokens.includes(token)) n++;
+  }
+  return n;
+}
+function bm25Score(queryTokens, doc, avgDocLen, n, guides) {
+  let score = 0;
+  const docLen = doc.tokens.length;
+  for (const q of queryTokens) {
+    const f = termFreq(q, doc.tokens);
+    if (f === 0) continue;
+    const df = docFreq(q, guides);
+    const idf = Math.log((n - df + 0.5) / (df + 0.5) + 1);
+    const norm = f * (K1 + 1) / (f + K1 * (1 - B + B * docLen / avgDocLen));
+    score += idf * norm;
+  }
+  return score;
+}
+function retrieve(query, index, maxAlternates = 3) {
+  const queryTokens = tokenizeQuery(query);
+  if (queryTokens.length === 0 || index.guides.length === 0) {
+    return { primary: null, alternates: [] };
+  }
+  const n = index.guides.length;
+  const totalLen = index.guides.reduce((s, g) => s + g.tokens.length, 0);
+  const avgDocLen = totalLen / n;
+  const scored = index.guides.map((g) => ({ guide: g, score: bm25Score(queryTokens, g, avgDocLen, n, index.guides) })).filter((s) => s.score > 0).sort((a, b) => b.score - a.score);
+  if (scored.length === 0) {
+    return { primary: null, alternates: [] };
+  }
+  const primary = scored[0].guide;
+  const alternates = scored.slice(1, 1 + maxAlternates).map((s) => s.guide);
+  return { primary, alternates };
+}
+
+// src/commands/help.ts
+function findGuidesDir() {
+  let dir = dirname3(fileURLToPath3(import.meta.url));
+  const seen = /* @__PURE__ */ new Set();
+  while (dir !== dirname3(dir) && !seen.has(dir)) {
+    seen.add(dir);
+    const candidate = join9(dir, "guides");
+    if (existsSync10(candidate) && existsSync10(join9(candidate, "index.json"))) {
+      return candidate;
+    }
+    dir = dirname3(dir);
+  }
+  throw new Error(
+    "Could not find the bundled Horus guides directory. Try reinstalling: npm install -g @arkhera30/cli"
+  );
+}
+function loadIndex(guidesDir) {
+  const indexPath = join9(guidesDir, "index.json");
+  return JSON.parse(readFileSync7(indexPath, "utf8"));
+}
+function stripFrontMatter(content) {
+  return content.replace(/^---\n[\s\S]*?\n---\n?/, "");
+}
+function printTopicIndex(index) {
+  console.log("");
+  console.log(chalk11.bold("Horus Help \u2014 Available Guides"));
+  console.log(chalk11.dim("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+  console.log("");
+  for (const g of index.guides) {
+    console.log(`  ${chalk11.cyan(g.slug.padEnd(20))} ${g.title}`);
+    console.log(`  ${" ".repeat(20)} ${chalk11.dim(g.description)}`);
+    console.log("");
+  }
+  console.log(chalk11.dim("Example queries:"));
+  console.log(chalk11.dim("  horus help how do I start"));
+  console.log(chalk11.dim("  horus help what is a forge workspace"));
+  console.log(chalk11.dim("  horus help create my first anvil note"));
+  console.log("");
+  console.log(chalk11.dim("To print a specific guide directly:"));
+  console.log(chalk11.dim("  horus guide <slug>"));
+  console.log("");
+}
+function printGuideBody(guidesDir, file) {
+  const path = join9(guidesDir, file);
+  const content = readFileSync7(path, "utf8");
+  console.log(stripFrontMatter(content));
+}
+function printSeeAlso(alternates, guidesDir) {
+  if (alternates.length === 0) return;
+  console.log(chalk11.dim("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+  console.log(chalk11.bold("See also:"));
+  for (const a of alternates) {
+    console.log(`  ${chalk11.cyan(a.slug.padEnd(20))} ${a.title}`);
+    console.log(`  ${" ".repeat(20)} ${chalk11.dim(join9(guidesDir, a.file))}`);
+  }
+  console.log("");
+}
+function printFooter() {
+  console.log(
+    chalk11.dim(
+      "Run `horus guide <slug>` to print a specific guide without retrieval, or `horus guide` to list all."
+    )
+  );
+  console.log("");
+}
+var helpCommand = new Command11("help").description("Search and print bundled Horus getting-started guides").argument("[query...]", "Natural-language query. Omit to see the topic index.").action((query) => {
+  const guidesDir = findGuidesDir();
+  const index = loadIndex(guidesDir);
+  if (!query || query.length === 0) {
+    printTopicIndex(index);
+    return;
+  }
+  const queryStr = query.join(" ");
+  const result = retrieve(queryStr, index, 3);
+  if (!result.primary) {
+    console.log("");
+    console.log(chalk11.yellow(`No guide matched "${queryStr}".`));
+    console.log("");
+    console.log(chalk11.dim("Try `horus help` with no arguments to see the full topic index,"));
+    console.log(chalk11.dim("or pick a slug directly with `horus guide <slug>`."));
+    console.log("");
+    return;
+  }
+  console.log("");
+  console.log(chalk11.dim(`# ${result.primary.title}  (${result.primary.slug})`));
+  console.log("");
+  printGuideBody(guidesDir, result.primary.file);
+  console.log("");
+  printSeeAlso(result.alternates, guidesDir);
+  printFooter();
+});
+
+// src/commands/guide.ts
+import { Command as Command12 } from "commander";
+import chalk12 from "chalk";
+import { readFileSync as readFileSync8, existsSync as existsSync11 } from "fs";
+import { join as join10, dirname as dirname4 } from "path";
+import { fileURLToPath as fileURLToPath4 } from "url";
+function findGuidesDir2() {
+  let dir = dirname4(fileURLToPath4(import.meta.url));
+  const seen = /* @__PURE__ */ new Set();
+  while (dir !== dirname4(dir) && !seen.has(dir)) {
+    seen.add(dir);
+    const candidate = join10(dir, "guides");
+    if (existsSync11(candidate) && existsSync11(join10(candidate, "index.json"))) {
+      return candidate;
+    }
+    dir = dirname4(dir);
+  }
+  throw new Error(
+    "Could not find the bundled Horus guides directory. Try reinstalling: npm install -g @arkhera30/cli"
+  );
+}
+function loadIndex2(guidesDir) {
+  return JSON.parse(readFileSync8(join10(guidesDir, "index.json"), "utf8"));
+}
+function lookupTopic(topic, index) {
+  const t = topic.trim().toLowerCase();
+  if (!t) return { tier: "none", matches: [] };
+  const exact = index.guides.filter((g) => g.slug === t);
+  if (exact.length > 0) return { tier: "exact-slug", matches: exact };
+  const prefix = index.guides.filter((g) => g.slug.startsWith(t));
+  if (prefix.length > 0) return { tier: "slug-prefix", matches: prefix };
+  const titleHits = index.guides.filter((g) => g.title.toLowerCase().includes(t));
+  if (titleHits.length > 0) return { tier: "title-fuzzy", matches: titleHits };
+  const kwHits = index.guides.filter(
+    (g) => g.keywords.some((k) => k.toLowerCase() === t)
+  );
+  if (kwHits.length > 0) return { tier: "keyword", matches: kwHits };
+  return { tier: "none", matches: [] };
+}
+function printGuideList(index) {
+  console.log("");
+  console.log(chalk12.bold("Bundled Horus Guides"));
+  console.log(chalk12.dim("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+  console.log("");
+  for (const g of index.guides) {
+    console.log(`  ${chalk12.cyan(g.slug.padEnd(20))} ${g.title}`);
+    console.log(`  ${" ".repeat(20)} ${chalk12.dim(g.description)}`);
+    console.log("");
+  }
+  console.log(chalk12.dim("Print a guide:            horus guide <slug>"));
+  console.log(chalk12.dim("Print a guide file path:  horus guide <slug> --path"));
+  console.log(chalk12.dim("Print the guides root:    horus guide --path"));
+  console.log("");
+}
+function printGuideBody2(guidesDir, file) {
+  const content = readFileSync8(join10(guidesDir, file), "utf8");
+  console.log(content.replace(/^---\n[\s\S]*?\n---\n?/, ""));
+}
+function printDisambiguation(tier, matches) {
+  console.log("");
+  console.log(chalk12.yellow(`Multiple guides matched (tier: ${tier}):`));
+  console.log("");
+  for (const m of matches) {
+    console.log(`  ${chalk12.cyan(m.slug.padEnd(20))} ${m.title}`);
+  }
+  console.log("");
+  console.log(chalk12.dim("Pick one: horus guide <slug>"));
+  console.log("");
+}
+var guideCommand = new Command12("guide").description("Print a bundled Horus guide, or list all guides").argument("[topic]", "Slug, slug prefix, or search term. Omit to list all guides.").option("--path", "Print the file path instead of the body (or the guides dir root if no topic)").action((topic, opts) => {
+  const guidesDir = findGuidesDir2();
+  const index = loadIndex2(guidesDir);
+  if (!topic) {
+    if (opts.path) {
+      console.log(guidesDir);
+      return;
+    }
+    printGuideList(index);
+    return;
+  }
+  const result = lookupTopic(topic, index);
+  if (result.matches.length === 0) {
+    console.log("");
+    console.log(chalk12.yellow(`No guide matched "${topic}".`));
+    console.log("");
+    console.log(chalk12.dim("Run `horus guide` to see all available guides."));
+    console.log("");
+    process.exitCode = 1;
+    return;
+  }
+  if (result.matches.length > 1) {
+    printDisambiguation(result.tier, result.matches);
+    process.exitCode = 1;
+    return;
+  }
+  const match = result.matches[0];
+  if (opts.path) {
+    console.log(join10(guidesDir, match.file));
+    return;
+  }
+  printGuideBody2(guidesDir, match.file);
+});
+
 // src/index.ts
-var program = new Command11();
+var program = new Command13();
 program.name("horus").description("CLI for managing the Horus Docker Compose stack").version(CLI_VERSION);
 program.addCommand(setupCommand);
 program.addCommand(upCommand);
@@ -3372,6 +3777,8 @@ program.addCommand(updateCommand);
 program.addCommand(doctorCommand);
 program.addCommand(backupCommand);
 program.addCommand(testEnvCommand);
+program.addCommand(helpCommand);
+program.addCommand(guideCommand);
 program.exitOverride();
 try {
   await program.parseAsync(process.argv);
@@ -3380,9 +3787,9 @@ try {
     process.exit(0);
   }
   if (error instanceof Error) {
-    console.error(chalk11.red(`Error: ${error.message}`));
+    console.error(chalk13.red(`Error: ${error.message}`));
   } else {
-    console.error(chalk11.red("An unexpected error occurred."));
+    console.error(chalk13.red("An unexpected error occurred."));
   }
   process.exit(1);
 }

package/guides/core-concepts.md

@@ -0,0 +1,111 @@
+---
+title: Horus Core Concepts
+description: The mental model for Anvil, Vault, Forge, and the supporting services Horus depends on.
+slug: core-concepts
+tags: [concepts, architecture, onboarding, anvil, vault, forge]
+schema_version: 1
+keywords: [concepts, architecture, mental-model, anvil, vault, forge, neo4j, typesense, mcp, services, how-it-works, overview]
+related_commands: [horus status, horus config]
+sidebar_position: 2
+---
+
+# Horus Core Concepts
+
+Horus is three primary systems (Anvil, Vault, Forge) backed by supporting services (Typesense, Neo4j, a web UI). This guide explains what each one does, why it exists as a separate service, and how they connect.
+
+## The three primary systems
+
+### Anvil — live state
+
+Anvil stores your structured, **changing** data: tasks, stories, projects, journals, notes, conversation state. Every entity is a markdown file with YAML front-matter, indexed by an embedded SQLite database for fast full-text search.
+
+Anvil has a **dynamic type system** — type definitions are YAML files, not hardcoded in the server. That means you can add new note types or extend existing ones without changing code. Claude always queries the current type schema before creating a note, so your types stay authoritative.
+
+**Use Anvil for:** tasks, projects, meeting notes, daily journals, research notes, anything you'd put in a personal knowledge-management app.
+
+**MCP endpoint:** `http://localhost:8100`
+
+### Vault — durable knowledge
+
+Vault stores your **long-lived**, structured documentation: repo profiles, architecture decisions, how-to guides, procedures, and learnings. Unlike Anvil (which tracks changing state), Vault is the place for knowledge you want to reference across sessions, weeks, and projects.
+
+Vault is a FastAPI knowledge service backed by a git repository per vault. You can run **multiple vaults** (e.g. `personal`, `work`, `client-acme`) — each is a separate repo with its own access controls and git history. A separate `vault-router` service fans out read queries to all vaults and routes writes to the correct one by UUID.
+
+Search is powered by both Typesense (full-text, typo-tolerant) and Neo4j (graph traversal for "what's related to what"). You get semantic-ish retrieval without a GPU or an external API.
+
+**Use Vault for:** how does this codebase work, what conventions does that team follow, what's the decision history for this architecture choice.
+
+**MCP endpoint:** `http://localhost:8300` (via the `vault-mcp` adapter)
+
+### Forge — execution environment
+
+Forge is the **workspace and session manager**. It does three distinct things:
+
+1. **Workspaces** — isolated contexts (MCP configs, skills, permissions) for a particular line of work. A workspace doesn't clone any code; it's just the agent environment.
+2. **Sessions** — git worktrees tied to a work item, created on demand via `forge_develop`. A session is where code changes actually happen.
+3. **Repo index** — a scanned index of your local Git repositories, made available to Claude so it can resolve and search across them.
+
+Forge also manages **plugins and skills** — reusable packages that install into the registry and add capabilities to your workspaces.
+
+**Use Forge for:** starting coded work, managing isolated contexts per project, discovering which repos exist on your machine.
+
+**MCP endpoint:** `http://localhost:8200`
+
+## Supporting services
+
+### Typesense
+
+A full-text and vector search engine that runs inside the Horus stack. Both Anvil and Vault use Typesense under the hood for fast, typo-tolerant search. You don't interact with Typesense directly — it's internal plumbing exposed only inside the Docker network.
+
+### Neo4j
+
+A graph database for relationship-aware queries. Vault uses Neo4j to store and traverse the graph of entities and edges between knowledge pages — useful for questions like "what's related to this decision" or "walk me from this ADR to the procedures that implement it". Runs on ports **7474** (browser / HTTP) and **7687** (Bolt protocol).
+
+### Horus UI
+
+A React web interface at **`http://localhost:8400`** that lets you browse Anvil notes, Vault pages, and Forge workspaces without going through Claude. It's served by an Express proxy that fans requests out to Anvil, Vault MCP, and Forge over the internal Docker network. Optional — Claude works fine without it — but handy for a visual sanity check.
+
+## How they connect
+
+Everything runs in a single Docker Compose stack on a bridge network named `horus-net`. Claude (Desktop, Code, or Cursor) connects via the Model Context Protocol (MCP) to three endpoints on your host:
+
+| Service | Host endpoint | Who talks to it |
+|---|---|---|
+| Anvil | `http://localhost:8100` | Claude, Horus UI |
+| Vault MCP | `http://localhost:8300` | Claude, Horus UI |
+| Forge | `http://localhost:8200` | Claude, Horus UI |
+
+Internally, Vault MCP proxies to the `vault-router`, which fans out to each `vault` instance on ports `8001`, `8002`, etc. Anvil and Vault both query Typesense over the internal network. Forge reads repo metadata from the host filesystem via a read-only bind mount.
+
+## Data layout
+
+All durable state lives under your data directory (default `~/Horus/data`). On a fresh install you'll see:
+
+```
+~/Horus/data/
+  notes/             Anvil notes (git repo)
+  vaults/
+    <name>/          Each vault is a separate git repo
+  registry/          Forge plugin registry (git repo)
+  workspaces/        Forge workspace directories
+  sessions/          Forge session git worktrees
+  repos/             Managed clone pool (created by forge_repo_clone)
+  config/            Forge-managed config (forge.yaml, repos.json, workspaces.json)
+  typesense-data/    Typesense index (internal)
+```
+
+User config lives at `~/Horus/config.yaml` and `~/Horus/.env`. The Docker Compose file is installed at `~/Horus/docker-compose.yml` — edit it only if you know what you're doing; `horus setup` regenerates it from the config.
+
+## Key principles
+
+1. **Everything is local.** All data stays on your machine. Search runs in-process. The only network traffic is to Anthropic (when Claude talks to the API) and to your own Git remotes for sync.
+2. **Data is durable.** Notes, knowledge, and workspaces are files on disk backed by git. Stopping the stack or removing containers never deletes your data.
+3. **Routing is automatic.** You don't pick Anvil vs Vault vs Forge — Claude reads the routing rules from the `horus-*` skills and picks the right system based on intent.
+4. **Types are dynamic.** Anvil's type system is runtime-defined. New types and fields land without a code release.
+
+## What's next
+
+- **`horus guide getting-started`** if you haven't installed yet
+- **`horus guide first-note`** to create your first Anvil entity
+- **`horus guide first-workspace`** to set up your first isolated working context
+- **`horus guide first-session`** to start your first isolated code session