@jaimevalasek/aioson 1.8.0 → 1.9.1

package/template/.aioson/brains/README.md

@@ -1,128 +1,132 @@
-# AIOSON Brains — Procedural Memory System
-
-> Inspired by: A-MEM (Zettelkasten networks), MemRL (quality-scored pattern extraction), Letta (OS-tiered loading), and retrieval-as-tool (agents call memory explicitly, not pre-injected).
-
-## What is this?
-
-Brains are **quality-scored pattern memory** — not event logs, not session history.  
-Each brain node answers: *"I've seen this before. Here's what works, what to avoid, and why."*
-
-Unlike RAG (retrieve-and-prepend), agents load only what's relevant, when it's relevant.
-
-## Loading strategy (tiered — OS-inspired)
-
-| Layer | File | When loaded | Token cost |
-|-------|------|-------------|------------|
-| Index | `_index.json` | Always, on activation | ~2KB |
-| Brain file | `agent/domain.brain.json` | Only when tags match the task | ~8–20KB |
-| Node detail | inside brain file | Read selectively by ID | negligible |
-
-**Rule:** Load `_index.json` first. If task tags match a brain's tag list, load that brain file. Use `query.js` for cross-referencing across multiple brains.
-
-## Brain node schema
-
-```json
-{
-  "id": "css-001",
-  "title": "Short name",
-  "tags": ["css", "hover", "animation"],
-  "q": 5,
-  "v": "EXCELLENT",
-  "s": "One-line summary of the pattern and why it works.",
-  "p": "code snippet or pseudocode",
-  "src": "source site or context",
-  "date": "YYYY-MM-DD",
-  "not": "what NOT to use instead — the anti-pattern this replaces",
-  "warn": "gotcha or edge case to watch out for",
-  "see": ["css-002", "css-007"]
-}
-```
-
-### Verdict values
-
-| Verdict | Meaning |
-|---------|---------|
-| `EXCELLENT` | Best-in-class — use by default |
-| `GOOD` | Solid choice — use when EXCELLENT variant isn't applicable |
-| `BEST_PRACTICE` | Mandatory baseline — always include |
-| `AVOID` | Anti-pattern — explicitly do NOT use this |
-| `BROKEN` | Known broken in current context |
-
-### Quality score (q)
-
-| Score | Meaning |
-|-------|---------|
-| 5 | Verified excellent — used in production, great result |
-| 4 | Verified good — used, worked well |
-| 3 | Theoretical — not yet validated in a real project |
-| 2 | Mixed results — use with caution |
-| 1 | Avoid — kept only for anti-pattern documentation |
-
-## Agent integration
-
-In your agent file, add a **Brain** section:
-
-```markdown
-## Brain (procedural memory)
-
-1. Load `.aioson/brains/_index.json` on activation.
-2. Identify relevant tags from the current task.
-3. Load matching brain files (from index `path` field).
-4. For patterns with q ≥ 4: apply as default approach.
-5. For nodes with v === "AVOID": never implement what's in `not` field.
-6. Use `see[]` to traverse linked nodes.
-
-Cross-reference query:
-  node .aioson/brains/scripts/query.js --tags <tags> --min-quality 4 --format compact
-
-After completing a project, record new learnings:
-  - Add nodes to the appropriate brain file
-  - Rate quality honestly (1-5)
-  - Update `_index.json` nodes count and updated date
-  - Add `see[]` links to related nodes (Zettelkasten web)
-```
-
-## Query script
-
-```bash
-# All EXCELLENT patterns about CSS animation
-node .aioson/brains/scripts/query.js --tags css,animation --verdict EXCELLENT --format compact
-
-# All anti-patterns (to know what NOT to do)
-node .aioson/brains/scripts/query.js --avoid --format compact
-
-# Best practices for site-forge cloning
-node .aioson/brains/scripts/query.js --agent site-forge --min-quality 4 --format compact
-
-# Get specific nodes by ID
-node .aioson/brains/scripts/query.js --id css-001,css-007,js-001
-
-# All patterns that match ALL these tags (AND)
-node .aioson/brains/scripts/query.js --tags css,hover,no-js --match all
-```
-
-## File structure
-
-```
-.aioson/brains/
-├── README.md                         # This file
-├── _index.json                       # Master index (always loaded, ~2KB)
-├── scripts/
-│   └── query.js                      # Cross-reference query script
-└── site-forge/
-    └── visual-patterns.brain.json    # CSS/animation/interaction patterns (14 nodes)
-```
-
-## Adding a new brain
-
-1. Create `agentname/domain.brain.json` following the node schema above
-2. Add an entry to `_index.json` with relevant tags, agent name, and path
-3. Annotate agents that should load it with the relevant tags in their Brain section
-
-## Design philosophy
-
-- **Procedural, not episodic** — "what works" not "what happened"
-- **Explicit anti-patterns** — `not` and `v:AVOID` nodes prevent regressions
-- **Zettelkasten web** — `see[]` links create traversable knowledge graphs
-- **Token-efficient** — index is tiny; brain files are loaded only when needed
-- **Agent-directed** — agents decide what to load, not an auto-injection system
+# AIOSON Brains — Procedural Memory System
+
+> Inspired by: A-MEM (Zettelkasten networks), MemRL (quality-scored pattern extraction), Letta (OS-tiered loading), and retrieval-as-tool (agents call memory explicitly, not pre-injected).
+
+## What is this?
+
+Brains are **quality-scored pattern memory** — not event logs, not session history.  
+Each brain node answers: *"I've seen this before. Here's what works, what to avoid, and why."*
+
+Unlike RAG (retrieve-and-prepend), agents load only what's relevant, when it's relevant.
+
+## Loading strategy (tiered — OS-inspired)
+
+| Layer | File | When loaded | Token cost |
+|-------|------|-------------|------------|
+| Index | `_index.json` | Always, on activation | ~2KB |
+| Brain file | `agent/domain.brain.json` | Only when tags match the task | ~8–20KB |
+| Node detail | inside brain file | Read selectively by ID | negligible |
+
+**Rule:** Load `_index.json` first. If task tags match a brain's tag list, load that brain file. Use `query.js` for cross-referencing across multiple brains.
+
+## Brain node schema
+
+```json
+{
+  "id": "css-001",
+  "title": "Short name",
+  "tags": ["css", "hover", "animation"],
+  "q": 5,
+  "v": "EXCELLENT",
+  "s": "One-line summary of the pattern and why it works.",
+  "p": "code snippet or pseudocode",
+  "src": "source site or context",
+  "date": "YYYY-MM-DD",
+  "not": "what NOT to use instead — the anti-pattern this replaces",
+  "warn": "gotcha or edge case to watch out for",
+  "see": ["css-002", "css-007"]
+}
+```
+
+### Verdict values
+
+| Verdict | Meaning |
+|---------|---------|
+| `EXCELLENT` | Best-in-class — use by default |
+| `GOOD` | Solid choice — use when EXCELLENT variant isn't applicable |
+| `BEST_PRACTICE` | Mandatory baseline — always include |
+| `AVOID` | Anti-pattern — explicitly do NOT use this |
+| `BROKEN` | Known broken in current context |
+
+### Quality score (q)
+
+| Score | Meaning |
+|-------|---------|
+| 5 | Verified excellent — used in production, great result |
+| 4 | Verified good — used, worked well |
+| 3 | Theoretical — not yet validated in a real project |
+| 2 | Mixed results — use with caution |
+| 1 | Avoid — kept only for anti-pattern documentation |
+
+## Agent integration
+
+In your agent file, add a **Brain** section:
+
+```markdown
+## Brain (procedural memory)
+
+1. Load `.aioson/brains/_index.json` on activation.
+2. Identify relevant tags from the current task.
+3. Load matching brain files (from index `path` field).
+4. For patterns with q ≥ 4: apply as default approach.
+5. For nodes with v === "AVOID": never implement what's in `not` field.
+6. Use `see[]` to traverse linked nodes.
+
+Cross-reference query:
+  node .aioson/brains/scripts/query.js --tags <tags> --min-quality 4 --format compact
+
+After completing a project, record new learnings:
+  - Add nodes to the appropriate brain file
+  - Rate quality honestly (1-5)
+  - Update `_index.json` nodes count and updated date
+  - Add `see[]` links to related nodes (Zettelkasten web)
+```
+
+## Query script
+
+```bash
+# All EXCELLENT patterns about CSS animation
+node .aioson/brains/scripts/query.js --tags css,animation --verdict EXCELLENT --format compact
+
+# All anti-patterns (to know what NOT to do)
+node .aioson/brains/scripts/query.js --avoid --format compact
+
+# Best practices for site-forge cloning
+node .aioson/brains/scripts/query.js --agent site-forge --min-quality 4 --format compact
+
+# Get specific nodes by ID
+node .aioson/brains/scripts/query.js --id css-001,css-007,js-001
+
+# All patterns that match ALL these tags (AND)
+node .aioson/brains/scripts/query.js --tags css,hover,no-js --match all
+```
+
+## File structure
+
+```
+.aioson/brains/
+├── README.md                              # This file
+├── _index.json                            # Master index (always loaded, ~2KB)
+├── scripts/
+│   └── query.js                           # Cross-reference query script
+├── dev/
+│   └── patterns.brain.json                # Implementation patterns for @dev (5 nodes)
+├── sheldon/
+│   └── architecture-decisions.brain.json  # Architecture decisions for @sheldon (5 nodes)
+└── site-forge/
+    └── visual-patterns.brain.json         # CSS/animation/interaction patterns (14 nodes)
+```
+
+## Adding a new brain
+
+1. Create `agentname/domain.brain.json` following the node schema above
+2. Add an entry to `_index.json` with relevant tags, agent name, and path
+3. Annotate agents that should load it with the relevant tags in their Brain section
+
+## Design philosophy
+
+- **Procedural, not episodic** — "what works" not "what happened"
+- **Explicit anti-patterns** — `not` and `v:AVOID` nodes prevent regressions
+- **Zettelkasten web** — `see[]` links create traversable knowledge graphs
+- **Token-efficient** — index is tiny; brain files are loaded only when needed
+- **Agent-directed** — agents decide what to load, not an auto-injection system

