vanara 0.3.0 → 0.5.0

package/bin/vanara.js

@@ -8,6 +8,9 @@ import { loadCatalog, resolveInstallSet } from '../src/catalog.js';
 import { applyInstall, applyUninstall, readLock, planUpdates } from '../src/installer.js';
 import { loadFreeTier, POLAR } from '../src/config.js';
 import { unlock, isUnlocked, readLicense, clearLicense, syncPremium } from '../src/license.js';
+import { readGaps, addGap, buildMailto, clearGaps } from '../src/request.js';
+import { readMemoryIndex, readAgentMemory, pruneEmpty } from '../src/memory.js';
+import { detect, recommend } from '../src/doctor.js';
 
 const HELP = `vanara — agent packs, agents, and skills for your project.
 
@@ -23,6 +26,9 @@ Commands:
   unlock <license-key>             Activate Pro (all items). Subscribe: ${POLAR.checkoutUrl}
   account                          Show your tier and license status.
   sync                             Re-download the premium catalog (Pro).
+  request ["<capability>"]         Request a missing agent (or list/submit logged gaps).
+  memory [<agent>] [--prune]       Show what installed agents have learned here.
+  doctor                           Scan this project and recommend agents to install.
   help                             This message.
 
 Options:
@@ -58,6 +64,8 @@ async function main() {
       kind: { type: 'string' },
       members: { type: 'boolean', default: false },
       apply: { type: 'boolean', default: false },
+      prune: { type: 'boolean', default: false },
+      clear: { type: 'boolean', default: false },
     },
   });
   const [command, ...names] = positionals;
@@ -218,6 +226,70 @@ async function main() {
     return;
   }
 
+  if (command === 'request') {
+    if (values.clear) { await clearGaps(); console.log('Cleared the local request log.'); return; }
+    const capability = names.join(' ').trim();
+    if (capability) {
+      try {
+        const { added } = await addGap(capability);
+        console.log(added ? `Logged: "${capability}"` : `Already logged: "${capability}"`);
+      } catch (err) { console.error(err.message); process.exitCode = 1; return; }
+    }
+    const gaps = await readGaps();
+    if (!gaps.length) {
+      console.log('No agent requests logged yet.\nAdd one:  vanara request "a Kafka consumer-lag alerting agent"');
+      console.log('The vanara-route skill also logs gaps here automatically when it finds no match.');
+      return;
+    }
+    console.log(`\n${gaps.length} capability request(s) — logged locally, nothing sent yet:`);
+    gaps.forEach((g, i) => console.log(`  ${i + 1}. ${g.capability}`));
+    console.log('\nTo send them to the Vanara team, open this in your mail client');
+    console.log('(nothing leaves your machine until you press send):\n');
+    console.log(buildMailto(gaps));
+    console.log('\nAfter sending, clear the log with:  vanara request --clear');
+    return;
+  }
+
+  if (command === 'memory') {
+    if (values.prune) {
+      const removed = await pruneEmpty(dest);
+      console.log(removed.length ? `Pruned empty memory for: ${removed.join(', ')}` : 'No empty memory files to prune.');
+      return;
+    }
+    const agent = names.find((n) => !n.startsWith('--'));
+    if (agent) {
+      const mem = await readAgentMemory(agent, dest);
+      if (mem == null) { console.log(`No memory yet for "${agent}" in this project.`); return; }
+      console.log(mem.trimEnd());
+      return;
+    }
+    const index = await readMemoryIndex(dest);
+    if (!index.length) {
+      console.log('No agent memory yet. Agents write to .claude/memory/ as they learn your project.');
+      return;
+    }
+    console.log('\nAgent memory in this project:');
+    for (const m of index) console.log(`  ${m.agent.padEnd(24)} ${m.bullets} lesson(s)  ·  ${m.bytes} bytes`);
+    console.log('\nView one:  vanara memory <agent>');
+    console.log('Tip: commit .claude/memory/ to git to share what agents learn across your team.');
+    return;
+  }
+
+  if (command === 'doctor') {
+    const signals = await detect(dest);
+    const { signals: matched, items } = recommend(signals);
+    console.log('\nDetected in this project:');
+    for (const s of matched) console.log(`  • ${s.label}`);
+    console.log('\nRecommended to install:');
+    const freeNames = new Set([...(FREE.agents ?? []), ...(FREE.skills ?? []), ...(FREE.packs ?? [])]);
+    for (const name of items) {
+      console.log(`  ${name}${freeNames.has(name) ? '  (free)' : '  [Pro]'}`);
+    }
+    console.log(`\nInstall them:\n  npx vanara install ${items.join(' ')}`);
+    console.log('\nNot sure which fits a specific task? Ask the vanara-route skill in Claude Code.');
+    return;
+  }
+
   console.error(`Unknown command: ${command}\n`);
   console.log(HELP);
   process.exitCode = 1;

package/catalog/agents/api-designer/AGENT.md

@@ -140,6 +140,24 @@ the conventions applied here), the `api-documenter` agent (turns this contract i
 the `security-auditor` agent (for the authz/threat review this agent deliberately leaves out).
 
 
+## Operating protocol
+
+You run under a standard Vanara protocol — it is what makes you safe to trust with real work.
+
+- **Ground every claim.** State findings with concrete evidence: a `file:line`, a command's
+  output, or the result of one of your own `scripts/`. Run your verification script(s) before
+  reporting when the task is in their scope. If you cannot ground a claim, say so plainly — never
+  invent a file, a line number, or a result.
+- **Say what you'll touch, then stay in scope.** Before acting, state briefly what you will read
+  and what (if anything) you will change. Default to read-only; only write files the task
+  requires. For anything destructive or irreversible — deleting, force-pushing, migrations, prod
+  config — stop and get explicit confirmation first.
+- **Leave a trail.** Whenever you change a file, append one line to `.claude/vanara-runs.log`:
+  `<ISO-8601 date> <your-name> — <what changed> — <why>` (create the file if it's missing).
+- **Check your own work before you finish.** Don't declare a task done until its exit criteria
+  hold — tests pass, no new secrets, lints/build clean, and the original ask is fully addressed.
+  If a criterion can't be met, report exactly which one and why; never claim success you can't back.
+
 ## Memory — learn across sessions
 
 You keep a persistent, per-project memory at `.claude/memory/api-designer.md`. It is

package/catalog/agents/code-reviewer/AGENT.md

@@ -168,6 +168,24 @@ audits, the `owasp-top10` skill for the vulnerability catalogue, and the `error-
 skill for correct error propagation.
 
 
