replen 0.4.0 → 1.0.0

package/README.md

@@ -1,54 +1,76 @@
 # replen
 
-**Smarter AI Development workflows.** One-command setup for [replen](https://replen.dev) - the AI that asks *"can we do this better?"* on your codebase. Calm cadence: 1-3 actionable matches a month, not a daily feed.
+**Make your AI coding tools aware of the wider OSS ecosystem.** One command, no API keys.
 
 ```bash
 npx replen
 ```
 
-While your AI coding tool waits for prompts, replen reads your code against the ecosystem and surfaces drop-in libraries, ideas to port, and patterns to learn from. A proactive layer for your AI coding workflow.
+Claude Code, Codex, Cursor already know your code. Replen tells them what else is out there — drop-in libraries, ideas worth porting, dead deps to swap. The match decision happens *inside your AI tool's session* on your subscription tokens. Your code stays on your laptop. Replen never sees it.
 
-The single command above:
-1. Opens your browser to sign in / sign up at `app.replen.dev`
+## What `npx replen` does
+
+In 60 seconds, the one-liner:
+
+1. Opens your browser to sign in (Google or GitHub via Firebase)
 2. Captures the auth back into the terminal (browser-callback flow, like `gh auth login`)
-3. Wires the [@replen/mcp](https://www.npmjs.com/package/@replen/mcp) server into your Claude Code / Codex config
+3. Scans your local repos under `~/github/`, `~/code/`, `~/projects/` for git repos
+4. Auto-extracts tags from each (`package.json` deps, `pyproject.toml`, etc.)
+5. Registers them with Replen as your projects (no GitHub PAT needed)
+6. Wires the [@replen/mcp](https://www.npmjs.com/package/@replen/mcp) server into your Claude Code / Codex config
+7. Installs the `/replen-match` skill into `~/.claude/skills/`
+8. Injects a small "Replen integration" section into each project's `CLAUDE.md` + `AGENTS.md`
+
+**What you do not provide:**
+- ❌ OpenAI / Anthropic API key — your AI tool's subscription handles all reasoning
+- ❌ GitHub PAT — optional, only if you want server-side handoff PRs later
+- ❌ Per-project setup — auto-discovered from your local filesystem
 
-Same flow that `claude` itself uses for auth.
+Open Claude Code (or Codex) in any of your tracked repos and start working normally. When Replen has matches, your AI tool mentions them after answering your first message. Silent on quiet days.
 
 ## Subcommands
 
 ```bash
-npx replen              # sign in + setup
-npx replen status       # show current config
-npx replen mcp setup    # re-wire MCP using saved auth
-npx replen logout       # forget saved auth (token stays valid; rotate on /settings to revoke)
+npx replen                 # sign in + setup (the one-liner above)
+npx replen status          # show current config
+npx replen sync-projects   # re-scan local repos for new GitHub remotes;
+                           #   run after cloning a new repo
+npx replen inject [-y]     # re-inject the "Replen integration" section
+                           #   into every CLAUDE.md + AGENTS.md
+npx replen mcp setup       # re-wire MCP using saved auth
+npx replen logout          # forget saved auth (rotate on /settings to revoke)
 ```
 
 ## Plain-shell usage (no Claude Code / Codex needed)
 
 ```bash
-npx replen run                  # trigger a pipeline run
-npx replen progress             # tail the run live; exits when done
-npx replen check-new            # one-shot: any new actionable matches since
-                                # you last engaged? (also runs automatically
-                                # at every Claude Code session start)
+npx replen check-new            # one-shot: any new matches since you last
+                                # engaged? (used by the SessionStart hook)
 npx replen feed                 # show recent matches (default 2 days)
 npx replen watch                # keep a terminal open — rings the bell when
                                 # a new match lands. Default poll 5min.
 npx replen search <query>       # full-text search past matches
 npx replen starred              # starred matches + handoff PR status
 npx replen handoff <matchId>    # open the handoff PR for a starred match
+npx replen run                  # trigger a fresh pipeline run (hosted-tier only)
+npx replen progress             # tail the run live; exits when done
 ```
 
-`watch` is the calm-utility companion: leave it running in a `tmux` pane and forget about it. The first poll establishes a baseline; existing matches don't ring.
+Every data command accepts `--json` for scripting.
 
-`check-new` is wired into Claude Code automatically by `npx replen` setup — it installs a SessionStart hook that runs `npx replen check-new --hook` whenever you open Claude Code. The hook is silent unless there's something new since you last engaged (across dashboard, email, or a prior session); when there is, the new matches show up in the agent's opening context without you having to ask. Calm-cadence by design.
+## How matches surface in Claude Code / Codex
 
-Every data command accepts `--json` for scripting.
+Three layers, defence-in-depth — at least one will fire:
+
+1. **SessionStart hook** runs `npx replen check-new --hook` at the start of every Claude Code session. If there's anything new, the JSON output appears in the agent's opening context.
+2. **MCP tool** `replen_check_new` is exposed to the agent at all times. The instructions in `CLAUDE.md` tell it to call this tool early in each session.
+3. **CLAUDE.md / AGENTS.md instruction** (idempotent, marker-versioned) is injected into every tracked repo on setup. This is the most reliable layer — survives Claude Code version churn.
+
+Calm-cadence by design: most days are silent. 1-3 actionable matches a month per project.
 
 ## Self-host
 
-Pointing at your own replen instance:
+Pointing at your own Replen instance:
 
 ```bash
 REPLEN_BASE=https://replen.mydomain.dev npx replen
@@ -64,7 +86,7 @@ REPLEN_BASE=https://replen.mydomain.dev npx replen
 6. CLI validates state, saves the token to `~/.replen/config.json` (mode 0600)
 7. CLI continues and writes the MCP config into `~/.claude.json`
 
-The token never transits anything other than your browser ↔ localhost ↔ disk. The replen backend only sees it on subsequent MCP / API requests.
+The token never transits anything other than your browser ↔ localhost ↔ disk. The Replen backend only sees it on subsequent MCP / API requests.
 
 ## Revoke
 

package/dist/commands.js

@@ -173,11 +173,14 @@ export async function runStarred(argv) {
 // One-shot "is there anything new" check. Used in two modes:
 //   1. interactive (`replen check-new`): always prints — useful for ad-hoc
 //      "did anything land?" before opening Claude Code.
-//   2. hook (`replen check-new --hook`): SILENT when nothing's new. Tight
-//      timeout so a slow API can't stall every Claude Code session opening.
-//      Errors are swallowed and never fail the session. Output is shaped
-//      so Claude Code's SessionStart-hook stdout injection naturally
-//      surfaces the matches in the agent's opening context.
+//   2. hook (`replen check-new --hook`): SILENT when nothing's new. Bounded
+//      timeout (5s) so a slow API can't stall every Claude Code session
+//      opening. Uses AbortController to actually cancel the in-flight fetch
+//      on timeout — without that, an aborted hook would still let the server
+//      finish + bump the cursor, "consuming" the matches without ever
+//      surfacing them. Errors are swallowed and never fail the session.
+//      Output is shaped so Claude Code's SessionStart-hook stdout injection
+//      naturally surfaces the matches in the agent's opening context.
 export async function runCheckNew(argv) {
     const hookMode = hasFlag(argv, "--hook");
     const json = hasFlag(argv, "--json");
@@ -199,12 +202,27 @@ export async function runCheckNew(argv) {
     let r;
     try {
         if (hookMode) {
-            // Tight timeout so a slow API never blocks a session open. AbortSignal
-            // would be cleaner but apiGet doesn't surface it; race a manual timer.
-            r = await Promise.race([
-                apiGet(cfg, "/api/mcp/check-new", query),
-                new Promise((_, reject) => setTimeout(() => reject(new Error("hook-timeout")), 2000)),
-            ]);
+            // Direct fetch with AbortController so the timeout actually cancels
+            // the request (apiGet has no signal). Without this, a "timed out"
+            // hook would still let the server complete the call and bump the
+            // cursor, silently consuming the matches.
+            const ctrl = new AbortController();
+            const timer = setTimeout(() => ctrl.abort(), 5000);
+            try {
+                const url = new URL(cfg.base + "/api/mcp/check-new");
+                if (query.repo !== undefined)
+                    url.searchParams.set("repo", query.repo);
+                const res = await fetch(url, {
+                    headers: { "x-digest-token": cfg.token, accept: "application/json" },
+                    signal: ctrl.signal,
+                });
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                r = (await res.json());
+            }
+            finally {
+                clearTimeout(timer);
+            }
         }
         else {
             r = await apiGet(cfg, "/api/mcp/check-new", query);

package/dist/discover-projects.js

@@ -0,0 +1,256 @@
+// Local-filesystem project discovery for day-1 onboarding.
+//
+// Walks the user's conventional repo roots (~/github/, ~/code/,
+// ~/projects/) for git repos, then for each one extracts:
+//   - The repo's `owner/name` from `git remote get-url origin`
+//   - A slug (from the directory basename, normalised)
+//   - A name (from package.json's `name` field if present, else slug)
+//   - Auto-suggested tags from the project's manifests
+//   - The primary language (best-effort, from manifest type)
+//
+// Output is shaped for POST /api/projects/bulk on the server. No
+// network or LLM calls — pure local filesystem.
+//
+// Why local-FS instead of asking GitHub via PAT: skill-mode's whole
+// pitch is "no API keys to share with us." Auto-detect via GitHub
+// API requires a PAT; auto-detect via local git remotes requires
+// nothing the user doesn't already have. PAT becomes optional, only
+// needed if/when the user wants server-side handoff PRs.
+import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const SCAN_ROOTS = ["github", "code", "projects"]; // immediate children of ~
+// Manifest-derived tag mappings. Each pattern matches a dep name (or
+// a substring) and yields one or more tags. Ordered by specificity:
+// more-specific patterns first so e.g. "next" doesn't accidentally
+// tag a "next-auth-only" project as "next.js".
+const DEP_TO_TAGS = [
+    // Frontend frameworks (Node)
+    { match: /^next$/, tags: ["next.js"] },
+    { match: /^react$/, tags: ["react"] },
+    { match: /^vue$/, tags: ["vue"] },
+    { match: /^svelte$/, tags: ["svelte"] },
+    { match: /^solid-js$/, tags: ["solid"] },
+    { match: /^astro$/, tags: ["astro"] },
+    { match: /^remix-run\//, tags: ["remix"] },
+    // Backend / runtime
+    { match: /^express$/, tags: ["express"] },
+    { match: /^fastify$/, tags: ["fastify"] },
+    { match: /^hono$/, tags: ["hono"] },
+    { match: /^nestjs\//, tags: ["nestjs"] },
+    // Database / ORM
+    { match: /^prisma$/, tags: ["prisma"] },
+    { match: /^@prisma\/client$/, tags: ["prisma"] },
+    { match: /^drizzle-orm/, tags: ["drizzle"] },
+    { match: /^kysely$/, tags: ["kysely"] },
+    { match: /^typeorm$/, tags: ["typeorm"] },
+    { match: /^mongoose$/, tags: ["mongoose"] },
+    { match: /postgres|pg$/, tags: ["postgres"] },
+    { match: /^mysql/, tags: ["mysql"] },
+    { match: /^redis|^ioredis$/, tags: ["redis"] },
+    // Queue / async
+    { match: /^bullmq$/, tags: ["bullmq", "queue"] },
+    { match: /^bee-queue$/, tags: ["bee-queue", "queue"] },
+    { match: /^node-cron$/, tags: ["cron"] },
+    // LLM / AI
+    { match: /^openai$/, tags: ["openai"] },
+    { match: /^@anthropic-ai\//, tags: ["anthropic"] },
+    { match: /^langchain/, tags: ["langchain"] },
+    // Auth
+    { match: /^next-auth$/, tags: ["next-auth"] },
+    { match: /^@auth\//, tags: ["next-auth"] },
+    { match: /firebase/, tags: ["firebase"] },
+    // Cloud / hosting
+    { match: /^@aws-sdk\//, tags: ["aws"] },
+    { match: /^@vercel\//, tags: ["vercel"] },
+    { match: /^@cloudflare\//, tags: ["cloudflare"] },
+    // Web3
+    { match: /^viem$/, tags: ["viem", "web3"] },
+    { match: /^ethers$/, tags: ["ethers", "web3"] },
+    { match: /^wagmi$/, tags: ["wagmi", "web3"] },
+    { match: /^@matterlabs\//, tags: ["zksync"] },
+    // Image / media
+    { match: /^sharp$/, tags: ["images"] },
+    { match: /^@napi-rs\/canvas$/, tags: ["canvas", "images"] },
+    { match: /ffmpeg/, tags: ["ffmpeg"] },
+    // Python (matches go through the same loop on requirements.txt)
+    { match: /^torch$/, tags: ["pytorch"] },
+    { match: /^tensorflow$/, tags: ["tensorflow"] },
+    { match: /^fastapi$/, tags: ["fastapi"] },
+    { match: /^flask$/, tags: ["flask"] },
+    { match: /^django$/, tags: ["django"] },
+    { match: /^segmentation-models-pytorch$/, tags: ["pytorch", "segmentation"] },
+    { match: /^albumentations$/, tags: ["augmentation"] },
+    { match: /^scikit-learn$/, tags: ["ml"] },
+];
+export function discoverProjects() {
+    const out = [];
+    const home = homedir();
+    for (const root of SCAN_ROOTS) {
+        const rootPath = join(home, root);
+        if (!existsSync(rootPath))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(rootPath);
+        }
+        catch {
+            continue;
+        }
+        for (const dirName of entries) {
+            if (dirName.startsWith(".") || dirName === "node_modules")
+                continue;
+            const localPath = join(rootPath, dirName);
+            try {
+                if (!statSync(localPath).isDirectory())
+                    continue;
+                if (!existsSync(join(localPath, ".git")))
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            const githubFullName = readGitRemote(localPath);
+            if (!githubFullName)
+                continue; // No GitHub remote → skip; can't register
+            const { name, tags, primaryLanguage } = extractMetadata(localPath, dirName);
+            const slug = normaliseSlug(dirName);
+            out.push({ localPath, slug, name, githubFullName, tags, primaryLanguage });
+        }
+    }
+    return out;
+}
+function normaliseSlug(dirName) {
+    return dirName
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80) || "project";
+}
+// Run `git remote get-url origin` in the repo. Returns owner/name on
+// success, null otherwise. Tolerates non-GitHub remotes (returns null
+// so the repo is skipped).
+function readGitRemote(repoPath) {
+    let url;
+    try {
+        url = execSync("git remote get-url origin", {
+            cwd: repoPath,
+            stdio: ["ignore", "pipe", "ignore"],
+            encoding: "utf8",
+            timeout: 3000,
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+    // Match both HTTPS (https://github.com/owner/name[.git]) and SSH
+    // (git@github.com:owner/name[.git]) formats.
+    const m = url.match(/github\.com[:/]([^/]+)\/([^/?#]+?)(?:\.git)?$/i);
+    if (!m)
+        return null;
+    return `${m[1]}/${m[2]}`;
+}
+function extractMetadata(repoPath, fallbackName) {
+    const tags = new Set();
+    let name = fallbackName;
+    let primaryLanguage = null;
+    // Node: package.json
+    const pkgPath = join(repoPath, "package.json");
+    if (existsSync(pkgPath)) {
+        primaryLanguage = "TypeScript"; // updated below if no TS detected
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+            if (typeof pkg.name === "string" && pkg.name.length > 0)
+                name = pkg.name;
+            if (Array.isArray(pkg.keywords)) {
+                for (const k of pkg.keywords) {
+                    if (typeof k === "string" && k.length > 0 && k.length <= 40) {
+                        tags.add(k.toLowerCase());
+                    }
+                }
+            }
+            const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+            // Detect TS vs JS from presence of typescript in deps.
+            if (deps["typescript"] !== undefined) {
+                tags.add("typescript");
+                primaryLanguage = "TypeScript";
+            }
+            else {
+                // Look for *.ts files at top level to decide TS vs JS.
+                try {
+                    const top = readdirSync(repoPath);
+                    if (top.some((f) => f.endsWith(".ts") || f.endsWith(".tsx"))) {
+                        tags.add("typescript");
+                        primaryLanguage = "TypeScript";
+                    }
+                    else {
+                        tags.add("javascript");
+                        primaryLanguage = "JavaScript";
+                    }
+                }
+                catch { /* ignore */ }
+            }
+            // Match deps against the tag mapping.
+            for (const depName of Object.keys(deps)) {
+                for (const { match, tags: ts } of DEP_TO_TAGS) {
+                    if (match.test(depName)) {
+                        for (const t of ts)
+                            tags.add(t);
+                    }
+                }
+            }
+        }
+        catch { /* malformed package.json — skip */ }
+    }
+    // Python: pyproject.toml / requirements.txt
+    const pyprojectPath = join(repoPath, "pyproject.toml");
+    const requirementsPath = join(repoPath, "requirements.txt");
+    if (existsSync(pyprojectPath) || existsSync(requirementsPath)) {
+        primaryLanguage = "Python";
+        tags.add("python");
+        const text = [pyprojectPath, requirementsPath]
+            .filter((p) => existsSync(p))
+            .map((p) => { try {
+            return readFileSync(p, "utf8");
+        }
+        catch {
+            return "";
+        } })
+            .join("\n");
+        // Pull dep names from "<name>>=<ver>" / "<name>==<ver>" / quoted strings.
+        const depMatches = text.matchAll(/^\s*["']?([a-zA-Z0-9][\w.-]*)["']?\s*[><=!~]/gm);
+        for (const dm of depMatches) {
+            const depName = dm[1].toLowerCase();
+            for (const { match, tags: ts } of DEP_TO_TAGS) {
+                if (match.test(depName)) {
+                    for (const t of ts)
+                        tags.add(t);
+                }
+            }
+        }
+    }
+    // Rust: Cargo.toml
+    if (existsSync(join(repoPath, "Cargo.toml"))) {
+        primaryLanguage = primaryLanguage ?? "Rust";
+        tags.add("rust");
+    }
+    // Go: go.mod
+    if (existsSync(join(repoPath, "go.mod"))) {
+        primaryLanguage = primaryLanguage ?? "Go";
+        tags.add("go");
+    }
+    // Solidity (web3 contracts under hardhat/foundry)
+    if (existsSync(join(repoPath, "hardhat.config.js")) ||
+        existsSync(join(repoPath, "hardhat.config.ts")) ||
+        existsSync(join(repoPath, "foundry.toml"))) {
+        tags.add("solidity");
+        tags.add("web3");
+    }
+    // Cap total tags so a kitchen-sink monorepo doesn't blow up the row.
+    return {
+        name,
+        tags: Array.from(tags).slice(0, 25),
+        primaryLanguage,
+    };
+}

package/dist/index.js

@@ -12,6 +12,14 @@ Usage:
   npx replen mcp setup       Re-wire MCP using saved auth
   npx replen project-init    Print a prompt your AI coding tool uses to draft
                              a CLAUDE.md tuned for replen
+  npx replen inject [-y]     Append the "## Replen integration" section to
+                             every CLAUDE.md + AGENTS.md (Claude Code +
+                             Codex) under ~/github/, ~/code/, ~/projects/
+                             so the agent auto-surfaces matches on session
+                             start. Idempotent. Asks for consent unless -y.
+  npx replen sync-projects   Re-scan local repos for new GitHub remotes
+                             and register them with Replen. Run after
+                             cloning a new repo.
   npx replen logout          Forget saved auth
   npx replen --help          This help
 
@@ -92,6 +100,25 @@ async function main() {
         console.log(`Note: this only clears local auth. The token is still valid until you rotate it on /settings.`);
         return;
     }
+    if (cmd === "inject") {
+        const { injectInstructions, summariseOutcome } = await import("./inject-instruction.js");
+        const yes = argv.includes("--yes") || argv.includes("-y");
+        const outcome = await injectInstructions({ yes });
+        const summary = summariseOutcome(outcome);
+        if (summary)
+            console.log(summary);
+        return;
+    }
+    if (cmd === "sync-projects" || cmd === "sync") {
+        const cfg = await readConfig();
+        if (!cfg) {
+            console.error("Not signed in. Run `npx replen` first.");
+            process.exit(1);
+        }
+        const { syncDiscoveredProjects } = await import("./sync-projects.js");
+        await syncDiscoveredProjects({ token: cfg.token, base: cfg.base });
+        return;
+    }
     if (cmd === "run")
         return runRun(argv);
     if (cmd === "progress")

package/dist/init.js

@@ -142,10 +142,22 @@ export async function runInit() {
     });
     console.log(`  ✓ Saved auth to ${configPath()}`);
     await setupMcp(exchange.token, exchange.base);
+    // Phase A: auto-discover the user's local projects, extract tags
+    // from manifests, and register them in one shot. Replaces the
+    // legacy "paste a GitHub PAT and let us call api.github.com" flow
+    // for project discovery.
     console.log("");
-    console.log("  All set. Restart Claude Code (or Codex) and try:");
-    console.log("    /replen-triage      → runs the morning triage protocol");
-    console.log("    use replen to replen_today → pulls today's matches");
+    console.log("  Scanning your local repos for projects…");
+    const { syncDiscoveredProjects } = await import("./sync-projects.js");
+    await syncDiscoveredProjects({ token: exchange.token, base: exchange.base });
+    console.log("");
+    console.log("  All set. Restart Claude Code and try:");
+    console.log("    /replen-match       → 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("");
+    console.log("  Other MCP hosts (Codex / Cursor / Aider):");
+    console.log("    \"use replen_match\" — same tool, no slash command");
     console.log("");
     console.log(`  Dashboard: ${exchange.base}`);
     console.log("");

package/dist/inject-instruction.js

@@ -0,0 +1,308 @@
+// Auto-inject the "## Replen integration" instruction block into the
+// user's local project CLAUDE.md files so Claude Code reads it at
+// session start and proactively calls replen_match before responding
+// to the user's first message.
+//
+// Why this exists: SessionStart hooks in Claude Code v2.1.141 don't
+// reliably inject stdout into the agent's context. The CLAUDE.md
+// instruction is the only mechanism today that consistently makes
+// Claude call the tool. Without auto-injection, every user has to
+// hand-edit every project's CLAUDE.md — adoption blocker.
+//
+// Discovery: scans the user's local filesystem under conventional
+// repo roots (~/github/*, ~/code/*, ~/projects/*) for directories
+// that are git repos (contain .git/) and have a CLAUDE.md OR are
+// likely Claude Code projects (look like dev repos with package.json,
+// pyproject.toml, etc.). We inject into both the existing-CLAUDE.md
+// case (append section) and the no-CLAUDE.md case (create with stub).
+//
+// Idempotent contract:
+//   - CLAUDE.md missing            → create stub with just the Replen
+//     section, header notes "edit freely above"
+//   - CLAUDE.md exists, current section present (same version) → no-op
+//   - CLAUDE.md exists, older-version section present → replace in place
+//   - CLAUDE.md exists, section absent → append at bottom
+//
+// Versioning: the section carries a hidden HTML comment marker
+// <!-- replen-integration: v<N> -->. Bumping INTEGRATION_VERSION
+// re-injects on next setup run.
+//
+// Consent: first-run shows the user the list of repos and asks Y/n.
+// --yes skips the prompt (CI / scripted use). Non-TTY also skips
+// (e.g. when invoked from a hook).
+import { readFileSync, writeFileSync, existsSync, statSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, basename } from "node:path";
+import { createInterface } from "node:readline";
+export const INTEGRATION_VERSION = "1";
+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, silently call the
+\`replen_match\` MCP tool (or invoke the \`/replen-match\` skill). It
+returns today's curated OSS candidate inventory scoped to this repo
+so you can mention real matches without making the user ask.
+
+**Response shape — ORDER MATTERS:**
+
+1. **Answer the user's actual ask first**, in full. The user didn't
+   ask about Replen; whatever they asked is the priority.
+2. **Then**, on a new line separated by a blank line, append a single-
+   paragraph tail like:
+   > _By the way — N new Replen matches landed for this repo. Top one:
+   > \`owner/name\` (1-line reason). Want the full triage?_
+3. Cap the tail at 3 sentences. The user's task is the headline; Replen
+   is the footnote.
+
+**When to stay silent:** if \`replen_match\` returns \`hasNew: false\`,
+OR the user's first message is itself a Replen command
+(\`/replen-match\`, "what's new from replen?", etc.).
+
+**Don't call \`replen_match\` again on subsequent turns** — once per
+session at start only. The user explicitly types \`/replen-match\` if
+they want a fresh triage mid-session.
+`;
+const SCAN_ROOTS = ["github", "code", "projects"]; // under ~/
+// Find candidate project directories: immediate children of SCAN_ROOTS
+// that are git repos. We don't recurse — most users keep one level of
+// nesting under their org-or-user-named root.
+function discoverRepos() {
+    const out = [];
+    const home = homedir();
+    for (const root of SCAN_ROOTS) {
+        const rootPath = join(home, root);
+        if (!existsSync(rootPath))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(rootPath);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            // Skip dotfiles + obvious non-repos.
+            if (name.startsWith(".") || name === "node_modules")
+                continue;
+            const path = join(rootPath, name);
+            try {
+                if (!statSync(path).isDirectory())
+                    continue;
+                if (!existsSync(join(path, ".git")))
+                    continue;
+                out.push(path);
+            }
+            catch {
+                // permission / symlink errors — skip silently
+            }
+        }
+    }
+    return out;
+}
+function applyToClaudeMd(claudeMdPath) {
+    if (!existsSync(claudeMdPath)) {
+        const header = `# CLAUDE.md\n\n<!-- This file is read by Claude Code at session start to understand the project. Edit freely above this marker — the Replen integration section below is auto-managed. -->\n\n`;
+        writeFileSync(claudeMdPath, header + SECTION_HEADER + "\n\n" + SECTION_BODY);
+        return "created";
+    }
+    const current = readFileSync(claudeMdPath, "utf8");
+    const markerMatch = current.match(MARKER_RE);
+    if (markerMatch) {
+        const existingVersion = markerMatch[1];
+        if (existingVersion === INTEGRATION_VERSION) {
+            // Marker present + current version. Defence-in-depth: a previous
+            // version of this CLI may have already appended a duplicate
+            // pre-marker section above. Collapse any extra `## Replen
+            // integration` blocks above the marker into the canonical one.
+            const collapsed = collapseDuplicateSections(current);
+            if (collapsed !== current) {
+                writeFileSync(claudeMdPath, collapsed);
+                return "versionUpdated";
+            }
+            return "alreadyCurrent";
+        }
+        writeFileSync(claudeMdPath, replaceSection(current));
+        return "versionUpdated";
+    }
+    // No marker. Check if a legacy/manual Replen section is here by
+    // header alone — replace it in place rather than appending a dupe.
+    const headerIdx = findFirstSectionHeader(current);
+    if (headerIdx !== -1) {
+        writeFileSync(claudeMdPath, replaceSection(current));
+        return "versionUpdated";
+    }
+    // Truly absent — append at end.
+    const sep = current.endsWith("\n") ? "\n" : "\n\n";
+    writeFileSync(claudeMdPath, current + sep + SECTION_HEADER + "\n\n" + SECTION_BODY);
+    return "appended";
+}
+function findFirstSectionHeader(claudeMd) {
+    const lines = claudeMd.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === SECTION_HEADER)
+            return i;
+    }
+    return -1;
+}
+// If a CLAUDE.md ended up with multiple `## Replen integration`
+// sections (e.g. a legacy manual one + an auto-injected one), keep
+// only the one carrying the canonical marker comment.
+function collapseDuplicateSections(claudeMd) {
+    const lines = claudeMd.split("\n");
+    // Find every `## Replen integration` block. Each block: header line
+    // through to the next `## ` or EOF.
+    const blocks = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === SECTION_HEADER) {
+            let end = lines.length;
+            for (let j = i + 1; j < lines.length; j++) {
+                if (lines[j].startsWith("## ") && !lines[j].startsWith("### ")) {
+                    end = j;
+                    break;
+                }
+            }
+            const body = lines.slice(i, end).join("\n");
+            blocks.push({ start: i, end, hasMarker: MARKER_RE.test(body) });
+            i = end - 1;
+        }
+    }
+    if (blocks.length <= 1)
+        return claudeMd; // nothing to collapse
+    // Keep the marker-equipped block, drop the others. If none has the
+    // marker (legacy file), keep the FIRST and drop the rest — caller's
+    // replaceSection will then upgrade it.
+    const keepIdx = blocks.findIndex((b) => b.hasMarker);
+    const keep = keepIdx >= 0 ? blocks[keepIdx] : blocks[0];
+    // Build the output keeping `keep` in place and removing the others.
+    const dropRanges = blocks.filter((b) => b !== keep).map((b) => [b.start, b.end]);
+    // Walk lines, skipping any line inside a drop range.
+    const out = [];
+    let i = 0;
+    while (i < lines.length) {
+        const inDrop = dropRanges.find(([s, e]) => i >= s && i < e);
+        if (inDrop) {
+            i = inDrop[1];
+            continue;
+        }
+        out.push(lines[i]);
+        i++;
+    }
+    // Collapse runs of >2 blank lines to exactly one blank.
+    const text = out.join("\n").replace(/\n{3,}/g, "\n\n");
+    return text;
+}
+// Replace the existing Replen section in place. Anchored on the H2
+// header, terminated by the next H2 (not H3+) or EOF.
+function replaceSection(claudeMd) {
+    const lines = claudeMd.split("\n");
+    let startIdx = -1;
+    let endIdx = lines.length;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === SECTION_HEADER) {
+            startIdx = i;
+            break;
+        }
+    }
+    if (startIdx === -1)
+        return claudeMd; // unreachable
+    for (let j = startIdx + 1; j < lines.length; j++) {
+        if (lines[j].startsWith("## ") && !lines[j].startsWith("### ")) {
+            endIdx = j;
+            break;
+        }
+    }
+    const before = lines.slice(0, startIdx).join("\n").replace(/\n+$/, "");
+    const after = endIdx < lines.length ? "\n\n" + lines.slice(endIdx).join("\n") : "\n";
+    return before + "\n\n" + SECTION_HEADER + "\n\n" + SECTION_BODY + after;
+}
+async function promptYes(question) {
+    if (!process.stdin.isTTY)
+        return true; // non-interactive → assume yes
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            const a = answer.trim().toLowerCase();
+            resolve(a === "" || a === "y" || a === "yes");
+        });
+    });
+}
+export async function injectInstructions(opts = {}) {
+    const repos = discoverRepos();
+    const outcome = {
+        scanned: repos.length,
+        created: 0,
+        appended: 0,
+        alreadyCurrent: 0,
+        versionUpdated: 0,
+        skipped: [],
+        declined: false,
+    };
+    if (repos.length === 0) {
+        console.log("  · no git repos found under ~/github/, ~/code/, or ~/projects/ — skipping CLAUDE.md inject");
+        return outcome;
+    }
+    // First-run consent. Shows the count + an example path so the user
+    // knows the blast radius. --yes (or non-TTY) bypasses.
+    if (!opts.yes) {
+        console.log(`\n  Found ${repos.length} git repo(s) under ~/github/, ~/code/, ~/projects/.`);
+        console.log(`  Append a "## Replen integration" section to each CLAUDE.md so Claude Code`);
+        console.log(`  surfaces today's matches at session start. Idempotent; edit freely above`);
+        console.log(`  the section. First 3:`);
+        for (const r of repos.slice(0, 3))
+            console.log(`    • ${r}`);
+        if (repos.length > 3)
+            console.log(`    … and ${repos.length - 3} more`);
+        const ok = await promptYes(`  Proceed? [Y/n] `);
+        if (!ok) {
+            outcome.declined = true;
+            console.log(`  · skipped. Run \`npx replen inject\` later to apply.`);
+            return outcome;
+        }
+    }
+    // We write to BOTH CLAUDE.md (Claude Code convention) and AGENTS.md
+    // (Codex convention). Same section content; each tool reads its own
+    // native file. Idempotent + collapsing applies to both.
+    for (const path of repos) {
+        for (const fileName of ["CLAUDE.md", "AGENTS.md"]) {
+            const filePath = join(path, fileName);
+            try {
+                const action = applyToClaudeMd(filePath);
+                outcome[action]++;
+            }
+            catch (e) {
+                outcome.skipped.push({ path: `${basename(path)}/${fileName}`, reason: e.message ?? String(e) });
+            }
+        }
+    }
+    return outcome;
+}
+export function summariseOutcome(o) {
+    if (o.declined)
+        return ""; // already printed the decline message
+    const lines = [];
+    const touched = o.created + o.appended + o.versionUpdated;
+    if (touched === 0 && o.alreadyCurrent === 0) {
+        if (o.scanned > 0)
+            lines.push(`  · ${o.scanned} repos scanned, none needed Replen inject`);
+        return lines.join("\n");
+    }
+    const parts = [];
+    if (o.created > 0)
+        parts.push(`${o.created} file${o.created === 1 ? "" : "s"} created`);
+    if (o.appended > 0)
+        parts.push(`${o.appended} appended`);
+    if (o.versionUpdated > 0)
+        parts.push(`${o.versionUpdated} updated to v${INTEGRATION_VERSION}`);
+    if (o.alreadyCurrent > 0)
+        parts.push(`${o.alreadyCurrent} already current`);
+    if (parts.length > 0)
+        lines.push(`  ✓ Replen integration: ${parts.join(", ")}`);
+    if (o.skipped.length > 0) {
+        lines.push(`  · skipped ${o.skipped.length}:`);
+        for (const s of o.skipped.slice(0, 5))
+            lines.push(`    - ${s.path}: ${s.reason}`);
+    }
+    return lines.join("\n");
+}