package/template/.aioson/brains/_index.json

@@ -1,16 +1,34 @@
-{
-  "v": 1,
-  "description": "AIOSON Brain Index — agent procedural memory (quality-scored patterns). Load this first, then load specific brain files only when relevant tags match.",
-  "loading_strategy": "tiered — this index is always loaded (~2KB); brain files loaded on-demand by tag match",
-  "brains": [
-    {
-      "id": "site-forge/visual-patterns",
-      "agents": ["site-forge"],
-      "tags": ["css", "animation", "cloning", "visual-effects", "hover", "scroll", "video", "font", "keyframes", "interaction"],
-      "desc": "CSS/animation/interaction patterns learned from real site cloning — quality-scored, anti-pattern aware",
-      "path": ".aioson/brains/site-forge/visual-patterns.brain.json",
-      "nodes": 14,
-      "updated": "2026-04-01"
-    }
-  ]
-}
+{
+  "v": 1,
+  "description": "AIOSON Brain Index — agent procedural memory (quality-scored patterns). Load this first, then load specific brain files only when relevant tags match.",
+  "loading_strategy": "tiered — this index is always loaded (~2KB); brain files loaded on-demand by tag match",
+  "brains": [
+    {
+      "id": "site-forge/visual-patterns",
+      "agents": ["site-forge"],
+      "tags": ["css", "animation", "cloning", "visual-effects", "hover", "scroll", "video", "font", "keyframes", "interaction"],
+      "desc": "CSS/animation/interaction patterns learned from real site cloning — quality-scored, anti-pattern aware",
+      "path": ".aioson/brains/site-forge/visual-patterns.brain.json",
+      "nodes": 14,
+      "updated": "2026-04-01"
+    },
+    {
+      "id": "dev/patterns",
+      "agents": ["dev", "deyvin", "pair"],
+      "tags": ["security", "shell", "injection", "git", "commit", "context", "bootstrap", "cache", "editing", "tooling", "process", "verification", "discipline", "node", "child-process"],
+      "desc": "Implementation patterns @dev defaults to — security, shell discipline, git mechanics, editing hygiene, validated-slice loop",
+      "path": ".aioson/brains/dev/patterns.brain.json",
+      "nodes": 5,
+      "updated": "2026-05-07"
+    },
+    {
+      "id": "sheldon/architecture-decisions",
+      "agents": ["sheldon", "architect"],
+      "tags": ["aioson", "template", "agents", "sync", "sdd", "classification", "process", "validator", "sandbox", "impartiality", "discovery", "architecture", "ordering", "cli", "integration", "telemetry"],
+      "desc": "Architecture and process decisions @sheldon defaults to — workspace/template parity, classification gates, validator sandbox, discovery-before-architecture, CLI-first integration",
+      "path": ".aioson/brains/sheldon/architecture-decisions.brain.json",
+      "nodes": 5,
+      "updated": "2026-05-07"
+    }
+  ]
+}

