1. Install KnoxCall Agent
   ↓ 1-line install on your host (Agents → "1-line install")
2. Start a Conversation
   ↓ Select repositories / code directories to analyze
3. AI Analysis
   ↓ Discovers endpoints, secrets, auth patterns
4. Review & Approve
   ↓ Agent shows findings, asks questions
5. Automatic Creation
   ↓ Routes, secrets, clients all created

✅ /var/www/api-backend
✅ /home/deploy/microservices/payment-service
✅ /opt/apps/user-service
❌ /var/log (skip - no code here)

Agent: Hello! I'll scan your codebase to discover API integrations.
       I've found 3 repositories to analyze. Starting scan...

Agent: Found 47 API calls in your code. Let me classify them...

Agent: I discovered calls to:
       - Stripe API (15 endpoints)
       - Twilio API (8 endpoints)
       - SendGrid API (5 endpoints)

       Are these external APIs you want to proxy through KnoxCall?

You: Yes, all of them

Agent: Great! I also found credentials in your .env files:
       - STRIPE_SECRET_KEY
       - TWILIO_AUTH_TOKEN
       - SENDGRID_API_KEY

       Should I create secrets for these?

You: Yes please

Collections:
  - Payment APIs (Stripe, PayPal)
  - Communication APIs (Twilio, SendGrid)

Routes:
  - 15 Stripe routes (charges, customers, subscriptions)
  - 8 Twilio routes (SMS, voice, verify)
  - 5 SendGrid routes (mail send, templates)

Secrets:
  - stripe_secret_key (detected: API key)
  - twilio_auth_token (detected: Auth token)
  - sendgrid_api_key (detected: API key)

Client:
  - Production Server (198.51.100.50)

✅ Created collection: Payment APIs
✅ Created secret: stripe_secret_key
✅ Created route: Stripe Charges API
✅ Created route: Stripe Customers API
... (continues for all resources)
✅ Created client: Production Server
✅ Linked client to all routes

Done! Created 28 routes, 3 secrets, 2 collections, and 1 client.

// Detected: Stripe API
const charge = await stripe.charges.create({
  amount: 2000,
  currency: 'usd',
  source: token
});

// Detected: Twilio API
await twilioClient.messages.create({
  to: phoneNumber,
  from: config.twilioNumber,
  body: message
});

// EXTERNAL - Will create route
fetch('https://api.stripe.com/v1/charges')

// INTERNAL - Skipped
fetch('/api/internal/users')

// Detected: Bearer token auth
$headers = ['Authorization: Bearer ' . $apiKey];

// Detected: Basic auth
curl_setopt($ch, CURLOPT_USERPWD, "$username:$password");

// Detected: API key in query
$url = "https://api.example.com/data?apiKey=" . $key;

STRIPE_SECRET_KEY=sk_live_abc123
TWILIO_AUTH_TOKEN=AC123456789
DATABASE_PASSWORD=supersecret

define('API_KEY', 'pk_live_xyz789');
$config['stripe_key'] = 'sk_test_123';

const SENDGRID_API_KEY = 'SG.abc123';
process.env.STRIPE_SECRET_KEY

STRIPE_KEY = "sk_live_abc123"
api_key = os.getenv('TWILIO_AUTH_TOKEN')

Agent: I found calls to api.internal-analytics.com
       Is this an external service or your own infrastructure?

You: That's our own service, skip it

Agent: Got it, I'll ignore api.internal-analytics.com

Agent: The endpoint "POST /payments" is called with different
       base URLs in different files:
       - https://api.stripe.com (prod)
       - https://api-sandbox.stripe.com (dev)

       Should I create separate routes or use environments?

You: Use environments

Agent: Perfect, I'll create one route with production and
       development environments

You: Why do you need my Stripe key?

Agent: I detected 15 Stripe API calls in your code at:
       - /var/www/api/payment.php (lines 45, 67, 89)
       - /var/www/api/subscriptions.php (lines 23, 56)

       The STRIPE_SECRET_KEY from your .env file will be stored
       encrypted and injected when proxying these calls. You can
       choose not to import it if you prefer manual setup.

Agent: I found endpoints from these domains:

  🌐 api.stripe.com (15 endpoints)
     EXTERNAL | High confidence | Payment processing

  🌐 api.twilio.com (8 endpoints)
     EXTERNAL | High confidence | Communication

  🌐 internal-api.yourcompany.com (47 endpoints)
     UNKNOWN | Needs your input

  🌐 analytics.yourcompany.com (12 endpoints)
     UNKNOWN | Needs your input

You: Stripe and Twilio are external. The others are internal, skip them.

Agent: ✅ Marked 23 external endpoints
       ⏭️ Skipped 59 internal endpoints

Use case: You've updated your code and want to discover new APIs
          without reinstalling anything.

1. Open the agent on the Agents page (or the Onboarding page)
2. Click "New Conversation"
3. Select the same repositories
4. Agent runs fresh analysis with updated code

