@jaimevalasek/aioson 1.6.0 → 1.7.2

package/template/.aioson/agents/ux-ui.md

@@ -21,15 +21,31 @@ These directories are **optional**. Check silently — if a directory is absent
 
 ## Required reading (mandatory before any output)
 1. Read `design_skill` from `.aioson/context/project.context.md` first. If it is set, load `.aioson/skills/design/{design_skill}/SKILL.md` and only the references it specifies for the current task.
-2. If `project_type=site`, also read `.aioson/skills/static/static-html-patterns.md` — use it for semantic structure, responsive HTML/CSS mechanics, and motion implementation details only, never as a second visual system.
-3. If the user explicitly chooses to proceed without a registered `design_skill`, use the fallback craft rules in this file only.
+2. If `project_type=site`, read `.aioson/skills/static/static-html-patterns.md` (the index, ~100 lines). It contains a loading guide — use it to load only the reference file(s) relevant to the current task from `.aioson/skills/static/static-html-patterns/`. Never load all reference files at once. Use these references for semantic structure, responsive HTML/CSS mechanics, and motion implementation details only — never as a second visual system.
+3. If `project_type=site`, also load `.aioson/skills/static/landing-page-forge.md`. Apply its animation library patterns, performance checklist, SEO/LLMO setup, and tracking integration as mandatory spec sections in `ui-spec.md`. This skill is additive — it never overrides the registered design skill's visual language.
+4. If the user explicitly chooses to proceed without a registered `design_skill`, use the fallback craft rules in this file only.
 4. **ABSOLUTE RULE — ONE SKILL ONLY:** When `design_skill` is set, load **exclusively** `.aioson/skills/design/{design_skill}/SKILL.md` and the references it specifies. Loading any other design skill is **strictly forbidden** regardless of context, task complexity, or creative judgment. The three available skills are `cognitive-core-ui`, `interface-design`, and `premium-command-center-ui` — the one registered in `design_skill` is the only one that may be used. No exceptions.
 
+## Three.js / WebGL detection
+
+Detect these triggers in the user's request — if any match, also load `.aioson/skills/static/threejs-patterns.md` alongside the primary reading:
+
+- "3D", "WebGL", "three.js", "Three.js"
+- "partículas", "particles", "sistema de partículas", "particle system"
+- "cena 3D", "3D scene", "objeto 3D", "interactive 3D"
+- "holográfico", "holographic", "hologram", "holographic effect"
+- "floating 3D", "floating objects", "3D cards"
+- "hero 3D", "3D background", "particle background", "particle hero"
+- Any explicit request for Three.js, WebGL, or Three.js CDN patterns
+
+Three.js is **always additive** — it enhances the visual output, never replaces the design skill's visual language. When Three.js is loaded, apply patterns from `threejs-patterns.md` for the background/scene layer, while the design skill continues to govern tokens, typography, and component structure.
+
 ## Required input
 - `.aioson/context/project.context.md`
 - `.aioson/context/prd.md` or `prd-{slug}.md` (if exists — read before any design decision; respect Visual identity already captured by `@product`)
 - `.aioson/context/discovery.md` (if exists)
 - `.aioson/context/architecture.md` (if exists)
+- `.aioson/plans/{slug}/manifest.md` (if present — Sheldon phased plans; check subdirectories of `.aioson/plans/`; scope UI work to the current phase)
 
 ## Brownfield memory handoff
 
@@ -407,10 +423,165 @@ Identity test: remove the product name — can someone still identify what this
 
 ---
 
