@pella-labs/pinakes 0.4.4 → 0.5.1

package/dist/paths.d.ts

@@ -66,6 +66,15 @@ export interface CliPathOverrides {
  * already exists.
  */
 export declare function ensurePinakesGitignore(projectRoot: string): void;
+/**
+ * Ensure Pinakes knowledge base instructions are present in both
+ * `CLAUDE.md` and `AGENTS.md`. Covers all major coding agents:
+ * Claude Code, Codex, OpenCode, Cursor, Goose, etc.
+ *
+ * Idempotent — skips files that already contain the marker comment.
+ * Creates the file if it doesn't exist; appends if it does.
+ */
+export declare function ensureAgentInstructions(projectRoot: string): void;
 /**
  * Resolve the DB path for a given scope, honoring CLI overrides.
  * Shared by all CLI subcommands (status, audit, export, import, purge, etc.)

package/dist/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAUH,yDAAyD;AACzD,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE9D;AAMD;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAIpC;AAMD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE/D;AAMD,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAMD,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAeD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAMhE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,SAAS,GAAG,UAAU,GAC5B,MAAM,CAOR"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAUH,yDAAyD;AACzD,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE9D;AAMD;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAIpC;AAMD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE/D;AAMD,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAMD,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAeD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAMhE;AAeD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAIjE;AAgBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,SAAS,GAAG,UAAU,GAC5B,MAAM,CAOR"}

package/dist/paths.js

@@ -22,7 +22,7 @@
  *         audit.jsonl                             # project audit
  *         manifest.json                           # project manifest
  */
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { isAbsolute, resolve } from 'node:path';
 // ---------------------------------------------------------------------------
@@ -124,6 +124,43 @@ export function ensurePinakesGitignore(projectRoot) {
     mkdirSync(pinakesDir, { recursive: true });
     writeFileSync(gitignorePath, PINAKES_GITIGNORE_CONTENT, 'utf-8');
 }
+// ---------------------------------------------------------------------------
+// Agent instruction file (CLAUDE.md / AGENTS.md)
+// ---------------------------------------------------------------------------
+const PINAKES_AGENT_MARKER = '<!-- pinakes-instructions -->';
+const PINAKES_AGENT_BLOCK = `
+${PINAKES_AGENT_MARKER}
+## Pinakes Knowledge Base
+
+This project has a curated knowledge base managed by Pinakes. **Always use the \`knowledge_search\` MCP tool as your first action** when you need to understand anything about this project — architecture, conventions, decisions, requirements, data models, deployment, testing strategy, or how subsystems relate. The knowledge base is faster and more token-efficient than reading raw source files. Only fall back to Grep/Read/Glob after checking the knowledge base, or when you need exact symbols or to make code changes.
+`;
+/**
+ * Ensure Pinakes knowledge base instructions are present in both
+ * `CLAUDE.md` and `AGENTS.md`. Covers all major coding agents:
+ * Claude Code, Codex, OpenCode, Cursor, Goose, etc.
+ *
+ * Idempotent — skips files that already contain the marker comment.
+ * Creates the file if it doesn't exist; appends if it does.
+ */
+export function ensureAgentInstructions(projectRoot) {
+    const root = resolveAbs(projectRoot);
+    ensureInstructionsInFile(resolve(root, 'CLAUDE.md'));
+    ensureInstructionsInFile(resolve(root, 'AGENTS.md'));
+}
+function ensureInstructionsInFile(filePath) {
+    if (existsSync(filePath)) {
+        appendIfMissing(filePath);
+    }
+    else {
+        writeFileSync(filePath, PINAKES_AGENT_BLOCK.trimStart(), 'utf-8');
+    }
+}
+function appendIfMissing(filePath) {
+    const content = readFileSync(filePath, 'utf-8');
+    if (content.includes(PINAKES_AGENT_MARKER))
+        return;
+    writeFileSync(filePath, content.trimEnd() + '\n' + PINAKES_AGENT_BLOCK, 'utf-8');
+}
 /**
  * Resolve the DB path for a given scope, honoring CLI overrides.
  * Shared by all CLI subcommands (status, audit, export, import, purge, etc.)

package/dist/paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pella-labs/pinakes",
-  "version": "0.4.4",
+  "version": "0.5.1",
   "description": "Local stdio MCP server that indexes a Karpathy-style two-level knowledge wiki into SQLite and exposes it to a coding LLM via Cloudflare-style code-mode.",
   "type": "module",
   "bin": {