package/dist/mcp-setup.js

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, chmodSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
+import { installSkills } from "./skill-install.js";
 // Write the @replen/mcp server entry into Claude Code's config. Uses npx so
 // the user doesn't need a separate global install; Claude Code will fetch
 // @replen/mcp on first MCP launch and cache it.
@@ -63,6 +64,24 @@ export async function setupMcp(token, base) {
     writeJsonAtomic(CONFIG_PATH, { ...config, mcpServers, hooks });
     console.log(`  ✓ ${overwrite ? "Updated" : "Added"} "${SERVER_NAME}" in ${CONFIG_PATH}`);
     console.log(`  ✓ Installed SessionStart hook (surfaces new matches automatically)`);
+    // Skill install runs alongside the MCP+hook setup so any Claude Code
+    // session can `/replen-match` to trigger in-session triage. Other MCP
+    // hosts (Codex, Cursor) don't have a skills concept; they use the
+    // replen_match MCP tool description as the equivalent instruction.
+    installSkills();
+    // Auto-inject the "## Replen integration" section into each local
+    // project's CLAUDE.md. This is the adoption-unblock — without it
+    // Claude Code (v2.1.141) doesn't reliably auto-surface matches
+    // because the SessionStart hook stdout-injection is buggy. Per-project
+    // CLAUDE.md instruction is the only working surface today, and we
+    // can't expect every user to hand-edit every repo. Idempotent +
+    // versioned; safe to re-run.
+    console.log("");
+    const { injectInstructions, summariseOutcome } = await import("./inject-instruction.js");
+    const outcome = await injectInstructions();
+    const summary = summariseOutcome(outcome);
+    if (summary)
+        console.log(summary);
 }
 // SessionStart hook: on every Claude Code session, runs `replen check-new
 // --hook`, which prints a one-block summary to stdout if (and only if)

