codex-dev-mcp-suite 1.5.1 → 1.7.0

package/CHANGELOG.md

@@ -117,3 +117,19 @@
 ### Compatibility
 - Legacy env names remain supported: `LLM_*`, `NINEROUTER_*`, `EMBED_*`, and `RERANK_*`.
 - Offline keyword search remains the default if no model endpoint is configured.
+
+## [1.7.0] - 2026-07-14 — Obsidian-grade vault (feat/obsidian-grade-vault)
+### Added (project-memory)
+- `memory_moc` — generate/refresh Obsidian-style Map of Content (`MOC.md`): all notes as wikilinks, `#tag` index, and backlink graph. Auto-refreshed on every save/delete.
+- `memory_graph` — export note graph (nodes + directed edges from `[[wikilinks]]`) as JSON for external graph views.
+- Auto-bootstrap `.obsidian/` workspace (`app.json` + `workspace.json`) on first save, so the vault opens directly in the Obsidian app with graph view + tag pages.
+- MOC regenerates automatically after `memory_save` and `memory_delete`.
+
+## [1.8.0] - 2026-07-14 — Vibecoder ergonomics (P1/P2, feat/obsidian-grade-vault)
+### Added (project-memory)
+- Auto-resolve `[[wikilinks]]` + backlinks immediately on `memory_save` (graph fresh without waiting for recall).
+- Per-tag index pages: `tags/<tag>.md` emitted alongside MOC, pruned when tag empties.
+- `aliases` field on notes (Obsidian-style); `[[alias]]` now resolves via `resolveLink`.
+### Added (devjournal)
+- `journal_daily` — Obsidian-style daily note (`daily/YYYY-MM-DD.md`); read or append mode.
+- `journal_log` now auto-appends a line to today's daily note.

package/bin/prune.mjs

@@ -35,7 +35,7 @@ function resolveRoot() {
       return parent;
     }
   }
-  return path.join(os.homedir(), ".codex", "memories");
+  return path.join(os.homedir(), ".ai-shared-memory");
 }
 
 function parseArgs(argv) {

package/bin/stats.mjs

@@ -36,7 +36,7 @@ function resolveRoot() {
       return parent;
     }
   }
-  return path.join(os.homedir(), ".codex", "memories");
+  return path.join(os.homedir(), ".ai-shared-memory");
 }
 
 function parseArgs(argv) {

package/checkpoint/server.js

@@ -24,7 +24,7 @@ import crypto from "crypto";
 
 const ROOT =
   process.env.CHECKPOINT_DIR ||
-  path.join(os.homedir(), ".codex", "memories", "checkpoints");
+  path.join(os.homedir(), ".ai-shared-memory", "checkpoints");
 
 const DEFAULT_IGNORE = new Set([
   "node_modules", ".git", ".next", "dist", "build", "target", ".venv",

package/context-pack/server.js

@@ -8,7 +8,7 @@
  * window. Detects stack, shows a pruned tree, surfaces key files, and
  * extracts top-level symbols (functions/classes/exports) heuristically.
  *
- * Tools: pack_overview, pack_tree, pack_outline, pack_search
+ * Tools: pack_overview, pack_tree, pack_outline, pack_search, pack_audit
  */
 
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -19,6 +19,7 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 import fs from "fs/promises";
 import path from "path";
+import { execSync } from "child_process";
 
 const IGNORE = new Set([
   "node_modules", ".git", ".next", "dist", "build", "target", ".venv",
@@ -34,6 +35,32 @@ const KEY_FILES = [
 ];
 const CODE_EXT = new Set([".js", ".mjs", ".ts", ".tsx", ".jsx", ".py", ".go", ".rs", ".java", ".rb", ".php", ".c", ".cpp", ".h", ".sh"]);
 const MAX_FILE_BYTES = 1_500_000;
+const AUDIT_SENSITIVE_PATTERNS = [
+  /^\.env/i, /\.pem$/i, /\.key$/i, /\.p12$/i, /\.pfx$/i,
+  /id_rsa/i, /id_ed25519/i, /id_ecdsa/i, /id_dsa/i,
+  /known_hosts/i, /authorized_keys/i,
+  /credentials/i, /password/i, /secret/i, /token/i,
+  /\.htpasswd/i, /\.netrc/i, /npmrc$/i,
+  /service[_-]?account.*\.json$/i,
+];
+const AUDIT_SECRET_CONTENT_RE = [
+  /sk-[a-zA-Z0-9]{20,}/i,
+  /ghp_[a-zA-Z0-9]{36}/i,
+  /gho_[a-zA-Z0-9]{36}/i,
+  /glpat-[a-zA-Z0-9\-_]{20}/i,
+  /AKIA[0-9A-Z]{16}/i,
+  /AIza[0-9A-Za-z_-]{35}/i,
+  /bearer\s+[a-zA-Z0-9_\-\.]{20,}/i,
+  /api[_-]?key\s*[:=]\s*["']?[a-zA-Z0-9_\-]{16,}/i,
+  /password\s*[:=]\s*["']?[^\s"']{6,}/i,
+];
+const AUDIT_LARGE_WARN = 100_000;
+const AUDIT_LARGE_CRIT = 1_000_000;
+const AUDIT_MAX_SCAN = 16_384;
+
+function isSensitiveName(filename) {
+  return AUDIT_SENSITIVE_PATTERNS.some((pattern) => pattern.test(filename));
+}
 
 function resolveDir(dir) { return path.resolve(dir || process.cwd()); }
 
@@ -155,6 +182,17 @@ class ContextPackServer {
             required: ["query"],
           },
         },
+        {
+          name: "pack_audit",
+          description: "Audit project for security risks, leaked secrets/credentials, missing .gitignore, uncommitted sensitive files, and overly large files.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              dir: { type: "string", description: "Project directory (defaults to CWD)" },
+              strict: { type: "boolean", description: "Flag missing .gitignore as critical instead of warn", default: false },
+            },
+          },
+        },
       ],
     }));
 
