AI Discovery (ai-discovery) — Workflow Guide

Documentation Navigation

This page is scenario-first (operational workflows, real run order, and troubleshooting). For the full autogenerated command/flag catalog, use the CLI Reference.

File Information

Property	Value
Binary Name	ai-discovery
Version	9.0.1
File Size	1.3MB
Author	Warith Al Maawali
License	Proprietary
Category	AI & Intelligence
Description	Kodachi Auto-Discovery Daemon - Monitors and indexes Rust service binaries
JSON Data	View Raw JSON

SHA256 Checksum

5fd962063e8f446145e00b1cd73e82b07e4831b865fef46f85c0e4a8ec19980f

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