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 ai-cmd's command knowledge current.

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 9.8.4 1.6 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 (v9.8.4): 704228a2a1a9808e3c91b3ccfd496d65b27fbd24ecc46140a00afa4c35840314

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. This keeps ai-cmd's knowledge of available commands always current.

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 ai-cmd's command index without 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 detects it and the full pipeline updates ai-cmd.

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-commands.json

# Step 7: Create a snapshot for safety
sudo ai-trainer snapshot -v "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 → Model retrained → ai-cmd queries new commands

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-commands.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 binary is indexed but ai-cmd still fails, the model may need retraining
sudo ai-trainer train --data ./data/training-data.json

# Step 8: Validate the retrained model
ai-trainer validate --test-data ./data/test-commands.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 -v "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-commands.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 -v "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