replen 1.2.1 → 1.3.0

package/dist/index.js

@@ -21,6 +21,15 @@ Usage:
        [--root PATH ...]     and register them with Replen. Run after
                              cloning a new repo, or pass --root to point
                              at a non-conventional layout.
+  npx replen vault <spec>... Point Replen at a knowledge-graph vault
+                             (Obsidian / Graphify / ADRs) that lives OUTSIDE
+                             a repo, so onboarding grounds from it. Repeatable.
+                             A bare path is a global vault (covers all repos);
+                             owner/name=path scopes one to a repo. e.g.
+                               npx replen vault ~/ObsidianVault
+                               npx replen vault me/drone=~/graphs/drone
+                             \`npx replen vault --list\` shows configured vaults.
+                             (--vault PATH also works on \`npx replen\` + sync.)
   npx replen atlas           Write your knowledge graph as an owned,
                              Obsidian-compatible markdown vault to
                              ~/.replen/atlas/ (projects, capabilities,
@@ -134,6 +143,38 @@ async function main() {
             console.log(summary);
         return;
     }
+    if (cmd === "vault") {
+        const cfg = await readConfig();
+        if (!cfg) {
+            console.error("Not signed in. Run `npx replen` first.");
+            process.exit(1);
+        }
+        const { collectVaultFlags, persistVaults, summariseVaults, hasVaultFlags } = await import("./vaults.js");
+        if (argv.includes("--list")) {
+            const v = cfg.vaults;
+            const empty = !v || ((v.global?.length ?? 0) === 0 && Object.keys(v.byRepo ?? {}).length === 0);
+            console.log(empty
+                ? "No vaults configured.\n  Add one:  npx replen vault ~/ObsidianVault\n            npx replen vault owner/name=~/graphs/thing"
+                : "Configured knowledge-graph vaults:\n" + summariseVaults(v));
+            return;
+        }
+        const specs = argv.slice(1).filter((a) => !a.startsWith("-"));
+        if (specs.length === 0) {
+            console.error("Usage: npx replen vault <path | owner/name=path> ...   (or --list)");
+            process.exit(1);
+        }
+        const parsed = collectVaultFlags(specs.flatMap((s) => ["--vault", s]));
+        if (!hasVaultFlags(parsed)) {
+            console.error("No valid vault paths given (each must be an existing directory).");
+            process.exit(1);
+        }
+        const vaults = await persistVaults(parsed);
+        if (vaults) {
+            console.log(summariseVaults(vaults));
+            console.log("\n  Re-run /replen-onboard in Claude Code so the agent re-grounds from the vault.");
+        }
+        return;
+    }
     if (cmd === "sync-projects" || cmd === "sync") {
         const cfg = await readConfig();
         if (!cfg) {
@@ -141,6 +182,10 @@ async function main() {
             process.exit(1);
         }
         const explicitRoots = collectRootFlags(argv);
+        const { collectVaultFlags, persistVaults, summariseVaults } = await import("./vaults.js");
+        const savedVaults = await persistVaults(collectVaultFlags(argv));
+        if (savedVaults)
+            console.log(summariseVaults(savedVaults));
         const { syncDiscoveredProjects } = await import("./sync-projects.js");
         await syncDiscoveredProjects({ token: cfg.token, base: cfg.base, explicitRoots });
         return;
@@ -166,13 +211,23 @@ async function main() {
     if (cmd === undefined) {
         // Default: if already signed in, just rerun mcp setup. Otherwise, full flow.
         const cfg = await readConfig();
+        const { collectVaultFlags, persistVaults, summariseVaults } = await import("./vaults.js");
+        const parsedVaults = collectVaultFlags(argv);
         if (cfg) {
             console.log(`Already signed in to ${cfg.base}. Re-wiring MCP config…`);
             await setupMcp(cfg.token, cfg.base);
+            const v = await persistVaults(parsedVaults);
+            if (v)
+                console.log(summariseVaults(v));
             console.log(`\nDone. Run \`npx replen status\` to inspect.`);
             return;
         }
         await runInit();
+        // Config now exists — persist any --vault passed to first-run setup so the
+        // onboarding agent (run next in Claude Code) grounds from it.
+        const v = await persistVaults(parsedVaults);
+        if (v)
+            console.log(summariseVaults(v));
         return;
     }
     console.error(`Unknown command: ${cmd}\n`);

package/dist/vaults.js