package/dist/skill-install.js

@@ -0,0 +1,58 @@
+// Install the bundled `replen-match` skill into Claude Code's
+// ~/.claude/skills/ tree so users can invoke it via `/replen-match`
+// (or by saying "use replen / triage today / what's new from replen").
+//
+// Idempotent: re-running setup overwrites the skill in place. The
+// skill is the source of truth in Replen's npm package; users
+// shouldn't be hand-editing the installed copy because it'll be
+// clobbered on next `npx replen mcp setup`.
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+// Resolved at runtime: the published package's bundled extras dir.
+// __dirname-equivalent for ESM. dist/ lives at <package>/dist/, so the
+// extras dir is one level up + "extras".
+const SELF_DIR = dirname(fileURLToPath(import.meta.url));
+const BUNDLED_SKILLS_ROOT = join(SELF_DIR, "..", "extras", "skills");
+// Claude Code reads skills from ~/.claude/skills/<name>/SKILL.md. Other
+// MCP hosts (Codex, Cursor) don't have a skills concept yet; they
+// follow the MCP tool's description instead. The CLAUDE.md instruction
+// shipped by `replen project-init` is the cross-host fallback.
+const CLAUDE_SKILLS_ROOT = join(homedir(), ".claude", "skills");
+const SKILLS = [
+    {
+        name: "replen-match",
+        files: ["replen-match/SKILL.md"],
+    },
+];
+export function installSkills() {
+    if (!existsSync(BUNDLED_SKILLS_ROOT)) {
+        // Bundle missing — running from a source tree without the
+        // extras/ dir, or a corrupt install. Skip rather than crash; the
+        // skill is a nice-to-have not a hard requirement (the MCP tool
+        // surface covers all hosts).
+        console.warn(`  · skills bundle not found at ${BUNDLED_SKILLS_ROOT}; skipping skill install`);
+        return;
+    }
+    mkdirSync(CLAUDE_SKILLS_ROOT, { recursive: true });
+    let installed = 0;
+    for (const skill of SKILLS) {
+        for (const rel of skill.files) {
+            const src = join(BUNDLED_SKILLS_ROOT, rel);
+            const dst = join(CLAUDE_SKILLS_ROOT, rel);
+            if (!existsSync(src)) {
+                console.warn(`  · missing in bundle: ${rel}`);
+                continue;
+            }
+            mkdirSync(dirname(dst), { recursive: true });
+            const body = readFileSync(src);
+            writeFileSync(dst, body);
+            installed++;
+        }
+        console.log(`  ✓ Installed skill: ${skill.name} → ~/.claude/skills/${skill.name}/`);
+    }
+    if (installed === 0) {
+        console.warn(`  · no skill files installed (bundle present but empty)`);
+    }
+}