@@ -166,6 +204,7 @@ class ContextPackServer {
           case "pack_tree": return await this.tree(args || {});
           case "pack_outline": return await this.outline(args || {});
           case "pack_search": return await this.search(args || {});
+          case "pack_audit": return await this.audit(args || {});
           default: throw new Error(`Unknown tool: ${name}`);
         }
       } catch (e) {
@@ -246,6 +285,139 @@ class ContextPackServer {
     return { content: [{ type: "text", text: hits.length ? `Matches for "${query}" (${hits.length}):\n` + hits.map((h) => `  ${h}`).join("\n") : `No path matches for "${query}" in ${root}` }] };
   }
 
+  
+
+  async audit({ dir, strict = false }) {
+    const root = resolveDir(dir);
+    const findings = [];
+
+    function add(sev, msg, fix) {
+      findings.push({ severity: sev, message: msg, fix });
+    }
+
+    // walk
+    let all = [];
+    try { all = await walk(root, "", [], 0, 6); } catch { /* ignore */ }
+    const files = all.filter((f) => !f.dir);
+
+    // git presence and status
+    let gitRoot = null;
+    try {
+      const g = execSync("git rev-parse --show-toplevel", { cwd: root, encoding: "utf8", timeout: 3000 }).trim();
+      gitRoot = g;
+    } catch { /* not a git repo */ }
+
+    let gitStatus = [];
+    if (gitRoot) {
+      try {
+        const out = execSync("git status --porcelain", { cwd: root, encoding: "utf8", timeout: 5000 });
+        gitStatus = out.trim().split("\n").filter(Boolean).map((line) => {
+          const code = line.slice(0, 2);
+          const file = line.slice(3);
+          return { code, file, untracked: code === "??" };
+        });
+      } catch { /* ignore */ }
+    }
+
+    const statusMap = new Map(gitStatus.map((s) => [s.file, s]));
+
+    // Helpers
+    const isGitTracked = (rel) => {
+      const s = statusMap.get(rel);
+      if (!s) return true; // assume tracked if no status (could be clean tracked)
+      return !s.untracked;
+    };
+    const isIgnored = (rel) => {
+      try {
+        execSync(`git check-ignore -q -- "${rel}"`, { cwd: root, timeout: 2000 });
+        return true;
+      } catch { return false; }
+    };
+
+    // --- Missing critical files ---
+    const hasGitignore = files.some((f) => f.rel === ".gitignore" || path.basename(f.rel) === ".gitignore");
+    const hasEnvExample = files.some((f) => f.rel === ".env.example" || f.rel === ".env.sample" || f.rel === ".env.template");
+    if (gitRoot && !hasGitignore) add(strict ? "critical" : "warn", "No .gitignore found in a git repository.", "Add a .gitignore to prevent accidental commits of build artifacts, secrets, and OS files.");
+    if (!hasEnvExample) add("info", "No .env.example / .env.sample found.", "Add .env.example with dummy values so contributors know which env vars are required.");
+
+    // --- File-by-file scan ---
+    for (const f of files) {
+      const basename = path.basename(f.rel);
+      const abs = path.join(root, f.rel);
+      let stat;
+      try { stat = await fs.stat(abs); } catch { continue; }
+      const size = stat.size;
+      const sensitiveName = isSensitiveName(basename);
+
+      // large files
+      if (size > AUDIT_LARGE_CRIT) {
+        add("critical", `Large file: ${f.rel} (${(size/1e6).toFixed(1)} MB)`, "Consider adding to .gitignore, using Git LFS, or splitting.");
+      } else if (size > AUDIT_LARGE_WARN) {
+        add("warn", `Large file: ${f.rel} (${(size/1e3).toFixed(0)} KB)`, "Consider adding to .gitignore, using Git LFS, or splitting.");
+      }
+
+      // exposed sensitive files
+      if (sensitiveName) {
+        if (gitRoot) {
+          const tracked = isGitTracked(f.rel);
+          const ignored = isIgnored(f.rel);
+          if (tracked && !ignored) {
+            add("critical", `Sensitive file committed to git: ${f.rel}`, "Remove from git history (e.g. git-filter-repo), add to .gitignore, rotate any exposed secrets.");
+          } else if (!tracked) {
+            add("warn", `Sensitive file untracked: ${f.rel}`, "Ensure it is listed in .gitignore and never committed.");
+          } else if (ignored) {
+            add("info", `Sensitive file present but gitignored: ${f.rel}`, "OK — ensure secrets are rotated if previously committed.");
+          }
+        } else {
+          add("warn", `Sensitive file found (not a git repo): ${f.rel}`, "Review permissions and consider encrypting or moving to a secret manager.");
+        }
+      }
+
+      // secret content scan (small text-ish files only)
+      if (!f.dir && (CODE_EXT.has(path.extname(basename)) || [".json", ".yaml", ".yml", ".toml", ".ini", ".cfg", ".env", ".sh"].includes(path.extname(basename).toLowerCase()) || basename.startsWith(".env"))) {
+        if (size > 0 && size < AUDIT_MAX_SCAN * 4) {
+          let content = "";
+          try {
+            const fd = await fs.open(abs, "r");
+            const buf = Buffer.alloc(Math.min(size, AUDIT_MAX_SCAN));
+            await fd.read(buf, 0, buf.length, 0);
+            await fd.close();
+            content = buf.toString("utf8");
+          } catch { continue; }
+          for (const re of AUDIT_SECRET_CONTENT_RE) {
+            if (re.test(content)) {
+              add("critical", `Possible secret/hardcoded credential in ${f.rel}`, "Move to environment vars, secret manager, or encrypted vault. Rotate leaked value immediately.");
+              break;
+            }
+          }
+        }
+      }
+    }
+
+    // --- duplicate / inconsistent configs ---
+    const envFiles = files.filter((f) => path.basename(f.rel).startsWith(".env"));
+    if (envFiles.length > 2) {
+      add("info", `Multiple env files found (${envFiles.map((f) => f.rel).join(", ")})`, "Consolidate variants into .env, .env.local, .env.production. Ensure .gitignore covers all .env* except .env.example.");
+    }
+
+    // --- render ---
+    const icon = { critical: "🔴", warn: "🟡", info: "🟢" };
+    const groups = { critical: [], warn: [], info: [] };
+    for (const f of findings) groups[f.severity].push(f);
+    const lines = [`# Audit: ${path.basename(root)}`, `Path: ${root}`, `Git repo: ${gitRoot ? gitRoot : "no"}`, ``];
+    for (const sev of ["critical", "warn", "info"]) {
+      if (!groups[sev].length) continue;
+      lines.push(`## ${icon[sev]} ${sev.toUpperCase()} (${groups[sev].length})`);
+      for (const f of groups[sev]) {
+        lines.push(`- ${f.message}`);
+        if (f.fix) lines.push(`  → Fix: ${f.fix}`);
+      }
+      lines.push("");
+    }
+    if (!findings.length) lines.push("🟢 No issues detected.");
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  }
+
   async run() {
     const t = new StdioServerTransport();
     await this.server.connect(t);

package/devjournal/server.js

@@ -36,7 +36,7 @@ import { deterministicEnabled } from "./env.js";
 
 const ROOT =
   process.env.JOURNAL_DIR ||
-  path.join(os.homedir(), ".codex", "memories", "journal");
+  path.join(os.homedir(), ".ai-shared-memory", "journal");
 
 const MAX_TEXT = 20_000;
 
@@ -170,6 +170,28 @@ class DevJournalServer {
             properties: { dir: { type: "string", description: "Project directory (defaults to CWD)" } },
           },
         },
+        {
+          name: "journal_daily",
+          description: "Read or create today's daily note for the project (Obsidian-style YYYY-MM-DD.md under daily/). Append mode adds a line; read mode returns the note. Great for a vibecoder's daily log that survives compaction.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              dir: { type: "string", description: "Project directory (defaults to CWD)" },
+              date: { type: "string", description: "Optional YYYY-MM-DD (defaults to today)" },
+              append: { type: "string", description: "If provided, append this line to the daily note" },
+            },
+          },
+        },
+        {
+          name: "initialize_agent_session",
+          description: "Initialize the current agent session. Run this ONCE when the agent starts in a new project to perform a handshake and get contextual handoff.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              dir: { type: "string", description: "Project directory (defaults to CWD)" },
+            },
+          },
+        },
       ],
     }));
 
