appydave-tools 0.79.0 → 0.81.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec01667ec40e9b0b051f2e834800cd458c736f27107df033ddebeaf7de413823
-  data.tar.gz: 6627f68aefaf25f40cd7d55ba87e8470bd8e5c5a99146927424149b84a31b3b6
+  metadata.gz: '09f48a7490c924291dff958e3df8ba53c28c2dae599cae0ab8581ac3e4ad3ee2'
+  data.tar.gz: f1e55198dd31bb3b2b61b61d4f929fc3bda799ecd4cedb96e5f810c994edae4a
 SHA512:
-  metadata.gz: 8e745ed73fc0f812a6275edb827df2901e5eb0b41c060b4ac68fdc27c9eff750b60b84d2244e21f2b6afb2cda98eacacc3895b6c82502673162202cb31075ddb
-  data.tar.gz: 1814d3250ecf2aebf1ccb9cf50e117fc7b9f220334c263b5b1677336848db1cd7e37f9b684df2903aba96ecc69bbad96368c1acc87fbd6addfed4086eeffe00a
+  metadata.gz: 9d4f2bc474af95d2ff538d5360d9ec659b559f155b611c9b7c13f9c475118311a1fc99a40b1f3fc6655b20bee568a3c5fcb4466f709eef948cd400d4efee6709
+  data.tar.gz: 84af7abbcc284e85742f1db64737622e8c929b57815988908a2aba716d970adcfd0f52e29f7a432fb2d544fd8be950fd27254d7ec61fdf705802c126b34e6d84

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+# [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)
+
+
+### Features
+
+* add --stdin support to llm_context for piping file paths ([8890cfe](https://github.com/appydave/appydave-tools/commit/8890cfebb80cfda81b679da3e52a185bbb1c9141))
+
 # [0.78.0](https://github.com/appydave/appydave-tools/compare/v0.77.7...v0.78.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

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+require 'appydave/tools'
+
+options = Appydave::Tools::BrainContextOptions.new
+
+def setup_options(options)
+  OptionParser.new do |opts| # rubocop:disable Metrics/BlockLength
+    opts.banner = 'Usage: query_brain [options]'
+
+    opts.on('--find TERM', 'Find brain by name, tag, or alias (repeatable)') do |term|
+      options.brain_names << term
+    end
+
+    opts.on('--category CAT', 'Find all brains in category (repeatable)') do |cat|
+      options.categories << cat
+    end
+
+    opts.on('--active', 'Return all high-activity brains') do
+      options.active = true
+    end
+
+    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
+      options.include_index = false
+    end
+
+    opts.on('-d', '--debug [MODE]', %w[none info params debug],
+            'Debug output level') do |level|
+      options.debug_level = level || 'info'
+    end
+
+    opts.on('-v', '--version', 'Show version') do
+      puts "query_brain v#{Appydave::Tools::VERSION}"
+      exit 0
+    end
+
+    opts.on('-h', '--help', 'Show this message') do
+      puts opts
+      exit 0
+    end
+  end.parse!
+end
+
+setup_options(options)
+
+# Query
+finder = Appydave::Tools::BrainQuery.new(options)
+
+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

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+require 'appydave/tools'
+
+options = Appydave::Tools::BrainContextOptions.new
+options.omi = true
+
+def setup_options(options)
+  OptionParser.new do |opts| # rubocop:disable Metrics/BlockLength
+    opts.banner = 'Usage: query_omi [options]'
+
+    opts.on('--brain NAME', 'Find OMI sessions mentioning this brain') do |name|
+      options.brain_names << name
+    end
+
+    opts.on('--routing ROUTING',
+            'Filter by routing (brain-update, todo-item, personal, til, archive; pipe-delimited)') do |routing|
+      options.omi_routings.concat(routing.split('|').map(&:strip))
+    end
+
+    opts.on('--activity ACTIVITY',
+            'Filter by activity (planning, reviewing, learning, debugging, etc.; pipe-delimited)') do |activity|
+      options.omi_activities.concat(activity.split('|').map(&:strip))
+    end
+
+    opts.on('--days N', Integer, 'Include sessions from the last N days') do |n|
+      options.days = n
+    end
+
+    opts.on('--meta', 'Return metadata as JSON instead of file paths') do
+      options.meta = true
+    end
+
+    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],
+            'Debug output level') do |level|
+      options.debug_level = level || 'info'
+    end
+
+    opts.on('-v', '--version', 'Show version') do
+      puts "query_omi v#{Appydave::Tools::VERSION}"
+      exit 0
+    end
+
+    opts.on('-h', '--help', 'Show this message') do
+      puts opts
+      exit 0
+    end
+  end.parse!
+end
+
+setup_options(options)
+
+# Query
+finder = Appydave::Tools::OmiQuery.new(options)
+
+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/exe/query_brain

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+require 'appydave/tools'
+
+load File.expand_path('../bin/query_brain.rb', __dir__)

