appydave-tools 0.80.0 → 0.81.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb0b711e430f2082be55712eb0c3e630726bcc77628dc8ab144d72f27fc05bd7
-  data.tar.gz: 8fc9be5413601f6da5cccd649d324578df676efb842b138623998a1f6dd7b676
+  metadata.gz: '09f48a7490c924291dff958e3df8ba53c28c2dae599cae0ab8581ac3e4ad3ee2'
+  data.tar.gz: f1e55198dd31bb3b2b61b61d4f929fc3bda799ecd4cedb96e5f810c994edae4a
 SHA512:
-  metadata.gz: d7527c25930ba5fb35206e6321fea074f12593a9188ed4b7d51f1f832f01f60a9929336b8670bf48bea0f68eeba0df150ecb542ea244be899334781ef432a7a1
-  data.tar.gz: 051f6c24d48fa6caa2ac342436a1105403d7524e871ee248996b772e0e16aafde612cd33386d4b6bba92b5f1f0c2e2f6cf61406e9f76db5a42e55d367031c642
+  metadata.gz: 9d4f2bc474af95d2ff538d5360d9ec659b559f155b611c9b7c13f9c475118311a1fc99a40b1f3fc6655b20bee568a3c5fcb4466f709eef948cd400d4efee6709
+  data.tar.gz: 84af7abbcc284e85742f1db64737622e8c929b57815988908a2aba716d970adcfd0f52e29f7a432fb2d544fd8be950fd27254d7ec61fdf705802c126b34e6d84

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [0.80.0](https://github.com/appydave/appydave-tools/compare/v0.79.0...v0.80.0) (2026-04-03)
+
+
+### Bug Fixes
+
+* resolve RSpec linting violations in test suite ([0bb643c](https://github.com/appydave/appydave-tools/commit/0bb643c374934227ab6831f87b4b8e7fd6d2444d))
+
+
+### Features
+
+* add brain_context CLI tool for querying brains + OMI ([7498e25](https://github.com/appydave/appydave-tools/commit/7498e25d8fa3094ee97ddfb67980d414f70efbab))
+
 # [0.79.0](https://github.com/appydave/appydave-tools/compare/v0.78.0...v0.79.0) (2026-04-03)
 
 

data/CLAUDE.md

@@ -170,6 +170,8 @@ bin/console         # Interactive Ruby console for experimentation
 | **DAM (Digital Asset Management)** | `vat` | Multi-tenant video project storage orchestration | ✅ ACTIVE |
 | **Configuration** | `ad_config` | Manage JSON configs (channels, paths, sequences) | ✅ ACTIVE |
 | **Move Images** | N/A (dev only) | Organize video asset images | ✅ ACTIVE |
+| **Brain Query** | `query_brain` | Query brain knowledge index by name/tag/category | ✅ ACTIVE |
+| **OMI Query** | `query_omi` | Query OMI transcripts by routing/brain/activity | ✅ ACTIVE |
 | **Prompt Tools** | `prompt_tools` | OpenAI Completion API wrapper | ⚠️ DEPRECATED API |
 | **YouTube Automation** | `youtube_automation` | Prompt sequence runner | ⚠️ INTERNAL USE |
 
@@ -434,7 +436,92 @@ bin/move_images.rb -f b40 thumb b40
 
 **Note:** This is a development/workflow tool specific to video project organization. Not installed as a gem command.
 
-#### 8. Bank Reconciliation (`bin/bank_reconciliation.rb`) 🗄️ DEPRECATED
+#### 8. Brain Query (`bin/query_brain`)
+Query the brain knowledge index to locate relevant brain files for LLM context pipelines:
+
+```bash
+# Find brains by name, alias, or tag
+query_brain --find paperclip
+query_brain --find bmad --find method
+
+# Find all brains in a category
+query_brain --category tools
+query_brain --category workflows
+
+# Find high-activity brains
+query_brain --active
+
+# Exclude INDEX.md from results
+query_brain --find paperclip --files-only
+
+# Return JSON metadata instead of file paths
+query_brain --active --meta
+query_brain --find bmad --meta
+```
+
+**Options:**
+- `--find TERM` — find by name, alias, or tag (repeatable)
+- `--category CAT` — all brains in a category (repeatable)
+- `--active` — all high-activity brains
+- `--files-only` — exclude INDEX.md from results
+- `--meta` — return JSON metadata instead of file paths
+
+**Pipeline examples:**
+```bash
+# Feed brain files directly into LLM context
+query_brain --find paperclip | xargs llm_context.rb -i
+
+# Metadata pipeline (direct to LLM — no llm_context needed)
+query_brain --active --meta
+```
+
+#### 9. OMI Query (`bin/query_omi`)
+Query OMI wearable transcript sessions by routing type, brain reference, or activity:
+
+```bash
+# Find sessions mentioning a brain
+query_omi --brain paperclip
+query_omi --brain bmad
+
+# Filter by routing type
+query_omi --routing brain-update
+query_omi --routing til
+query_omi --routing todo-item
+query_omi --routing personal
+query_omi --routing archive
+
+# Filter by activity
+query_omi --activity planning
+query_omi --activity meeting
+query_omi --activity debugging
+
+# Limit by recency
+query_omi --days 7
+query_omi --brain paperclip --days 30 --limit 10
+
+# Return JSON metadata instead of file paths
+query_omi --brain paperclip --meta
+query_omi --routing brain-update --limit 5 --meta
+```
+
+**Options:**
+- `--brain NAME` — sessions mentioning a brain
+- `--routing TYPE` — brain-update, til, todo-item, personal, archive
+- `--activity ACT` — planning, meeting, debugging, etc.
+- `--days N` — last N days
+- `--limit N` — most recent N results
+- `--meta` — return JSON metadata instead of file paths
+
+**Pipeline examples:**
+```bash
+# Feed recent brain-update sessions into LLM context
+query_omi --routing brain-update --limit 5 | xargs llm_context.rb -i
+
+# Metadata pipeline (direct to LLM — no llm_context needed)
+query_omi --brain paperclip --meta
+```
+
+#### 10. Bank Reconciliation (`bin/bank_reconciliation.rb`) 🗄️ DEPRECATED
 Bank transaction reconciliation tool - **DEPRECATED, DO NOT USE**
 
 **WARNING:** This tool contains deprecated code and should not be used for new work. Code has been moved to `lib/appydave/tools/deprecated/bank_reconciliation/`

data/bin/query_brain.rb

@@ -10,26 +10,20 @@ def setup_options(options)
   OptionParser.new do |opts| # rubocop:disable Metrics/BlockLength
     opts.banner = 'Usage: query_brain [options]'
 
-    opts.on('--brain NAME', 'Query brain by name, alias, or fuzzy match') do |name|
-      options.brain_names << name
+    opts.on('--find TERM', 'Find brain by name, tag, or alias (repeatable)') do |term|
+      options.brain_names << term
     end
 
-    opts.on('--tag TAG', 'Query brains by tag') do |tag|
-      options.tags << tag
-    end
-
-    opts.on('--category CAT', 'Query all brains in category') do |cat|
+    opts.on('--category CAT', 'Find all brains in category (repeatable)') do |cat|
       options.categories << cat
     end
 
-    opts.on('--activity-min LEVEL', %w[high medium low none],
-            'Filter brains by minimum activity level') do |level|
-      options.activity_levels << level
+    opts.on('--active', 'Return all high-activity brains') do
+      options.active = true
     end
 
-    opts.on('--status STATUS', %w[active stable deprecated],
-            'Filter brains by status (default: exclude deprecated)') do |status|
-      options.status = status
+    opts.on('--meta', 'Return metadata as JSON instead of file paths') do
+      options.meta = true
     end
 
     opts.on('--files-only', 'Exclude INDEX.md, only include content files') do
@@ -57,9 +51,12 @@ setup_options(options)
 
 # Query
 finder = Appydave::Tools::BrainQuery.new(options)
-paths = finder.find
 
-# Output file paths, one per line
-paths.each { |p| puts p }
+if options.meta
+  require 'json'
+  puts JSON.pretty_generate(finder.find_meta)
+else
+  finder.find.each { |p| puts p }
+end
 
 exit 0

data/bin/query_omi.rb

@@ -11,9 +11,8 @@ def setup_options(options)
   OptionParser.new do |opts| # rubocop:disable Metrics/BlockLength
     opts.banner = 'Usage: query_omi [options]'
 
-    opts.on('--signal SIGNAL', %w[work life ambient],
-            'Filter by signal') do |signal|
-      options.omi_signals << signal
+    opts.on('--brain NAME', 'Find OMI sessions mentioning this brain') do |name|
+      options.brain_names << name
     end
 
     opts.on('--routing ROUTING',
@@ -26,20 +25,16 @@ def setup_options(options)
       options.omi_activities.concat(activity.split('|').map(&:strip))
     end
 
-    opts.on('--date-from DATE', 'Include files from date (YYYY-MM-DD)') do |date|
-      options.date_from = date
+    opts.on('--days N', Integer, 'Include sessions from the last N days') do |n|
+      options.days = n
     end
 
-    opts.on('--date-to DATE', 'Include files up to date (YYYY-MM-DD)') do |date|
-      options.date_to = date
+    opts.on('--meta', 'Return metadata as JSON instead of file paths') do
+      options.meta = true
     end
 
-    opts.on('--enriched-only', 'Skip raw (non-enriched) transcripts') do
-      options.enriched_only = true
-    end
-
-    opts.on('--brain NAME', 'Find OMI files mentioning this brain') do |name|
-      options.brain_names << name
+    opts.on('--limit N', Integer, 'Return at most N results (most recent)') do |n|
+      options.limit = n
     end
 
     opts.on('-d', '--debug [MODE]', %w[none info params debug],
@@ -63,9 +58,12 @@ setup_options(options)
 
 # Query
 finder = Appydave::Tools::OmiQuery.new(options)
-paths = finder.find
 
-# Output file paths, one per line
-paths.each { |p| puts p }
+if options.meta
+  require 'json'
+  puts JSON.pretty_generate(finder.find_meta)
+else
+  finder.find.each { |p| puts p }
+end
 
 exit 0

data/docs/guides/query-tools-handover.md

@@ -0,0 +1,58 @@
+---
+title: Handover — Query Tools Session (2026-04-04)
+type: handover
+---
+
+# Handover — Query Tools Session (2026-04-04)
+
+## What Was Built
+
+Three tools in `appydave-tools` now work as a unified query pipeline:
+
+- **`query_brain`** — queries the brains knowledge index
+- **`query_omi`** — queries OMI conversation transcripts by frontmatter
+- **`llm_context`** — assembles file content for LLM consumption (pre-existing, unchanged)
+
+Full documentation: `/Users/davidcruwys/dev/ad/appydave-tools/docs/guides/query-tools.md`
+
+---
+
+## What Changed Today
+
+### API Simplification
+Both query tools had their APIs simplified — fewer flags, unified search:
+
+**query_brain**: `--find` replaces separate `--brain` + `--tag`. `--active` replaces broken `--activity-min`. Removed: `--status` (dead code), `--tag`, `--activity-min`.
+
+**query_omi**: Added `--days N` and `--limit N`. Removed: `--signal`, `--date-from`, `--date-to`, `--enriched-only` (enriched is now default).
+
+### New --meta Mode
+Both tools now support `--meta` — returns JSON metadata instead of file paths. This is a **separate pipeline** from llm_context, used when you want summaries without loading full file content.
+
+### Bug Fixed
+`query_brain --active` was silently returning nothing. Fixed — now correctly returns all 29 high-activity brains.
+
+---
+
+## Relevant Skills That May Want This Context
+
+### OMI Skill (`/Users/davidcruwys/dev/ad/appydave-plugins/appydave/skills/omi/`)
+The `query_omi` tool is the programmatic interface to the same OMI data that the OMI skill works with. The frontmatter fields (`routing`, `matched_brains`, `extraction_summary`, etc.) that `query_omi` filters on are produced by the OMI enrichment pipeline. The skill should know:
+- `--routing brain-update` surfaces the backlog of conversations that should feed into brains
+- `--meta` gives extraction summaries without loading full transcripts
+
+### Brain Librarian (wherever it lives)
+The `query_brain` tool consumes `brains-index.json` built by brain-librarian. The librarian should know:
+- Index must be at `~/dev/ad/brains/audit/brains-index.json`
+- Fields used: `activity_level`, `tags`, `category`, `status`, `file_count`, `index_path`, `files[]`
+- `files[]` array is currently empty for most brains — only `INDEX.md` is returned. Populating this would make `query_brain --find X` return actual content files, not just index files.
+
+### LLM Context Skill (if one exists)
+The pipeline pattern is: `query_brain --find X | xargs llm_context.rb -i -f content`. The query tools are the **selector layer** feeding into llm_context as the **assembler layer**.
+
+---
+
+## What Is Not Done Yet (Intentionally Deferred)
+
+- **Randomizer** — a discovery tool that pre-validates queries against result counts and randomly surfaces one. Concept is clear, not yet implemented. Would live as `/Users/davidcruwys/dev/ad/appydave-tools/bin/random_context.rb`.
+- **Markdown format for --meta** — decided against. JSON is sufficient for LLM consumption and adding a format flag adds complexity back that was just removed.

data/docs/guides/query-tools.md

@@ -0,0 +1,255 @@
+---
+title: Query Tools — brain, OMI, and LLM Context Pipeline
+category: guides
+tools: [query_brain, query_omi, llm_context]
+status: active
+created: 2026-04-04
+---
+
+# Query Tools — Brain, OMI, and LLM Context Pipeline
+
+## Purpose
+
+Three tools work together as a **file selection and context assembly pipeline** for AI-assisted workflows:
+
+| Tool | Role | Output |
+|------|------|--------|
+| `query_brain` | Select brain knowledge files | File paths or JSON metadata |
+| `query_omi` | Select OMI conversation files | File paths or JSON metadata |
+| `llm_context` | Assemble file content for LLM | Tree listing or full content |
+
+The tools are **composable**: query tools select files, `llm_context` loads them.
+
+---
+
+## What Is Being Queried
+
+### query_brain
+Reads `~/dev/ad/brains/audit/brains-index.json` — a pre-built index of all brain folders. Does **not** scan brain files at query time. The index contains per-brain metadata: name, category, activity_level, tags, status, file_count.
+
+Brain folders live at `~/dev/ad/brains/<brain-name>/`. Each has an `INDEX.md` and optional content files.
+
+### query_omi
+Scans `~/dev/raw-intake/omi/*.md` and reads YAML frontmatter from each file. Enriched files (processed by Gemini extraction) have rich frontmatter. Raw files (unprocessed transcripts) have minimal frontmatter. Default behaviour: **enriched files only**.
+
+### llm_context
+Takes file paths (from stdin or arguments) and assembles content for LLM consumption. Two formats: `tree` (file listing) and `content` (file listing + full file content).
+
+---
+
+## query_brain API
+
+```bash
+query_brain [options]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--find TERM` | Find brain by name, alias, or tag — unified search (repeatable) |
+| `--category CAT` | All brains in a category (repeatable) |
+| `--active` | All high-activity brains |
+| `--files-only` | Exclude INDEX.md, return content files only |
+| `--meta` | Return JSON metadata instead of file paths |
+
+### Categories (as of 2026-04)
+`claude-core`, `agent-frameworks`, `agent-systems`, `infrastructure`, `content-production`, `brand-strategy`, `knowledge-capture`, `client-infrastructure`, `lifestyle`, `private`
+
+### Activity Levels
+`high` (29 brains), `medium`, `low`, `none`
+
+### Search Resolution Order (--find)
+1. Exact brain name match
+2. Alias match (from alias_index in brains-index.json)
+3. Substring match on brain name
+4. Tag match (falls through to tag_index)
+
+### Examples
+```bash
+# Find a specific brain (name, partial name, or tag all work)
+query_brain --find paperclip
+query_brain --find agentic-engineering   # searches by tag
+
+# Browse a category
+query_brain --category agent-systems
+query_brain --category agent-systems --category agent-frameworks
+
+# All high-activity brains
+query_brain --active
+
+# Metadata instead of file paths
+query_brain --active --meta
+query_brain --find paperclip --meta
+```
+
+### --meta Output Structure
+```json
+[
+  {
+    "name": "paperclip",
+    "category": "agent-systems",
+    "activity_level": "high",
+    "status": "active",
+    "tags": ["paperclip", "multi-agent", "orchestration"],
+    "file_count": 6
+  }
+]
+```
+
+---
+
+## query_omi API
+
+```bash
+query_omi [options]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--brain NAME` | Sessions where this brain appears in matched_brains |
+| `--routing TYPE` | Filter by routing tag (pipe-delimited values supported) |
+| `--activity ACT` | Filter by activity type (pipe-delimited values supported) |
+| `--days N` | Sessions from the last N days (based on extracted_at) |
+| `--limit N` | Return at most N results, most recent first |
+| `--meta` | Return JSON metadata instead of file paths |
+
+### Routing Values
+`brain-update`, `til`, `todo-item`, `personal`, `archive`
+
+### Activity Values
+`planning`, `meeting`, `learning`, `debugging`, `reviewing`, `building`, `teaching`
+
+### Enriched Frontmatter Structure
+```yaml
+signal: work
+extraction_summary: "One-sentence summary of the conversation"
+extracted_at: 2026-04-03
+matched_brains: [agentic-os, anthropic-claude, paperclip]
+activity: meeting|planning|learning
+routing: brain-update
+people_present: [david, nick]
+people_mentioned: [boris]
+entities_tools: [Claude, Gemini, Archon]
+entities_projects: [Agent Workflow Builder]
+entities_concepts: [token economics, RAG, prompt caching]
+overflow_topics: [Thai chocolate, mask hardware]
+```
+
+### Examples
+```bash
+# Sessions flagged for brain updates (your backlog)
+query_omi --routing brain-update
+query_omi --routing brain-update --limit 10
+
+# Recent planning sessions
+query_omi --activity planning --days 7
+
+# Everything related to a specific brain
+query_omi --brain paperclip
+
+# Metadata view — summaries without loading full files
+query_omi --routing brain-update --limit 5 --meta
+query_omi --brain paperclip --days 14 --meta
+```
+
+### --meta Output Structure
+```json
+[
+  {
+    "file": "2026-04-03-1705-group-debates.md",
+    "extracted_at": "2026-04-03",
+    "extraction_summary": "A group discusses LLM usage and agentic workflows...",
+    "matched_brains": ["agentic-os", "anthropic-claude", "paperclip"],
+    "activity": "meeting|planning",
+    "routing": "brain-update",
+    "entities_tools": ["Claude", "Gemini", "Archon"],
+    "entities_projects": ["Archon"],
+    "entities_concepts": ["token economics", "RAG"]
+  }
+]
+```
+
+---
+
+## Pipeline Patterns
+
+### Content pipeline — load files into LLM context
+```bash
+# Brain knowledge files → LLM
+query_brain --find paperclip | xargs llm_context.rb -i -f content
+
+# OMI sessions → LLM
+query_omi --brain paperclip --limit 5 | xargs llm_context.rb -i -f content
+
+# Mixed: brain + OMI for a topic
+{ query_brain --find paperclip; query_omi --brain paperclip --limit 5; } | sort -u | xargs llm_context.rb -i -f content
+```
+
+### Metadata pipeline — summaries direct to LLM (no llm_context needed)
+```bash
+# What's in my brain-update backlog?
+query_omi --routing brain-update --meta
+
+# What are all my active brains?
+query_brain --active --meta
+
+# What OMI sessions touched paperclip recently?
+query_omi --brain paperclip --days 14 --meta
+```
+
+### Discovery pattern — bounded queries for randomizer
+```bash
+# These return 1–20 results — good for random surfacing
+query_brain --find paperclip            # 1 brain
+query_brain --category agent-systems   # ~10 brains
+query_omi --brain paperclip            # ~10 sessions
+query_omi --routing til --limit 5      # 5 things-I-learned
+```
+
+---
+
+## Two Different Data Shapes
+
+**Brain files** are **curated knowledge** — processed, structured, human-maintained. High signal density. Use when you want what is known and confirmed.
+
+**OMI files** are **conversation transcripts** — raw or AI-enriched recordings of spoken work sessions. Variable quality. Use when you want recent context, planning discussions, or to find what should be promoted into a brain.
+
+These are intentionally separate query tools. Do not combine them by default.
+
+---
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `/Users/davidcruwys/dev/ad/brains/audit/brains-index.json` | Brain index — built by brain-librarian |
+| `/Users/davidcruwys/dev/raw-intake/omi/*.md` | OMI conversation transcripts |
+| `/Users/davidcruwys/dev/ad/appydave-tools/bin/query_brain.rb` | Brain query CLI |
+| `/Users/davidcruwys/dev/ad/appydave-tools/bin/query_omi.rb` | OMI query CLI |
+| `/Users/davidcruwys/dev/ad/appydave-tools/bin/llm_context.rb` | File content assembler |
+| `/Users/davidcruwys/dev/ad/appydave-tools/exe/query_brain` | Gem-installed wrapper |
+| `/Users/davidcruwys/dev/ad/appydave-tools/exe/query_omi` | Gem-installed wrapper |
+| `/Users/davidcruwys/dev/ad/appydave-tools/lib/appydave/tools/brain_context/brain_finder.rb` | BrainQuery implementation |
+| `/Users/davidcruwys/dev/ad/appydave-tools/lib/appydave/tools/brain_context/omi_finder.rb` | OmiQuery implementation |
+| `/Users/davidcruwys/dev/ad/appydave-tools/lib/appydave/tools/brain_context/options.rb` | Shared options struct |
+
+---
+
+## Rebuilding the Brain Index
+
+The `brains-index.json` is not auto-updated. When brain folders change, rebuild it:
+
+```bash
+python /Users/davidcruwys/dev/ad/brains/.claude/skills/brain-librarian/scripts/build_brain_index.py build --all /Users/davidcruwys/dev/ad/brains
+```
+
+OMI files are queried directly — no index rebuild needed.
+
+---
+
+## Design Decisions
+
+- **query_brain and query_omi are separate tools** — brains are confirmed knowledge, OMI is conversation. Different trust levels.
+- **`--meta` bypasses llm_context** — metadata is already summarised; loading full file content adds tokens without value for discovery use cases.
+- **enriched_only defaults to true** in query_omi — raw transcripts have no frontmatter to filter on; they're noise in most query contexts.
+- **`--find` unifies name/alias/tag** — users shouldn't need to know whether something is a name or a tag.
+- **`--active` standalone** — returns all 29 high-activity brains without needing to enumerate categories.

data/lib/appydave/tools/brain_context/brain_finder.rb

@@ -18,28 +18,35 @@ module Appydave
         load_index!
         paths = []
 
-        # Handle brain name queries
+        # Active brains: return all high-activity brains
+        paths.concat(find_active) if @options.active
+
+        # Handle brain name/tag/alias queries (unified)
         @options.brain_names.each do |name|
           paths.concat(find_by_name(name))
         end
 
-        # Handle tag queries
-        @options.tags.each do |tag|
-          paths.concat(find_by_tag(tag))
-        end
-
         # Handle category queries
         @options.categories.each do |category|
           paths.concat(find_by_category(category))
         end
 
-        # Handle activity level filters
-        paths.select! { |p| matches_activity_level?(p) } if @options.activity_levels.any?
-
-        # Remove duplicates and return
         paths.uniq.sort
       end
 
+      def find_meta
+        return [] unless @options.brain_query?
+
+        load_index!
+        entries = []
+
+        entries.concat(active_meta_entries) if @options.active
+        @options.brain_names.each { |name| entries.concat(meta_entries_by_name(name)) }
+        @options.categories.each { |cat| entries.concat(meta_entries_by_category(cat)) }
+
+        entries.uniq { |e| e['name'] }.sort_by { |e| e['name'] }
+      end
+
       private
 
       def load_index!
@@ -80,11 +87,10 @@ module Appydave
             matches << brain_data if brain_name.downcase.include?(name.downcase)
           end
         end
-        return brain_entries_to_paths(matches) if matches.length == 1
         return brain_entries_to_paths(matches) if matches.any?
 
-        # Not found
-        []
+        # Step 4: Tag match (so --find works for tags too)
+        find_by_tag(name)
       end
 
       def find_by_tag(tag)
@@ -148,17 +154,82 @@ module Appydave
         entry['index_path'].split('/')[0]
       end
 
-      def matches_activity_level?(file_path)
-        # Extract brain name from path
-        brain_name = file_path.match(%r{#{Regexp.escape(@options.brains_root)}/([^/]+)})&.[](1)
-        return false unless brain_name
+      def find_active
+        brain_entries = []
+        @index['categories'].each_value do |category_data|
+          category_data['brains'].each_value do |brain_data|
+            brain_entries << brain_data if brain_data['activity_level'] == 'high'
+          end
+        end
+        brain_entries_to_paths(brain_entries)
+      end
+
+      # --- find_meta helpers ---
 
-        # Find the brain entry
-        entry = find_brain_in_index(brain_name)
-        return false unless entry
+      def active_meta_entries
+        result = []
+        @index['categories'].each do |category_name, category_data|
+          category_data['brains'].each do |brain_name, brain_data|
+            result << build_meta_entry(brain_name, category_name, brain_data) if brain_data['activity_level'] == 'high'
+          end
+        end
+        result
+      end
+
+      def meta_entries_by_category(category)
+        category_key = @index['categories'].keys.find { |k| k.casecmp(category).zero? }
+        return [] unless category_key
+
+        @index['categories'][category_key]['brains'].map do |brain_name, brain_data|
+          build_meta_entry(brain_name, category_key, brain_data)
+        end
+      end
+
+      def meta_entries_by_name(name)
+        # Exact match
+        brain_name, category, data = find_brain_with_context(name)
+        return [build_meta_entry(brain_name, category, data)] if data
+
+        # Alias match
+        if @alias_map&.[](name.downcase)
+          brain_name, category, data = find_brain_with_context(@alias_map[name.downcase])
+          return [build_meta_entry(brain_name, category, data)] if data
+        end
+
+        # Substring match
+        matches = []
+        @index['categories'].each do |category_name, category_data|
+          category_data['brains'].each do |bname, bdata|
+            matches << build_meta_entry(bname, category_name, bdata) if bname.downcase.include?(name.downcase)
+          end
+        end
+        return matches if matches.any?
+
+        # Tag match
+        tag = name.downcase.gsub('_', '-')
+        (@index['tag_index']&.[](tag) || []).filter_map do |bname|
+          brain_name, category, data = find_brain_with_context(bname)
+          build_meta_entry(brain_name, category, data) if data
+        end
+      end
+
+      def find_brain_with_context(brain_name)
+        @index['categories'].each do |category_name, category_data|
+          data = category_data['brains'][brain_name]
+          return [brain_name, category_name, data] if data
+        end
+        [nil, nil, nil]
+      end
 
-        # Check if activity level matches filter
-        @options.activity_levels.include?(entry['activity_level'])
+      def build_meta_entry(name, category, data)
+        {
+          'name' => name,
+          'category' => category,
+          'activity_level' => data['activity_level'],
+          'status' => data['status'],
+          'tags' => data['tags'] || [],
+          'file_count' => data['file_count'] || 0
+        }
       end
     end
   end

data/lib/appydave/tools/brain_context/omi_finder.rb

@@ -13,28 +13,39 @@ module Appydave
       def find
         return [] unless @options.omi_query?
 
-        paths = []
+        resolve_days!
+        paths = each_matching.map { |file_path, _frontmatter| file_path }
+        paths = paths.last(@options.limit) if @options.limit
+        paths
+      end
 
-        Dir.glob(File.join(@options.omi_dir, '*.md')).each do |file_path|
-          next unless include_file?(file_path)
+      def find_meta
+        return [] unless @options.omi_query?
 
-          paths << file_path
+        resolve_days!
+        entries = each_matching.map do |file_path, frontmatter|
+          build_omi_meta(file_path, frontmatter)
         end
-
-        paths.sort
+        entries = entries.last(@options.limit) if @options.limit
+        entries
       end
 
       private
 
-      def include_file?(file_path)
-        frontmatter = extract_frontmatter(file_path)
-        return false unless frontmatter
+      def each_matching
+        results = []
+        Dir.glob(File.join(@options.omi_dir, '*.md')).sort.each do |file_path|
+          frontmatter = extract_frontmatter(file_path)
+          next unless frontmatter
+          next unless passes_filters?(frontmatter)
 
-        # If enriched-only requested, skip raw files
-        return false if @options.enriched_only && (!frontmatter['signal'] || !frontmatter['extraction_summary'])
+          results << [file_path, frontmatter]
+        end
+        results
+      end
 
-        # Apply filters
-        return false unless signal_matches?(frontmatter)
+      def passes_filters?(frontmatter)
+        return false if @options.enriched_only && (!frontmatter['signal'] || !frontmatter['extraction_summary'])
         return false unless routing_matches?(frontmatter)
         return false unless activity_matches?(frontmatter)
         return false unless date_matches?(frontmatter)
@@ -43,6 +54,20 @@ module Appydave
         true
       end
 
+      def build_omi_meta(file_path, frontmatter)
+        {
+          'file' => File.basename(file_path),
+          'extracted_at' => frontmatter['extracted_at'],
+          'extraction_summary' => frontmatter['extraction_summary'],
+          'matched_brains' => frontmatter['matched_brains'] || [],
+          'activity' => frontmatter['activity'],
+          'routing' => frontmatter['routing'],
+          'entities_tools' => frontmatter['entities_tools'] || [],
+          'entities_projects' => frontmatter['entities_projects'] || [],
+          'entities_concepts' => frontmatter['entities_concepts'] || []
+        }
+      end
+
       def extract_frontmatter(file_path)
         content = File.read(file_path, encoding: 'utf-8')
         lines = content.split("\n")
@@ -91,13 +116,10 @@ module Appydave
         [key, value]
       end
 
-      def signal_matches?(frontmatter)
-        return true if @options.omi_signals.empty?
-
-        signal = frontmatter['signal']
-        return false unless signal
+      def resolve_days!
+        return unless @options.days
 
-        @options.omi_signals.include?(signal)
+        @options.date_from = (Date.today - @options.days).to_s
       end
 
       def routing_matches?(frontmatter)

data/lib/appydave/tools/brain_context/options.rb

@@ -4,26 +4,26 @@ module Appydave
   module Tools
     # Options struct for brain/OMI query tools
     class BrainContextOptions
-      attr_accessor :brain_names, :tags, :categories, :activity_levels, :status,
-                    :omi, :omi_signals, :omi_routings, :omi_activities,
-                    :date_from, :date_to, :enriched_only,
+      attr_accessor :brain_names, :categories, :active, :meta,
+                    :omi, :omi_routings, :omi_activities,
+                    :date_from, :date_to, :enriched_only, :days, :limit,
                     :include_index, :output_targets, :formats, :line_limit,
                     :debug_level, :dry_run, :tokens, :base_dir, :omi_dir
 
       def initialize
         @brain_names = []
-        @tags = []
         @categories = []
-        @activity_levels = []
-        @status = 'active' # default: exclude deprecated
+        @active = false
+        @meta = false
 
         @omi = false
-        @omi_signals = []
         @omi_routings = []
         @omi_activities = []
         @date_from = nil
         @date_to = nil
-        @enriched_only = false
+        @enriched_only = true
+        @days = nil
+        @limit = nil
 
         @include_index = true
         @output_targets = ['clipboard'] # default to clipboard
@@ -46,7 +46,7 @@ module Appydave
       end
 
       def brain_query?
-        brain_names.any? || tags.any? || categories.any? || activity_levels.any?
+        brain_names.any? || categories.any? || active
       end
 
       def omi_query?

data/lib/appydave/tools/version.rb

@@ -2,6 +2,6 @@
 
 module Appydave
   module Tools
-    VERSION = '0.80.0'
+    VERSION = '0.81.0'
   end
 end

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appydave-tools",
-  "version": "0.80.0",
+  "version": "0.81.0",
   "description": "AppyDave YouTube Automation Tools",
   "scripts": {
     "release": "semantic-release"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: appydave-tools
 version: !ruby/object:Gem::Version
-  version: 0.80.0
+  version: 0.81.0
 platform: ruby
 authors:
 - David Cruwys
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-03 00:00:00.000000000 Z
+date: 2026-04-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -285,6 +285,8 @@ files:
 - docs/guides/platforms/windows/README.md
 - docs/guides/platforms/windows/dam-testing-plan-windows-powershell.md
 - docs/guides/platforms/windows/installation.md
+- docs/guides/query-tools-handover.md
+- docs/guides/query-tools.md
 - docs/guides/tools/bank-reconciliation.md
 - docs/guides/tools/cli-actions.md
 - docs/guides/tools/configuration.md