package/template/.aioson/brains/dev/patterns.brain.json

@@ -0,0 +1,79 @@
+{
+  "v": 1,
+  "agent": "dev",
+  "domain": "patterns",
+  "desc": "Implementation patterns @dev should default to. Quality-scored, anti-pattern aware. Seed nodes — extend with new q≥4 patterns after each significant slice.",
+  "updated": "2026-05-07",
+  "nodes": [
+    {
+      "id": "dev-001",
+      "title": "spawn with array args over execSync template literals",
+      "tags": ["security", "shell", "injection", "node", "child-process"],
+      "q": 5,
+      "v": "BEST_PRACTICE",
+      "s": "When invoking external commands from Node, use spawn/execFile with an argv array. Never interpolate user-controlled values into a template-literal command string passed to execSync — that is shell-injection by construction.",
+      "p": "// good\nconst { spawnSync } = require('node:child_process');\nspawnSync('git', ['log', '--oneline', '-n', String(n)], { encoding: 'utf8' });\n// bad\nexecSync(`git log --oneline -n ${n}`);",
+      "src": "AIOSON commit 171dbf0 (fix tool-invocation)",
+      "date": "2026-05-07",
+      "not": "execSync(`cmd ${userInput}`) — interpolation goes through /bin/sh and any whitespace/metachar in userInput becomes a new command",
+      "warn": "applies even when input feels trusted — slugs, file paths, agent names can all contain shell metachars in tests/fixtures",
+      "see": ["dev-002"]
+    },
+    {
+      "id": "dev-002",
+      "title": "git commit -m via HEREDOC for multi-line bodies",
+      "tags": ["git", "commit", "shell", "formatting"],
+      "q": 5,
+      "v": "BEST_PRACTICE",
+      "s": "Multi-line commit messages must come from a HEREDOC with single-quoted EOF — anything else mangles backticks, $-escapes, and indentation.",
+      "p": "git commit -m \"$(cat <<'EOF'\nfix(scope): subject\n\nBody paragraph.\nEOF\n)\"",
+      "src": "CLAUDE.md commit protocol",
+      "date": "2026-05-07",
+      "not": "git commit -m \"line1\\nline2\" — \\n is literal; $vars expand; backticks execute",
+      "warn": "the EOF marker must be single-quoted ('EOF') to prevent shell expansion inside the body",
+      "see": ["dev-001"]
+    },
+    {
+      "id": "dev-003",
+      "title": "append-only updates to context cache files",
+      "tags": ["context", "bootstrap", "cache", "idempotency"],
+      "q": 4,
+      "v": "BEST_PRACTICE",
+      "s": "Files that act as system state caches (bootstrap/current-state.md, project-pulse.md, features.md) are append-only. Never replace existing entries — add a new line/row. Other agents trust historical entries to remain stable.",
+      "p": "// good — Edit appending one bullet under existing section\n// bad — Write replacing the whole file",
+      "src": "AIOSON audit Lote B (commits ff14ccf, 5aa1c0c)",
+      "date": "2026-05-07",
+      "not": "regenerating the cache from scratch on every update — destroys the audit trail downstream agents read",
+      "warn": "if an entry is wrong, mark it superseded with a follow-up entry — do not edit the original line",
+      "see": ["dev-005"]
+    },
+    {
+      "id": "dev-004",
+      "title": "Read before Edit — surgical edits over rewrites",
+      "tags": ["editing", "tooling", "discipline"],
+      "q": 5,
+      "v": "BEST_PRACTICE",
+      "s": "Always read the target file before editing. Prefer Edit (single old_string→new_string) over Write (full rewrite). Anchors must be unique enough to match exactly — surrounding context is your friend.",
+      "p": "// good — Edit with a 2-3 line unique anchor\n// bad — Write the whole file just to change one line",
+      "src": "Claude Code Edit tool contract; AIOSON dev.md execution invariants",
+      "date": "2026-05-07",
+      "not": "Write to overwrite an existing file when only one section needs to change — loses concurrent edits and bypasses staleness checks",
+      "warn": "if old_string isn't unique, EITHER widen the anchor OR use replace_all — never guess",
+      "see": ["dev-003"]
+    },
+    {
+      "id": "dev-005",
+      "title": "small validated slices over big-bang implementation",
+      "tags": ["process", "verification", "tdd-lite", "discipline"],
+      "q": 4,
+      "v": "GOOD",
+      "s": "Implement one slice → run the actual verification command (tsc, cargo check, npm test) → only then move to the next slice. Batched debugging at the end is the slowest path.",
+      "p": "loop: { write code → run verification → fix → commit-ready }",
+      "src": "dev.md Execution invariants; Motor AIOSON hardening rules",
+      "date": "2026-05-07",
+      "not": "write 10 files then run tsc — error cascades make root cause hard to find",
+      "warn": "verification command must be the real one (the one CI runs), not a proxy you trust",
+      "see": ["dev-003"]
+    }
+  ]
+}