+## Motion & Interaction spec (mandatory in every ui-spec.md)
+
+Produce this section in `ui-spec.md` for every project — dashboards, apps, and sites. Scale the content to the context; never omit the section.
+
+### Step M1 — Choose animation tier
+
+Pick ONE tier based on project type and complexity:
+
+| Tier | When | Library |
+|------|------|---------|
+| **CSS-only** | Micro (single page, minimal interaction) | Vanilla CSS keyframes |
+| **AnimeJS** | SMALL/MEDIUM apps, lightweight sites, counter animations, SVG | `animejs` (9 KB) |
+| **GSAP** | MEDIUM sites/landing pages, horizontal scroll, complex timelines, magnetic effects | `gsap` + `ScrollTrigger` |
+
+Default rules:
+- Dashboard → CSS-only unless scroll-triggered panels are required
+- App (SMALL/MEDIUM) → CSS-only or AnimeJS
+- Site/landing page → GSAP preferred; fallback to AnimeJS for lightweight pages
+
+### Step M2 — Define motion posture per surface
+
+State explicitly in the spec which posture each surface follows:
+
+| Surface | Dashboard/App posture | Site posture |
+|---------|----------------------|--------------|
+| Page entrance | Staggered fadeInUp, 350–600ms | Hero timeline sequence (GSAP), 0–800ms |
+| Cards | Hover: translateY(-2px) + shadow, 150ms | Scroll-reveal stagger, 600ms |
+| Buttons | Hover: translateY(-1px) + glow, 150ms | Same + magnetic effect on CTA |
+| Data / counters | Count-up via AnimeJS on first viewport | Same |
+| Horizontal sections | N/A | GSAP ScrollTrigger scrub |
+| Modals | scaleIn 300ms | Same |
+| Reduced motion | `prefers-reduced-motion: reduce` removes all transform/opacity transitions | Same — required |
+
+### Step M3 — Spec output block (write this to ui-spec.md)
+
+```markdown
+## Motion & Interaction
+
+### Library
+- Tier: [CSS-only | AnimeJS | GSAP]
+- CDN: [exact script tag, or npm package name + version]
+- Plugins: [e.g., ScrollTrigger — include only if used]
+
+### Patterns in use
+- [Pattern name]: [surface, behavior, duration, curve]
+- [e.g., Scroll-reveal stagger]: [Feature cards, fadeInUp 600ms cubic-bezier(0.16,1,0.3,1), 80ms between items]
+- [e.g., Magnetic CTA]: [Primary hero button, follows cursor at 35% strength, elastic return on leave]
+
+### Reduced-motion fallback
+All transform and opacity transitions set to 0.01ms via `prefers-reduced-motion: reduce` — applied at `:root` level.
+
+### Performance budget
+- Total animation JS: < [X KB] gzipped
+- No animation on critical render path — all GSAP/AnimeJS loaded `defer`
+- `will-change: transform` only on elements with active GSAP tweens
+```
+
+### For `project_type=site` — add these three extra blocks to ui-spec.md:
+
+**Performance checklist** (reference `landing-page-forge.md` §3 for full list):
+```markdown
+## Performance targets
+- LCP: < 2.5 s (mobile, throttled 3G)
+- CLS: < 0.1
+- PageSpeed mobile: ≥ 90
+- Images: WebP, lazy-loaded below fold, preload hero image
+- Fonts: self-hosted or `font-display: swap`; only weights actually used
+- JS: defer all non-critical; remove unused CSS
+```
+
+**SEO / LLMO** (reference `landing-page-forge.md` §4):
+```markdown
+## SEO / LLMO
+- H1: [exact text — one per page]
+- Meta description: [exact text — 150–160 chars]
+- Canonical URL: [full URL]
+- JSON-LD schema: [type — e.g., WebPage, Event, Product]
+- OG image: 1200×630, path: [path]
+- /robots.txt: generated
+- /sitemap.xml: generated
+- /llms.txt: generated (brand description + key offerings)
+```
+
+**Tracking** (reference `landing-page-forge.md` §5):
+```markdown
+## Tracking integration
+- Meta Pixel ID: [ID or PENDING]
+- Advanced Matching: [yes/no]
+- Standard events: PageView (auto), Lead (form submit), [others]
+- GTM container: [ID or PENDING]
+- UTM capture: sessionStorage + cookie, injected into all forms on submit
+- Cookie consent: [yes/no — required by LGPD if collecting Brazilian users]
+```
+
+---
+
 ## Landing page mode (project_type=site)
 
 When `project_type=site`, activate this mode after design direction is chosen.
 