package/dist/sync-projects.js

@@ -0,0 +1,71 @@
+// Wraps discoverProjects() (local FS walk) + POST /api/projects/bulk
+// (server-side upsert) so it can be invoked both during the initial
+// `npx replen` flow and as a standalone `npx replen sync-projects`
+// command for ongoing use (after cloning new repos).
+import { discoverProjects } from "./discover-projects.js";
+export async function syncDiscoveredProjects({ token, base, }) {
+    const projects = discoverProjects();
+    if (projects.length === 0) {
+        console.log("  · no git repos found under ~/github/, ~/code/, ~/projects/ — skipping project registration");
+        return { discovered: 0, created: 0, updated: 0 };
+    }
+    // Show the user what we found before sending. Three examples is
+    // enough context; full list lives in the API call.
+    console.log(`  ✓ Found ${projects.length} git repo(s) with GitHub remotes:`);
+    for (const p of projects.slice(0, 3)) {
+        const sampleTags = p.tags.slice(0, 4).join(", ") || "(no auto-tags)";
+        console.log(`    • ${p.githubFullName}  →  tags: ${sampleTags}`);
+    }
+    if (projects.length > 3)
+        console.log(`    … and ${projects.length - 3} more`);
+    const payload = {
+        projects: projects.map((p) => ({
+            slug: p.slug,
+            githubFullName: p.githubFullName,
+            name: p.name,
+            tags: p.tags,
+            primaryLanguage: p.primaryLanguage ?? undefined,
+        })),
+    };
+    let res;
+    try {
+        res = await fetch(`${base}/api/projects/bulk`, {
+            method: "POST",
+            headers: {
+                "x-digest-token": token,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify(payload),
+        });
+    }
+    catch (e) {
+        console.warn(`  ✗ Failed to reach ${base}/api/projects/bulk: ${e.message}`);
+        console.warn(`    Skipping project registration. Run \`npx replen sync-projects\` later to retry.`);
+        return { discovered: projects.length, created: 0, updated: 0 };
+    }
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        console.warn(`  ✗ Project registration failed (HTTP ${res.status}): ${text.slice(0, 200)}`);
+        return { discovered: projects.length, created: 0, updated: 0 };
+    }
+    const body = (await res.json());
+    const created = body.created ?? 0;
+    const updated = body.updated ?? 0;
+    if (created > 0 || updated > 0) {
+        const parts = [];
+        if (created > 0)
+            parts.push(`${created} new`);
+        if (updated > 0)
+            parts.push(`${updated} updated`);
+        console.log(`  ✓ Registered with Replen: ${parts.join(", ")}`);
+    }
+    else {
+        console.log(`  · All ${projects.length} projects already up to date with Replen`);
+    }
+    return { discovered: projects.length, created, updated };
+}
+// Returns just the discovered list without sending. Useful for the
+// CLI's `replen list-projects` subcommand (preview mode).
+export function previewDiscovery() {
+    return discoverProjects();
+}

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

