replen 1.2.0 → 1.2.2

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/init.js

@@ -166,13 +166,20 @@ export async function runInit() {
     const { runFirstIngest } = await import("./first-ingest.js");
     await runFirstIngest({ token: exchange.token, base: exchange.base, savedAt: "" });
     console.log("");
-    console.log("  All set. Restart Claude Code and try:");
-    console.log("    /replen       → triage today's candidates against this repo,");
-    console.log("                         in-session, using your subscription tokens");
-    console.log("    (no LLM API keys needed — the agent does the reasoning)");
+    console.log("  All set. Restart Claude Code, then do these two — IN THIS ORDER:");
     console.log("");
-    console.log("  Other MCP hosts (Codex / Cursor / Aider):");
-    console.log("    \"use replen_match\" — same tool, no slash command");
+    console.log("    1. /replen-onboard   ONE-TIME, FIRST. Reads your repos and builds a");
+    console.log("                         tailored profile so matches are relevant, not");
+    console.log("                         generic. Runs in the background — kick it off,");
+    console.log("                         then just keep working.");
+    console.log("");
+    console.log("    2. /replen           ANYTIME after that. Triages the candidates for");
+    console.log("                         the current repo, in-session, on your own");
+    console.log("                         subscription tokens — no LLM API key needed.");
+    console.log("");
+    console.log("  (Onboarding is once per project. After that, it's just /replen.)");
+    console.log("");
+    console.log("  Other MCP hosts (Codex / Cursor / Aider): \"use replen_match\" — same tool.");
     console.log("");
     console.log(`  Dashboard: ${exchange.base}`);
     console.log("");

package/dist/inject-instruction.js

@@ -33,12 +33,25 @@
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { join, basename } from "node:path";
 import { createInterface } from "node:readline";
-export const INTEGRATION_VERSION = "9";
+export const INTEGRATION_VERSION = "10";
 const SECTION_HEADER = "## Replen integration";
 const MARKER_RE = /<!--\s*replen-integration:\s*v(\d+)\s*-->/;
 const SECTION_BODY = `<!-- replen-integration: v${INTEGRATION_VERSION} -->
 
-On your **very first response** of each session:
+**FIRST, on your first response in a repo: check onboarding.** Call
+\`replen_onboard_state\` once. If it reports this repo (or the user's
+portfolio) is NOT yet onboarded/grounded, do NOT run the footnote flow
+this turn. Answer the user's message normally, then offer this VERBATIM
+as a new paragraph at the end:
+
+> Replen isn't set up for your repos yet — want me to do that now? Replen builds a profile so matches are relevant. Onboarding runs in the background, ~a few minutes.
+
+If they accept, invoke the \`replen-onboard\` skill. If they decline, carry
+on and do NOT re-offer for the rest of this session. Once \`replen_onboard_state\`
+shows the repo is onboarded, SKIP this check entirely and use the footnote
+flow below.
+
+Once onboarded, on your **very first response** of each session:
 
 1. **Skip the whole flow ONLY if** the user's first message is a
    pure trivial greeting with no content ("hi", "hey", "yo",

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/SKILL.md

@@ -40,7 +40,10 @@ Parse the JSON response. Note:
 
 - `filterMode` — `tags`, `zero-knowledge`, or `fingerprint`
 - `scopedTo` — confirms the project context the user has open
-- `candidates[]` — the actual list to triage
+- `candidates[]` — the actual list to triage. Each carries `solid: true|false` —
+  the ones Replen counts as genuinely worth your time (clear domain-fit + posture +
+  not-already-covered, or a dependency-maintenance match). The footnote's count is
+  the number of `solid` ones; the rest are "worth a glance" laterals.
 
 If `candidates.length === 0`, tell the user "No new candidates today for
 `<owner/name>`. Calm-cadence working as designed — 1-3 actionable
@@ -50,8 +53,11 @@ If 1+ candidates, continue.
 
 ### Step 3 — Per-candidate analysis
 
-**Cap at 5 candidates.** If the inventory returned more, take the top 5
-by `whyShortlisted` strength + stars + recency, defer the rest.
+**Triage the `solid` candidates first** (cap at 5). If there are more than 5
+solid, take the top 5 by `whyShortlisted` strength + stars + recency. The
+non-`solid` "worth a glance" entries are optional — skim them only if the solid
+set is thin or the user asks. A low-domain-fit lateral there can still be a real
+port/cherry-pick, so don't dismiss them blindly, but they're not the headline.
 
 For each candidate, do this loop:
 
@@ -210,9 +216,15 @@ For tech-news-site:
 
 (Triaged 9 candidates; surfacing the 2 worth acting on + 1 idea worth keeping.)
 
-What would you like to do with each? (star / hide / handoff)
+What would you like to do with each? — star (save it for later; won't
+re-surface), hide (dismiss; never show again), or handoff (open a pull
+request against your repo for it). Or skip and decide later.
 ```
 
+Always present the options WITH that one-line gloss the first time in a
+session — never the bare "(star / hide / handoff)". A new user doesn't know
+what they mean, and the calm-cadence promise dies if the user has to ask.
+
 The one-line "(Triaged N…)" footer is the *only* acknowledgement that skips
 happened — honest, but it doesn't parade them.
 

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replen",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "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",