package/template/.aioson/brains/scripts/query.js

@@ -1,107 +1,107 @@
-#!/usr/bin/env node
-/**
- * AIOSON Brain Query
- * Cross-references pattern nodes across brain files by tags, quality, verdict, and agent.
- *
- * Usage:
- *   node query.js --tags css,hover                    # nodes matching any of these tags
- *   node query.js --tags css,hover --match all        # nodes matching ALL tags (AND)
- *   node query.js --min-quality 4                     # quality >= 4 only
- *   node query.js --agent site-forge                  # brain files for this agent
- *   node query.js --verdict EXCELLENT,BEST_PRACTICE   # filter by verdict
- *   node query.js --avoid                             # show only AVOID nodes (anti-patterns)
- *   node query.js --id css-001,css-002                # fetch specific node IDs
- *   node query.js --tags animation --format compact   # one-line per node output
- *
- * Output: JSON array of matching nodes (default) or compact table (--format compact)
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const BRAINS_DIR = path.resolve(__dirname, '..');
-const INDEX_PATH = path.join(BRAINS_DIR, '_index.json');
-
-// --- Parse args ---
-const args = process.argv.slice(2);
-const get = (flag) => { const i = args.indexOf(flag); return i !== -1 ? args[i + 1] : null; };
-const has = (flag) => args.includes(flag);
-
-const tagsRaw   = get('--tags');
-const tags      = tagsRaw ? tagsRaw.split(',').map(t => t.trim()) : [];
-const matchMode = get('--match') || 'any';       // 'any' | 'all'
-const minQ      = parseInt(get('--min-quality') || '0', 10);
-const agentFilter = get('--agent');
-const verdictRaw  = get('--verdict');
-const verdicts    = verdictRaw ? verdictRaw.split(',').map(v => v.trim().toUpperCase()) : [];
-const idRaw       = get('--id');
-const ids         = idRaw ? idRaw.split(',').map(i => i.trim()) : [];
-const avoidOnly   = has('--avoid');
-const format      = get('--format') || 'json';
-
-// --- Load index ---
-if (!fs.existsSync(INDEX_PATH)) {
-  console.error('No _index.json found at', INDEX_PATH);
-  process.exit(1);
-}
-const index = JSON.parse(fs.readFileSync(INDEX_PATH, 'utf8'));
-
-// --- Determine which brain files to load ---
-let brainFiles = index.brains;
-if (agentFilter) {
-  brainFiles = brainFiles.filter(b => b.agents.includes(agentFilter));
-}
-if (tags.length > 0) {
-  brainFiles = brainFiles.filter(b => tags.some(t => b.tags.includes(t)));
-}
-
-// --- Load nodes ---
-let nodes = [];
-for (const brain of brainFiles) {
-  const brainPath = path.isAbsolute(brain.path)
-    ? brain.path
-    : brain.path.startsWith('.aioson/brains/')
-      ? path.join(BRAINS_DIR, '..', '..', brain.path)
-      : path.join(BRAINS_DIR, brain.path);
-  if (!fs.existsSync(brainPath)) {
-    process.stderr.write(`Warning: brain file not found: ${brainPath}\n`);
-    continue;
-  }
-  const data = JSON.parse(fs.readFileSync(brainPath, 'utf8'));
-  nodes.push(...(data.nodes || []).map(n => ({ ...n, _brain: brain.id })));
-}
-
-// --- Filter nodes ---
-if (ids.length > 0) {
-  nodes = nodes.filter(n => ids.includes(n.id));
-} else {
-  if (tags.length > 0) {
-    if (matchMode === 'all') {
-      nodes = nodes.filter(n => tags.every(t => (n.tags || []).includes(t)));
-    } else {
-      nodes = nodes.filter(n => tags.some(t => (n.tags || []).includes(t)));
-    }
-  }
-  if (minQ > 0) {
-    nodes = nodes.filter(n => (n.q || 0) >= minQ);
-  }
-  if (verdicts.length > 0) {
-    nodes = nodes.filter(n => verdicts.includes((n.v || '').toUpperCase()));
-  }
-  if (avoidOnly) {
-    nodes = nodes.filter(n => n.v === 'AVOID' || n.v === 'BROKEN');
-  }
-}
-
-// --- Output ---
-if (format === 'compact') {
-  const rows = nodes.map(n => `[${n.q}★ ${n.v}] ${n.id} — ${n.title}\n  ${n.s}`);
-  console.log(rows.join('\n\n') || '(no matches)');
-} else if (format === 'ids') {
-  console.log(nodes.map(n => n.id).join('\n'));
-} else {
-  console.log(JSON.stringify(nodes, null, 2));
-}
-
-// --- Stats footer ---
-process.stderr.write(`\n${nodes.length} node(s) matched across ${brainFiles.length} brain file(s)\n`);
+#!/usr/bin/env node
+/**
+ * AIOSON Brain Query
+ * Cross-references pattern nodes across brain files by tags, quality, verdict, and agent.
+ *
+ * Usage:
+ *   node query.js --tags css,hover                    # nodes matching any of these tags
+ *   node query.js --tags css,hover --match all        # nodes matching ALL tags (AND)
+ *   node query.js --min-quality 4                     # quality >= 4 only
+ *   node query.js --agent site-forge                  # brain files for this agent
+ *   node query.js --verdict EXCELLENT,BEST_PRACTICE   # filter by verdict
+ *   node query.js --avoid                             # show only AVOID nodes (anti-patterns)
+ *   node query.js --id css-001,css-002                # fetch specific node IDs
+ *   node query.js --tags animation --format compact   # one-line per node output
+ *
+ * Output: JSON array of matching nodes (default) or compact table (--format compact)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const BRAINS_DIR = path.resolve(__dirname, '..');
+const INDEX_PATH = path.join(BRAINS_DIR, '_index.json');
+
+// --- Parse args ---
+const args = process.argv.slice(2);
+const get = (flag) => { const i = args.indexOf(flag); return i !== -1 ? args[i + 1] : null; };
+const has = (flag) => args.includes(flag);
+
+const tagsRaw   = get('--tags');
+const tags      = tagsRaw ? tagsRaw.split(',').map(t => t.trim()) : [];
+const matchMode = get('--match') || 'any';       // 'any' | 'all'
+const minQ      = parseInt(get('--min-quality') || '0', 10);
+const agentFilter = get('--agent');
+const verdictRaw  = get('--verdict');
+const verdicts    = verdictRaw ? verdictRaw.split(',').map(v => v.trim().toUpperCase()) : [];
+const idRaw       = get('--id');
+const ids         = idRaw ? idRaw.split(',').map(i => i.trim()) : [];
+const avoidOnly   = has('--avoid');
+const format      = get('--format') || 'json';
+
+// --- Load index ---
+if (!fs.existsSync(INDEX_PATH)) {
+  console.error('No _index.json found at', INDEX_PATH);
+  process.exit(1);
+}
+const index = JSON.parse(fs.readFileSync(INDEX_PATH, 'utf8'));
+
+// --- Determine which brain files to load ---
+let brainFiles = index.brains;
+if (agentFilter) {
+  brainFiles = brainFiles.filter(b => b.agents.includes(agentFilter));
+}
+if (tags.length > 0) {
+  brainFiles = brainFiles.filter(b => tags.some(t => b.tags.includes(t)));
+}
+
+// --- Load nodes ---
+let nodes = [];
+for (const brain of brainFiles) {
+  const brainPath = path.isAbsolute(brain.path)
+    ? brain.path
+    : brain.path.startsWith('.aioson/brains/')
+      ? path.join(BRAINS_DIR, '..', '..', brain.path)
+      : path.join(BRAINS_DIR, brain.path);
+  if (!fs.existsSync(brainPath)) {
+    process.stderr.write(`Warning: brain file not found: ${brainPath}\n`);
+    continue;
+  }
+  const data = JSON.parse(fs.readFileSync(brainPath, 'utf8'));
+  nodes.push(...(data.nodes || []).map(n => ({ ...n, _brain: brain.id })));
+}
+
+// --- Filter nodes ---
+if (ids.length > 0) {
+  nodes = nodes.filter(n => ids.includes(n.id));
+} else {
+  if (tags.length > 0) {
+    if (matchMode === 'all') {
+      nodes = nodes.filter(n => tags.every(t => (n.tags || []).includes(t)));
+    } else {
+      nodes = nodes.filter(n => tags.some(t => (n.tags || []).includes(t)));
+    }
+  }
+  if (minQ > 0) {
+    nodes = nodes.filter(n => (n.q || 0) >= minQ);
+  }
+  if (verdicts.length > 0) {
+    nodes = nodes.filter(n => verdicts.includes((n.v || '').toUpperCase()));
+  }
+  if (avoidOnly) {
+    nodes = nodes.filter(n => n.v === 'AVOID' || n.v === 'BROKEN');
+  }
+}
+
+// --- Output ---
+if (format === 'compact') {
+  const rows = nodes.map(n => `[${n.q}★ ${n.v}] ${n.id} — ${n.title}\n  ${n.s}`);
+  console.log(rows.join('\n\n') || '(no matches)');
+} else if (format === 'ids') {
+  console.log(nodes.map(n => n.id).join('\n'));
+} else {
+  console.log(JSON.stringify(nodes, null, 2));
+}
+
+// --- Stats footer ---
+process.stderr.write(`\n${nodes.length} node(s) matched across ${brainFiles.length} brain file(s)\n`);