@@ -0,0 +1,230 @@
+---
+name: replen-match
+description: Triage today's Replen candidates against the open codebase, in-session, using subscription tokens. Pulls the day's inventory from Replen, reads the user's local source, produces per-candidate writeups with verdict + effort + concrete file-level impact, then captures star/hide/handoff actions back to Replen. Invoke with `/replen-match` or by saying "run replen on this repo" / "what's new from replen?".
+---
+
+# Replen Match — in-session candidate triage
+
+You are running the matching loop locally. Replen has fetched a list of
+plausible OSS candidates from the wider ecosystem; you've got the user's
+codebase open. Your job is to decide which (if any) are worth their
+attention, write up the strong ones, and capture what they want to do
+about them.
+
+**This runs entirely on the user's subscription tokens.** No API keys
+get used. Replen's hosted side did the cheap structural filtering; you
+do the expensive, code-grounded reasoning.
+
+## Protocol
+
+### Step 1 — Auth + context
+
+1. Read `~/.replen/config.json` to get the user's DIGEST_TOKEN and base
+   URL. If the file doesn't exist, stop and tell the user to run
+   `npx replen` first.
+2. Run `git remote get-url origin` to detect the repo. Extract
+   `owner/name` from the URL.
+3. Run `git log --oneline -20` to get a sense of recent activity (will
+   inform scoring — what's the user actively working on?).
+
+### Step 2 — Pull today's inventory
+
+Call:
+
+```bash
+curl -sS -H "x-digest-token: $TOKEN" \
+  "$BASE/api/inventory/today?repo=<owner/name>&days=2&limit=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
+
+If `candidates.length === 0`, tell the user "No new candidates today for
+`<owner/name>`. Calm-cadence working as designed — 1-3 actionable
+matches a month is the goal." Stop.
+
+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.
+
+For each candidate, do this loop:
+
+#### 3a. Gather signals
+
+- WebFetch `<candidate.url>` — the GitHub repo page. Pull description +
+  README.
+- If the README mentions specific files (e.g. `src/index.ts`), WebFetch
+  the raw file too (`https://raw.githubusercontent.com/<owner>/<name>/<default-branch>/<path>`).
+- Search the user's local codebase for related code:
+  - If the candidate is in a known package ecosystem, grep the user's
+    `package.json` / `pyproject.toml` / etc. for the candidate's name
+    or close variants (the user might already have a similar dep).
+  - If the candidate solves a problem area (e.g. "social card generator"),
+    grep the user's source for files that already do that work
+    (e.g. `grep -rln "Canvas\|imageRenderer\|OG"` under `lib/` and `src/`).
+  - If you find one, read the file to understand what the user has built.
+
+#### 3b. Form a verdict
+
+You're answering: **is this worth the user's attention right now?**
+
+Verdicts:
+
+- **adopt** — drop-in replacement / direct dep. The candidate does
+  something the user genuinely needs and isn't doing well. Wire up.
+- **port** — the candidate has an idea / pattern / algorithm worth
+  copying, but the candidate's runtime / language / license is
+  mismatched. Worth reading + adapting; not worth depending on.
+- **skip** — the candidate is a worse version of what the user has, the
+  candidate's runtime is incompatible, or the candidate's not actively
+  maintained. Honest skips are valuable signal; don't manufacture
+  reasons to keep something.
+
+Score the fit on a 0-100 scale:
+
+- 80-100 = high (strong fit, clear adopt or port path, no major blockers)
+- 50-79 = medium (real value, but caveats — port path required, or
+  partial overlap, or active-area-mismatched)
+- 0-49 = general-awareness or skip (interesting but not directly
+  actionable; or definitely skip)
+
+Estimate effort:
+
+- **quick** — <1 day. Single-file swap, drop a dep, copy a file.
+- **moderate** — 1-3 days. Real API delta, multi-site update, light port.
+- **deep** — 1+ week. Framework adoption, paradigm shift, full rewrite.
+
+#### 3c. Compose the writeup
+
+Format **exactly** like this for each candidate:
+
+```
+### owner/name — VERDICT (score) · effort
+
+**One-liner.** What the candidate is, in one sentence.
+
+**Why this could help.** 2-3 sentences. Be specific. Reference the
+user's actual files when possible:
+- "Could replace `lib/social/imageRenderer.ts` (180 LoC) with a 30-line
+  wrapper around X."
+- "Their `<approach>` is what `scripts/auto-process.ts:124` tries to do
+  in 80 lines; copying the algorithm saves ~50 lines and the buggy
+  edge cases."
+
+**Integration approach.** One of: cherry-pick / vendor /
+cleanroom-rebuild / depend-on-it / n/a. Plus a one-sentence note on what
+that means here.
+
+**Caveats.** Anything to watch for — license, abandonment, runtime
+mismatch, security flag. Empty list is fine; don't manufacture.
+```
+
+No marketing voice. No hype. The user is a working engineer; talk to
+them like a peer. Concrete > clever.
+
+### Step 4 — Present + capture actions
+
+After all writeups, summarise:
+
+```
+3 candidates triaged for tech-news-site:
+  ✓ adopt: kribblo/node-ffmpeg-installer (high · quick) — ffmpeg-static swap
+  ⏭ port:  tj/n (medium · moderate) — version-manager pattern
+  ✗ skip:  vercel/turbo (medium · deep) — wrong runtime, already have Vite
+
+For each, what would you like to do? (star / hide / handoff / skip)
+```
+
+Then, for each candidate, capture the user's choice. For each action,
+POST to `/api/state`:
+
+```bash
+curl -sS -X POST \
+  -H "x-digest-token: $TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"repo":"owner/name","status":"<star|hide|handed_off|surfaced>","projectId":<id-from-inventory-projectMatch-or-null>}' \
+  "$BASE/api/state"
+```
+
+Status values:
+
+- `starred` — user wants to come back to this. Won't re-surface.
+- `hidden` — user dismissed it. Never re-surface unless they clear it.
+- `handed_off` — user wants a handoff PR opened against their project.
+  Use the existing `mcp__replen__replen_handoff` MCP tool to actually
+  open the PR (server-side, needs write-scoped GitHub auth). Pass the
+  PR URL back to /api/state via `handoffPrUrl` so future sessions see
+  the status.
+- `surfaced` — neutral "I showed this, user neither stared nor hid."
+  Bumps the surface counter so the inventory deprioritises it next
+  call without locking it out. POST this for EVERY candidate you
+  presented, even the skips. It's the closing bookend of this skill.
+
+### Step 5 — Close out
+
+End with one line summarising what got actioned:
+
+```
+Done. 1 starred, 0 handoff PRs opened, 1 hidden, 1 skipped.
+Run /replen-match again tomorrow for the next batch (or whenever a
+fresh candidate shows up at session start via the hook).
+```
+
+## What to do if things go wrong
+
+**Inventory call returns 401.** User's token expired or got rotated.
+Tell them to run `npx replen` to re-auth.
+
+**Inventory returns `scopedTo: null` with a `note` about "repo not in
+your project list"**. The cwd isn't a known project. Ask the user:
+"This repo isn't in your Replen projects yet. Add it via /projects?"
+Then either stop or re-run with `?repo=` (empty) to see the global
+firehose.
+
+**Candidate's README is unreachable (WebFetch 404)**. Note it in the
+writeup (`Caveats: README unreachable; verdict based on description
+only`) and proceed with a more conservative score.
+
+**Local codebase is large / search is slow.** Don't do `grep -r` from
+the root; scope to `src/`, `lib/`, `app/`. Skip `node_modules`,
+`dist`, `build`, `.next`, `vendor`. If you genuinely can't find
+related code in 3 grep attempts, say so in the writeup ("No directly
+related code found in src/; verdict based on README + project shape
+only").
+
+**No project tags configured (inventory returns
+`whyShortlisted: "no project tags configured; showing unfiltered"`)**.
+The user hasn't set up filter-mode B's tag list. Mention it once: "Heads
+up — you'd get sharper matches if you set project tags at /settings.
+Continuing with unfiltered for now."
+
+## When NOT to run this skill
+
+- The user is mid-task and just wants help with the current thing. The
+  match flow is interruptive; don't volunteer it. Only run when invoked
+  via `/replen-match` or when the user explicitly asks.
+- The repo isn't a tracked Replen project. Tell them how to add it,
+  don't try to match against an unknown project.
+- The session-start hook already surfaced matches in the opening
+  context and the user hasn't asked for more. Don't double-deliver.
+
+## Voice guide
+
+- **Concrete.** "Replaces `lib/foo.ts:42-180`" beats "could simplify
+  your image pipeline."
+- **Honest.** Skip is a valid verdict, often the right one. Don't pad.
+- **One-block-per-candidate.** Don't sprawl. The user will read 1-3
+  candidates; if you write 9 paragraphs each, they bail.
+- **Show your work.** When the verdict is "adopt", say WHAT in the
+  user's code it replaces. When "port", say WHAT idea is worth
+  porting. When "skip", say WHY.
+- **No salesmanship.** Don't end with "would you like to learn more?"
+  The user will tell you what they want.
+- **Match the calm-cadence positioning.** Most days, no candidates.
+  When there are some, they're real. Treat them that way.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "replen",
-  "version": "0.4.0",
-  "description": "Smarter AI Development workflows. The AI that asks 'can we do this better?' - replen reads your codebase against the live ecosystem and surfaces drop-in libraries, ideas to port, and patterns to learn from. Calm cadence: 1-3 actionable matches a month. One-command setup: opens a browser to sign in, then wires the MCP server into Claude Code / Codex.",
+  "version": "1.0.0",
+  "description": "Make your AI coding tools smarter. One command, no API keys. Replen scouts the OSS firehose against your projects and surfaces drop-in libraries, ideas to port, and dead deps to swap — the match decision happens inside your AI tool's session on your subscription tokens. 1-3 actionable matches a month, by design.",
   "type": "module",
   "bin": {
     "replen": "dist/index.js"
@@ -13,6 +13,7 @@
   },
   "files": [
     "dist",
+    "extras",
     "README.md",
     "LICENSE"
   ],