AI SUITE GUIDE

ai-discovery Guide

Background daemon that watches the binary directory with inotify and automatically re-indexes the AI command registry whenever binaries are added, updated, or removed, keeping its own registry file current. ai-cmd does not read that registry; its command catalogue is compiled in.

inotify watcher Auto re-index Registry sync Daemon

ai-discovery at a glance

ai-discovery is a background daemon that uses inotify to watch the binary directory for changes. When binaries are added, updated, or removed, it automatically re-indexes them and updates the AI command registry, keeping ai-cmd's knowledge of available commands always current.

Version 10.0.3 1.7 MB binary Rust 1.82.0 Background daemon

Reference and verification

This is a scenario-first guide: operational workflows, real run order, and troubleshooting. For the full autogenerated command and flag catalog, use the ai-discovery CLI Reference, or read the raw signer JSON.

SHA256 (v10.0.3): 2d0ac02123ab363c0cf37ca2f53fe53ef1d30a6ff67f2f02f83ad8a8cfee7032

What ai-discovery Does

ai-discovery is a background daemon that uses inotify to watch the binary directory for changes. When binaries are added, updated, or removed, it automatically re-indexes them and updates the AI command registry (data/ai-command-registry.json). ai-cmd does not read this registry: it resolves queries against the catalogue compiled into it, so a binary ai-cmd does not know needs an ai-cmd update.

Key Capabilities

Feature	Description
inotify Watcher	Monitors binary directory for file changes
Auto-Indexing	Automatically indexes new/updated binaries
Service Registry	Maintains a complete catalog of available services
Hot Reload	Updates the discovery registry without a daemon restart
Service-Specific Reindex	Reindex individual services
JSON Output	All commands support `--json` for programmatic access

Scenario 1: Initial Setup, Getting Discovery Running

Start ai-discovery and verify it has indexed all binaries.

Cross-binary workflow: ai-discovery + ai-cmd

# Step 1: Start the discovery daemon
sudo ai-discovery start

# Step 2: Check daemon status
ai-discovery status

# Step 3: View detailed registry contents
ai-discovery status --verbose

# Step 4: Verify ai-cmd can see all indexed commands
ai-cmd query "check network" --dry-run
ai-cmd preview "rotate tor" --alternatives 5

JSON output for automation:

sudo ai-discovery start --json
ai-discovery status --json
ai-discovery status --verbose --json

Scenario 2: New Binary Installed, Complete Integration Flow

When a new Kodachi binary is deployed, ai-discovery indexes it and ai-trainer can add its commands to ai-trainer's own database for validation. ai-cmd itself learns a new binary with an ai-cmd update, not from this flow.

Cross-binary workflow: ai-discovery + ai-trainer + ai-cmd

# Step 1: If discovery daemon is running, it auto-detects the new binary
# Check if it was detected:
ai-discovery status --verbose

# Step 2: If not auto-detected, force a full reindex
sudo ai-discovery reindex

# Step 3: Verify the new binary appears in the registry
ai-discovery status --verbose

# Step 4: Update training data with new binary's commands
# (Edit training-data.json to add the new binary's commands)
nano ./data/training-data.json

# Step 5: Retrain the model to include new commands
sudo ai-trainer train --data ./data/training-data.json

# Step 6: Validate the updated model
ai-trainer validate --test-data ./data/test-cases.json

# Step 7: Create a snapshot for safety
sudo ai-trainer snapshot -s "new-binary-$(date +%Y%m%d)"

# Step 8: Test new commands via ai-cmd
ai-cmd query "use new binary" --dry-run
ai-cmd preview "new binary command" --alternatives 5

Flow: Discovery indexes → training data updated → ai-trainer's database rebuilt and validated

Scenario 3: Binary Updated, Keeping AI in Sync

When an existing binary is updated (new commands, changed syntax), reindex it.

Cross-binary workflow: ai-discovery + ai-trainer + ai-cmd

# Step 1: Reindex just the updated service
ai-discovery reindex --service tor-switch

# Step 2: Verify the reindex
ai-discovery status --verbose

# Step 3: If commands changed, update training data and retrain
sudo ai-trainer incremental --new-data ./data/training-data.json

# Step 4: Validate the update
ai-trainer validate --test-data ./data/test-cases.json

# Step 5: Test the updated commands
ai-cmd preview "tor command" --alternatives 5

For multiple updated services:

ai-discovery reindex --service dns-switch
ai-discovery reindex --service health-control
ai-discovery reindex --service routing-switch

# Verify all reindexed
ai-discovery status --verbose

# Then retrain once
sudo ai-trainer train --data ./data/training-data.json

JSON output for automation:

ai-discovery reindex --service health-control --json
ai-discovery status --verbose --json

Scenario 4: Troubleshooting, Commands Not Found by ai-cmd

When ai-cmd can't find a command that should exist, check if discovery has indexed it.

Cross-binary workflow: ai-cmd + ai-discovery + ai-trainer

# Step 1: Check what ai-cmd knows about the command
ai-cmd preview "check integrity" --alternatives 5

# Step 2: Check discovery registry for the binary
ai-discovery status --verbose

# Step 3: If binary is missing from registry, force full reindex
sudo ai-discovery reindex

# Step 4: Verify binary now appears
ai-discovery status

# Step 5: If still missing, reindex the specific service
ai-discovery reindex --service integrity-check

# Step 6: Verify service-specific reindex
ai-discovery status --verbose

# Step 7: If the binary is indexed but ai-cmd still fails, ai-cmd's compiled catalogue lacks it; optionally rebuild ai-trainer's database
sudo ai-trainer train --data ./data/training-data.json

# Step 8: Validate the retrained model
ai-trainer validate --test-data ./data/test-cases.json

# Step 9: Verify fix
ai-cmd query "check integrity" --dry-run

Scenario 5: System Update, Reindexing After OS Upgrade

After a Kodachi OS upgrade that installs/updates multiple binaries, reindex everything.

Cross-binary workflow: ai-discovery + ai-admin + ai-trainer + ai-cmd + ai-learner

# Step 1: Force full reindex of all binaries
sudo ai-discovery reindex

# Step 2: Verify all services are indexed
ai-discovery status --verbose

# Step 3: Backup current database before retraining
ai-admin db backup --output ./backup/pre-upgrade-$(date +%Y%m%d).db

# Step 4: Create pre-upgrade model snapshot
sudo ai-trainer snapshot -s "pre-upgrade-$(date +%Y%m%d)"

# Step 5: Full retraining with updated binary data
sudo ai-trainer train --data ./data/training-data.json

# Step 6: Validate the retrained model
ai-trainer validate --test-data ./data/test-cases.json

# Step 7: Test critical commands
ai-cmd query "check network" --dry-run
ai-cmd query "check dns leaks" --dry-run
ai-cmd query "rotate tor" --dry-run
ai-cmd query "enable panic mode" --dry-run

# Step 8: If everything works, create post-upgrade snapshot
sudo ai-trainer snapshot -s "post-upgrade-$(date +%Y%m%d)"

# Step 9: Analyze model accuracy after upgrade
sudo ai-learner analyze --period last-7-days --metric accuracy

Daemon Control Commands

Based on actual ai-discovery -e output:

# Start daemon (runs in background)
sudo ai-discovery start

# Start in foreground (for debugging)
sudo ai-discovery start --foreground

# Start in foreground with JSON output
sudo ai-discovery start --foreground --json

# Check daemon status
ai-discovery status
ai-discovery status --json

Registry Management Commands