@@ -0,0 +1,102 @@
+// `--vault` handling: let users point Replen at knowledge-graph vaults that
+// live OUTSIDE a repo (a central Obsidian vault, a Graphify graph kept
+// elsewhere, an ADR folder). In-repo vaults are auto-detected by the onboard
+// skill; this is the escape hatch for everything that isn't sitting in the repo.
+//
+// Two shapes, both via `--vault`:
+//   --vault ~/ObsidianVault              → GLOBAL: may cover many/all repos.
+//   --vault owner/name=~/graphs/thing    → scoped to one repo (GitHub owner/name).
+//
+// Parsed values are validated (must be an existing directory), tilde-expanded to
+// absolute paths, and merged into ~/.replen/config.json under `vaults`. The
+// onboarding agent reads that config and consults these paths as grounding
+// sources alongside the in-repo locations.
+import { statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { readConfig, writeConfig } from "./config.js";
+function expandTilde(p) {
+    if (p === "~" || p.startsWith("~/"))
+        return p === "~" ? homedir() : join(homedir(), p.slice(2));
+    return resolve(p);
+}
+function isDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Looks like a GitHub "owner/name" (no spaces, exactly one slash, no leading ./~). */
+function isRepoKey(s) {
+    return /^[^\s/]+\/[^\s/]+$/.test(s);
+}
+/**
+ * Pull every `--vault <val>` / `--vault=<val>` out of argv. A value of the form
+ * `owner/name=path` is repo-scoped; anything else is a global vault path.
+ * Invalid (non-directory) paths are reported and skipped, not fatal.
+ */
+export function collectVaultFlags(argv) {
+    const raw = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--vault" && argv[i + 1])
+            raw.push(argv[++i]);
+        else if (a.startsWith("--vault="))
+            raw.push(a.slice("--vault=".length));
+    }
+    const out = { global: [], byRepo: {} };
+    for (const val of raw) {
+        // Repo-scoped only when the part BEFORE the first "=" is a repo key — so a
+        // Windows-y or "="-containing path on the global side isn't misparsed.
+        const eq = val.indexOf("=");
+        if (eq > 0 && isRepoKey(val.slice(0, eq))) {
+            const repo = val.slice(0, eq);
+            const path = expandTilde(val.slice(eq + 1));
+            if (!isDir(path)) {
+                console.warn(`  · --vault ${repo}: not a directory, skipping: ${path}`);
+                continue;
+            }
+            out.byRepo[repo] = path;
+        }
+        else {
+            const path = expandTilde(val);
+            if (!isDir(path)) {
+                console.warn(`  · --vault: not a directory, skipping: ${path}`);
+                continue;
+            }
+            out.global.push(path);
+        }
+    }
+    return out;
+}
+export function hasVaultFlags(parsed) {
+    return parsed.global.length > 0 || Object.keys(parsed.byRepo).length > 0;
+}
+/**
+ * Merge newly-parsed vaults into the saved config (union global paths, overwrite
+ * per-repo entries). Idempotent. No-op if nothing was passed. Returns the
+ * resulting vaults block for an immediate confirmation message.
+ */
+export async function persistVaults(parsed) {
+    if (!hasVaultFlags(parsed))
+        return null;
+    const cfg = await readConfig();
+    if (!cfg)
+        return null;
+    const existing = cfg.vaults ?? {};
+    const global = Array.from(new Set([...(existing.global ?? []), ...parsed.global]));
+    const byRepo = { ...(existing.byRepo ?? {}), ...parsed.byRepo };
+    const vaults = { global, byRepo };
+    await writeConfig({ ...cfg, vaults });
+    return vaults;
+}
+export function summariseVaults(vaults) {
+    const lines = [];
+    for (const g of vaults.global ?? [])
+        lines.push(`  ✓ vault (all repos): ${g}`);
+    for (const [repo, p] of Object.entries(vaults.byRepo ?? {}))
+        lines.push(`  ✓ vault for ${repo}: ${p}`);
+    return lines.join("\n");
+}

package/extras/skills/replen-onboard/SKILL.md

@@ -155,6 +155,19 @@ grounding source (faster AND richer than a cold code-read):
 - **ADRs** (`docs/adr/*.md`, `doc/decisions/`) — architecture decisions are
   high-grade descriptor material and often name the load-bearing files.
 