data/exe/query_omi

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+require 'appydave/tools'
+
+load File.expand_path('../bin/query_omi.rb', __dir__)

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

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Appydave
+  module Tools
+    # Queries brains-index.json to find brain files
+    class BrainQuery
+      def initialize(options)
+        @options = options
+        @index = nil
+        @alias_map = nil
+      end
+
+      def find
+        return [] unless @options.brain_query?
+
+        load_index!
+        paths = []
+
+        # 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 category queries
+        @options.categories.each do |category|
+          paths.concat(find_by_category(category))
+        end
+
+        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!
+        return if @index
+
+        index_path = @options.brains_index_path
+        unless File.exist?(index_path)
+          raise "brains-index.json not found at #{index_path}. Run: python ~/dev/ad/brains/.claude/skills/brain-librarian/scripts/build_brain_index.py build --all ~/dev/ad/brains"
+        end
+
+        @index = JSON.parse(File.read(index_path))
+        build_alias_map!
+      end
+
+      def build_alias_map!
+        @alias_map = {}
+        @index['alias_index']&.each { |alias_name, brain_name| @alias_map[alias_name.downcase] = brain_name }
+      end
+
+      def find_by_name(name)
+        load_index!
+
+        # Step 1: Exact match on brain key
+        brain_entry = find_brain_in_index(name)
+        return brain_entries_to_paths([brain_entry]) if brain_entry
+
+        # Step 2: Alias match
+        if @alias_map && @alias_map[name.downcase]
+          brain_name = @alias_map[name.downcase]
+          brain_entry = find_brain_in_index(brain_name)
+          return brain_entries_to_paths([brain_entry]) if brain_entry
+        end
+
+        # Step 3: Substring match on brain key (case-insensitive)
+        matches = []
+        @index['categories'].each_value do |category_data|
+          category_data['brains'].each do |brain_name, brain_data|
+            matches << brain_data if brain_name.downcase.include?(name.downcase)
+          end
+        end
+        return brain_entries_to_paths(matches) if matches.any?
+
+        # Step 4: Tag match (so --find works for tags too)
+        find_by_tag(name)
+      end
+
+      def find_by_tag(tag)
+        load_index!
+        tag = tag.downcase.gsub('_', '-')
+
+        brain_names = @index['tag_index']&.[](tag) || []
+        brain_entries = []
+
+        brain_names.each do |brain_name|
+          entry = find_brain_in_index(brain_name)
+          brain_entries << entry if entry
+        end
+
+        brain_entries_to_paths(brain_entries)
+      end
+
+      def find_by_category(category)
+        load_index!
+        category_data = @index['categories'][category] || @index['categories'][category.downcase]
+
+        return [] unless category_data
+
+        brain_entries = category_data['brains'].values
+        brain_entries_to_paths(brain_entries)
+      end
+
+      def find_brain_in_index(brain_name)
+        @index['categories'].each_value do |category_data|
+          return category_data['brains'][brain_name] if category_data['brains'][brain_name]
+        end
+        nil
+      end
+
+      def brain_entries_to_paths(brain_entries)
+        paths = []
+
+        brain_entries.each do |entry|
+          next unless entry
+
+          # Add files from files[] array
+          entry['files']&.each do |file|
+            # File entry is relative to the brain directory
+            brain_name = extract_brain_name(entry)
+            full_path = File.join(@options.brains_root, brain_name, file)
+            paths << full_path if File.exist?(full_path)
+          end
+
+          # Add INDEX.md if requested
+          if @options.include_index
+            index_path = File.join(@options.brains_root, entry['index_path'])
+            paths << index_path if File.exist?(index_path)
+          end
+        end
+
+        paths
+      end
+
+      def extract_brain_name(entry)
+        # index_path is like "brain-name/INDEX.md"
+        entry['index_path'].split('/')[0]
+      end
+
+      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 ---
+
+      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
+
+      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
+end

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

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module Appydave
+  module Tools
+    # Queries OMI transcript directory by enriched frontmatter
+    class OmiQuery
+      def initialize(options)
+        @options = options
+      end
+
+      def find
+        return [] unless @options.omi_query?
+
+        resolve_days!
+        paths = each_matching.map { |file_path, _frontmatter| file_path }
+        paths = paths.last(@options.limit) if @options.limit
+        paths
+      end
+
+      def find_meta
+        return [] unless @options.omi_query?
+
+        resolve_days!
+        entries = each_matching.map do |file_path, frontmatter|
+          build_omi_meta(file_path, frontmatter)
+        end
+        entries = entries.last(@options.limit) if @options.limit
+        entries
+      end
+
+      private
+
+      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)
+
+          results << [file_path, frontmatter]
+        end
+        results
+      end
+
+      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)
+        return false unless brain_matches?(frontmatter)
+
+        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")
+
+        return nil unless lines[0] == '---'
+
+        frontmatter = {}
+        i = 1
+        while i < lines.length
+          line = lines[i]
+          break if line == '---'
+
+          # Parse YAML-like: key: value
+          if line.match?(/^[a-z_]+:/)
+            key, value = parse_yaml_line(line)
+            frontmatter[key] = value
+          end
+
+          i += 1
+        end
+
+        frontmatter.empty? ? nil : frontmatter
+      end
+
+      def parse_yaml_line(line)
+        # Handle simple cases: key: value, key: [a, b, c]
+        match = line.match(/^([a-z_]+):\s*(.*)$/)
+        return [nil, nil] unless match
+
+        key = match[1]
+        value_str = match[2].strip
+
+        # Parse array [a, b, c]
+        if value_str.start_with?('[') && value_str.end_with?(']')
+          array_content = value_str[1..-2]
+          value = array_content.split(',').map { |v| v.strip.gsub(/^["']|["']$/, '') }
+        # Parse quoted string
+        elsif (value_str.start_with?('"') && value_str.end_with?('"')) ||
+              (value_str.start_with?("'") && value_str.end_with?("'"))
+          value = value_str[1..-2]
+        # Parse date (YYYY-MM-DD) or other values as-is
+        else
+          value = value_str
+        end
+
+        [key, value]
+      end
+
+      def resolve_days!
+        return unless @options.days
+
+        @options.date_from = (Date.today - @options.days).to_s
+      end
+
+      def routing_matches?(frontmatter)
+        return true if @options.omi_routings.empty?
+
+        routing = frontmatter['routing']
+        return false unless routing
+
+        # routing can be pipe-delimited
+        routings = routing.split('|').map(&:strip)
+        routings.any? { |r| @options.omi_routings.include?(r) }
+      end
+
+      def activity_matches?(frontmatter)
+        return true if @options.omi_activities.empty?
+
+        activity = frontmatter['activity']
+        return false unless activity
+
+        # activity can be pipe-delimited
+        activities = activity.split('|').map(&:strip)
+        activities.any? { |a| @options.omi_activities.include?(a) }
+      end
+
+      def date_matches?(frontmatter)
+        extracted_at = frontmatter['extracted_at']
+        return true if extracted_at.nil? # No date field = include
+
+        begin
+          date = Date.parse(extracted_at)
+        rescue StandardError
+          return true # Can't parse = include
+        end
+
+        from_ok = @options.date_from.nil? || date >= Date.parse(@options.date_from)
+        to_ok = @options.date_to.nil? || date <= Date.parse(@options.date_to)
+
+        from_ok && to_ok
+      end
+
+      def brain_matches?(frontmatter)
+        return true if @options.brain_names.empty?
+
+        matched_brains = frontmatter['matched_brains']
+        return false unless matched_brains
+
+        # matched_brains is an array
+        matched_brains_list = matched_brains.is_a?(Array) ? matched_brains : [matched_brains]
+        matched_brains_list.any? { |brain| @options.brain_names.include?(brain) }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Appydave
+  module Tools
+    # Options struct for brain/OMI query tools
+    class BrainContextOptions
+      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 = []
+        @categories = []
+        @active = false
+        @meta = false
+
+        @omi = false
+        @omi_routings = []
+        @omi_activities = []
+        @date_from = nil
+        @date_to = nil
+        @enriched_only = true
+        @days = nil
+        @limit = nil
+
+        @include_index = true
+        @output_targets = ['clipboard'] # default to clipboard
+        @formats = ['content']
+        @line_limit = nil
+        @debug_level = 'none'
+        @dry_run = false
+        @tokens = false
+        @base_dir = Dir.pwd
+
+        @omi_dir = File.expand_path('~/dev/raw-intake/omi')
+      end
+
+      def brains_root
+        @brains_root ||= File.expand_path('~/dev/ad/brains')
+      end
+
+      def brains_index_path
+        File.join(brains_root, 'audit', 'brains-index.json')
+      end
+
+      def brain_query?
+        brain_names.any? || categories.any? || active
+      end
+
+      def omi_query?
+        omi
+      end
+    end
+  end
+end

data/lib/appydave/tools/version.rb

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

data/lib/appydave/tools.rb

@@ -37,6 +37,10 @@ require 'appydave/tools/llm_context/options'
 require 'appydave/tools/llm_context/file_collector'
 require 'appydave/tools/llm_context/output_handler'
 
+require 'appydave/tools/brain_context/options'
+require 'appydave/tools/brain_context/brain_finder'
+require 'appydave/tools/brain_context/omi_finder'
+
 require 'appydave/tools/configuration/openai'
 require 'appydave/tools/configuration/configurable'
 require 'appydave/tools/configuration/config'

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appydave-tools",
-  "version": "0.79.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.79.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
@@ -190,6 +190,8 @@ executables:
 - jump
 - llm_context
 - prompt_tools
+- query_brain
+- query_omi
 - subtitle_processor
 - youtube_automation
 - youtube_manager
@@ -229,6 +231,8 @@ files:
 - bin/llm_context.rb
 - bin/move_images.rb
 - bin/prompt_tools.rb
+- bin/query_brain.rb
+- bin/query_omi.rb
 - bin/setup
 - bin/subtitle_manager-old.rb
 - bin/subtitle_manager.rb
@@ -281,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
@@ -338,12 +344,17 @@ files:
 - exe/jump
 - exe/llm_context
 - exe/prompt_tools
+- exe/query_brain
+- exe/query_omi
 - exe/subtitle_processor
 - exe/youtube_automation
 - exe/youtube_manager
 - exe/zsh_history
 - images.log
 - lib/appydave/tools.rb
+- lib/appydave/tools/brain_context/brain_finder.rb
+- lib/appydave/tools/brain_context/omi_finder.rb
+- lib/appydave/tools/brain_context/options.rb
 - lib/appydave/tools/cli_actions/_doc.md
 - lib/appydave/tools/cli_actions/base_action.rb
 - lib/appydave/tools/cli_actions/get_video_action.rb