Agent: I can create these collections:
       - Payment APIs (Stripe, PayPal)
       - Communication (Twilio, SendGrid)
       - Data Storage (AWS S3, Google Cloud Storage)

You: Create separate collections for each service

Agent: ✅ Will create 5 collections instead of 3

       OR

You: Put everything in one collection called "Production APIs"

Agent: ✅ All routes in single collection "Production APIs"

Agent: I found these endpoint patterns:
       Production: https://api.stripe.com
       Sandbox: https://api-sandbox.stripe.com (in test files)

       Create environments for both?

You: Yes

Agent: ✅ Creating routes with "production" and "sandbox" environments
       You'll need to configure sandbox credentials later

-- Conversation history
SELECT * FROM onboarding_conversation_messages
WHERE session_id = 'your-session-id';

-- Files accessed
SELECT tool_input->>'path' FROM onboarding_conversation_messages
WHERE tool_name = 'read_file';

-- Resources created
SELECT created_route_id, created_secret_id
FROM onboarding_discovered_endpoints;

// Node.js
fetch(), axios, got, request, superagent

// PHP
curl_exec(), file_get_contents(), Guzzle

// Python
requests, httpx, urllib, aiohttp

// Ruby
Net::HTTP, RestClient, Faraday, HTTParty

// Go
http.Client, resty

// Java
HttpClient, OkHttp, RestTemplate

# .env files
.env, .env.local, .env.production, .env.development

# Framework-specific
config/secrets.yml (Rails)
.env.php (Laravel)
settings.py (Django)
application.properties (Spring)

Solution:
1. Confirm the KnoxCall Agent shows as "active" on the Agents page
2. Verify the agent process is running on your host
3. Confirm the host can reach KnoxCall outbound over HTTPS/WSS
4. Re-run the 1-line install if the agent was removed or revoked

Solution:
1. Ensure the OS user the agent runs as has read access to code directories
2. Check: ls -la /var/www/yourapp
3. May need to add the agent's user to the www-data group:
   sudo usermod -a -G www-data <agent-user>

Possible causes:
1. Code uses indirect API calls (variables instead of strings)
2. Selected wrong directory (no source code)
3. Unsupported language/framework

Solution:
- Manually review files at: /var/www/yourapp/src
- Look for API client initialization
- Check if framework uses config files instead of inline URLs

Agent detected internal URLs as external APIs

Solution:
- Use bulk domain classification
- Mark internal domains as "skip"
- Agent learns: skips similar patterns

Agent found .env files but no secrets

Possible causes:
1. Environment variables loaded at runtime (not in files)
2. Secrets stored in external vault (AWS Secrets Manager, etc.)
3. Config files in non-standard locations

Solution:
- Manually create secrets after onboarding
- Point agent to custom config directories

Solution:
1. Check that the KnoxCall Agent is still active on the Agents page
2. Refresh page (agent state persists)
3. Send a message to wake agent
4. Check /var/www/knoxcall/logs for errors

Agent keeps asking same question

Solution:
1. Answer with specific details:
   ❌ "yes"
   ✅ "Yes, all Stripe endpoints are external"
2. If unclear, ask agent: "What do you need from me?"
3. Last resort: restart session (data preserved)

POST /admin/agents/{agentId}/start-conversation
{
  "root": "/srv/app"   // optional: filesystem root to scan
}

POST /admin/onboarding/sessions/{id}/messages
{
  "content": "Yes, create all routes"
}

GET /admin/onboarding/sessions/{id}/stream?token={jwt}

Events:
- agent.message: Agent sent a message
- agent.thinking: Agent is processing
- agent.tool_call: Agent using a tool (read_file, etc.)
- agent.tool_result: Tool execution completed
- agent.action_needed: Agent needs user input
- agent.error: Error occurred
- agent.complete: Session complete

{
  "id": "msg_abc123",
  "content": "I found 15 Stripe API calls",
  "sequence": 42
}

{
  "id": "tool_xyz789",
  "toolName": "read_file",
  "toolInput": {
    "path": "/var/www/api/payment.php",
    "offset": 1,
    "limit": 100
  }
}

{
  "id": "action_123",
  "actionType": "approve_routes",
  "message": "Should I create these 15 routes?",
  "options": {
    "routes": [...]
  }
}

// ❌ Agent cannot detect
const baseUrl = config.getUrl();
fetch(baseUrl + '/api/endpoint');

// ✅ Agent can detect
fetch('https://api.stripe.com' + '/v1/charges');

# ❌ Agent cannot find these secrets
# (loaded from AWS Secrets Manager at runtime)
client = boto3.client('secretsmanager')
secret = client.get_secret_value(SecretId='prod/api/key')

# ✅ Agent can find these
# (.env file)
API_KEY=sk_live_abc123

// ❌ Hard to detect
$apiClient->call('charge.create', $params);

// ✅ Easy to detect
curl_exec($ch, "https://api.stripe.com/v1/charges");