appydave-tools 0.84.0 → 0.85.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbde49937db92444ee47416c1fbd53d0cd3ca6c99bc65b30e30a58cf2490facc
-  data.tar.gz: 1807239701f53c00bd7e692c51e6792056b2e951d0b71720059fdd5c5fbd4414
+  metadata.gz: 9bdf9ee95d2587f01a5939fc780148a9da0bdc06c5acac865dc36077d34181c9
+  data.tar.gz: 54f137a91341ec1b9487a7dc68fd44c837d2a53d52181dd7681d0f1a11135062
 SHA512:
-  metadata.gz: be1b84a9fb1b45b7377c8cc0e0371f234b5b56e96f23a44f1733e6face17c489a288bd3f8128a5e8548eb09247ff3deffd38144eb6480214b5ba8401406bf022
-  data.tar.gz: e3cffdedb85686158bc251361f04b0b2ea44f354f472968efd92bf84c165dd1aa69ca37aa0e1105c191b5f84d70ccccbf0ed7e9418e0e194dbf1a1dceca0bfd8
+  metadata.gz: 216862256621db14b1384bfdef38d34749f734601d9c382497a0193240eda80227cffb2940daa8326f30154bfb48b2404af48e5ccf9f54f52d1a7042721b7dae
+  data.tar.gz: 205f2cd87df58e2c12b426aceea29c7c1dd88e52622e5fff889d8d655f1ad572621d795718f5ea0d7e603663cbc3acd2f5ac1a04f765144e5b6de3dc9361abdb

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.84.0](https://github.com/appydave/appydave-tools/compare/v0.83.0...v0.84.0) (2026-04-05)
+
+
+### Features
+
+* add jump query subcommand for scriptable location lookup ([fe3429b](https://github.com/appydave/appydave-tools/commit/fe3429bc08ccb6167c1a0575c2154852fba29ccd))
+
 # [0.83.0](https://github.com/appydave/appydave-tools/compare/v0.82.0...v0.83.0) (2026-04-04)
 
 

data/CLAUDE.md

@@ -27,7 +27,7 @@ Two-phase validation for the 75-commit DAM enhancement sprint (9e49668 → 4228b
 - **Shareable individually** - Tools can be featured in standalone videos
 - **Language flexible** - Currently Ruby, could be rewritten if needed
 
-**System context**: See [CONTEXT.md](CONTEXT.md) for purpose, domain concepts, design rationale, and scope boundaries.
+**System context**: See [CONTEXT.md](CONTEXT.md) for purpose, core abstractions, key workflows, design decisions, non-obvious constraints, expert mental model, scope limits, and failure modes.
 
 ## Documentation Discovery Protocol
 

data/CONTEXT.md

@@ -1,5 +1,5 @@
 ---
-generated: 2026-04-03
+generated: 2026-04-05
 generator: system-context
 status: snapshot
 sources:
@@ -8,37 +8,147 @@ sources:
   - lib/appydave/tools.rb
   - lib/appydave/tools/dam/brand_resolver.rb
   - lib/appydave/tools/dam/project_resolver.rb
+  - lib/appydave/tools/jump/config.rb
   - lib/appydave/tools/jump/commands/generate.rb
-  - docs/dam/batch-s3-listing-requirements.md
-  - CHANGELOG.md (versions 0.76.0-0.77.7)
+  - lib/appydave/tools/brain_context/brain_finder.rb
+  - lib/appydave/tools/brain_context/options.rb
+  - lib/appydave/tools/app_context/app_finder.rb
+  - lib/appydave/tools/app_context/globs_loader.rb
+  - lib/appydave/tools/app_context/options.rb
+  - lib/appydave/tools/configuration/models/settings_config.rb
+  - lib/appydave/tools/configuration/example_installer.rb
+  - lib/appydave/tools/zsh_history/config.rb
+  - lib/appydave/tools/zsh_history/filter.rb
+  - docs/planning/multi-user-support.md
+  - docs/planning/query-apps-design.md
+  - docs/planning/query-skills-plan.md
+  - CHANGELOG.md
+  - context.globs.json
 regenerate: "Run /appydave:system-context in the repo root"
 ---
 
 # AppyDave Tools — System Context
 
 ## Purpose
-Eliminate repetitive manual tasks from YouTube content creation workflows by bundling single-purpose CLI utilities that operate independently on video projects, metadata, and assets.
+Eliminate repetitive manual tasks from a solo YouTube content creator's workflow by bundling single-purpose CLI utilities — for file discovery, asset management, knowledge querying, and LLM context assembly — in one Ruby gem that multiple developers can independently configure and install.
 
-## Domain Concepts
-- **Brand** — A business entity that owns video projects (AppyDave, VOZ, SupportSignal, etc.). Shortcuts (ad, joy, ss) resolve to brand keys (appydave, beauty-and-joy, supportsignal) in configs.
-- **Project** — A discrete video deliverable. Named by pattern: FliVideo uses short codes (b65 → expands to b65-guy-monroe-marketing-plan), Storyline uses full names (boy-baker). Projects contain assets, metadata, and source files.
-- **Digital Asset Management (DAM)** — Hybrid 3-tier storage: local working copies → S3 staging for collaboration (90-day lifecycle) → SSD archive for long-term cold storage. Orchestrates file sync and lifecycle across tiers.
-- **Project Naming Patterns** — FliVideo: `b<num>` (short) expands to `b<num>-*` full name. Patterns like `b6*` match b60-b69. Storyline uses exact full names (no expansion).
-- **Configuration-driven Architecture** — JSON configs (settings, channels, brands) stored in `~/.config/appydave/` per developer; secrets (.env) gitignored. Enables team collaboration: shared structure, per-dev customization.
-- **Multi-channel YouTube Management** — Handles multiple YouTube channels (each with code, name, handle, locations). Single tool manages metadata updates across channels.
+## Core Abstractions
+
+- **Location** — A named, user-specific folder registered in `~/.config/appydave/locations.json`. Every query tool (jump, query_apps, query_brain, query_omi) uses locations as its resolution anchor. A location has a `key` (canonical name), `path` (machine-specific), optional `jump` alias, and optional `context` pointer to `CONTEXT.md`. Without locations, no tool can find anything.
+
+- **Query Ecosystem** — Three tools that each output file paths on stdout: `query_brain` (finds second-brain knowledge files via `brains-index.json`), `query_omi` (finds OMI wearable transcript sessions), and `query_apps` (finds project source files via `context.globs.json`). All three feed into `llm_context`, which assembles the paths into formatted content for an LLM. The tools are composable by design — the output of any query tool can be piped to `llm_context --stdin`.
+
+- **DAM (Digital Asset Management)** — Hybrid 3-tier storage for video project files: local working copies → S3 staging for team collaboration (90-day lifecycle) → SSD for cold archive. Operates on whole project directories as atomic units. Multi-tenant: a single tool manages assets for 6 brands (appydave, voz, aitldr, kiros, joy, ss), each with independent S3 buckets and SSD paths.
+
+- **Brand/Project Resolution** — A two-step lookup used by DAM. `BrandResolver` maps shorthand brand codes (`ad`, `ss`) to config keys (`appydave`, `supportsignal`). `ProjectResolver` maps short codes (`b65`) to full project names (`b65-guy-monroe-marketing-plan`) using glob expansion. Decouples what users type from what the filesystem requires.
+
+- **context.globs.json** — A sidecar file generated by the `system-context` skill alongside each project's `CONTEXT.md`. Contains named glob patterns (`docs`, `services`, `types`), aliases (`backend` → services + routes), and composites (`understand` → context + docs + types + config). `query_apps` reads this file; `GlobsLoader` handles 3-tier resolution (direct name → alias → composite → substring fuzzy fallback). Projects without this file are invisible to `query_apps`.
+
+- **Settings Config** — Per-user JSON at `~/.config/appydave/settings.json`. Provides the canonical store for machine-specific paths that tools resolve at runtime: `video-projects-root`, `brains-root-path`, `omi-directory-path`, `aliases-output-path`. Tools read settings via `Configuration::Config.settings.get(key)` and fall back to hardcoded defaults if the key is absent.
+
+## Key Workflows
+
+### Assemble LLM Context from a Project
+1. User identifies the project they want context for (e.g., `flihub`)
+2. `query_apps flihub --glob understand` resolves the app via `locations.json`, reads `flihub/context.globs.json`, and expands the `understand` composite (context + docs + types + config) to a list of absolute file paths
+3. Paths are piped to `llm_context --stdin -f content --smart`
+4. `llm_context` reads each file, formats it with headers, estimates token count, and routes output to clipboard (≤100k tokens) or a temp file (larger)
+5. User pastes the assembled content into their LLM session
+
+### Query the Second Brain for a Topic
+1. User knows a topic or brain name (e.g., `paperclip`, `agent-systems`)
+2. `query_brain --find paperclip` loads `brains-index.json` (pre-built by `build_brain_index.py`), resolves the name through 4 tiers (exact key → alias → substring → tag match), and returns absolute paths to brain files
+3. Optionally `--files-only` to exclude `INDEX.md`; `--meta` to return JSON instead of paths
+4. User pipes to `llm_context --stdin -f content --smart` or reviews paths directly
+
+### Video Project Collaboration via DAM
+1. Videographer has edited files in a local video project (e.g., `b65-guy-monroe-marketing-plan`)
+2. `dam s3-up appydave b65` resolves brand → config → S3 bucket, computes MD5 checksums for all files, uploads only changed files to S3
+3. Collaborator runs `dam s3-down appydave b65` on their machine — same MD5 logic skips unchanged files
+4. When the project is complete, `dam archive appydave b65` moves it to the external SSD; S3 lifecycle policy removes it after 90 days
+
+### Onboard a New Developer (Multi-user)
+1. New user runs `gem install appydave-tools`
+2. `ad_config -c` creates the `~/.config/appydave/` directory structure with all config templates from the gem's bundled `config/examples/*.example.*` files (via `ExampleInstaller`)
+3. User edits `settings.json` to set their machine-specific paths (`video-projects-root`, `brains-root-path`, etc.)
+4. User populates `locations.json` with their project paths and runs `jump generate` to produce shell aliases
+5. User sources the generated aliases file from their `.zshrc` to activate `j<alias>` navigation
+
+### ZSH History Crash Recovery
+1. After a terminal crash or mid-session confusion, user runs `zsh_history --profile crash-recovery`
+2. `ZshHistory::Filter` loads config from `~/.config/appydave/zsh_history/` — base exclude patterns (noise) plus profile-specific include/exclude patterns
+3. Commands are classified into `wanted` (matched include patterns), `unwanted` (matched exclude), or `unsure` (matched neither)
+4. User reviews the `wanted` list to reconstruct what they were working on before the crash
 
 ## Design Decisions
-- **Single consolidated repository** — instead of separate gems per tool. Reduces maintenance overhead, enables code reuse, allows individual tools to be featured in standalone tutorials.
-- **Single-purpose tools that operate independently** — each CLI does one thing (llm_context, youtube_manager, dam, etc.). Prevents feature creep, keeps coupling low, enables composition.
-- **Configuration as data** — JSON files enable team sharing of project structure + team-specific path customization in .env. Separates secrets (API keys) from configuration (paths, channels).
-- **Hybrid storage lifecycle** — S3 for short-term collaboration, SSD for archive. Balances cost (S3 pay-per-access), availability (local for daily work), and durability (SSD backup).
-- **Brand/Project resolution layer** — BrandResolver + ProjectResolver decouple CLI input (shortcuts like ad, b65) from system state (config keys, full paths). Users type short codes; system maps to canonical names.
-- **Parallel status checking** — `dam list <brand> --s3` parallelizes git and S3 status checks instead of N sequential API calls. Reduces list latency from 3-5s to <1s.
+
+- **Single consolidated repository** instead of separate gems per tool. Reduces maintenance overhead, allows code reuse (e.g., `BrainContextOptions` shared by both `query_brain` and `query_omi`), and enables individual tools to be featured in standalone tutorials without needing cross-gem dependency management.
+  - *Alternative considered*: One gem per tool
+  - *Why rejected*: Separate gems double the CI setup, versioning work, and gem publish steps per tool added; the tools share too much infrastructure (config, settings, output handling)
+
+- **Configuration as data in `~/.config/appydave/`** — JSON files per user, secrets in `.env`, structure in JSON. This means the gem can be shared via RubyGems.org with zero David-specific paths baked in. Each user configures their own machine independently.
+  - *Alternative considered*: Bundled config files committed to the repo
+  - *Why rejected*: Binds the gem to one user's machine layout; makes it impossible for Lars or anyone else to install without overwriting David's paths
+
+- **Query tools output file paths, not content** — `query_brain`, `query_omi`, `query_apps` all emit one path per line. This makes them pipe-composable with `llm_context`, `xargs`, or any Unix tool without intermediate temp files.
+  - *Alternative considered*: Query tools output content directly
+  - *Why rejected*: Conflates discovery (which files?) with assembly (what format?); forces the query tool to duplicate output logic that `llm_context` already owns
+
+- **context.globs.json as a sidecar file** — Named glob patterns live in each project root, not in a central registry. This means each project self-describes its own structure; no central config needs updating when a project is restructured.
+  - *Alternative considered*: Central registry mapping project keys to glob patterns
+  - *Why rejected*: Central registry goes stale as projects evolve; a sidecar file is updated when `system-context` is re-run in that project
+
+- **Hybrid S3 + SSD storage** for DAM. S3 handles team collaboration (anyone with credentials can push/pull); SSD handles archival (local, fast, no recurring cost for cold files).
+  - *Alternative considered*: S3-only or git-lfs
+  - *Why rejected*: S3-only means paying for cold storage indefinitely; git-lfs can't handle 50GB+ video files with binary diffs
+
+- **MD5-based sync** instead of timestamp comparison in DAM. MD5 checksums correctly detect when a file has been re-encoded identically (same content, new timestamp) — common when re-exporting video.
+  - *Alternative considered*: rsync with `--update` (timestamp-based)
+  - *Why rejected*: Video export tools reset timestamps on every render even for identical output; timestamp sync would re-upload unnecessarily every time
+
+## Non-obvious Constraints
+
+- **`query_brain` requires `brains-index.json` to exist** — it does not scan the brains folder directly. The index is built by a separate Python script (`build_brain_index.py`) in the `brain-librarian` skill. If the index is missing or stale, `query_brain` raises a descriptive error pointing to the build command. A new developer who hasn't run `brain-librarian` will see this error immediately.
+
+- **`query_apps` requires `context.globs.json` in each project root** — it does not fall back to filesystem scanning. A project that has never had `/system-context` run against it is simply invisible to `query_apps --list-apps`. The `--list-apps` command will show zero results for that project even if `locations.json` knows about it.
+
+- **`brains-root-path` and `omi-directory-path` in settings.json override the hardcoded defaults** — but silently do nothing if the key is missing. `BrainContextOptions` falls back to `~/dev/ad/brains` and `~/dev/raw-intake/omi` respectively. A developer on a different machine layout must set these keys explicitly; there is no warning if the default paths don't exist.
+
+- **Jump aliases require manual shell sourcing** — `jump generate` writes a `.aliases` file (path configured by `aliases-output-path` in settings.json) but does NOT source it automatically. The user must add `source <path>` to their `.zshrc`. Running `jump generate` without sourcing produces no visible `j<alias>` commands in the current shell.
+
+- **DAM brand resolution is case-sensitive at the config level** — `BrandResolver` lowercases input before lookup, so `vat s3-up AppyDave b65` works. But `settings.json` and `channels.json` keys must be lowercase. A brand key `AppyDave` in the config will never match.
+
+- **ZshHistory filter applies exclude before include** — a command that matches both an exclude pattern and an include pattern is classified as `unwanted`. Exclude wins. This matters when writing profile-specific patterns: a general exclude like `^cd` will suppress `^cd ~/dev` even if the include pattern explicitly lists it.
+
+## Expert Mental Model
+
+- **Think of locations.json as the root of all resolution** — every query tool starts here. An expert's first debugging step when a tool can't find a project is to verify the project exists in `locations.json`, that its `path` is correct on this machine, and that `query_apps` requires a `context.globs.json` at that path. The tool chain is: `locations.json` → `context.globs.json` → filesystem. A break at any link silently returns empty results, not an error.
+
+- **The query ecosystem is a pipeline, not a single command** — an expert treats `query_brain`, `query_omi`, `query_apps` as interchangeable producers and `llm_context` as the sole consumer. The skill layer (`/omi-query`, `/app-query`, `/brain-query`) is just documentation for Claude Code about how to invoke the producers. An expert composes them with `|` and uses `--meta` when they need to reason about what exists before deciding what to fetch.
+
+- **Settings config is the machine-portability layer** — an expert keeps all hardcoded paths out of gem code and inside `settings.json`. When something works on David's machine but fails on Lars's, the root cause is almost always a missing or wrong key in `settings.json`. The key names are documented in `SettingsConfig` as named methods (`brains_root_path`, `omi_directory_path`, etc.) — reading that file tells you exactly what keys each tool expects.
+
+- **ExampleInstaller is the onboarding contract** — the `config/examples/` directory inside the gem is the canonical template for a correct initial config. When adding a new config key, an expert updates both `SettingsConfig` (for named accessor) and the relevant `*.example.json` file (so new users get it on `ad_config -c`).
 
 ## Scope Limits
-- Does NOT edit video files directly — only manages metadata, assets, and file organization. Video editing remains in post-production tools (Premiere, DaVinci, etc.).
-- Does NOT provide local playback or streaming — focuses on storage, sync, and metadata. Video playback via external players or YouTube.
-- Does NOT implement YouTube OAuth UI — wraps Google's authentication library. OAuth token generation handled by google-api-client flows, not custom UI.
-- Does NOT manage individual files in DAM — operates on whole project directories as atomic units. Granular file operations are external (rsync, direct S3 CLI).
-- Does NOT provide IDE integration for Jump tool — generates shell aliases and help text. IDE navigation handled by native IDE shortcuts or external plugins.
-- Does NOT handle video versioning or branching — DAM is a flat archive. Version control (git) handles project versioning separately from media storage.
+
+- Does NOT edit video files directly — only manages metadata, assets, and file sync. Video editing remains in Premiere, DaVinci, etc.
+- Does NOT implement a YouTube UI or web interface — wraps Google's youtube-api-client library for CLI metadata updates. Browsing or uploading video content requires YouTube's own interface.
+- Does NOT manage individual files within a DAM project — operates on whole project directories as atomic units. Granular in-project file operations are handled by the user's editor, Finder, or direct `rsync`.
+- Does NOT handle video versioning or branching — DAM is flat archive. Version control for code remains in git; media versioning is not addressed.
+- Does NOT scan the brains folder directly — `query_brain` reads a pre-built `brains-index.json`. Brain discovery, indexing, and metadata enrichment are the responsibility of the `brain-librarian` skill's Python scripts.
+- Does NOT provide IDE integration for Jump — generates shell aliases only. IDE navigation handled by native IDE shortcuts.
+
+## Failure Modes
+
+- **`query_brain` raises "brains-index.json not found"** — the pre-built brain index doesn't exist at the path configured by `brains-root-path` (or the default `~/dev/ad/brains/audit/`). Fix: run `build_brain_index.py build --all <brains-root>` from the `brain-librarian` skill. This is a loud failure with a clear message.
+
+- **`query_apps` returns empty results silently** — the app exists in `locations.json` but has no `context.globs.json`. The tool returns `[]` without error. Fix: run `/system-context` in that project root to generate the sidecar file. Diagnosable via `query_apps --list-apps` (the app won't appear) or by checking `File.exist?(project_path + '/context.globs.json')` manually.
+
+- **Jump aliases don't work after `jump generate`** — the `.aliases` file was written but not sourced in the current shell. Fix: add `source <aliases-output-path>` to `.zshrc` and re-open the terminal, or source it manually in the current shell. Diagnosable by running `type jad-tools` — if it says "not found", the aliases aren't loaded.
+
+- **DAM sync uploads every file on each run** — `video-projects-root` in `settings.json` points to the wrong directory or has a trailing slash difference. `ProjectResolver` builds paths by joining the root with brand and project subdirectories; if the root is wrong, MD5 comparison reads no local files and treats everything as new. Fix: verify `settings.json` contains the correct absolute path.
+
+- **`ad_config -c` creates empty configs but tools still error on missing keys** — `ExampleInstaller` copies `*.example.json` files from `config/examples/` into `~/.config/appydave/`, but the example files contain placeholder values like `NOT-SET` and `""`. Tools that require a specific key (e.g., `video-projects-root` for DAM, `brains-root-path` for brain query) will silently return `nil` or fall back to hardcoded defaults that may not exist on this machine. Fix: edit the installed files to set real paths.
+
+- **ZshHistory filter classifies too many commands as `unsure`** — no configured profile exists or the profile directory is missing, causing `Filter` to fall back to built-in defaults. The defaults are tailored to David's workflow; they may not match a different developer's commands. Fix: create a custom profile in `~/.config/appydave/zsh_history/profiles/<name>/` with `include.txt` and `exclude.txt` patterns, then set `default_profile=<name>` in `config.txt`.

data/bin/configuration.rb

@@ -29,6 +29,10 @@ OptionParser.new do |opts|
     options[:command] = :create
   end
 
+  opts.on('-x', '--install-examples', 'Install bundled example configs (safe — skips existing files)') do
+    options[:command] = :install_examples
+  end
+
   opts.on('-p', '--print [KEYS]', Array, 'Print configuration details for specified keys') do |keys|
     options[:command] = :print
     options[:keys] = keys
@@ -72,6 +76,22 @@ when :create
     puts "\n⚠️  Skipped (already exist):"
     skipped.each { |name| puts "  - #{name}" }
   end
+when :install_examples
+  Appydave::Tools::Configuration::Config.configure
+  installer = Appydave::Tools::Configuration::ExampleInstaller.new
+  result = installer.install
+
+  puts "\n✅ Installed example configurations:"
+  if result[:installed].any?
+    result[:installed].each { |name| puts "  - #{name}" }
+  else
+    puts '  (none — all examples already present)'
+  end
+
+  if result[:skipped].any?
+    puts "\n⚠️  Skipped (already exist):"
+    result[:skipped].each { |name| puts "  - #{name}" }
+  end
 when :print
   Appydave::Tools::Configuration::Config.configure
   Appydave::Tools::Configuration::Config.print(*options[:keys])

data/bin/query_apps.rb

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+require 'appydave/tools'
+
+options = Appydave::Tools::AppContext::Options.new
+
+def setup_options(options)
+  OptionParser.new do |opts| # rubocop:disable Metrics/BlockLength
+    opts.banner = 'Usage: query_apps [APP] [options]'
+
+    opts.on('--find APP', 'Find app by key, jump alias, or substring (repeatable)') do |app|
+      options.app_names << app
+    end
+
+    opts.on('--glob NAMES', 'Glob names to resolve (comma-separated)') do |names|
+      options.glob_names.concat(names.split(',').map(&:strip))
+    end
+
+    opts.on('--pattern PATTERN', 'Filter by project pattern type (e.g., rvets, nextjs)') do |pat|
+      options.pattern_filter = pat
+    end
+
+    opts.on('--list', 'List available glob names for the specified app') do
+      options.list = true
+    end
+
+    opts.on('--list-apps', 'List all apps with context.globs.json') do
+      options.list_apps = true
+    end
+
+    opts.on('--meta', 'Return metadata as JSON instead of file paths') do
+      options.meta = true
+    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_apps 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)
+
+# Positional arg as app name if no --find given
+options.app_names << ARGV.shift if ARGV.any? && options.app_names.empty?
+
+finder = Appydave::Tools::AppContext::AppQuery.new(options)
+
+if options.list_apps
+  require 'json'
+  puts JSON.pretty_generate(finder.list_apps)
+elsif options.list && options.app_names.any?
+  require 'json'
+  puts JSON.pretty_generate(finder.list_globs(options.app_names.first))
+elsif options.meta
+  require 'json'
+  puts JSON.pretty_generate(finder.find_meta)
+else
+  finder.find.each { |p| puts p }
+end
+
+exit 0

data/config/examples/locations.example.json

@@ -0,0 +1,48 @@
+{
+  "meta": {
+    "version": "1.0",
+    "description": "Jump locations — edit paths to match your dev folder structure, then run: jump generate"
+  },
+  "categories": {
+    "type": {
+      "description": "Kind of location",
+      "values": ["brand", "client", "gem", "video", "brain", "site", "tool", "config"]
+    },
+    "technology": {
+      "description": "Primary language/framework",
+      "values": ["ruby", "javascript", "typescript", "python", "astro"]
+    }
+  },
+  "brands": {},
+  "clients": {},
+  "locations": [
+    {
+      "key": "dev",
+      "path": "~/dev",
+      "alias": "jdev",
+      "description": "Root dev folder",
+      "type": "tool"
+    },
+    {
+      "key": "brain",
+      "path": "~/dev/brains",
+      "alias": "jbrain",
+      "description": "Second brain knowledge base",
+      "type": "brain"
+    },
+    {
+      "key": "omi",
+      "path": "~/dev/raw-intake/omi",
+      "alias": "jomi",
+      "description": "OMI wearable transcripts",
+      "type": "brain"
+    },
+    {
+      "key": "clients",
+      "path": "~/dev/clients",
+      "alias": "jclients",
+      "description": "Client work root",
+      "type": "client"
+    }
+  ]
+}

data/config/examples/settings.example.json

@@ -0,0 +1,9 @@
+{
+  "video-projects-root": "~/dev/video-projects",
+  "ecamm-recording-folder": "~/ecamm",
+  "download-folder": "~/Downloads",
+  "download-image-folder": "~/Downloads/images",
+  "aliases-output-path": "~/.config/appydave/aliases.sh",
+  "brains-root-path": "~/dev/brains",
+  "omi-directory-path": "~/dev/raw-intake/omi"
+}

data/config/random-queries.yml

@@ -8,39 +8,22 @@
 #   min_results: Minimum results to be considered a "good" match (default: 1)
 #   max_results: Maximum results to be considered a "good" match (default: 15)
 #
-# The OMI skill can extend this file by appending new entries under queries:.
+# This is the bundled default — it ships with the gem and is bootstrapped to
+# ~/.config/appydave/random-queries.yml on first use.
+#
+# All queries here use generic flags (--active, --category, --routing) that
+# work regardless of what brain names or folder structure a user has.
+#
+# To add personal queries (brain names, custom paths), edit your own copy at
+# ~/.config/appydave/random-queries.yml after it has been bootstrapped.
 
 queries:
-  # --- Brain queries ---
-  - label: "What do I know about paperclip?"
-    command: "query_brain --find paperclip"
-    min_results: 1
-    max_results: 20
-
-  - label: "What do I know about OMI?"
-    command: "query_brain --find omi"
-    min_results: 1
-    max_results: 20
-
-  - label: "What do I know about BMAD method?"
-    command: "query_brain --find bmad"
-    min_results: 1
-    max_results: 20
-
-  - label: "What do I know about agentic engineering?"
-    command: "query_brain --find agentic-engineering"
-    min_results: 1
-    max_results: 30
+  # --- Brain queries (generic — works for any user with a configured brains-root-path) ---
 
-  - label: "What are my active high-priority brains?"
+  - label: "What are my most active areas of knowledge?"
     command: "query_brain --active"
-    min_results: 5
-    max_results: 50
-
-  - label: "What do I know about Claude / Anthropic?"
-    command: "query_brain --find anthropic"
     min_results: 1
-    max_results: 20
+    max_results: 50
 
   - label: "Browse my agent systems knowledge"
     command: "query_brain --category agent-systems"
@@ -52,17 +35,18 @@ queries:
     min_results: 1
     max_results: 30
 
-  - label: "What do I know about context engineering?"
-    command: "query_brain --find context-engineering"
+  - label: "Browse my tools and utilities knowledge"
+    command: "query_brain --category tools"
     min_results: 1
-    max_results: 20
+    max_results: 30
 
-  - label: "What do I know about FliVideo?"
-    command: "query_brain --find flivideo"
+  - label: "Browse my workflows knowledge"
+    command: "query_brain --category workflows"
     min_results: 1
-    max_results: 20
+    max_results: 30
+
+  # --- OMI queries (generic — works for any user with a configured omi-directory-path) ---
 
-  # --- OMI queries ---
   - label: "Recent things I learned (TIL)"
     command: "query_omi --routing til --limit 5"
     min_results: 1
@@ -83,16 +67,6 @@ queries:
     min_results: 1
     max_results: 10
 
-  - label: "Recent OMI conversations about paperclip"
-    command: "query_omi --brain paperclip --limit 3"
-    min_results: 1
-    max_results: 3
-
-  - label: "Recent OMI conversations about BMAD"
-    command: "query_omi --brain bmad --limit 3"
-    min_results: 1
-    max_results: 3
-
   - label: "What was I planning recently?"
     command: "query_omi --activity planning --days 14 --limit 5"
     min_results: 1
@@ -102,3 +76,8 @@ queries:
     command: "query_omi --activity learning --days 14 --limit 5"
     min_results: 1
     max_results: 5
+
+  - label: "Recent meeting notes"
+    command: "query_omi --activity meeting --days 30 --limit 5"
+    min_results: 1
+    max_results: 5

data/context.globs.json

@@ -0,0 +1,24 @@
+{
+  "generated": "2026-04-05",
+  "generator": "system-context",
+  "project": "appydave-tools",
+  "pattern": "ruby-gem",
+  "globs": {
+    "docs": ["docs/**/*.md"],
+    "config": ["config/**/*.json"],
+    "lib": ["lib/**/*.rb"],
+    "bin": ["bin/*"],
+    "tests": ["spec/**/*_spec.rb"],
+    "planning": ["docs/planning/**/*.md"],
+    "context": ["CLAUDE.md", "CONTEXT.md"]
+  },
+  "aliases": {
+    "source": ["lib", "bin"],
+    "specs": ["tests"]
+  },
+  "composites": {
+    "understand": ["context", "docs", "config"],
+    "codebase": ["lib", "bin"],
+    "full": ["*"]
+  }
+}

data/docs/planning/multi-user-support.md

@@ -0,0 +1,108 @@
+---
+title: Multi-User Support — AppyDave Tools
+status: planning
+created: 2026-04-05
+context: Lars onboarding — first external user of appydave-tools
+---
+
+# Multi-User Support
+
+## Current State
+
+AppyDave Tools was built for a single user on David's M4 creator machine. It is not intentionally single-user — the architecture is already mostly correct — but it has never been tested with a second person's folder structure.
+
+**What works for multi-user today:**
+- Config is stored in `~/.config/appydave/` — per-user, not shared, no collision
+- `gem install appydave-tools` gives Lars a clean install with no locations
+- All tools read their paths from `~/.config/appydave/locations.json` at runtime
+
+**What doesn't work yet:**
+- Lars starts with an empty `locations.json` — no seed, no onboarding flow
+- Lars's dev folder structure is unknown (capturing via `ls ~/dev/` in next relay session)
+- David's `locations.json` has 100 entries, all pointing to `/Users/davidcruwys/` — not portable
+- Brain query, OMI query, and LLM context tools likely assume specific location keys exist (e.g., `brain`, `omi`) — if Lars's keys are different or missing, these will fail silently or error
+
+---
+
+## Tools Lars Needs
+
+### 1. Jump (immediate value)
+
+The `jump` command generates shell aliases for folder navigation. Lars currently has only `jb` (jump to brain) — hardcoded, not managed by this tool.
+
+**What Lars gets after setup:**
+- Any folder registered in `locations.json` becomes a `j<alias>` shell alias
+- Running `jump generate` writes a `.aliases` file; sourcing it activates them
+- He can register his `~/dev/clients/`, relay folder, growth-intelligence repo, etc.
+
+**Blocker:** He needs entries in `locations.json` before any aliases are generated.
+
+### 2. Brain Query
+
+Queries Lars's second brain folder structure. Likely reads from a location keyed `brain` in `locations.json`.
+
+**Risk:** Key name may be hardcoded. Need to verify the tool reads `brain` key or is configurable.
+
+### 3. OMI Query
+
+Queries saved OMI transcripts. Likely reads from a location keyed `omi` or a path in `settings.json`.
+
+**Risk:** Lars's OMI intake is at `~/dev/raw-intake/omi/` — this needs to be registered in his config.
+
+### 4. LLM Context Builder
+
+Builds context bundles for pasting into LLM sessions. Probably reads from multiple registered locations.
+
+**Risk:** May depend on several location keys existing. Needs testing with minimal config.
+
+---
+
+## Installation Plan for Lars
+
+```bash
+gem install appydave-tools
+```
+
+Then verify:
+
+```bash
+appydave --version
+appydave jump report
+```
+
+`jump report` with an empty `locations.json` should return zero locations without error — if it crashes, that's the first bug to fix.
+
+### After Install — Bootstrap Lars's Locations
+
+Lars needs a minimal seed `locations.json` tailored to his machine. Suggested starting set once we know his `~/dev/` structure:
+
+| Key | Path (approximate) | Purpose |
+|-----|--------------------|---------|
+| `dev` | `~/dev` | Root dev folder |
+| `brain` | `~/dev/brains/` | Second brain |
+| `omi` | `~/dev/raw-intake/omi/` | OMI transcripts |
+| `clients` | `~/dev/clients/` | Client work |
+| `growth` | `~/dev/clients/lars-projects/growth-intelligence/` | Growth Intelligence repo |
+| `relay` | `~/Dropbox/relay/people/david-lars/` | Relay folder |
+
+Lars adds these via `appydave jump add` or by editing `~/.config/appydave/locations.json` directly.
+
+---
+
+## Known Gaps to Resolve
+
+1. **Empty-config behaviour** — run all four tools with a blank `locations.json` and confirm they fail gracefully, not with a Ruby stack trace
+2. **Location key conventions** — are keys like `brain` and `omi` hardcoded in brain-query and omi-query, or configurable? Document the expected keys.
+3. **Aliases output path** — `aliases-output-path` in `settings.json` tells jump where to write the `.aliases` file. Lars needs this set before `jump generate` works. Default: `~/.config/appydave/aliases.sh` (check current default).
+4. **Shell sourcing** — after `jump generate`, Lars needs `source ~/.config/appydave/aliases.sh` (or equivalent) in his `.zshrc`. This needs to be part of the setup guide.
+5. **Ruby version** — gemspec requires `>= 2.7`. Lars's Ruby version is unknown — check during session.
+
+---
+
+## What This Is Not
+
+This is not a multi-tenant SaaS problem. Each user has their own machine, their own `~/.config/appydave/`, and their own gem install. There is no shared state. The "multi-user support" work is really:
+
+- Making sure the tools don't assume David's paths
+- Providing a repeatable onboarding flow for a new machine
+- Writing a short setup guide Lars can follow independently next time