@swarmvaultai/cli 0.1.32 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SwarmVault
+
+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/README.md

@@ -2,7 +2,7 @@
 
 `@swarmvaultai/cli` is the global command-line entry point for SwarmVault.
 
-It gives you the `swarmvault` command for building a local-first knowledge vault from files, DOCX documents, URLs, browser clips, saved query outputs, and guided exploration runs.
+It gives you the `swarmvault` command for building a local-first knowledge vault from files, reStructuredText and DOCX documents, URLs, browser clips, saved query outputs, and guided exploration runs.
 
 ## Install
 
@@ -23,6 +23,10 @@ Installed commands:
 mkdir my-vault
 cd my-vault
 swarmvault init --obsidian
+swarmvault source add https://github.com/karpathy/micrograd
+swarmvault source add https://example.com/docs/getting-started
+swarmvault source list
+swarmvault source reload --all
 sed -n '1,120p' swarmvault.schema.md
 swarmvault ingest ./notes.md
 swarmvault ingest ./repo
@@ -63,6 +67,26 @@ Create a workspace with:
 
 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 source add|list|reload|delete`
+
+Manage recurring source roots through a registry-backed workflow.
+
+- `source add <input>` supports local directories, public GitHub repo root URLs such as `https://github.com/karpathy/micrograd`, and docs/wiki/help/reference/tutorial hubs
+- by default `source add` registers the source, syncs it into the vault, runs one compile, and writes a source brief to `wiki/outputs/source-briefs/<source-id>.md`
+- `source list` shows every managed source with its kind, status, and current brief path
+- `source reload [id]` re-syncs one source, or use `--all` to refresh everything in the registry and compile once
+- `source delete <id>` unregisters the source and removes transient sync state under `state/sources/<id>/`, but leaves canonical `raw/`, `wiki/`, and saved output artifacts intact
+
+Useful flags:
+
+- `--all`
+- `--no-compile`
+- `--no-brief`
+- `--max-pages <n>`
+- `--max-depth <n>`
+
+Managed sources write registry state to `state/sources.json`. Local directory entries remain compatible with `watch --repo`; remote GitHub and docs-crawl sources are manual `source reload` sources in this release.
+
 ### `swarmvault ingest <path-or-url>`
 
 Ingest a local file path, directory path, or URL into immutable source storage and write manifests to `state/manifests/`.
@@ -70,9 +94,10 @@ Ingest a local file path, directory path, or URL into immutable source storage a
 - local directories recurse by default
 - directory ingest respects `.gitignore` unless you pass `--no-gitignore`
 - repo-aware directory ingest records `repoRelativePath` and later compile writes `state/code-index.json`
+- use `source add` instead when the same local directory, public GitHub repo root, or docs hub should stay registered and reloadable
 - URL ingest still localizes remote image references by default
-- local file ingest supports markdown, text, HTML, PDF, DOCX, images, and code
-- code-aware directory ingest currently covers JavaScript, TypeScript, Python, Go, Rust, Java, C#, C, C++, PHP, Ruby, and PowerShell
+- local file ingest supports markdown, text, reStructuredText, HTML, PDF, DOCX, images, and code
+- code-aware directory ingest currently covers JavaScript, TypeScript, Python, Go, Rust, Java, C#, C, C++, PHP, Ruby, PowerShell, Kotlin, and Scala
 
 Useful flags:
 
@@ -89,6 +114,8 @@ Useful flags:
 
 Repo ingest defaults to `first_party` material. The extra `--include-*` flags opt dependency trees, resource bundles, and generated output back in when you actually want them in the vault.
 
+Large repo ingest now emits low-noise progress on materially large batches, and parser compatibility failures stay local to the affected source instead of aborting unrelated analysis.
+
 ### `swarmvault add <url>`
 
 Capture supported URLs through a normalized markdown layer before ingesting them into the vault.
@@ -100,6 +127,7 @@ Capture supported URLs through a normalized markdown layer before ingesting them
 - unsupported URLs fall back to generic URL ingest instead of failing
 - optional metadata: `--author <name>` and `--contributor <name>`
 - normalized captures record fields such as `source_type`, `source_url`, `canonical_url`, `title`, `authors`, `published_at`, `updated_at`, `doi`, and `tags` when available
+- use `source add` instead when the URL is a public GitHub repo root or a docs hub that should stay synced over time
 
 ### `swarmvault inbox import [dir]`
 
@@ -315,6 +343,20 @@ Hook semantics:
 
 `aider` is intentionally file/config-based in this release rather than hook-based.
 
+### OpenClaw / ClawHub Skill
+
+If you use OpenClaw through ClawHub, install the packaged skill:
+
+```bash
+clawhub install swarmvault
+```
+
+That published bundle includes `SKILL.md`, a ClawHub README, examples, references, troubleshooting notes, and release-validation prompts. The CLI binary still comes from npm:
+
+```bash
+npm install -g @swarmvaultai/cli
+```
+
 ## Provider Configuration
 
 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.

package/dist/index.js

