nogrep 1.0.0

package/dist/write.js

@@ -0,0 +1,267 @@
+// scripts/write.ts
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { join, resolve, dirname } from "path";
+import { execFile } from "child_process";
+import { promisify } from "util";
+import yaml from "js-yaml";
+var execFileAsync = promisify(execFile);
+function extractManualNotes(content) {
+  const match = content.match(
+    /## Manual Notes\n([\s\S]*?)(?=\n## |\n---|\s*$)/
+  );
+  return match ? match[1].trim() : "";
+}
+function buildNodeFrontmatter(node) {
+  return {
+    id: node.id,
+    title: node.title,
+    category: node.category,
+    tags: {
+      domain: node.tags.domain,
+      layer: node.tags.layer,
+      tech: node.tags.tech,
+      concern: node.tags.concern,
+      type: node.tags.type
+    },
+    relates_to: node.relatesTo.map((r) => ({ id: r.id, reason: r.reason })),
+    inverse_relations: node.inverseRelations.map((r) => ({ id: r.id, reason: r.reason })),
+    src_paths: node.srcPaths,
+    keywords: node.keywords,
+    last_synced: {
+      commit: node.lastSynced.commit,
+      timestamp: node.lastSynced.timestamp,
+      src_hash: node.lastSynced.srcHash
+    }
+  };
+}
+function buildNodeMarkdown(node, manualNotes) {
+  const fm = buildNodeFrontmatter(node);
+  const yamlStr = yaml.dump(fm, { lineWidth: -1, quotingType: '"', forceQuotes: false });
+  const sections = [];
+  sections.push(`---
+${yamlStr.trimEnd()}
+---`);
+  sections.push(`
+## Purpose
+${node.purpose}`);
+  if (node.publicSurface.length > 0) {
+    sections.push(`
+## Public Surface
+
+\`\`\`
+${node.publicSurface.join("\n")}
+\`\`\``);
+  }
+  if (node.doesNotOwn.length > 0) {
+    sections.push(`
+## Does Not Own
+${node.doesNotOwn.map((d) => `- ${d}`).join("\n")}`);
+  }
+  if (node.gotchas.length > 0) {
+    sections.push(`
+## Gotchas
+${node.gotchas.map((g) => `- ${g}`).join("\n")}`);
+  }
+  const notesContent = manualNotes || "_Human annotations. Never overwritten by nogrep update._";
+  sections.push(`
+## Manual Notes
+${notesContent}`);
+  return sections.join("\n") + "\n";
+}
+function categoryDir(category) {
+  switch (category) {
+    case "domain":
+      return "domains";
+    case "architecture":
+      return "architecture";
+    case "flow":
+      return "flows";
+    case "entity":
+      return "entities";
+  }
+}
+async function writeContextNodes(nodes, outputDir) {
+  for (const node of nodes) {
+    const dir = join(outputDir, categoryDir(node.category));
+    await mkdir(dir, { recursive: true });
+    const filePath = join(dir, `${node.id}.md`);
+    let manualNotes = "";
+    try {
+      const existing = await readFile(filePath, "utf-8");
+      manualNotes = extractManualNotes(existing);
+    } catch {
+    }
+    const content = buildNodeMarkdown(node, manualNotes);
+    await writeFile(filePath, content, "utf-8");
+  }
+}
+function buildIndex(nodes, stack) {
+  const tags = {};
+  const keywords = {};
+  const paths = {};
+  const inverseMap = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    for (const rel of node.relatesTo) {
+      const existing = inverseMap.get(rel.id) ?? [];
+      existing.push({ fromId: node.id, reason: rel.reason });
+      inverseMap.set(rel.id, existing);
+    }
+  }
+  for (const node of nodes) {
+    const contextFile = `.nogrep/${categoryDir(node.category)}/${node.id}.md`;
+    const inverseEntries = inverseMap.get(node.id) ?? [];
+    for (const inv of inverseEntries) {
+      if (!node.inverseRelations.some((r) => r.id === inv.fromId)) {
+        node.inverseRelations.push({ id: inv.fromId, reason: inv.reason });
+      }
+    }
+    const tagCategories = [
+      ["domain", node.tags.domain],
+      ["layer", node.tags.layer],
+      ["tech", node.tags.tech],
+      ["concern", node.tags.concern],
+      ["type", node.tags.type]
+    ];
+    const flatTags = [];
+    for (const [cat, values] of tagCategories) {
+      for (const val of values) {
+        const tagKey = `${cat}:${val}`;
+        flatTags.push(tagKey);
+        const tagList = tags[tagKey] ?? [];
+        if (!tagList.includes(contextFile)) {
+          tagList.push(contextFile);
+        }
+        tags[tagKey] = tagList;
+      }
+    }
+    for (const kw of node.keywords) {
+      const kwList = keywords[kw] ?? [];
+      if (!kwList.includes(contextFile)) {
+        kwList.push(contextFile);
+      }
+      keywords[kw] = kwList;
+    }
+    for (const srcPath of node.srcPaths) {
+      paths[srcPath] = { context: contextFile, tags: flatTags };
+    }
+  }
+  let commit = "";
+  try {
+  } catch {
+  }
+  return {
+    version: "1.0",
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    commit,
+    stack: {
+      primaryLanguage: stack.primaryLanguage,
+      frameworks: stack.frameworks,
+      architecture: stack.architecture
+    },
+    tags,
+    keywords,
+    paths
+  };
+}
+function buildRegistry(nodes) {
+  const mappings = nodes.flatMap(
+    (node) => node.srcPaths.map((srcPath) => ({
+      glob: srcPath,
+      contextFile: `.nogrep/${categoryDir(node.category)}/${node.id}.md`,
+      watch: true
+    }))
+  );
+  return { mappings };
+}
+async function patchClaudeMd(projectRoot) {
+  const claudeMdPath = join(projectRoot, "CLAUDE.md");
+  const patchPath = join(dirname(import.meta.url.replace("file://", "")), "..", "templates", "claude-md-patch.md");
+  let patch;
+  try {
+    patch = await readFile(patchPath, "utf-8");
+  } catch {
+    patch = [
+      "<!-- nogrep -->",
+      "## Code Navigation",
+      "",
+      "This project uses [nogrep](https://github.com/techtulp/nogrep).",
+      "Context files in `.nogrep/` are a navigable index of this codebase.",
+      "When you see nogrep results injected into your context, trust them \u2014",
+      "read those files before exploring source.",
+      "<!-- /nogrep -->"
+    ].join("\n") + "\n";
+  }
+  let existing = "";
+  try {
+    existing = await readFile(claudeMdPath, "utf-8");
+  } catch {
+  }
+  if (existing.includes("<!-- nogrep -->")) {
+    return;
+  }
+  const newContent = existing ? existing.trimEnd() + "\n\n" + patch : patch;
+  await writeFile(claudeMdPath, newContent, "utf-8");
+}
+async function writeAll(input, projectRoot) {
+  const outputDir = join(projectRoot, ".nogrep");
+  await mkdir(outputDir, { recursive: true });
+  await writeContextNodes(input.nodes, outputDir);
+  const index = buildIndex(input.nodes, input.stack);
+  try {
+    const { stdout } = await execFileAsync("git", ["rev-parse", "--short", "HEAD"], {
+      cwd: projectRoot
+    });
+    index.commit = stdout.trim();
+  } catch {
+  }
+  await writeFile(
+    join(outputDir, "_index.json"),
+    JSON.stringify(index, null, 2) + "\n",
+    "utf-8"
+  );
+  const registry = buildRegistry(input.nodes);
+  await writeFile(
+    join(outputDir, "_registry.json"),
+    JSON.stringify(registry, null, 2) + "\n",
+    "utf-8"
+  );
+  await patchClaudeMd(projectRoot);
+}
+async function main() {
+  const args = process.argv.slice(2);
+  let inputFile;
+  let projectRoot = process.cwd();
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--input" && args[i + 1]) {
+      inputFile = args[i + 1];
+      i++;
+    } else if (args[i] === "--root" && args[i + 1]) {
+      projectRoot = resolve(args[i + 1]);
+      i++;
+    }
+  }
+  let rawInput;
+  if (inputFile) {
+    rawInput = await readFile(resolve(inputFile), "utf-8");
+  } else {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+    rawInput = Buffer.concat(chunks).toString("utf-8");
+  }
+  const input = JSON.parse(rawInput);
+  await writeAll(input, projectRoot);
+}
+main().catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  process.stderr.write(JSON.stringify({ error: message }) + "\n");
+  process.exitCode = 1;
+});
+export {
+  buildIndex,
+  buildRegistry,
+  patchClaudeMd,
+  writeContextNodes
+};
+//# sourceMappingURL=write.js.map

