@swarmvaultai/cli 0.1.2 → 0.1.4

package/README.md

@@ -1,8 +1,8 @@
 # @swarmvaultai/cli
 
-`@swarmvaultai/cli` is the globally installable entry point for SwarmVault.
+`@swarmvaultai/cli` is the global command-line entry point for SwarmVault.
 
-It gives you the `swarmvault` command for creating and operating a local-first LLM knowledge vault that compiles into markdown, graph data, and local search artifacts.
+It gives you the `swarmvault` command for building a local-first knowledge vault from files, URLs, browser clips, and saved query outputs.
 
 ## Install
 
@@ -23,9 +23,10 @@ Installed commands:
 mkdir my-vault
 cd my-vault
 swarmvault init
+sed -n '1,120p' swarmvault.schema.md
 swarmvault ingest ./notes.md
 swarmvault compile
-swarmvault query "What themes keep recurring?" --save
+swarmvault query "What keeps recurring?" --save
 swarmvault graph serve
 ```
 
@@ -33,47 +34,76 @@ swarmvault graph serve
 
 ### `swarmvault init`
 
-Creates a new SwarmVault workspace in the current directory, including:
+Create a workspace with:
 
+- `inbox/`
 - `raw/`
 - `wiki/`
 - `state/`
 - `agent/`
 - `swarmvault.config.json`
+- `swarmvault.schema.md`
+
+The schema file is the vault-specific instruction layer. Edit it to define naming rules, categories, grounding expectations, and exclusions before a serious compile.
 
 ### `swarmvault ingest <path-or-url>`
 
-Adds a local file or URL to the vault and records a manifest in `state/manifests/`.
+Ingest a local file path or URL into immutable source storage and write a manifest to `state/manifests/`.
+
+### `swarmvault inbox import [dir]`
+
+Import supported files from the configured inbox directory. This is meant for browser-clipper style markdown bundles and other capture workflows. Local image and asset references are preserved and copied into canonical storage under `raw/assets/`.
 
 ### `swarmvault compile`
 
-Compiles the current manifests into:
+Compile the current manifests into:
 
 - generated markdown in `wiki/`
 - structured graph data in `state/graph.json`
 - local search data in `state/search.sqlite`
 
+The compiler also reads `swarmvault.schema.md` and records a `schema_hash` in generated pages so schema edits can mark pages stale.
+
 ### `swarmvault query "<question>" [--save]`
 
-Queries the compiled vault. Use `--save` to write the result into `wiki/outputs/` so the answer becomes part of the vault.
+Query the compiled vault. The query layer also reads `swarmvault.schema.md`, so answers follow the vault’s own structure and grounding rules. With `--save`, the answer is written into `wiki/outputs/` so the result becomes part of the vault.
 
 ### `swarmvault lint`
 
-Runs anti-drift checks and other health checks against the current vault state.
+Run anti-drift and vault health checks such as stale pages, missing graph artifacts, and other structural issues.
+
+### `swarmvault watch [--lint] [--debounce <ms>]`
+
+Watch the inbox directory and trigger import and compile cycles when files change. With `--lint`, each cycle also runs linting. Run metadata is appended to `state/jobs.ndjson`.
+
+### `swarmvault mcp`
+
+Run SwarmVault as a local MCP server over stdio. This exposes the vault to compatible clients and agents through tools and resources such as:
+
+- `workspace_info`
+- `search_pages`
+- `read_page`
+- `list_sources`
+- `query_vault`
+- `ingest_input`
+- `compile_vault`
+- `lint_vault`
+
+The MCP surface also exposes `swarmvault://schema` and includes `schemaPath` in `workspace_info`.
 
 ### `swarmvault graph serve`
 
-Starts the local graph UI backed by `state/graph.json`.
+Start the local graph UI backed by `state/graph.json`.
 
 ### `swarmvault install --agent <codex|claude|cursor>`
 
-Writes agent-specific rules into the current project so your coding agent understands the SwarmVault directory contract and workflow.
+Install agent-specific rules into the current project so an agent understands the SwarmVault workspace contract and workflow.
 
 ## Provider Configuration
 
-SwarmVault defaults to a local heuristic provider so the CLI can run without API keys, but real vaults should usually point at an actual model provider.
+SwarmVault defaults to a local `heuristic` provider so the CLI works without API keys, but real vaults will usually point at an actual model provider.
 
-Inside an existing `swarmvault.config.json`, your `providers` and `tasks` sections can look like this:
+Example:
 
 ```json
 {
@@ -94,10 +124,16 @@ Inside an existing `swarmvault.config.json`, your `providers` and `tasks` sectio
 }
 ```
 