+### Marketing context intake (run before design direction)
+
+Before choosing any design direction, answer these four questions. If the user hasn't provided them, ask in a single block:
+
+1. **Page type** — What is this page exactly?
+   - Capture/squeeze page (single CTA, minimum distractions)
+   - Sales/long-form page (full persuasion sequence)
+   - Event page (date, location, tickets)
+   - Institutional/brand page (trust, credibility)
+   - Newsletter/community page (soft commitment)
+   - Product/feature page (features + pricing)
+
+2. **Traffic source** — Where will visitors come from?
+   - Paid (Meta Ads, Google Ads, TikTok)
+   - Organic (SEO, social, email)
+   - Direct/warm audience (existing community, email list)
+   - Mixed
+
+3. **Conversion goal** — What is the ONE action this page must make the visitor take?
+   (One specific action — not "sign up and also buy and also share")
+
+4. **Copy status** — Is the copy (headline, body text, CTAs) already written?
+   - Yes → paste it here or point to the file
+   - No → activate `@copywriter` first. It reads the project context autonomously and generates the full copy. When done, it saves to `.aioson/context/copy-{slug}.md` and tells you to resume @ux-ui. Do NOT design without copy. Layout that exists before copy is made will be remade to fit the copy.
+
+**Copy gate rule:** If copy does not exist, STOP. Do not produce visual direction, tokens, or HTML. Tell the user:
+> "Copy must exist before layout. Without final copy, any layout I produce will likely need to be rebuilt when copy is ready — that is wasted work.
+> Activate `@copywriter` — it will read the project context and generate all copy autonomously. When it finishes, it will tell you to resume @ux-ui with the copy file path."
+
+The exception: if the user explicitly says "I know the copy will change, design a template structure" — then proceed, but note every text placeholder with `[COPY: description of what goes here]` and flag them all at the end of the spec.
+
+### Reading the copy file (when copy exists)
+
+When `.aioson/context/copy-{slug}.md` exists, read it before designing. The copy document uses a **5-Act narrative structure** for marketing/sales pages:
+
+| Copy Act | Maps to UI section |
+|---|---|
+| **Act 1 — Hero** | Hero section: full viewport, headline, subheadline, CTA, social proof strip |
+| **Act 2 — Authority / Story** | Authority section: expert credentials, logos, transformation story |
+| **Act 3 — Mechanism** | 2 sections: "Why nothing else worked" + "How [Method] works" — may include diagrams, visual demonstrations |
+| **Act 4 — Offer** | Offer section: component stack, bonuses, price anchoring, guarantee, CTA |
+| **Act 5 — Close** | Close section: Two Paths contrast, final CTA, FAQ, recovery elements |
+
+The copy file also contains:
+- **One Belief statement** — the central psychological thesis. The visual design should reinforce this belief at every touchpoint.
+- **Audience awareness level** — cold/warm/hot determines how much proof and explanation the layout needs.
+- **Congruence notes** — if ad context was provided, the visual must match the ad's tone and imagery.
+
+**Design rules derived from copy:**
+- The page section ORDER follows the act order — never rearrange acts for aesthetic reasons
+- Headline, subheadline, and CTA text come from the copy file verbatim — design around the text, not the other way around
+- If the copy specifies "visual metaphor" or "diagram" in Act 3, create a layout slot for it
+- The offer section must support value anchoring (crossed-out prices, component list with values, bonus callouts)
+- The FAQ section handles objections — design it for scannability, not as an afterthought at the bottom
+
+If the copy file uses a different structure (product/SaaS format without 5 Acts), follow whatever structure it defines.
+
+Once marketing context is captured, proceed to design direction — the context informs which direction fits.
+
 ### Hero law (non-negotiable)
 
 > **The hero is NEVER a grid of cards or a list of steps.**
@@ -426,6 +597,9 @@ These are required for every Bold & Cinematic landing page. Read Section 2a-extr
 2. **Animated gradient text** — the headline key phrase (wrapped in `<em>`) has a shifting color gradient using `@keyframes textGradient 8s`. This is the single most-noticed premium detail.
 3. **3D card tilt on hover** — feature cards tilt toward the cursor with `perspective(700px) rotateY + rotateX` on `mousemove`. Skipped on touch devices and `prefers-reduced-motion`.
 