+## Operating protocol
+
+You run under a standard Vanara protocol — it is what makes you safe to trust with real work.
+
+- **Ground every claim.** State findings with concrete evidence: a `file:line`, a command's
+  output, or the result of one of your own `scripts/`. Run your verification script(s) before
+  reporting when the task is in their scope. If you cannot ground a claim, say so plainly — never
+  invent a file, a line number, or a result.
+- **Say what you'll touch, then stay in scope.** Before acting, state briefly what you will read
+  and what (if anything) you will change. Default to read-only; only write files the task
+  requires. For anything destructive or irreversible — deleting, force-pushing, migrations, prod
+  config — stop and get explicit confirmation first.
+- **Leave a trail.** Whenever you change a file, append one line to `.claude/vanara-runs.log`:
+  `<ISO-8601 date> <your-name> — <what changed> — <why>` (create the file if it's missing).
+- **Check your own work before you finish.** Don't declare a task done until its exit criteria
+  hold — tests pass, no new secrets, lints/build clean, and the original ask is fully addressed.
+  If a criterion can't be met, report exactly which one and why; never claim success you can't back.
+
 ## Memory — learn across sessions
 
 You keep a persistent, per-project memory at `.claude/memory/code-reviewer.md`. It is

package/catalog/agents/debugger/AGENT.md

@@ -112,6 +112,24 @@ Pairs with the `code-reviewer` agent (review the fix before merge), the `tdd-gui
 into a failing test first), and the `error-handling-patterns` skill (so the cause can't silently recur).
 
 
+## Operating protocol
+
+You run under a standard Vanara protocol — it is what makes you safe to trust with real work.
+
+- **Ground every claim.** State findings with concrete evidence: a `file:line`, a command's
+  output, or the result of one of your own `scripts/`. Run your verification script(s) before
+  reporting when the task is in their scope. If you cannot ground a claim, say so plainly — never
+  invent a file, a line number, or a result.
+- **Say what you'll touch, then stay in scope.** Before acting, state briefly what you will read
+  and what (if anything) you will change. Default to read-only; only write files the task
+  requires. For anything destructive or irreversible — deleting, force-pushing, migrations, prod
+  config — stop and get explicit confirmation first.
+- **Leave a trail.** Whenever you change a file, append one line to `.claude/vanara-runs.log`:
+  `<ISO-8601 date> <your-name> — <what changed> — <why>` (create the file if it's missing).
+- **Check your own work before you finish.** Don't declare a task done until its exit criteria
+  hold — tests pass, no new secrets, lints/build clean, and the original ask is fully addressed.
+  If a criterion can't be met, report exactly which one and why; never claim success you can't back.
+
 ## Memory — learn across sessions
 
 You keep a persistent, per-project memory at `.claude/memory/debugger.md`. It is

package/catalog/agents/pr-summarizer/AGENT.md

@@ -156,6 +156,24 @@ migration. The PR is described as "add export auth," but it also changes the def
 skill (for authoring the PR title/body once the summary is written).
 
 
+## Operating protocol
+
+You run under a standard Vanara protocol — it is what makes you safe to trust with real work.
+
+- **Ground every claim.** State findings with concrete evidence: a `file:line`, a command's
+  output, or the result of one of your own `scripts/`. Run your verification script(s) before
+  reporting when the task is in their scope. If you cannot ground a claim, say so plainly — never
+  invent a file, a line number, or a result.
+- **Say what you'll touch, then stay in scope.** Before acting, state briefly what you will read
+  and what (if anything) you will change. Default to read-only; only write files the task
+  requires. For anything destructive or irreversible — deleting, force-pushing, migrations, prod
+  config — stop and get explicit confirmation first.
+- **Leave a trail.** Whenever you change a file, append one line to `.claude/vanara-runs.log`:
+  `<ISO-8601 date> <your-name> — <what changed> — <why>` (create the file if it's missing).
+- **Check your own work before you finish.** Don't declare a task done until its exit criteria
+  hold — tests pass, no new secrets, lints/build clean, and the original ask is fully addressed.
+  If a criterion can't be met, report exactly which one and why; never claim success you can't back.
+
 ## Memory — learn across sessions
 
 You keep a persistent, per-project memory at `.claude/memory/pr-summarizer.md`. It is

package/catalog/agents/refactoring-specialist/AGENT.md

@@ -185,6 +185,24 @@ Do not use this agent when:
 Pairs with the `refactoring-patterns` skill, the `code-reviewer` agent, and the `test-author` agent.
 
 
+## Operating protocol
+
+You run under a standard Vanara protocol — it is what makes you safe to trust with real work.
+
+- **Ground every claim.** State findings with concrete evidence: a `file:line`, a command's
+  output, or the result of one of your own `scripts/`. Run your verification script(s) before
+  reporting when the task is in their scope. If you cannot ground a claim, say so plainly — never
+  invent a file, a line number, or a result.
+- **Say what you'll touch, then stay in scope.** Before acting, state briefly what you will read
+  and what (if anything) you will change. Default to read-only; only write files the task
+  requires. For anything destructive or irreversible — deleting, force-pushing, migrations, prod
+  config — stop and get explicit confirmation first.
+- **Leave a trail.** Whenever you change a file, append one line to `.claude/vanara-runs.log`:
+  `<ISO-8601 date> <your-name> — <what changed> — <why>` (create the file if it's missing).
+- **Check your own work before you finish.** Don't declare a task done until its exit criteria
+  hold — tests pass, no new secrets, lints/build clean, and the original ask is fully addressed.
+  If a criterion can't be met, report exactly which one and why; never claim success you can't back.
+
 ## Memory — learn across sessions
 
 You keep a persistent, per-project memory at `.claude/memory/refactoring-specialist.md`. It is

package/catalog/agents/security-auditor/AGENT.md

@@ -168,6 +168,24 @@ analysis, the [`vuln-scanner`](../vuln-scanner/AGENT.md) agent for automated SAS
 the `owasp-top10` skill for the full vulnerability catalogue.
 
 
+## Operating protocol
+
+You run under a standard Vanara protocol — it is what makes you safe to trust with real work.
+
+- **Ground every claim.** State findings with concrete evidence: a `file:line`, a command's
+  output, or the result of one of your own `scripts/`. Run your verification script(s) before
+  reporting when the task is in their scope. If you cannot ground a claim, say so plainly — never
+  invent a file, a line number, or a result.
+- **Say what you'll touch, then stay in scope.** Before acting, state briefly what you will read
+  and what (if anything) you will change. Default to read-only; only write files the task
+  requires. For anything destructive or irreversible — deleting, force-pushing, migrations, prod
+  config — stop and get explicit confirmation first.
+- **Leave a trail.** Whenever you change a file, append one line to `.claude/vanara-runs.log`:
+  `<ISO-8601 date> <your-name> — <what changed> — <why>` (create the file if it's missing).
+- **Check your own work before you finish.** Don't declare a task done until its exit criteria
+  hold — tests pass, no new secrets, lints/build clean, and the original ask is fully addressed.
+  If a criterion can't be met, report exactly which one and why; never claim success you can't back.
+
 ## Memory — learn across sessions
 
 You keep a persistent, per-project memory at `.claude/memory/security-auditor.md`. It is

package/catalog/agents/technical-writer/AGENT.md

@@ -163,6 +163,24 @@ Pairs with the `readme-writing` and `documentation-structure` skills for assembl
 documentation set, and with `update-docs` for keeping generated docs in sync with their source.
 
 
+## Operating protocol
+
+You run under a standard Vanara protocol — it is what makes you safe to trust with real work.
+
+- **Ground every claim.** State findings with concrete evidence: a `file:line`, a command's
+  output, or the result of one of your own `scripts/`. Run your verification script(s) before
+  reporting when the task is in their scope. If you cannot ground a claim, say so plainly — never
+  invent a file, a line number, or a result.
+- **Say what you'll touch, then stay in scope.** Before acting, state briefly what you will read
+  and what (if anything) you will change. Default to read-only; only write files the task
+  requires. For anything destructive or irreversible — deleting, force-pushing, migrations, prod
+  config — stop and get explicit confirmation first.
+- **Leave a trail.** Whenever you change a file, append one line to `.claude/vanara-runs.log`:
+  `<ISO-8601 date> <your-name> — <what changed> — <why>` (create the file if it's missing).
+- **Check your own work before you finish.** Don't declare a task done until its exit criteria
+  hold — tests pass, no new secrets, lints/build clean, and the original ask is fully addressed.
+  If a criterion can't be met, report exactly which one and why; never claim success you can't back.
+
 ## Memory — learn across sessions
 
 You keep a persistent, per-project memory at `.claude/memory/technical-writer.md`. It is

package/catalog/agents/test-author/AGENT.md

@@ -177,6 +177,24 @@ agent (quality and security pass after tests are green). See
 layer belongs.
 
 
+## Operating protocol
+
+You run under a standard Vanara protocol — it is what makes you safe to trust with real work.
+
+- **Ground every claim.** State findings with concrete evidence: a `file:line`, a command's
+  output, or the result of one of your own `scripts/`. Run your verification script(s) before
+  reporting when the task is in their scope. If you cannot ground a claim, say so plainly — never
+  invent a file, a line number, or a result.
+- **Say what you'll touch, then stay in scope.** Before acting, state briefly what you will read
+  and what (if anything) you will change. Default to read-only; only write files the task
+  requires. For anything destructive or irreversible — deleting, force-pushing, migrations, prod
+  config — stop and get explicit confirmation first.
+- **Leave a trail.** Whenever you change a file, append one line to `.claude/vanara-runs.log`:
+  `<ISO-8601 date> <your-name> — <what changed> — <why>` (create the file if it's missing).
+- **Check your own work before you finish.** Don't declare a task done until its exit criteria
+  hold — tests pass, no new secrets, lints/build clean, and the original ask is fully addressed.
+  If a criterion can't be met, report exactly which one and why; never claim success you can't back.
+
 ## Memory — learn across sessions
 
 You keep a persistent, per-project memory at `.claude/memory/test-author.md`. It is

package/catalog/agents/threat-modeler/AGENT.md

@@ -163,6 +163,24 @@ Pairs with the `security-auditor` agent (for code-level vulnerability findings),
 (for mapping threats to the most common web weakness classes).
 
 
+## Operating protocol
+
+You run under a standard Vanara protocol — it is what makes you safe to trust with real work.
+
+- **Ground every claim.** State findings with concrete evidence: a `file:line`, a command's
+  output, or the result of one of your own `scripts/`. Run your verification script(s) before
+  reporting when the task is in their scope. If you cannot ground a claim, say so plainly — never
+  invent a file, a line number, or a result.
+- **Say what you'll touch, then stay in scope.** Before acting, state briefly what you will read
+  and what (if anything) you will change. Default to read-only; only write files the task
+  requires. For anything destructive or irreversible — deleting, force-pushing, migrations, prod
+  config — stop and get explicit confirmation first.
+- **Leave a trail.** Whenever you change a file, append one line to `.claude/vanara-runs.log`:
+  `<ISO-8601 date> <your-name> — <what changed> — <why>` (create the file if it's missing).
+- **Check your own work before you finish.** Don't declare a task done until its exit criteria
+  hold — tests pass, no new secrets, lints/build clean, and the original ask is fully addressed.
+  If a criterion can't be met, report exactly which one and why; never claim success you can't back.
+
 ## Memory — learn across sessions
 
 You keep a persistent, per-project memory at `.claude/memory/threat-modeler.md`. It is

package/catalog/agents/vuln-scanner/AGENT.md

@@ -146,6 +146,24 @@ Pairs with the `security-auditor` agent, the `threat-modeler` agent, the `secret
 the `owasp-top10` skill.
 
 
+## Operating protocol
+
+You run under a standard Vanara protocol — it is what makes you safe to trust with real work.
+
+- **Ground every claim.** State findings with concrete evidence: a `file:line`, a command's
+  output, or the result of one of your own `scripts/`. Run your verification script(s) before
+  reporting when the task is in their scope. If you cannot ground a claim, say so plainly — never
+  invent a file, a line number, or a result.
+- **Say what you'll touch, then stay in scope.** Before acting, state briefly what you will read
+  and what (if anything) you will change. Default to read-only; only write files the task
+  requires. For anything destructive or irreversible — deleting, force-pushing, migrations, prod
+  config — stop and get explicit confirmation first.
+- **Leave a trail.** Whenever you change a file, append one line to `.claude/vanara-runs.log`:
+  `<ISO-8601 date> <your-name> — <what changed> — <why>` (create the file if it's missing).
+- **Check your own work before you finish.** Don't declare a task done until its exit criteria
+  hold — tests pass, no new secrets, lints/build clean, and the original ask is fully addressed.
+  If a criterion can't be met, report exactly which one and why; never claim success you can't back.
+
 ## Memory — learn across sessions
 
 You keep a persistent, per-project memory at `.claude/memory/vuln-scanner.md`. It is

package/catalog/skills/vanara-route/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: vanara-route
+description: Given a task, find the best-fit installed Vanara agent and run it. Reads the installed agent roster, scores each by how well its stated purpose matches the task, delegates to the strongest match, and — when nothing fits — records the gap so you can request the missing agent. Use when you are not sure which specialist should handle a job, or you want the toolkit to pick for you.
+type: skill
+version: 1.0.0
+updated: 2026-07-13
+---
+
+# vanara-route — the dispatcher
+
+You are routing a task to the **best-capable installed agent**, then handing off to it.
+Claude Code already auto-selects agents from their descriptions; this skill adds two things
+on top: an *explicit* "pick the strongest specialist for this exact task" step you can invoke
+on demand, and a **gap-capture** path for when the toolkit has nothing that fits.
+
+## When to use
+
+- The user asks "which agent should handle X?" or "use the right agent for this."
+- A task spans several specialties and you want the single best owner (or a short list).
+- You suspect no installed agent covers the task and want that recorded, not silently dropped.
+
+## The routing procedure
+
+1. **Enumerate the roster.** Run `node .claude/skills/vanara-route/scripts/roster.mjs` (or read
+   `.claude/agents/*.md` directly) to list every installed agent with its `name` and
+   `description` — the path is from your project root, where Claude Code runs. The description
+   is the agent's own statement of when it should be used — treat it as the primary signal.
+
+2. **Score each candidate against the task.** For every agent, judge fit on:
+   - **Domain match** — does the task fall in this agent's stated domain? (a Terraform change
+     → `iac-author`; a failing test → `test-author`; a slow query → `database-administrator`).
+   - **Verb match** — does the agent *do* what the task needs (review vs. write vs. audit vs.
+     plan)? A read-only reviewer is the wrong pick for "implement".
+   - **Proactivity cues** — descriptions that say "Use PROACTIVELY when …" are strong matches
+     for exactly those triggers.
+   Assign each a confidence: **strong / partial / none**.
+
+3. **Act on the best match.**
+   - **One strong match** → delegate the task to that agent (invoke it via the Task tool) and
+     return its result. Say which agent you chose and why in one line.
+   - **Several strong matches** (e.g. review + security on the same diff) → run them in the
+     order the work implies, or present the short list and let the user pick.
+   - **Only partial matches** → name the closest agent, state plainly that it is an approximate
+     fit, and ask before running it.
+   - **No match** → do **not** improvise a fake specialist. Record the gap (next section).
+
+4. **Never fabricate a specialist.** If the roster has no agent for the job, routing has
+   failed on purpose — that failure is a signal, not something to paper over.
+
+## Recording a gap (when nothing fits)
+
+When no installed agent covers the task, append one line to the local gap log so it is not
+lost. Do this with the helper (it is append-only and creates the file if needed):
+
+```bash
+node .claude/skills/vanara-route/scripts/log-gap.mjs "one-line capability that was missing"
+```
+
+This writes to `~/.vanara/gaps.jsonl` **on the user's machine only** — nothing is sent
+anywhere. Then tell the user, in one sentence, that they can submit the request with
+`vanara request` (which prepares an email to the Vanara team; the user sends it, or not).
+See [references/gap-reporting.md](references/gap-reporting.md) for the privacy model.
+
+## Edge cases and failure modes
+
+- **Empty roster** (nothing installed yet): tell the user to `npx vanara install <name>` or
+  `vanara list` first; there is nothing to route to.
+- **Over-eager matching:** a vaguely-related description is a *partial* match, not a strong
+  one. Prefer asking over running the wrong specialist on a real task.
+- **Ambiguous verbs:** "fix the auth bug" implies reproduce → test → patch → review, which is
+  an *orchestration* job — prefer an orchestrator pack if one is installed over a single agent.
+- **Secrets:** never write task contents, code, credentials, or customer data into the gap
+  log — only a short, generic description of the missing capability.
+- **Do not loop:** route once. If the chosen agent itself can't finish, report that back to
+  the user rather than re-routing endlessly.
+
+## Example
+
+> **Task:** "our Terraform plan keeps showing drift on the prod VPC — figure out why."
+>
+> Roster scan → `iac-author` (writes/refactors IaC) is a *partial* verb match (this is
+> diagnosis, not authoring); no dedicated drift-diagnosis agent exists. Route names
+> `iac-author` as the closest fit, flags it as approximate, and logs the gap
+> *"Terraform drift diagnosis / state reconciliation"* so it can be requested.
+
+See [references/matching-heuristics.md](references/matching-heuristics.md) for the full scoring
+rubric and worked examples.

package/catalog/skills/vanara-route/references/gap-reporting.md

@@ -0,0 +1,29 @@
+# Gap reporting — the privacy model
+
+When the router finds no installed agent for a task, that is a useful signal: it tells the
+Vanara team which specialist to build next. But a task description can contain proprietary
+code, customer data, or business context — so **nothing is ever sent automatically.**
+
+## How it works
+
+1. **Local log.** The router appends a one-line, generic description of the *missing
+   capability* (not the task contents) to `~/.vanara/gaps.jsonl` on your machine. Example line:
+   ```json
+   {"ts":"2026-07-13T18:00:00Z","capability":"Terraform drift diagnosis / state reconciliation"}
+   ```
+2. **You decide.** Running `vanara request` reads that log and prepares an email to the Vanara
+   team (`support@vanaraagents.com`) with the capability phrases pre-filled. You review it and
+   **you** send it — or edit it, or delete a line, or send nothing.
+3. **No telemetry.** There is no background upload, no phone-home, no account tie-in. If you
+   never run `vanara request`, nothing leaves your machine.
+
+## What to record — and what never to
+
+| Record (generic capability) | Never record |
+|---|---|
+| "Kafka consumer-lag alerting agent" | the task's actual code or config |
+| "Stripe webhook reconciliation reviewer" | customer names, emails, secrets |
+| "ARM template (Bicep) linter" | proprietary business logic |
+
+The rule is one short phrase naming the *kind of agent* that was missing. If in doubt, write
+less. You can always add detail yourself when you send the request.

package/catalog/skills/vanara-route/references/matching-heuristics.md

@@ -0,0 +1,35 @@
+# Matching heuristics — scoring an agent against a task
+
+The router's job is to map a task to the installed agent whose *stated purpose* fits best.
+The signal is each agent's `description` frontmatter — agents are authored to declare exactly
+when they should be used. Score on three axes, then combine.
+
+## The three axes
+
+| Axis | Question | Strong signal | Weak / no signal |
+|---|---|---|---|
+| **Domain** | Is the task in this agent's field? | task nouns match the agent's domain (schema → database, WCAG → accessibility) | domain is adjacent but not the same |
+| **Verb** | Does the agent *do* the needed action? | review↔reviewer, write↔author, audit↔auditor, plan↔planner | agent only reads when the task needs writing |
+| **Trigger** | Does the description name this situation? | "Use PROACTIVELY when \<exactly this\>" | generic description with no trigger |
+
+Confidence = **strong** only when Domain and Verb both match. Domain-only or Verb-only is
+**partial**. Neither is **none**.
+
+## Worked examples
+
+- *"add pagination to the orders endpoint"* → `api-designer` **partial** (domain match, but it
+  advises rather than implements) + `feature-builder` **strong** (writes the code). Route to
+  `feature-builder`; mention `api-designer` for the contract if the user wants review.
+- *"is this dependency bump safe?"* → `dependency-upgrader` **strong**. One clear owner.
+- *"our SOC 2 auditor asked for an access-review policy"* → `compliance-auditor` **strong**.
+- *"make the game's boss fight less frustrating"* → `game-systems-designer` **strong** (design),
+  `game-developer` **partial** (implements once the design is decided).
+
+## Anti-patterns
+
+- **Keyword collision:** the word "review" appears in many descriptions — confirm the *domain*
+  too before routing a security task to a code reviewer.
+- **One agent for an orchestration job:** "fix the failing build and stop it regressing" is
+  reproduce → test → patch → review. Prefer an installed orchestrator pack over a lone agent.
+- **Forcing a fit:** a partial match on a real, consequential task is a reason to ask the user,
+  or to log a gap — not to run the wrong specialist and hope.

package/catalog/skills/vanara-route/scripts/log-gap.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// Appends a missing-capability gap to ~/.vanara/gaps.jsonl — LOCAL ONLY, nothing
+// is sent anywhere. `vanara request` later lets the user submit these on purpose.
+//   node log-gap.mjs "short capability that was missing"   |   --selftest
+import { appendFileSync, mkdirSync, readFileSync, existsSync, mkdtempSync, rmSync, realpathSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+
+// Windows-safe direct-run check (see roster.mjs).
+function isDirectRun() {
+  try {
+    return Boolean(process.argv[1]) &&
+      realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch { return false; }
+}
+
+export function gapsPath(home = os.homedir()) {
+  return path.join(home, ".vanara", "gaps.jsonl");
+}
+
+export function logGap(capability, { home = os.homedir(), now = new Date() } = {}) {
+  const cap = String(capability ?? "").trim();
+  if (!cap) throw new Error("empty capability");
+  if (cap.length > 200) throw new Error("capability too long — keep it a short phrase");
+  const file = gapsPath(home);
+  mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  // De-dupe: skip if the same capability was already logged.
+  if (existsSync(file)) {
+    for (const line of readFileSync(file, "utf8").split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      try { if (JSON.parse(line).capability === cap) return { added: false, file }; } catch {}
+    }
+  }
+  appendFileSync(file, `${JSON.stringify({ ts: now.toISOString(), capability: cap })}\n`, "utf8");
+  return { added: true, file };
+}
+
+function selftest() {
+  const home = mkdtempSync(path.join(os.tmpdir(), "gap-"));
+  const a = logGap("drift diagnosis", { home });
+  const b = logGap("drift diagnosis", { home }); // dupe
+  const ok = a.added === true && b.added === false;
+  rmSync(home, { recursive: true, force: true });
+  if (ok) { console.log("selftest ok"); process.exit(0); }
+  console.error("selftest FAILED"); process.exit(1);
+}
+
+if (process.argv.includes("--selftest")) selftest();
+else if (isDirectRun()) {
+  const cap = process.argv.slice(2).join(" ").trim();
+  if (!cap) { console.error('usage: node log-gap.mjs "missing capability"'); process.exit(1); }
+  const r = logGap(cap);
+  console.log(r.added ? `logged gap → ${r.file}` : "already logged (skipped duplicate)");
+  console.log("submit it any time with:  vanara request");
+}

package/catalog/skills/vanara-route/scripts/roster.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// Lists installed Vanara agents (name + description) so the router can score
+// them against a task. Reads .claude/agents/*.md in the current project.
+//   node roster.mjs [--json] [--dir <project-root>]  |  --selftest
+import { readdirSync, readFileSync, existsSync, statSync, mkdtempSync, writeFileSync, mkdirSync, rmSync, realpathSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+
+// Cross-platform "is this file being run directly?" — compare canonical paths.
+// A plain string/URL compare breaks on Windows (backslashes, drive-letter case,
+// 8.3 short names in TEMP); realpathSync normalizes both sides.
+function isDirectRun() {
+  try {
+    return Boolean(process.argv[1]) &&
+      realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch { return false; }
+}
+
+function frontmatter(md) {
+  const m = md.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return {};
+  const out = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const i = line.indexOf(":");
+    if (i === -1) continue;
+    out[line.slice(0, i).trim()] = line.slice(i + 1).trim().replace(/^["']|["']$/g, "");
+  }
+  return out;
+}
+
+export function readRoster(root = process.cwd()) {
+  const dir = path.join(root, ".claude", "agents");
+  if (!existsSync(dir)) return [];
+  const agents = [];
+  for (const entry of readdirSync(dir)) {
+    const full = path.join(dir, entry);
+    let file = null;
+    if (entry.endsWith(".md")) file = full;
+    else if (statSync(full).isDirectory()) {
+      const a = path.join(full, "AGENT.md");
+      if (existsSync(a)) file = a;
+    }
+    if (!file) continue;
+    const fm = frontmatter(readFileSync(file, "utf8"));
+    if (fm.name) agents.push({ name: fm.name, description: fm.description ?? "" });
+  }
+  return agents.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function selftest() {
+  const tmp = mkdtempSync(path.join(os.tmpdir(), "roster-"));
+  mkdirSync(path.join(tmp, ".claude", "agents"), { recursive: true });
+  writeFileSync(
+    path.join(tmp, ".claude", "agents", "code-reviewer.md"),
+    "---\nname: code-reviewer\ndescription: Reviews diffs.\n---\nbody",
+  );
+  const r = readRoster(tmp);
+  rmSync(tmp, { recursive: true, force: true });
+  if (r.length === 1 && r[0].name === "code-reviewer") { console.log("selftest ok"); process.exit(0); }
+  console.error("selftest FAILED", r); process.exit(1);
+}
+
+if (process.argv.includes("--selftest")) selftest();
+else if (isDirectRun()) {
+  const dirFlag = process.argv.indexOf("--dir");
+  const root = dirFlag !== -1 ? process.argv[dirFlag + 1] : process.cwd();
+  const roster = readRoster(root);
+  if (process.argv.includes("--json")) console.log(JSON.stringify(roster, null, 2));
+  else {
+    if (!roster.length) console.log("(no installed agents — run: npx vanara install <name>)");
+    for (const a of roster) console.log(`${a.name} — ${a.description.slice(0, 100)}`);
+  }
+}

package/free-tier.json

@@ -1,15 +1,37 @@
-{
-  "$comment": "Items installable without a license. Everything else in the bundled catalog requires `vanara unlock <license-key>` (Pro subscription). Packs listed here imply their members are free too.",
-  "packs": ["code-review-pack", "security-pack"],
-  "agents": [
-    "code-reviewer", "pr-summarizer", "threat-modeler", "security-auditor", "vuln-scanner",
-    "debugger", "test-author", "api-designer", "refactoring-specialist", "technical-writer"
-  ],
-  "skills": [
-    "git-collaboration-workflows", "conventional-commits", "sql-index-tuning",
-    "owasp-top10", "secure-auth", "secrets-management",
-    "rest-api-design", "api-pagination", "error-handling-patterns",
-    "test-plan-design", "readme-writing", "refactoring-patterns",
-    "caching-strategies", "database-migrations", "prompt-engineering"
-  ]
-}
+{
+ "$comment": "Items installable without a license. Everything else in the bundled catalog requires `vanara unlock <license-key>` (Pro subscription). Packs listed here imply their members are free too.",
+ "packs": [
+  "code-review-pack",
+  "security-pack"
+ ],
+ "agents": [
+  "code-reviewer",
+  "pr-summarizer",
+  "threat-modeler",
+  "security-auditor",
+  "vuln-scanner",
+  "debugger",
+  "test-author",
+  "api-designer",
+  "refactoring-specialist",
+  "technical-writer"
+ ],
+ "skills": [
+  "git-collaboration-workflows",
+  "conventional-commits",
+  "sql-index-tuning",
+  "owasp-top10",
+  "secure-auth",
+  "secrets-management",
+  "rest-api-design",
+  "api-pagination",
+  "error-handling-patterns",
+  "test-plan-design",
+  "readme-writing",
+  "refactoring-patterns",
+  "caching-strategies",
+  "database-migrations",
+  "prompt-engineering",
+  "vanara-route"
+ ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vanara",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Vanara — deploy packs of skilled AI agents. Install agents, skills, and packs into any project from the Vanara catalog.",
   "type": "module",
   "bin": {

package/src/doctor.js

@@ -0,0 +1,49 @@
+// `vanara doctor` — inspect a project and recommend which agents/packs to install.
+// Pure heuristics over files + package.json; no network. Every recommended name
+// is a real catalog item. The inverse of routing: proactive at setup time.
+import { readFile, readdir, access } from 'node:fs/promises';
+import path from 'node:path';
+
+const exists = async (p) => { try { await access(p); return true; } catch { return false; } };
+
+// signal -> { detect, recommend } ; recommend names must exist in the catalog.
+const SIGNALS = [
+  { id: 'always', label: 'any codebase', recommend: ['code-review-pack', 'test-author', 'vanara-route'] },
+  { id: 'web',      label: 'frontend / web UI',       recommend: ['accessibility-auditor', 'code-reviewer', 'component-builder'] },
+  { id: 'backend',  label: 'backend / API service',   recommend: ['backend-essentials-pack', 'api-designer', 'database-administrator'] },
+  { id: 'infra',    label: 'containers / IaC',         recommend: ['iac-author', 'cicd-engineer', 'sre-reliability-pack'] },
+  { id: 'security', label: 'auth / payments / secrets', recommend: ['security-pack', 'threat-modeler', 'security-auditor'] },
+  { id: 'data',     label: 'data / ML',                recommend: ['data-pipeline-engineer', 'ml-model-reviewer'] },
+];
+
+export async function detect(root = process.cwd()) {
+  const found = new Set(['always']);
+  let deps = {};
+  try {
+    const pkg = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+    deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  } catch { /* no package.json */ }
+  const dep = (re) => Object.keys(deps).some((d) => re.test(d));
+
+  let files = [];
+  try { files = await readdir(root); } catch { /* unreadable */ }
+  const has = async (...names) => (await Promise.all(names.map((n) => exists(path.join(root, n))))).some(Boolean);
+  const ext = (re) => files.some((f) => re.test(f));
+
+  if (dep(/^(react|next|vue|svelte|@angular)/) || ext(/\.(tsx|jsx|vue|svelte)$/)) found.add('web');
+  if (dep(/^(express|fastify|koa|@nestjs|django|flask|fastapi)/) || (await has('go.mod', 'requirements.txt', 'pyproject.toml', 'Gemfile'))) found.add('backend');
+  if (await has('Dockerfile', 'docker-compose.yml', 'compose.yaml') || ext(/\.tf$/) || (await has('.github', 'k8s', 'helm'))) found.add('infra');
+  if (dep(/(auth|passport|jsonwebtoken|bcrypt|stripe|paypal|oauth)/)) found.add('security');
+  if (dep(/(tensorflow|torch|scikit|pandas|numpy|langchain)/) || ext(/\.ipynb$/)) found.add('data');
+  return [...found];
+}
+
+export function recommend(signalIds) {
+  const seen = new Set();
+  const items = [];
+  for (const s of SIGNALS) {
+    if (!signalIds.includes(s.id)) continue;
+    for (const name of s.recommend) if (!seen.has(name)) { seen.add(name); items.push(name); }
+  }
+  return { signals: SIGNALS.filter((s) => signalIds.includes(s.id)), items };
+}

package/src/memory.js

@@ -0,0 +1,39 @@
+// `vanara memory` — inspect what installed agents have learned for this project.
+// Agents write to .claude/memory/<name>.md (see the memory protocol). Committing
+// that folder to git shares the accumulated knowledge across a whole team.
+import { readdir, readFile, stat, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+const MEMORY_DIR = path.join('.claude', 'memory');
+
+/** List memory files with entry/line counts. Returns [] if none. */
+export async function readMemoryIndex(root = process.cwd()) {
+  const dir = path.join(root, MEMORY_DIR);
+  let entries;
+  try { entries = await readdir(dir); }
+  catch (err) { if (err.code === 'ENOENT') return []; throw err; }
+  const out = [];
+  for (const name of entries) {
+    if (!name.endsWith('.md')) continue;
+    const file = path.join(dir, name);
+    const [text, st] = await Promise.all([readFile(file, 'utf8'), stat(file)]);
+    const bullets = (text.match(/^\s*[-*]\s+/gm) ?? []).length;
+    out.push({ agent: name.replace(/\.md$/, ''), bullets, bytes: st.size, mtime: st.mtime, file });
+  }
+  return out.sort((a, b) => a.agent.localeCompare(b.agent));
+}
+
+/** Read one agent's memory text, or null if absent. */
+export async function readAgentMemory(agent, root = process.cwd()) {
+  try { return await readFile(path.join(root, MEMORY_DIR, `${agent}.md`), 'utf8'); }
+  catch (err) { if (err.code === 'ENOENT') return null; throw err; }
+}
+
+/** Remove empty (zero-bullet) memory files. Returns the removed agent names. */
+export async function pruneEmpty(root = process.cwd()) {
+  const removed = [];
+  for (const m of await readMemoryIndex(root)) {
+    if (m.bullets === 0) { await rm(m.file, { force: true }); removed.push(m.agent); }
+  }
+  return removed;
+}

package/src/request.js

@@ -0,0 +1,63 @@
+// `vanara request` — submit missing-capability requests to the Vanara team.
+// Gaps are logged LOCALLY (by the vanara-route skill or by this command) to
+// ~/.vanara/gaps.jsonl. Submission is always user-initiated: this builds a
+// pre-filled email to support@vanaraagents.com — nothing is sent automatically,
+// no telemetry, no phone-home. See catalog/skills/vanara-route/references.
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+const SUPPORT = 'support@vanaraagents.com';
+const MAX_CAP = 200;
+
+export const gapsPath = (home = os.homedir()) => path.join(home, '.vanara', 'gaps.jsonl');
+
+export async function readGaps(fileOverride) {
+  const file = fileOverride ?? gapsPath();
+  let text;
+  try { text = await readFile(file, 'utf8'); }
+  catch (err) { if (err.code === 'ENOENT') return []; throw err; }
+  const gaps = [];
+  for (const line of text.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      const g = JSON.parse(line);
+      if (g && typeof g.capability === 'string') gaps.push(g);
+    } catch { /* skip malformed line */ }
+  }
+  return gaps;
+}
+
+export async function addGap(capability, { fileOverride, now = new Date() } = {}) {
+  const cap = String(capability ?? '').trim();
+  if (!cap) throw new Error('Describe the missing capability in a short phrase.');
+  if (cap.length > MAX_CAP) throw new Error(`Keep it under ${MAX_CAP} characters.`);
+  const file = fileOverride ?? gapsPath();
+  const existing = await readGaps(file);
+  if (existing.some((g) => g.capability === cap)) return { added: false, gaps: existing };
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  const next = [...existing, { ts: now.toISOString(), capability: cap }];
+  await writeFile(file, `${next.map((g) => JSON.stringify(g)).join('\n')}\n`, { encoding: 'utf8', mode: 0o600 });
+  return { added: true, gaps: next };
+}
+
+/** Build a mailto: URL the user can open to send the request themselves. */
+export function buildMailto(gaps) {
+  const lines = gaps.map((g, i) => `${i + 1}. ${g.capability}`);
+  const subject = `Vanara agent request (${gaps.length})`;
+  const body = [
+    'Hi Vanara team,',
+    '',
+    'These are capabilities I looked for but the toolkit did not have an agent for:',
+    '',
+    ...lines,
+    '',
+    '(Sent by me via `vanara request` — feel free to reach out.)',
+  ].join('\n');
+  return `mailto:${SUPPORT}?subject=${encodeURIComponent(subject)}&body=${encodeURIComponent(body)}`;
+}
+
+export async function clearGaps(fileOverride) {
+  const file = fileOverride ?? gapsPath();
+  await writeFile(file, '', 'utf8');
+}