@pella-labs/pinakes 0.3.15 → 0.4.0

package/README.md

@@ -145,13 +145,14 @@ knowledge_query({
 All data is stored under `~/.pinakes/` (override with `PINAKES_ROOT`). Project data lives at `~/.pinakes/projects/<mangled-path>/`.
 
 ```bash
-npx @pella-labs/pinakes serve   [--wiki-path <dir>]   # Start the stdio MCP server
-npx @pella-labs/pinakes rebuild [--wiki-path <dir>]   # Full rebuild from markdown
-npx @pella-labs/pinakes status                        # Health check + row counts
-npx @pella-labs/pinakes audit   [--n 20]              # Tail the audit log
-npx @pella-labs/pinakes purge   --scope <s> --confirm # Delete a scope's DB
-npx @pella-labs/pinakes export  --scope <s> [--out f] # Dump nodes + edges as JSON
-npx @pella-labs/pinakes import  --scope <s> --in f    # Restore from dump
+npx @pella-labs/pinakes serve      [--wiki-path <dir>]   # Start the stdio MCP server
+npx @pella-labs/pinakes rebuild    [--wiki-path <dir>]   # Full rebuild from markdown
+npx @pella-labs/pinakes status                           # Health check + row counts
+npx @pella-labs/pinakes audit      [--n 20]              # Tail the audit log
+npx @pella-labs/pinakes audit-wiki                       # Wiki audit (contradictions, gaps)
+npx @pella-labs/pinakes purge      --scope <s> --confirm # Delete a scope's DB
+npx @pella-labs/pinakes export     --scope <s> [--out f] # Dump nodes + edges as JSON
+npx @pella-labs/pinakes import     --scope <s> --in f    # Restore from dump
 ```
 
 ## Embedder configuration
@@ -192,6 +193,14 @@ Changing the embedder requires a full rebuild (`pinakes rebuild`) since the vect
 - **Deterministic IDs**: `sha1(scope + ':' + source_uri + ':' + section_path)` means re-indexing is idempotent
 - **Centralized storage**: all data under `~/.pinakes/`, project paths mirrored as `~/.pinakes/projects/<mangled-path>/`
 
+## Wiki auditing
+
+Two paths for auditing your knowledge base:
+
+**Claude Code users** — run `/audit-wiki` for a deep agent-powered audit. This runs the pipeline first, then has Claude read through wiki files to find cross-file contradictions, broken references, terminology inconsistencies, and stale info that the pipeline can't catch.
+
+**All users** — run `npx @pella-labs/pinakes audit-wiki` (or `pnpm run pinakes -- audit-wiki` from source) for the deterministic pipeline audit. Produces `_audit-report.md` in the wiki directory with contradictions, documentation gaps, and health metrics. Requires an LLM provider (Ollama, API key, or `claude` CLI).
+
 ## Development
 
 ```bash

package/dist/cli/audit-wiki.d.ts

@@ -1,14 +1,58 @@
+import type { Database as BetterSqliteDatabase } from 'better-sqlite3';
+import { type GapRow } from '../gaps/detector.js';
+import { type LlmProvider } from '../llm/provider.js';
 import { type ContradictionResult } from './contradiction.js';
+import { createProgressReporter } from './progress.js';
 export interface WikiAuditOptions {
     projectRoot?: string;
     dbPath?: string;
     scope?: 'project' | 'personal';
+    quiet?: boolean;
+    generateStubs?: boolean;
 }
 export interface WikiAuditResult {
     contradictions: ContradictionResult;
     gaps_found: number;
-    stub_pages_created: string[];
+    topology_gaps: number;
+    stubs_generated: number;
     audit_report_path: string;
 }
 export declare function auditWikiCommand(opts: WikiAuditOptions): Promise<WikiAuditResult>;
+export declare function llmFilterGaps(gaps: GapRow[], llmProvider: LlmProvider, progress?: {
+    tick: (label: string, detail?: string) => void;
+}): Promise<GapRow[]>;
+export declare function parseLlmFilterResponse(response: string): string[];
+export interface TopologyGap {
+    topic: string;
+    in_degree: number;
+    source: 'graph-topology';
+}
+export declare function findTopologyGaps(reader: BetterSqliteDatabase, scope: string): TopologyGap[];
+export interface GapContext {
+    topic: string;
+    mentions: Array<{
+        source_uri: string;
+        excerpt: string;
+    }>;
+}
+export declare function gatherGapContexts(reader: BetterSqliteDatabase, scope: string, gaps: GapRow[]): GapContext[];
+export declare function generateSynthesisStubs(gaps: GapRow[], contexts: GapContext[], wikiRoot: string, llmProvider: LlmProvider, progress?: ReturnType<typeof createProgressReporter>): Promise<number>;
+export interface HealthMetrics {
+    file_count: number;
+    chunk_count: number;
+    node_count: number;
+    edge_count: number;
+}
+export declare function getHealthMetrics(reader: BetterSqliteDatabase, scope: string): HealthMetrics;
+/**
+ * Filter out noise from the gap detector (D42 Tier 1 tightening).
+ *
+ * Rejects topics that are:
+ * - Too short
+ * - URLs, file paths, qualified names
+ * - Code fragments (snake_case, camelCase, SCREAMING_SNAKE)
+ * - Common stopwords (English + technical)
+ * - Single-word generic terms that aren't proper nouns/acronyms
+ */
+export declare function isRealGap(topic: string): boolean;
 //# sourceMappingURL=audit-wiki.d.ts.map

package/dist/cli/audit-wiki.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit-wiki.d.ts","sourceRoot":"","sources":["../../src/cli/audit-wiki.ts"],"names":[],"mappings":"AAaA,OAAO,EAAqB,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAgBjF,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,mBAAmB,CAAC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CA8FvF"}
+{"version":3,"file":"audit-wiki.d.ts","sourceRoot":"","sources":["../../src/cli/audit-wiki.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,IAAI,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAGvE,OAAO,EAAa,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAQzE,OAAO,EAAqB,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAgBvD,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,mBAAmB,CAAC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAkGvF;AAkBD,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,WAAW,EAAE,WAAW,EACxB,QAAQ,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GAC5D,OAAO,CAAC,MAAM,EAAE,CAAC,CAgCnB;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAYjE;AAMD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,MAAM,GACZ,WAAW,EAAE,CA0Bf;AAMD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC1D;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EAAE,GACb,UAAU,EAAE,CA4Bd;AAeD,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,EAAE,EACd,QAAQ,EAAE,UAAU,EAAE,EACtB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,WAAW,EACxB,QAAQ,CAAC,EAAE,UAAU,CAAC,OAAO,sBAAsB,CAAC,GACnD,OAAO,CAAC,MAAM,CAAC,CAoDjB;AAmBD,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,MAAM,GACZ,aAAa,CAoBf;AA6GD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAgChD"}