+**Also check vaults the user pointed us at OUT of the repo.** Read
+`~/.replen/config.json`; if it has a `vaults` block, consult those paths too —
+`vaults.byRepo["<owner/name>"]` for this repo specifically, and every
+`vaults.global[]` path (a central Obsidian vault that covers many repos). These
+are first-class grounding sources, same treatment as an in-repo vault. This is
+how a user feeds a central vault that auto-detection can't see.
+
+If you find NO knowledge graph — not in the repo and none configured — and the
+session is interactive, ask once: "Do you keep design notes or an Obsidian /
+Graphify vault for this project? If so, point me at it with
+`npx replen vault <path>` (or `npx replen vault <owner/name>=<path>`) and re-run
+/replen-onboard — I'll ground from it." Then fall back to the code-read.
+
 If you ground from one of these, START the report (2c) with one line:
 `Grounding source: Graphify vault at <path>` (or `Obsidian vault…` / `ADRs…`)
 — it renders into the user's Atlas tiles, linking the two tools. Then skim the
@@ -162,6 +175,15 @@ code only to VERIFY (the vault may be stale); don't re-derive what it already
 holds. Privacy is unchanged: only capabilities/descriptors/paths/tags leave
 the machine, exactly as with a code-read — never vault content or code.
 
+**Use the note→note `[[wikilinks]]` BETWEEN concept/entity notes as capability-
+BOUNDARY evidence** (today you only follow note→FILE links, for `paths`). A tight
+same-as cluster of concepts → emit ONE capability tag (don't split a thing the
+user models as one). A concept fanning out to distinct linked clusters → split
+into the concrete techniques (this is the 2d "break broad capabilities" move,
+now backed by the user's own structure). A typed/deliberate cross-link between
+two distinct concepts → keep them as two RELATED tags. Then, if the vault gave
+you this structure, assemble the optional `concepts` array described in 2d.
+
 ### 2a. Read the code (not just the README)
 
 Read enough source to actually understand the project: entry points, the core
@@ -255,6 +277,18 @@ strings. Each is `{tag, descriptor, modality}`:
 Break broad capabilities into the concrete techniques the code uses. Be
 specific — `cloudflare bypass`/`proxy rotation`, not just `web scraping`.
 
+**If you grounded from a vault (2a-pre), also assemble a `concepts` array** so
+Replen can traverse the user's OWN graph for cross-repo leaps. For each
+concept/entity note — **NEVER a file/symbol/function/class/module note** — emit
+`{title, grounds: [the capability tags this note grounded], links: [{to: <other
+concept title>, rel}]}` where `rel` is one of `relates | refines | depends |
+same-as | contrast`. Pass it to `replen_set_capabilities` in 2e (it's optional —
+omit it entirely if there's no vault). Hard rules (already true for everything
+else, restated because this is new structure leaving the machine): lift only
+concept/capability-LEVEL notes; note BODIES and code never leave; a note→file
+link stays as a capability `path`, never a concept link; respect the cover —
+sanitize titles, no codenames.
+
 **Also capture architectural PRACTICES as capabilities.** Beyond what the code
 *does*, note the distinctive structural *moves* it makes — these are what let
 Replen suggest a pattern to your OTHER projects ("Aegis made its domain model
@@ -320,6 +354,10 @@ typed properties, computed properties as rows", never the entity names).
    Paths only, never code. You just read these files; recording WHERE each
    capability lives lets Replen point another of the user's projects straight
    at the implementation worth porting ("aegis solved this — see src/cv/…").
+   **If you grounded from a vault, also pass the `concepts` array from 2d** —
+   concept titles + their `[[wikilinks]]` only (never file/symbol notes, never
+   bodies). Replen turns these into graph nodes + your-own-graph leaps. Omit it
+   when there's no vault.
 4. **Report pinned versions** with `replen_set_versions` — the resolved DIRECT
    dependency versions from the lockfile (package-lock.json / poetry.lock /
    uv.lock / Cargo.lock), plus runtimes under canonical keys (`node` from

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replen",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Make your AI coding tools smarter. One command, no API keys, free. Replen watches what your projects actually do and surfaces a few things worth bringing in each month. Use one as is, port a piece of another, cherry pick an idea, or build it clean room. The match happens inside your AI tool's session. A few actionable matches a month, by design.",
   "type": "module",
   "bin": {
@@ -9,7 +9,8 @@
   "scripts": {
     "build": "tsc && chmod +x dist/index.js",
     "dev": "tsx src/index.ts",
-    "prepublishOnly": "npm run build"
+    "check:skill-sync": "node scripts/check-skill-sync.mjs",
+    "prepublishOnly": "npm run build && npm run check:skill-sync"
   },
   "files": [
     "dist",