-Generic OpenAI-compatible APIs are also supported through config alone when the provider follows the same request shape closely enough.
+Generic OpenAI-compatible APIs are supported through config when the provider follows the OpenAI request shape closely enough.
 
 ## Troubleshooting
 
-- If `graph serve` says the viewer build is missing, run `pnpm build` in the repository first
+- If you are running from a source checkout and `graph serve` says the viewer build is missing, run `pnpm build` in the repository first
 - If a provider claims OpenAI compatibility but fails structured generation, declare only the capabilities it actually supports
-- Node 24 may emit an experimental warning for `node:sqlite`; this is expected in the current release
+- Node 24 may emit an experimental warning for `node:sqlite`; that is expected in the current release
+
+## Links
+
+- Website: https://www.swarmvault.ai
+- Docs: https://www.swarmvault.ai/docs
+- GitHub: https://github.com/swarmclawai/swarmvault

package/dist/index.js

@@ -5,15 +5,18 @@ import { Command } from "commander";
 import process from "process";
 import {
   compileVault,
+  importInbox,
   ingestInput,
   initVault,
   installAgent,
   lintVault,
   queryVault,
-  startGraphServer
+  startGraphServer,
+  startMcpServer,
+  watchVault
 } from "@swarmvaultai/engine";
 var program = new Command();
-program.name("swarmvault").description("SwarmVault is a local-first LLM wiki compiler with graph outputs and pluggable providers.").version("0.1.2");
+program.name("swarmvault").description("SwarmVault is a local-first LLM wiki compiler with graph outputs and pluggable providers.").version("0.1.4");
 program.command("init").description("Initialize a SwarmVault workspace in the current directory.").action(async () => {
   await initVault(process.cwd());
   process.stdout.write("Initialized SwarmVault workspace.\n");
@@ -23,6 +26,14 @@ program.command("ingest").description("Ingest a local file path or URL into the
   process.stdout.write(`${manifest.sourceId}
 `);
 });
+var inbox = program.command("inbox").description("Inbox and capture workflows.");
+inbox.command("import").description("Import supported files from the configured inbox directory.").argument("[dir]", "Optional inbox directory override").action(async (dir) => {
+  const result = await importInbox(process.cwd(), dir);
+  process.stdout.write(
+    `Imported ${result.imported.length} source(s) from ${result.inputDir}. Scanned: ${result.scannedCount}. Attachments: ${result.attachmentCount}. Skipped: ${result.skipped.length}.
+`
+  );
+});
 program.command("compile").description("Compile manifests into wiki pages, graph JSON, and search index.").action(async () => {
   const result = await compileVault(process.cwd());
   process.stdout.write(
@@ -63,6 +74,25 @@ graph.command("serve").description("Serve the local graph viewer.").option("--po
     process.exit(0);
   });
 });
+program.command("watch").description("Watch the inbox directory and run import/compile cycles on changes.").option("--lint", "Run lint after each compile cycle", false).option("--debounce <ms>", "Debounce window in milliseconds", "900").action(async (options) => {
+  const debounceMs = Number.parseInt(options.debounce ?? "900", 10);
+  const controller = await watchVault(process.cwd(), {
+    lint: options.lint ?? false,
+    debounceMs: Number.isFinite(debounceMs) ? debounceMs : 900
+  });
+  process.stdout.write("Watching inbox for changes. Press Ctrl+C to stop.\n");
+  process.on("SIGINT", async () => {
+    await controller.close();
+    process.exit(0);
+  });
+});
+program.command("mcp").description("Run SwarmVault as a local MCP server over stdio.").action(async () => {
+  const controller = await startMcpServer(process.cwd());
+  process.on("SIGINT", async () => {
+    await controller.close();
+    process.exit(0);
+  });
+});
 program.command("install").description("Install SwarmVault instructions for an agent in the current project.").requiredOption("--agent <agent>", "codex, claude, or cursor").action(async (options) => {
   const target = await installAgent(process.cwd(), options.agent);
   process.stdout.write(`Installed rules into ${target}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Global CLI for SwarmVault.",
   "type": "module",
   "main": "dist/index.js",
@@ -12,7 +12,7 @@
     "type": "git",
     "url": "git+https://github.com/swarmclawai/swarmvault.git"
   },
-  "homepage": "https://swarmvault.ai",
+  "homepage": "https://www.swarmvault.ai",
   "bugs": {
     "url": "https://github.com/swarmclawai/swarmvault/issues"
   },
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "commander": "^14.0.1",
-    "@swarmvaultai/engine": "0.1.2"
+    "@swarmvaultai/engine": "0.1.4"
   },
   "devDependencies": {
     "@types/node": "^24.6.0",