package/dist/write.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../scripts/write.ts"],"sourcesContent":["import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises'\nimport { join, resolve, dirname } from 'node:path'\nimport { execFile } from 'node:child_process'\nimport { promisify } from 'node:util'\nimport { createHash } from 'node:crypto'\nimport { glob } from 'glob'\nimport matter from 'gray-matter'\nimport yaml from 'js-yaml'\nimport type {\n  NodeResult,\n  StackResult,\n  IndexJson,\n  RegistryJson,\n  PathEntry,\n  NogrepError,\n} from './types.js'\n\nconst execFileAsync = promisify(execFile)\n\n// --- Manual Notes preservation ---\n\nfunction extractManualNotes(content: string): string {\n  const match = content.match(\n    /## Manual Notes\\n([\\s\\S]*?)(?=\\n## |\\n---|\\s*$)/,\n  )\n  return match ? match[1]!.trim() : ''\n}\n\n// --- Context node markdown generation ---\n\nfunction buildNodeFrontmatter(node: NodeResult): Record<string, unknown> {\n  return {\n    id: node.id,\n    title: node.title,\n    category: node.category,\n    tags: {\n      domain: node.tags.domain,\n      layer: node.tags.layer,\n      tech: node.tags.tech,\n      concern: node.tags.concern,\n      type: node.tags.type,\n    },\n    relates_to: node.relatesTo.map(r => ({ id: r.id, reason: r.reason })),\n    inverse_relations: node.inverseRelations.map(r => ({ id: r.id, reason: r.reason })),\n    src_paths: node.srcPaths,\n    keywords: node.keywords,\n    last_synced: {\n      commit: node.lastSynced.commit,\n      timestamp: node.lastSynced.timestamp,\n      src_hash: node.lastSynced.srcHash,\n    },\n  }\n}\n\nfunction buildNodeMarkdown(node: NodeResult, manualNotes: string): string {\n  const fm = buildNodeFrontmatter(node)\n  const yamlStr = yaml.dump(fm, { lineWidth: -1, quotingType: '\"', forceQuotes: false })\n\n  const sections: string[] = []\n  sections.push(`---\\n${yamlStr.trimEnd()}\\n---`)\n\n  sections.push(`\\n## Purpose\\n${node.purpose}`)\n\n  if (node.publicSurface.length > 0) {\n    sections.push(`\\n## Public Surface\\n\\n\\`\\`\\`\\n${node.publicSurface.join('\\n')}\\n\\`\\`\\``)\n  }\n\n  if (node.doesNotOwn.length > 0) {\n    sections.push(`\\n## Does Not Own\\n${node.doesNotOwn.map(d => `- ${d}`).join('\\n')}`)\n  }\n\n  if (node.gotchas.length > 0) {\n    sections.push(`\\n## Gotchas\\n${node.gotchas.map(g => `- ${g}`).join('\\n')}`)\n  }\n\n  const notesContent = manualNotes || '_Human annotations. Never overwritten by nogrep update._'\n  sections.push(`\\n## Manual Notes\\n${notesContent}`)\n\n  return sections.join('\\n') + '\\n'\n}\n\n// --- Write context files ---\n\nfunction categoryDir(category: NodeResult['category']): string {\n  switch (category) {\n    case 'domain': return 'domains'\n    case 'architecture': return 'architecture'\n    case 'flow': return 'flows'\n    case 'entity': return 'entities'\n  }\n}\n\nexport async function writeContextNodes(\n  nodes: NodeResult[],\n  outputDir: string,\n): Promise<void> {\n  for (const node of nodes) {\n    const dir = join(outputDir, categoryDir(node.category))\n    await mkdir(dir, { recursive: true })\n\n    const filePath = join(dir, `${node.id}.md`)\n\n    // Preserve existing manual notes\n    let manualNotes = ''\n    try {\n      const existing = await readFile(filePath, 'utf-8')\n      manualNotes = extractManualNotes(existing)\n    } catch {\n      // File doesn't exist yet\n    }\n\n    const content = buildNodeMarkdown(node, manualNotes)\n    await writeFile(filePath, content, 'utf-8')\n  }\n}\n\n// --- Build index ---\n\nexport function buildIndex(\n  nodes: NodeResult[],\n  stack: Pick<StackResult, 'primaryLanguage' | 'frameworks' | 'architecture'>,\n): IndexJson {\n  const tags: Record<string, string[]> = {}\n  const keywords: Record<string, string[]> = {}\n  const paths: Record<string, PathEntry> = {}\n\n  // Populate inverse relations\n  const inverseMap = new Map<string, Array<{ fromId: string; reason: string }>>()\n  for (const node of nodes) {\n    for (const rel of node.relatesTo) {\n      const existing = inverseMap.get(rel.id) ?? []\n      existing.push({ fromId: node.id, reason: rel.reason })\n      inverseMap.set(rel.id, existing)\n    }\n  }\n\n  for (const node of nodes) {\n    const contextFile = `.nogrep/${categoryDir(node.category)}/${node.id}.md`\n\n    // Merge inverse relations from the map\n    const inverseEntries = inverseMap.get(node.id) ?? []\n    for (const inv of inverseEntries) {\n      if (!node.inverseRelations.some(r => r.id === inv.fromId)) {\n        node.inverseRelations.push({ id: inv.fromId, reason: inv.reason })\n      }\n    }\n\n    // Build tag index\n    const tagCategories: Array<[string, string[]]> = [\n      ['domain', node.tags.domain],\n      ['layer', node.tags.layer],\n      ['tech', node.tags.tech],\n      ['concern', node.tags.concern],\n      ['type', node.tags.type],\n    ]\n\n    const flatTags: string[] = []\n    for (const [cat, values] of tagCategories) {\n      for (const val of values) {\n        const tagKey = `${cat}:${val}`\n        flatTags.push(tagKey)\n        const tagList = tags[tagKey] ?? []\n        if (!tagList.includes(contextFile)) {\n          tagList.push(contextFile)\n        }\n        tags[tagKey] = tagList\n      }\n    }\n\n    // Build keyword index\n    for (const kw of node.keywords) {\n      const kwList = keywords[kw] ?? []\n      if (!kwList.includes(contextFile)) {\n        kwList.push(contextFile)\n      }\n      keywords[kw] = kwList\n    }\n\n    // Build path index\n    for (const srcPath of node.srcPaths) {\n      paths[srcPath] = { context: contextFile, tags: flatTags }\n    }\n  }\n\n  let commit = ''\n  try {\n    // Sync exec not ideal but this is a one-time build step\n    // We'll set it from the caller if available\n  } catch {\n    // no git\n  }\n\n  return {\n    version: '1.0',\n    generatedAt: new Date().toISOString(),\n    commit,\n    stack: {\n      primaryLanguage: stack.primaryLanguage,\n      frameworks: stack.frameworks,\n      architecture: stack.architecture,\n    },\n    tags,\n    keywords,\n    paths,\n  }\n}\n\n// --- Build registry ---\n\nexport function buildRegistry(nodes: NodeResult[]): RegistryJson {\n  const mappings = nodes.flatMap(node =>\n    node.srcPaths.map(srcPath => ({\n      glob: srcPath,\n      contextFile: `.nogrep/${categoryDir(node.category)}/${node.id}.md`,\n      watch: true,\n    })),\n  )\n\n  return { mappings }\n}\n\n// --- Patch CLAUDE.md ---\n\nexport async function patchClaudeMd(projectRoot: string): Promise<void> {\n  const claudeMdPath = join(projectRoot, 'CLAUDE.md')\n  const patchPath = join(dirname(import.meta.url.replace('file://', '')), '..', 'templates', 'claude-md-patch.md')\n\n  let patch: string\n  try {\n    patch = await readFile(patchPath, 'utf-8')\n  } catch {\n    // Fallback: inline the patch content\n    patch = [\n      '<!-- nogrep -->',\n      '## Code Navigation',\n      '',\n      'This project uses [nogrep](https://github.com/techtulp/nogrep).',\n      'Context files in `.nogrep/` are a navigable index of this codebase.',\n      'When you see nogrep results injected into your context, trust them —',\n      'read those files before exploring source.',\n      '<!-- /nogrep -->',\n    ].join('\\n') + '\\n'\n  }\n\n  let existing = ''\n  try {\n    existing = await readFile(claudeMdPath, 'utf-8')\n  } catch {\n    // File doesn't exist\n  }\n\n  // Check for existing nogrep marker\n  if (existing.includes('<!-- nogrep -->')) {\n    return\n  }\n\n  const newContent = existing\n    ? existing.trimEnd() + '\\n\\n' + patch\n    : patch\n\n  await writeFile(claudeMdPath, newContent, 'utf-8')\n}\n\n// --- Write all outputs ---\n\ninterface WriteInput {\n  nodes: NodeResult[]\n  stack: Pick<StackResult, 'primaryLanguage' | 'frameworks' | 'architecture'>\n}\n\nasync function writeAll(input: WriteInput, projectRoot: string): Promise<void> {\n  const outputDir = join(projectRoot, '.nogrep')\n  await mkdir(outputDir, { recursive: true })\n\n  // Write context node files\n  await writeContextNodes(input.nodes, outputDir)\n\n  // Build and write index\n  const index = buildIndex(input.nodes, input.stack)\n\n  // Try to get current git commit\n  try {\n    const { stdout } = await execFileAsync('git', ['rev-parse', '--short', 'HEAD'], {\n      cwd: projectRoot,\n    })\n    index.commit = stdout.trim()\n  } catch {\n    // no git\n  }\n\n  await writeFile(\n    join(outputDir, '_index.json'),\n    JSON.stringify(index, null, 2) + '\\n',\n    'utf-8',\n  )\n\n  // Build and write registry\n  const registry = buildRegistry(input.nodes)\n  await writeFile(\n    join(outputDir, '_registry.json'),\n    JSON.stringify(registry, null, 2) + '\\n',\n    'utf-8',\n  )\n\n  // Patch CLAUDE.md\n  await patchClaudeMd(projectRoot)\n}\n\n// --- CLI interface ---\n\nasync function main(): Promise<void> {\n  const args = process.argv.slice(2)\n  let inputFile: string | undefined\n  let projectRoot = process.cwd()\n\n  for (let i = 0; i < args.length; i++) {\n    if (args[i] === '--input' && args[i + 1]) {\n      inputFile = args[i + 1]!\n      i++\n    } else if (args[i] === '--root' && args[i + 1]) {\n      projectRoot = resolve(args[i + 1]!)\n      i++\n    }\n  }\n\n  let rawInput: string\n  if (inputFile) {\n    rawInput = await readFile(resolve(inputFile), 'utf-8')\n  } else {\n    // Read from stdin\n    const chunks: Buffer[] = []\n    for await (const chunk of process.stdin) {\n      chunks.push(chunk as Buffer)\n    }\n    rawInput = Buffer.concat(chunks).toString('utf-8')\n  }\n\n  const input = JSON.parse(rawInput) as WriteInput\n  await writeAll(input, projectRoot)\n}\n\nmain().catch((err: unknown) => {\n  const message = err instanceof Error ? err.message : String(err)\n  process.stderr.write(JSON.stringify({ error: message }) + '\\n')\n  process.exitCode = 1\n})\n"],"mappings":"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","names":[]}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,239 @@
+# nogrep — Internal Architecture
+
+## Module Boundaries
+
+```
+┌──────────────────────────────────────────────────────┐
+│              CC Plugin (slash commands)                │
+│  /init · /update · /query · /status · /on · /off      │
+│  Claude orchestrates — AI work happens here            │
+└────────────────────────┬─────────────────────────────┘
+                         │ calls scripts via Bash
+         ┌───────────────┼───────────────┐
+         ▼               ▼               ▼
+┌─────────────┐  ┌─────────────┐  ┌──────────────┐
+│  Signals    │  │    Query    │  │   Settings   │
+│  (collect)  │  │  (lookup)   │  │  (r/w JSON)  │
+└─────────────┘  └──────┬──────┘  └──────────────┘
+                        │
+┌─────────────┐  ┌──────┴──────┐
+│   Writer    │  │  Validator  │
+│ (file I/O)  │  │ (freshness) │
+└─────────────┘  └─────────────┘
+```
+
+No AI client module — Claude IS the AI. The slash commands contain the analysis prompts, and Claude executes them directly during the session.
+
+---
+
+## Module Responsibilities
+
+### `commands/` (slash commands)
+Markdown prompts that guide Claude through each operation. `init.md` is the most complex — it orchestrates the full pipeline. Claude reads script output, performs analysis, and writes results.
+
+### `scripts/signals.ts`
+Collects language-agnostic signals from the filesystem. Pure data collection — no AI, no writes to `.nogrep/`.
+
+```typescript
+collectSignals(root, options) → SignalResult
+```
+
+### `scripts/write.ts`
+All file I/O for the `.nogrep/` directory. Takes structured JSON input (from Claude's analysis), writes files.
+
+```typescript
+writeContextFiles(nodes: NodeResult[], outputDir: string) → void
+buildIndex(nodes: NodeResult[]) → IndexJson
+buildRegistry(nodes: NodeResult[]) → RegistryJson
+patchClaudeMd(projectRoot: string) → void
+```
+
+### `scripts/query.ts`
+Pure lookup logic. Reads `_index.json`, matches tags/keywords, ranks results. No AI, no file writes. Called by hooks and `/nogrep:query`.
+
+```typescript
+extractTerms(question: string, taxonomy: Taxonomy) → { tags, keywords }
+resolve(terms, index) → RankedResult[]
+```
+
+### `scripts/validate.ts`
+Computes SHA256 of `src_paths` contents, compares to stored `src_hash` in node frontmatter.
+
+```typescript
+checkFreshness(node: ContextNode, projectRoot: string) → StaleResult
+```
+
+### `scripts/settings.ts`
+Read/write `.claude/settings.json` and `.claude/settings.local.json`. Handles merge logic (local takes precedence).
+
+---
+
+## Data Flow: `/nogrep:init`
+
+> `$PLUGIN` = `${CLAUDE_PLUGIN_ROOT}` — the absolute path to the installed plugin directory.
+
+```
+Slash command: init.md (Claude orchestrates)
+  │
+  ├─→ Bash: node $PLUGIN/dist/signals.js    → SignalResult (JSON stdout)
+  │
+  ├─→ Claude analyzes signals           → StackResult
+  │
+  ├─→ For each cluster:
+  │     Claude reads trimmed source      → NodeResult
+  │
+  ├─→ Claude detects flows              → FlowResult[]
+  │
+  └─→ Bash: node $PLUGIN/dist/write.js      (receives JSON stdin)
+        writes .nogrep/domains/*.md etc
+        writes .nogrep/_index.json
+        writes .nogrep/_registry.json
+        patches CLAUDE.md
+        writes .claude/settings.json
+```
+
+---
+
+## Data Flow: Hooks
+
+```
+User types prompt
+  │
+  └─→ prompt-submit.sh
+        node $PLUGIN/dist/query.js --question "$PROMPT"
+        → injects additionalContext
+
+CC decides to run grep
+  │
+  └─→ pre-tool-use.sh (PreToolUse hook)
+        extracts keywords from grep command
+        node $PLUGIN/dist/query.js --keywords "$KEYWORDS"
+        → injects additionalContext
+
+CC starts session
+  │
+  └─→ session-start.sh (SessionStart hook)
+        node $PLUGIN/dist/validate.js
+        → injects staleness warning if needed
+```
+
+---
+
+## Key Types (`scripts/types.ts`)
+
+```typescript
+export interface SignalResult {
+  directoryTree: DirectoryNode[]
+  extensionMap: Record<string, number>
+  manifests: ManifestFile[]
+  entryPoints: string[]
+  gitChurn: ChurnEntry[]
+  largeFiles: FileSize[]
+  envFiles: string[]
+  testFiles: string[]
+}
+
+export interface StackResult {
+  primaryLanguage: string
+  frameworks: string[]
+  architecture: 'monolith' | 'monorepo' | 'multi-repo' | 'microservice' | 'library'
+  domainClusters: DomainCluster[]
+  conventions: StackConventions
+  stackHints: string
+  dynamicTaxonomy: { domain: string[]; tech: string[] }
+}
+
+export interface DomainCluster {
+  name: string
+  path: string
+  confidence: number
+}
+
+export interface NodeResult {
+  id: string
+  title: string
+  category: 'domain' | 'architecture' | 'flow' | 'entity'
+  tags: TagSet
+  relatesTo: Relation[]
+  inverseRelations: Relation[]
+  srcPaths: string[]
+  keywords: string[]
+  lastSynced: SyncMeta
+  // content fields
+  purpose: string
+  publicSurface: string[]
+  doesNotOwn: string[]
+  externalDeps: ExternalDep[]
+  gotchas: string[]
+}
+
+export interface TagSet {
+  domain: string[]
+  layer: string[]
+  tech: string[]
+  concern: string[]
+  type: string[]
+}
+
+export interface IndexJson {
+  version: string
+  generatedAt: string
+  commit: string
+  stack: Pick<StackResult, 'primaryLanguage' | 'frameworks' | 'architecture'>
+  tags: Record<string, string[]>
+  keywords: Record<string, string[]>
+  paths: Record<string, PathEntry>
+}
+
+export interface RankedResult {
+  contextFile: string
+  score: number
+  matchedOn: string[]
+  summary: string
+}
+
+export interface StaleResult {
+  file: string
+  isStale: boolean
+  reason?: string
+}
+```
+
+---
+
+## Error Handling Strategy
+
+- Scripts: throw typed errors (`NogrepError` with `code` field), exit 1 with JSON error on stderr
+- Hooks: fail silently (exit 0) — never block CC session
+- Never swallow errors silently in scripts
+
+```typescript
+export class NogrepError extends Error {
+  constructor(
+    message: string,
+    public code: 'NO_INDEX' | 'NO_GIT' | 'IO_ERROR' | 'STALE'
+  ) {
+    super(message)
+  }
+}
+```
+
+---
+
+## Testing Strategy
+
+### Unit tests (no filesystem)
+- `query/extractor.test.ts` — NL extraction logic
+- `query/resolver.test.ts` — index lookup ranking
+- `validator/staleness.test.ts` — hash comparison logic
+- `settings/index.test.ts` — merge logic
+
+### Integration tests (real filesystem)
+- `signals.test.ts` — run against fixture projects
+- `writer/*.test.ts` — write to temp dir, verify file contents
+
+### Fixture projects (`tests/fixtures/`)
+Minimal 5-10 file projects, enough for signal detection:
+- `nestjs-project/` — NestJS with billing + auth modules
+- `django-project/` — Django with users + payments apps
+- `react-project/` — React app with auth + dashboard features