@@ -6,9 +6,11 @@ import process2 from "process";
 import {
   acceptApproval,
   addInput,
+  addManagedSource,
   archiveCandidate,
   benchmarkVault,
   compileVault,
+  deleteManagedSource,
   explainGraphVault,
   exploreVault,
   exportGraphFormat,
@@ -25,6 +27,7 @@ import {
   listApprovals,
   listCandidates,
   listGodNodes,
+  listManagedSourceRecords,
   listSchedules,
   loadVaultConfig,
   pathGraphVault,
@@ -34,6 +37,7 @@ import {
   queryVault,
   readApproval,
   rejectApproval,
+  reloadManagedSources,
   runSchedule,
   runWatchCycle,
   serveSchedules,
@@ -217,9 +221,9 @@ program.name("swarmvault").description("SwarmVault is a local-first LLM wiki com
 function readCliVersion() {
   try {
     const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "0.1.32";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "0.2.0";
   } catch {
-    return "0.1.32";
+    return "0.2.0";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -329,6 +333,61 @@ program.command("add").description("Capture supported URLs into normalized markd
     log(`${result.captureType}${result.fallback ? " (fallback)" : ""}: ${result.manifest.sourceId}`);
   }
 });
+var source = program.command("source").description("Manage recurring directory, public repo, and docs sources.");
+source.command("add").description("Register and sync a managed source from a directory, public GitHub repo root URL, or docs hub URL.").argument("<input>", "Directory path, public GitHub repo root URL, or docs hub URL").option("--no-compile", "Register and sync without compiling the vault").option("--no-brief", "Skip source brief generation after sync").option("--max-pages <n>", "Maximum number of pages to crawl for docs sources").option("--max-depth <n>", "Maximum crawl depth for docs sources").action(async (input, options) => {
+  const result = await addManagedSource(process2.cwd(), input, {
+    compile: options.compile,
+    brief: options.brief,
+    maxPages: options.maxPages ? parsePositiveInt(options.maxPages, 0) || void 0 : void 0,
+    maxDepth: options.maxDepth ? parsePositiveInt(options.maxDepth, 0) || void 0 : void 0
+  });
+  if (isJson()) {
+    emitJson(result);
+  } else {
+    log(
+      `Registered ${result.source.kind} source ${result.source.id}. Status: ${result.source.status}.${result.compile ? ` Compiled ${result.compile.sourceCount} source(s).` : ""}${result.briefGenerated ? ` Brief: ${result.source.briefPath}` : ""}`
+    );
+  }
+});
+source.command("list").description("List managed sources registered in this vault.").action(async () => {
+  const sources = await listManagedSourceRecords(process2.cwd());
+  if (isJson()) {
+    emitJson(sources);
+  } else if (sources.length === 0) {
+    log("No managed sources registered.");
+  } else {
+    for (const entry of sources) {
+      log(`${entry.id}  ${entry.kind}  ${entry.status}  ${entry.title}`);
+    }
+  }
+});
+source.command("reload").description("Re-sync one managed source or all managed sources, then optionally compile and refresh briefs.").argument("[id]", "Managed source id").option("--all", "Reload all managed sources", false).option("--no-compile", "Re-sync without compiling the vault").option("--no-brief", "Skip source brief generation after sync").option("--max-pages <n>", "Maximum number of pages to crawl for docs sources").option("--max-depth <n>", "Maximum crawl depth for docs sources").action(
+  async (id, options) => {
+    const result = await reloadManagedSources(process2.cwd(), {
+      id,
+      all: options.all ?? false,
+      compile: options.compile,
+      brief: options.brief,
+      maxPages: options.maxPages ? parsePositiveInt(options.maxPages, 0) || void 0 : void 0,
+      maxDepth: options.maxDepth ? parsePositiveInt(options.maxDepth, 0) || void 0 : void 0
+    });
+    if (isJson()) {
+      emitJson(result);
+    } else {
+      log(
+        `Reloaded ${result.sources.length} source(s).${result.compile ? ` Compiled ${result.compile.sourceCount} source(s).` : ""}${result.briefPaths.length ? ` Briefs: ${result.briefPaths.length}.` : ""}`
+      );
+    }
+  }
+);
+source.command("delete").description("Unregister a managed source and remove its transient sync state without deleting canonical vault content.").argument("<id>", "Managed source id").action(async (id) => {
+  const result = await deleteManagedSource(process2.cwd(), id);
+  if (isJson()) {
+    emitJson(result);
+  } else {
+    log(`Deleted managed source ${result.removed.id}. Canonical vault content was left in place.`);
+  }
+});
 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(process2.cwd(), dir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "0.1.32",
+  "version": "0.2.0",
   "description": "Global CLI for SwarmVault.",
   "type": "module",
   "main": "dist/index.js",
@@ -37,18 +37,18 @@
   "engines": {
     "node": ">=24.0.0"
   },
-  "scripts": {
-    "build": "tsup src/index.ts --format esm --dts",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
-  },
   "dependencies": {
-    "@swarmvaultai/engine": "0.1.32",
+    "@swarmvaultai/engine": "0.2.0",
     "commander": "^14.0.1"
   },
   "devDependencies": {
     "@types/node": "^24.6.0",
     "tsup": "^8.5.0",
     "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
-}
+}