@@ -183,6 +205,8 @@ class DevJournalServer {
           case "journal_timeline": return await this.timeline(args || {});
           case "journal_search": return await this.search(args || {});
           case "journal_clear_handoff": return await this.clearHandoff(args || {});
+          case "journal_daily": return await this.daily(args || {});
+          case "initialize_agent_session": return await this.initializeAgent(args || {});
           default: throw new Error(`Unknown tool: ${name}`);
         }
       } catch (e) {
@@ -198,9 +222,34 @@ class DevJournalServer {
     const ts = (tsArg && /^\d{4}-\d{2}-\d{2}/.test(String(tsArg))) ? String(tsArg) : nowIso();
     const entry = { ts, type, title, body };
     await this.append(p, entry);
+    await this.appendDaily(p, ts.slice(0, 10), `- [${type}] ${title}${body ? ` — ${body.split("\n")[0].slice(0, 160)}` : ""}`);
     return { content: [{ type: "text", text: `Logged [${type}] "${title}" to ${p.slug}` }] };
   }
 
+  // Obsidian-style daily note: one file per date under daily/. Read or append.
+  async appendDaily(p, date, line) {
+    const dir = path.join(p.dir, "daily");
+    await fs.mkdir(dir, { recursive: true });
+    const file = path.join(dir, `${date}.md`);
+    const stamp = new Date().toISOString().slice(11, 19);
+    await fs.appendFile(file, `- ${stamp} ${line}\n`);
+  }
+
+  async daily({ dir, date, append } = {}) {
+    const p = this.paths(dir);
+    const day = (date && /^\d{4}-\d{2}-\d{2}$/.test(String(date))) ? String(date) : nowIso().slice(0, 10);
+    const dirPath = path.join(p.dir, "daily");
+    const file = path.join(dirPath, `${day}.md`);
+    if (append && String(append).trim()) {
+      await this.appendDaily(p, day, String(append).trim());
+      return { content: [{ type: "text", text: `Appended to daily note ${day}.md for ${p.slug}` }] };
+    }
+    let text;
+    try { text = await fs.readFile(file, "utf8"); }
+    catch { return { content: [{ type: "text", text: `No daily note for ${day} in ${p.slug} yet.` }] }; }
+    return { content: [{ type: "text", text: `# Daily — ${day}\n\n${text}` }] };
+  }
+
   async doHandoff({ summary, next_steps, open_questions, active_files, dir }) {
     summary = clip(summary, "summary", MAX_TEXT);
     const p = this.paths(dir);
@@ -301,6 +350,30 @@ class DevJournalServer {
     return { content: [{ type: "text", text: `Cleared handoff for ${p.slug}` }] };
   }
 
+  async initializeAgent({ dir }) {
+    const agentName = process.env.MCP_AGENT_NAME || 'Unknown-Agent';
+    const resumeData = await this.resume({ dir, recent: 5 });
+    
+    let rules = "";
+    try {
+      const p = this.paths(dir);
+      const rulePath = path.join(p.root, ".ai", "AGENTS.md");
+      const r = await fs.readFile(rulePath, "utf8");
+      rules = `\n\n## Project Rules (.ai/AGENTS.md)\n${r}`;
+    } catch { 
+      try {
+        const rootRule = path.join(this.paths(dir).root, "AGENTS.md");
+        const rr = await fs.readFile(rootRule, "utf8");
+        rules = `\n\n## Project Rules (AGENTS.md)\n${rr}`;
+      } catch {}
+    }
+
+    const greeting = `# Universal MCP Handshake\nAgent: ${agentName}\n\n`;
+    const content = greeting + resumeData.content[0].text + rules;
+    
+    return { content: [{ type: "text", text: content }] };
+  }
+
   async run() {
     const t = new StdioServerTransport();
     await this.server.connect(t);

package/docs/ROADMAP.md

@@ -0,0 +1,74 @@
+# 🚀 Rencana Kerja & Roadmap Masa Depan — codex-dev-mcp-suite
+
+> **Repository:** [verrysimatupang99/codex-dev-mcp-suite](https://github.com/verrysimatupang99/codex-dev-mcp-suite)  
+> **Versi Terbaru:** `v1.7.0` (Obsidian Vault Grade & Codebase Security Audit)  
+> **Lisensi:** MIT  
+
+---
+
+## 📌 Status Terkini (v1.7.0)
+
+Rilis `v1.7.0` baru saja digabung (*merged*) ke `master` & dipublikasikan dengan pencapaian:
+- ✅ **Obsidian Vault Parity**: Dukungan `.obsidian` setup otomatis, `memory_moc` (Map of Content), `memory_graph`, dan format Markdown standar Obsidian (`[[WikiLinks]]`).
+- ✅ **Codebase Security Audit (`pack_audit`)**: Tool otomatis untuk deteksi kebocoran file sensitif (`.env`, `.pem`, `id_rsa`), deteksi kunci API ter-hardcode, file besar, dan kelengkapan `.gitignore`.
+- ✅ **Stabilitas & Test**: **97 / 97 unit test (100% PASS)** di seluruh 4 server MCP + 3 utility CLI.
+
+---
+
+## 🎯 Roadmap Pengembangan Kedepan
+
+```mermaid
+graph TD
+    v17["v1.7.0 (Current)
+    Obsidian Vault & Security Audit"] --> v18["v1.8.0 (Q3 2026)
+    Local Offline Embeddings"]
+    v18 --> v19["v1.9.0 (Q4 2026)
+    Multi-Agent & Cross-Project"]
+    v19 --> v20["v2.0.0 (Q1 2027)
+    Obsidian Live Sync & Web Dashboard"]
+```
+
+---
+
+### 1. 🟢 v1.8.0 — Local Offline Semantic Search & ONNX Embedding
+> **Fokus:** Menjadikan `project-memory` 100% mandiri tanpa butuh API key eksternal untuk pencarian semantik.
+
+- [ ] **Engine Embedding Lokal (WASM/ONNX)**:
+  - Integrasi `@xenova/transformers` / ONNX Runtime Web dengan model ringan (`all-MiniLM-L6-v2` atau `bge-small-en-v1.5`).
+  - Pencarian semantik otomatis berfungsi saat laptop *offline* / tanpa jaringan internet.
+- [ ] **Fast Keyword-Semantic Hybrid Search**:
+  - Penggabungan BM25 / TF-IDF keyword search dengan cosine similarity vektor lokal.
+- [ ] **Smart Cache Vector Storage**:
+  - Menyimpan cache vektor di `.project-memory/vectors.json` tanpa membuat ketergantungan database eksternal.
+
+---
+
+### 2. 🔵 v1.9.0 — Multi-Agent Sync & Cross-Project Memory
+> **Fokus:** Koordinasi memori antar sub-agent AI dan pengelolaan memori lintas proyek.
+
+- [ ] **Multi-Agent Timeline Stream (`devjournal_stream`)**:
+  - Live event stream untuk melihat log & status pengerjaan subagent secara real-time.
+- [ ] **Cross-Project Memory Link (`memory_crosslink`)**:
+  - Menghubungkan dokumentasi/solusi bug dari proyek A ke proyek B (misal: solusi konfigurasi server/VPS bisa dipakai ulang di proyek aplikasi).
+- [ ] **Subagent Handoff Lock (`handoff_claim`)**:
+  - Mencegah dua subagent menimpa *handoff log* yang sama secara bersamaan.
+
+---
+
+### 3. 🟣 v2.0.0 — Native IDE GUI & Obsidian Live 2-Way Sync
+> **Fokus:** Pengalaman pengguna (*Developer Ergonomics*) tingkat lanjut & visualisasi grafik.
+
+- [ ] **Obsidian 2-Way Live Sync**:
+  - Sinkronisasi otomatis secara dua arah: editan di Obsidian Desktop langsung ter-update di `project-memory` AI, dan sebaliknya.
+- [ ] **Web Dashboard & GUI (`npx codex-dev-mcp-suite ui`)**:
+  - Dashboard web lokal berbasis Svelte/React ringan untuk melihat grafik proyek, statistik memori, checkpoint diff, dan timeline devjournal.
+- [ ] **Git Pre-commit Hook Integration**:
+  - Integrasi `pack_audit` langsung ke `.git/hooks/pre-commit` untuk mencegah developer sengaja/tidak sengaja memuat `.env` atau *secret key* ke repository.
+
+---
+
+### 🟡 Peningkatan Berkelanjutan (Ongoing Maintenance)
+- [ ] **Templates Kredensial & Preset MCP**:
+  - Konfigurasi siap pakai untuk Cursor, Claude Code, Windsurf, VS Code, dan Antigravity.
+- [ ] **CI/CD Auto-Publish**:
+  - GitHub Actions pipeline untuk auto-build & test saat ada `tag` baru.

package/docs/providers.md

@@ -0,0 +1,13 @@
+# Provider smoke matrix
+
+_Generated 2026-06-17T01:58:41.412Z_
+
+| Provider | Kind | Status | Latency | HTTP | Sample / dim | Error |
+|---|---|---|---|---|---|---|
+| groq | chat | ✓ | 430ms | 200 | `OK` |  |
+| cerebras | chat | ✓ | 554ms | 200 | — |  |
+| openai | chat | ✗ | 158ms | 401 | — | {"error":{"message":"unauthorized client detected, contact support for assistance at https://discord.com/invite/V6kaP6Rg44"},"message":"UNAUTHENTICATED","success":false,"type":"unauthorized_client_err |
+| openai | embed | ✗ | 147ms | 401 | — | {"error":{"message":"unauthorized client detected, contact support for assistance at https://discord.com/invite/V6kaP6Rg44"},"message":"UNAUTHENTICATED","success":false,"type":"unauthorized_client_err |
+| anthropic | chat | ✓ | 5.83s | 200 | — |  |
+| cloudflare | chat | ✗ | 907ms | 400 | — | {"errors":[{"message":"AiError: Bad input: Error: oneOf at '/' not met, 0 matches: required properties at '/' are 'text', required properties at '/' are 'requests' (f3f58c5f-7207-461a-96e1-d809e15ede3 |
+| cloudflare | embed | ✓ | 194ms | 200 | dim=768 |  |

package/docs/superpowers/plans/2026-06-15-hardening-v1-2-implementation.md

@@ -0,0 +1,60 @@
+# Hardening v1.2 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add CLI UX (help/version/doctor), secret redaction, provider validation, per-provider timeout + 429/5xx cooldown, and a packaged-tarball CI smoke test, without breaking existing behavior.
+
+**Architecture:** Add a shared bin meta-handler that intercepts `--help/--version/--doctor` before starting the stdio server. Add redaction + provider diagnostics + cooldown helpers in the provider layer. Wire rerank chat calls through cooldown-aware provider iteration. Extend CI with a tarball install smoke job.
+
+**Tech Stack:** Node.js ESM, existing MCP SDK servers, built-in `http`/`https`, offline test harness, GitHub Actions.
+
+---
+
+### Task 1: Bin CLI Meta (help/version/doctor)
+
+**Files:**
+- Create: `bin/_meta.mjs`
+- Modify: `bin/project-memory.mjs`, `bin/devjournal.mjs`, `bin/checkpoint.mjs`, `bin/context-pack.mjs`
+
+- [ ] Add `handleCliMeta({ bin, title, serverDir })` that handles `-h/--help`, `-v/--version`, `--doctor` then exits; returns false otherwise.
+- [ ] Read version from root `package.json`.
+- [ ] `--doctor` prints storage + model/provider config with API keys redacted (never raw values).
+- [ ] Each bin calls meta first, then imports its server only when not handled.
+
+### Task 2: Redaction + Provider Diagnostics + Cooldown
+
+**Files:**
+- Modify: `project-memory/provider-chain.js`, `devjournal/provider-chain.js`
+
+- [ ] Add `redactKey(value)` returning `set (<n> chars)` / `not set`, never the value.
+- [ ] Add `providerChainDiagnostics()` listing active providers (redacted) and incomplete-slot issues.
+- [ ] Add pure cooldown helpers `recordOutcome(key, ok, now)` and `isCoolingDown(key, now)` using `MCP_PROVIDER_COOLDOWN_MS` (default 60000).
+
+### Task 3: Cooldown-Aware Rerank
+
+**Files:**
+- Modify: `project-memory/rerank.js`, `devjournal/rerank.js`
+
+- [ ] Make provider chat return status so 429/5xx/network failures are retryable.
+- [ ] Skip providers currently cooling down; record outcomes.
+- [ ] Stop after first success; fall back to keyword if all fail. Never log keys/bodies.
+
+### Task 4: Tests
+
+**Files:**
+- Modify: `project-memory/test.mjs`, `devjournal/test.mjs`
+
+- [ ] Test `providerChainDiagnostics()` flags an incomplete slot and redacts keys.
+- [ ] Test cooldown helpers: failure starts cooldown, expiry clears it, success clears it.
+- [ ] Test bin `--version` prints package version and `--doctor` output excludes raw key value.
+
+### Task 5: CI Tarball Smoke + Verify
+
+**Files:**
+- Modify: `.github/workflows/ci.yml`
+- Modify: `CHANGELOG.md`, `package.json`, `docs/configuration.md`, `.env.example`
+
+- [ ] Add CI job: `npm pack`, install tarball in temp dir, run each bin `--version`.
+- [ ] Document `--doctor` and `MCP_PROVIDER_COOLDOWN_MS`.
+- [ ] Bump version to 1.2.0 and add changelog entry.
+- [ ] Run `npm test` and `npm pack --dry-run`; expect all pass.

package/docs/superpowers/plans/2026-06-15-provider-chain-v1-1-implementation.md

@@ -0,0 +1,65 @@
+# Provider Chain v1.1 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add optional numbered OpenAI-compatible provider fallback for rerank/chat calls while preserving deterministic no-network mode and legacy env compatibility.
+
+**Architecture:** Add focused provider-chain helpers to `project-memory` and `devjournal`, then route existing rerank chat calls through those helpers. Provider slots are built from `MCP_PROVIDER_PRIMARY_*`, `MCP_PROVIDER_CHAIN2_*`, `MCP_PROVIDER_CHAIN3_*`, etc.; if absent, existing `MCP_RERANK_*`/`MCP_LLM_*`/legacy config is used.
+
+**Tech Stack:** Node.js ESM, existing MCP SDK servers, built-in `http`/`https`, existing offline test harness.
+
+---
+
+### Task 1: Provider Chain Helpers
+
+**Files:**
+- Create: `project-memory/provider-chain.js`
+- Create: `devjournal/provider-chain.js`
+- Test: `project-memory/test.mjs`
+- Test: `devjournal/test.mjs`
+
+- [ ] Create a `providerEnv(slotPrefix)` helper that reads `NAME`, `BASE_URL`, `API_KEY`, and `MODEL` from a prefix such as `MCP_PROVIDER_PRIMARY`.
+- [ ] Create `providerChainConfig()` returning `{ providers, enabled, deterministic }`.
+- [ ] Include `MCP_PROVIDER_PRIMARY` first when complete.
+- [ ] Include every complete numbered slot matching `MCP_PROVIDER_CHAIN<N>` in numeric order for `N >= 2`.
+- [ ] Fall back to one legacy provider from existing rerank/LLM envs when no numbered slots exist.
+- [ ] Return disabled config if deterministic mode is on.
+- [ ] Add tests for primary-only, primary+chain2+chain3 ordering, arbitrary chain4, incomplete slot skip, deterministic disable, and legacy fallback.
+
+### Task 2: Rerank Uses Provider Chain
+
+**Files:**
+- Modify: `project-memory/rerank.js`
+- Modify: `devjournal/rerank.js`
+- Test: existing `npm test`
+
+- [ ] Replace single `BASE`/`KEY`/`MODEL` request selection with `providerChainConfig()`.
+- [ ] Try providers in order for each chat request.
+- [ ] Return first valid OpenAI-compatible response.
+- [ ] On non-200, timeout, network error, invalid JSON, or SSE parse failure, try the next provider.
+- [ ] Keep returning `null` if every provider fails so keyword fallback still works.
+- [ ] Never log API keys or response bodies.
+
+### Task 3: Docs and Examples
+
+**Files:**
+- Modify: `docs/configuration.md`
+- Modify: `docs/privacy.md`
+- Modify: `.env.example`
+- Modify: `CHANGELOG.md`
+- Modify: `README.md` if needed
+
+- [ ] Document numbered provider slots.
+- [ ] Document Groq/Cerebras/OpenRouter as recommended examples, not required providers.
+- [ ] Clarify users can use any OpenAI-compatible base URL, token, and model ID.
+- [ ] Clarify deterministic mode overrides provider chain.
+- [ ] Add changelog entry for v1.1 unreleased.
+
+### Task 4: Verification
+
+**Files:**
+- No source changes.
+
+- [ ] Run `npm test` and expect 33+ tests all pass.
+- [ ] Run `npm pack --dry-run` and confirm runtime provider-chain helpers are included.
+- [ ] Run secret scan on changed/staged files and confirm no real secrets.

package/docs/superpowers/plans/2026-06-15-provider-client-agnostic-config.md

@@ -0,0 +1,41 @@
+# Provider- and Client-Agnostic Config Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make the MCP suite configurable for any OpenAI-compatible gateway and document usage beyond Codex.
+
+**Architecture:** Keep backward compatibility with existing `NINEROUTER_*` env vars while introducing neutral `MCP_*` env names. Documentation separates generic install, provider config, and client-specific config examples.
+
+**Tech Stack:** Node.js MCP servers, OpenAI-compatible HTTP APIs for embeddings/rerank, Markdown docs.
+
+---
+
+### Task 1: Neutral Provider Env Aliases
+
+**Files:**
+- Modify: `project-memory/embedding.js`
+- Modify: `project-memory/rerank.js`
+- Modify: `devjournal/rerank.js`
+- Test: existing `npm test`
+
+- [ ] Add `MCP_EMBED_BASE_URL`, `MCP_EMBED_API_KEY`, `MCP_EMBED_MODEL` with fallback to existing `NINEROUTER_URL`, `NINEROUTER_KEY`, `EMBED_MODEL`.
+- [ ] Add `MCP_LLM_BASE_URL`, `MCP_LLM_API_KEY`, `MCP_RERANK_MODEL` with fallback to existing `NINEROUTER_URL`, `NINEROUTER_KEY`, `RERANK_MODEL`.
+- [ ] Keep default disabled behavior when no key/url/model is configured.
+- [ ] Run `npm test` and expect all tests pass.
+
+### Task 2: Client-Agnostic Docs
+
+**Files:**
+- Create: `docs/configuration.md`
+- Create: `docs/clients/codex.md`
+- Create: `docs/clients/claude-code.md`
+- Create: `docs/clients/generic-mcp.md`
+- Modify: `.env.example`
+- Modify: `README.md`
+
+- [ ] Document neutral env names and legacy aliases.
+- [ ] Provide Codex TOML config using npm bin commands.
+- [ ] Provide Claude Code MCP JSON config using npm bin commands.
+- [ ] Provide generic MCP JSON config.
+- [ ] Update README to call the suite “Dev MCP Suite” while preserving package name.
+- [ ] Run tests again after docs changes.