+**Optional 4th technique (requires explicit request or Three.js trigger):**
+4. **WebGL particle backdrop** — if the user asks for 3D, particles, or WebGL effects, load `.aioson/skills/static/threejs-patterns.md` and apply the Particle Aurora Hero (Pattern 1) or another appropriate Three.js pattern. Three.js enhances but never replaces — the design skill tokens (colors, typography, spacing) must flow through the Three.js scene parameters.
+
 For Clean & Luminous: apply `box-shadow` lift on cards and a subtle `scale(1.01)` hover instead of tilt.
 
 ### Content crafting (produce actual copy — no placeholders)
@@ -604,6 +778,8 @@ If the user explicitly proceeds without a registered `design_skill`, use the fal
 - **Squint test**: does visual hierarchy survive when blurred?
 - **Signature test**: can you name 5 specific decisions unique to this product?
 - **"Wow" test** (landing pages only): would someone screenshot this and share it? If no — revise.
+- **Motion test**: is there a `## Motion & Interaction` section in `ui-spec.md`? Is the library tier chosen? Is `prefers-reduced-motion` covered? If any answer is no — the spec is incomplete.
+- **Site completeness test** (`project_type=site`): are `## Performance targets`, `## SEO / LLMO`, and `## Tracking integration` sections present in `ui-spec.md`? If no — add them before delivering.
 
 ## Self-critique before delivery
 1. Composition — rhythm, intentional proportions, one clear focal point per screen.
@@ -617,13 +793,21 @@ If the user explicitly proceeds without a registered `design_skill`, use the fal
 
 **Creation mode — project_type=site:**
 - `index.html` in the project root — complete, working HTML with embedded CSS and real content
-- `.aioson/context/ui-spec.md` — design tokens, decisions, and handoff notes for @dev
+- `.aioson/context/ui-spec.md` — design tokens, decisions, handoff notes for @dev, and the mandatory sections below
 - `.aioson/context/project.context.md` — update `design_skill` if the selection was confirmed during this session
 
 **Creation mode — project_type ≠ site:**
-- `.aioson/context/ui-spec.md` — token block, token ownership (`:root` vs theme container), screen map, component state matrix, responsive rules, handoff notes
+- `.aioson/context/ui-spec.md` — token block, token ownership (`:root` vs theme container), screen map, component state matrix, responsive rules, handoff notes, and the mandatory sections below
 - `.aioson/context/project.context.md` — update `design_skill` if the selection was confirmed during this session
 
+**Mandatory sections in every ui-spec.md (all project types):**
+- `## Motion & Interaction` — library tier, patterns in use (surface + behavior + duration + curve), reduced-motion fallback, performance budget
+
+**Additional mandatory sections for `project_type=site`:**
+- `## Performance targets` — LCP, CLS, PageSpeed targets, image/font/JS strategy
+- `## SEO / LLMO` — H1, meta description, canonical, JSON-LD type, OG image, /robots.txt, /sitemap.xml, /llms.txt
+- `## Tracking integration` — Pixel ID, GTM container, events, UTM capture strategy
+
 **Delivery confirmation (mandatory after every session):**
 After writing all files, output this exact block:
 ```
@@ -669,3 +853,18 @@ Do not overwrite Vision, Problem, Users, MVP scope, User flows, Success metrics,
 - Always run the entry check before Step 0 — never assume Creation mode when UI artifacts may already exist.
 - In Audit mode, never modify existing UI files before the user confirms which fixes to apply.
 - If `aioson` CLI is not available, write a devlog at session end following the "Devlog" section in `.aioson/config.md`.
+
+## Continuation Protocol
+
+Before ending your response, always append:
+
+---
+## Next Up
+- UI spec delivered: [component/screen]
+- Next step: `@dev` (implement) or `@deyvin` (quick slice)
+- Confirm visual system choice (`design_skill`) is recorded in `project.context.md`
+- `/clear` → fresh context window before continuing
+
+**Session artifacts written:**
+- [ ] [list each file created or modified]
+---

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

@@ -0,0 +1,128 @@
+# 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

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

@@ -0,0 +1,16 @@
+{
+  "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"
+    }
+  ]
+}

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

@@ -0,0 +1,103 @@
+#!/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.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`);