@useconductor/conductor 1.0.0

package/dist/security/keychain.js

@@ -0,0 +1,213 @@
+import crypto from 'crypto';
+import fs from 'fs/promises';
+import { readFileSync, mkdirSync, writeFileSync } from 'fs';
+import { execSync } from 'child_process';
+import path from 'path';
+import os from 'os';
+/**
+ * Keychain — encrypted credential storage.
+ *
+ * Supports two formats:
+ *   v2  — AES-256-GCM with machine-specific key derivation (written by install.sh)
+ *   v1  — AES-256-CBC legacy format (written by older versions)
+ *
+ * New writes always use the v2 format.
+ */
+export class Keychain {
+    keychainDir;
+    masterKey;
+    constructor(configDir) {
+        this.keychainDir = path.join(configDir, 'keychain');
+        this.masterKey = this.deriveMasterKey();
+    }
+    /**
+     * Derive a machine-specific master key.
+     * Matches the install.sh derivation so credentials saved by either
+     * the installer or the app are interchangeable.
+     */
+    deriveMasterKey() {
+        const machineSecret = this.getMachineSecret();
+        const salt = crypto.createHash('sha256').update('conductor:keychain:v1').digest();
+        return crypto.scryptSync(machineSecret, salt, 32, { N: 16384, r: 8, p: 1 });
+    }
+    /**
+     * Get a machine-specific secret for key derivation.
+     * Mirrors the logic in install.sh's save_cred function.
+     */
+    getMachineSecret() {
+        // Linux: /etc/machine-id or /var/lib/dbus/machine-id
+        const linuxSources = ['/etc/machine-id', '/var/lib/dbus/machine-id', '/proc/sys/kernel/random/boot_id'];
+        for (const src of linuxSources) {
+            try {
+                const data = readFileSync(src, 'utf8').trim();
+                if (data)
+                    return data;
+            }
+            catch {
+                // Not available on this platform
+            }
+        }
+        // macOS: IOPlatformUUID
+        if (process.platform === 'darwin') {
+            try {
+                const out = execSync("ioreg -rd1 -c IOPlatformExpertDevice | awk '/IOPlatformUUID/{print $NF}'", {
+                    encoding: 'utf8',
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                })
+                    .trim()
+                    .replace(/"/g, '');
+                if (out)
+                    return out;
+            }
+            catch {
+                // ioreg not available
+            }
+        }
+        // Windows: MachineGuid from registry
+        if (process.platform === 'win32') {
+            try {
+                const out = execSync('reg query "HKLM\\SOFTWARE\\Microsoft\\Cryptography" /v MachineGuid', {
+                    encoding: 'utf8',
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+                const match = out.match(/MachineGuid\s+REG_SZ\s+(.+)/);
+                if (match?.[1]?.trim())
+                    return match[1].trim();
+            }
+            catch {
+                // Registry not accessible
+            }
+        }
+        // Persistent fallback: Save a random UUID to a file if hardware IDs fail.
+        // This is safer than hostname which can change.
+        const fallbackPath = path.join(this.keychainDir, 'machine_secret');
+        try {
+            if (readFileSync(fallbackPath, 'utf8').trim()) {
+                return readFileSync(fallbackPath, 'utf8').trim();
+            }
+        }
+        catch {
+            try {
+                const secret = crypto.randomUUID();
+                // Use synchronous write since this is inside deriveMasterKey constructor path
+                mkdirSync(this.keychainDir, { recursive: true, mode: 0o700 });
+                writeFileSync(fallbackPath, secret, { mode: 0o600 });
+                return secret;
+            }
+            catch {
+                // Absolute last resort
+                return os.hostname();
+            }
+        }
+        return os.hostname();
+    }
+    /**
+     * Store an encrypted credential (v2 format: AES-256-GCM).
+     */
+    async set(service, key, value) {
+        await fs.mkdir(this.keychainDir, { recursive: true, mode: 0o700 });
+        // Enforce 0700 permissions in case dir already existed with wrong perms
+        await fs.chmod(this.keychainDir, 0o700).catch(() => { });
+        const iv = crypto.randomBytes(12); // 96-bit IV for GCM
+        const cipher = crypto.createCipheriv('aes-256-gcm', this.masterKey, iv);
+        let encrypted = cipher.update(value, 'utf8', 'hex');
+        encrypted += cipher.final('hex');
+        const tag = cipher.getAuthTag().toString('hex');
+        // Format: v2:iv:tag:ciphertext
+        const result = ['v2', iv.toString('hex'), tag, encrypted].join(':');
+        const filepath = path.join(this.keychainDir, `${service}.${key}.enc`);
+        await fs.writeFile(filepath, result, { mode: 0o600 });
+    }
+    /**
+     * Retrieve and decrypt a credential.
+     * Handles both v2 (GCM) and legacy v1 (CBC) formats.
+     */
+    async get(service, key) {
+        try {
+            const filepath = path.join(this.keychainDir, `${service}.${key}.enc`);
+            const data = await fs.readFile(filepath, 'utf-8');
+            return this.decrypt(data.trim());
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Delete a credential.
+     */
+    async delete(service, key) {
+        const filepath = path.join(this.keychainDir, `${service}.${key}.enc`);
+        try {
+            await fs.unlink(filepath);
+        }
+        catch {
+            // File doesn't exist — that's fine
+        }
+    }
+    /**
+     * Check if a credential exists.
+     */
+    async has(service, key) {
+        try {
+            const filepath = path.join(this.keychainDir, `${service}.${key}.enc`);
+            await fs.access(filepath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * List all credential keys for a service.
+     */
+    async list(service) {
+        try {
+            const files = await fs.readdir(this.keychainDir);
+            return files
+                .filter((f) => f.startsWith(`${service}.`) && f.endsWith('.enc'))
+                .map((f) => f.replace(`${service}.`, '').replace('.enc', ''));
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Decrypt a stored value, auto-detecting format version.
+     */
+    decrypt(stored) {
+        const parts = stored.split(':');
+        if (parts[0] === 'v2' && parts.length === 4) {
+            // v2: AES-256-GCM — iv:tag:ciphertext
+            return this.decryptGCM(parts[1], parts[2], parts[3]);
+        }
+        if (parts.length === 2) {
+            // Legacy v1: AES-256-CBC — iv:ciphertext (no version prefix)
+            return this.decryptCBC(parts[0], parts[1]);
+        }
+        throw new Error('Unrecognized credential format');
+    }
+    /**
+     * AES-256-GCM decryption (v2 format, matches install.sh).
+     */
+    decryptGCM(ivHex, tagHex, cipherHex) {
+        const iv = Buffer.from(ivHex, 'hex');
+        const tag = Buffer.from(tagHex, 'hex');
+        const decipher = crypto.createDecipheriv('aes-256-gcm', this.masterKey, iv);
+        decipher.setAuthTag(tag);
+        let decrypted = decipher.update(cipherHex, 'hex', 'utf8');
+        decrypted += decipher.final('utf8');
+        return decrypted;
+    }
+    /**
+     * AES-256-CBC decryption (legacy v1 format).
+     * Kept for backward-compat with credentials written before the v2 migration.
+     */
+    decryptCBC(ivHex, cipherHex) {
+        const iv = Buffer.from(ivHex, 'hex');
+        const decipher = crypto.createDecipheriv('aes-256-cbc', this.masterKey, iv);
+        let decrypted = decipher.update(cipherHex, 'hex', 'utf8');
+        decrypted += decipher.final('utf8');
+        return decrypted;
+    }
+}
+//# sourceMappingURL=keychain.js.map

package/dist/security/keychain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keychain.js","sourceRoot":"","sources":["../../src/security/keychain.ts"],"names":[],"mappings":"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"}

package/dist/utils/google-auth.d.ts

@@ -0,0 +1,21 @@
+import { Conductor } from '../core/conductor.js';
+export interface GoogleAuthOptions {
+    scopes: string[];
+    port?: number;
+}
+export declare class GoogleAuthManager {
+    private conductor;
+    private keychain;
+    private oauth2Client;
+    constructor(conductor: Conductor);
+    /**
+     * Start the browser-based OAuth flow.
+     * Returns a promise that resolves when authentication is complete.
+     */
+    login(options: GoogleAuthOptions): Promise<void>;
+    /**
+     * Import OAuth credentials from a Google JSON file.
+     */
+    importFromJson(filePath: string): Promise<void>;
+}
+//# sourceMappingURL=google-auth.d.ts.map

package/dist/utils/google-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-auth.d.ts","sourceRoot":"","sources":["../../src/utils/google-auth.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAKjD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,YAAY,CAAa;gBAErB,SAAS,EAAE,SAAS;IAKhC;;;OAGG;IACG,KAAK,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IA2GtD;;OAEG;IACG,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAqBtD"}

package/dist/utils/google-auth.js

@@ -0,0 +1,135 @@
+import { google } from 'googleapis';
+import http from 'http';
+import { URL } from 'url';
+import { Keychain } from '../security/keychain.js';
+import { getOAuthCredentials } from '../config/oauth.js';
+import fs from 'fs/promises';
+export class GoogleAuthManager {
+    conductor;
+    keychain;
+    oauth2Client = null;
+    constructor(conductor) {
+        this.conductor = conductor;
+        this.keychain = new Keychain(conductor.getConfig().getConfigDir());
+    }
+    /**
+     * Start the browser-based OAuth flow.
+     * Returns a promise that resolves when authentication is complete.
+     */
+    async login(options) {
+        let creds;
+        try {
+            creds = getOAuthCredentials(this.conductor, 'google');
+        }
+        catch {
+            console.log('\n  🔑 Google OAuth configuration missing.');
+            console.log('  To get these, go to: https://console.cloud.google.com/apis/credentials');
+            console.log('  1. Create a "OAuth client ID" for "Web application"');
+            console.log('  2. Set Redirect URI to: http://localhost:3000/callback\n');
+            const { default: inquirer } = await import('inquirer');
+            const answers = await inquirer.prompt([
+                {
+                    type: 'input',
+                    name: 'clientId',
+                    message: 'Enter your Google Client ID:',
+                    validate: (input) => input.length > 0 || 'Client ID is required',
+                },
+                {
+                    type: 'password',
+                    name: 'clientSecret',
+                    message: 'Enter your Google Client Secret:',
+                    mask: '*',
+                    validate: (input) => input.length > 0 || 'Client Secret is required',
+                },
+            ]);
+            await this.conductor.getConfig().set('oauth.google', {
+                clientId: answers.clientId,
+                clientSecret: answers.clientSecret,
+                redirectUri: 'http://localhost:3000/callback',
+            });
+            console.log('\n  ✅ Credentials saved locally.');
+            creds = {
+                clientId: answers.clientId,
+                clientSecret: answers.clientSecret,
+                redirectUri: 'http://localhost:3000/callback',
+            };
+        }
+        const port = options.port || 3000;
+        const redirectUri = creds.redirectUri || `http://localhost:${port}/google/callback`;
+        this.oauth2Client = new google.auth.OAuth2(creds.clientId, creds.clientSecret, redirectUri);
+        const authUrl = this.oauth2Client.generateAuthUrl({
+            access_type: 'offline',
+            prompt: 'consent',
+            scope: options.scopes,
+        });
+        const open = (await import('open')).default;
+        await open(authUrl);
+        console.log('\n  🌍 Opening browser for Google authentication...');
+        console.log('  ⌛ Waiting for authorization...\n');
+        return new Promise((resolve, reject) => {
+            const server = http.createServer(async (req, res) => {
+                const url = new URL(req.url || '', `http://localhost:${port}`);
+                if (url.pathname === '/google/callback' || url.pathname === '/callback') {
+                    const code = url.searchParams.get('code');
+                    if (code) {
+                        try {
+                            const { tokens } = await this.oauth2Client.getToken(code);
+                            // Save tokens to keychain
+                            if (tokens.access_token) {
+                                await this.keychain.set('google', 'access_token', tokens.access_token);
+                            }
+                            if (tokens.refresh_token) {
+                                await this.keychain.set('google', 'refresh_token', tokens.refresh_token);
+                            }
+                            res.writeHead(200, { 'Content-Type': 'text/html' });
+                            res.end(`
+                <html>
+                  <body style="font-family: sans-serif; text-align: center; padding: 50px; background: #f4f7f6;">
+                    <div style="max-width: 500px; margin: auto; background: white; padding: 40px; border-radius: 12px; box-shadow: 0 4px 12px rgba(0,0,0,0.1);">
+                      <h1 style="color: #2e7d32;">✅ Success!</h1>
+                      <p style="font-size: 18px; color: #444;">Conductor is now connected to your Google account.</p>
+                      <p style="color: #666;">You can safely close this window and return to the terminal.</p>
+                    </div>
+                  </body>
+                </html>
+              `);
+                            server.close();
+                            resolve();
+                        }
+                        catch (error) {
+                            res.writeHead(500, { 'Content-Type': 'text/html' });
+                            res.end('<h1>Authentication failed</h1>');
+                            server.close();
+                            reject(error);
+                        }
+                    }
+                }
+            });
+            server.listen(port);
+            server.on('error', reject);
+        });
+    }
+    /**
+     * Import OAuth credentials from a Google JSON file.
+     */
+    async importFromJson(filePath) {
+        try {
+            const data = await fs.readFile(filePath, 'utf-8');
+            const json = JSON.parse(data);
+            const web = json.web || json.installed;
+            if (!web || !web.client_id || !web.client_secret) {
+                throw new Error('Invalid Google OAuth JSON file structure.');
+            }
+            await this.conductor.getConfig().set('oauth.google', {
+                clientId: web.client_id,
+                clientSecret: web.client_secret,
+                redirectUri: web.redirect_uris?.[0] || 'http://localhost:3000/callback',
+            });
+            console.log(`  ✅ Successfully imported Google credentials from ${filePath}`);
+        }
+        catch (error) {
+            throw new Error(`Failed to import JSON: ${error.message}`);
+        }
+    }
+}
+//# sourceMappingURL=google-auth.js.map

package/dist/utils/google-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-auth.js","sourceRoot":"","sources":["../../src/utils/google-auth.ts"],"names":[],"mappings":"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"}

package/dist/utils/retry.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Utility for handling network retries with exponential backoff.
+ */
+export declare function withRetry<T>(operation: () => Promise<T>, maxRetries?: number, baseDelayMs?: number): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/utils/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,UAAU,GAAE,MAAU,EACtB,WAAW,GAAE,MAAa,GACzB,OAAO,CAAC,CAAC,CAAC,CAgCZ"}

package/dist/utils/retry.js

@@ -0,0 +1,34 @@
+/**
+ * Utility for handling network retries with exponential backoff.
+ */
+export async function withRetry(operation, maxRetries = 3, baseDelayMs = 1000) {
+    let attempt = 0;
+    while (true) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            attempt++;
+            if (attempt > maxRetries) {
+                throw error;
+            }
+            // Determine if error is retryable.
+            // Network errors (fetch failed), 429 Too Many Requests, and 5xx Server Errors are retryable.
+            const isRetryable = error.message?.includes('429') ||
+                error.message?.includes('500') ||
+                error.message?.includes('502') ||
+                error.message?.includes('503') ||
+                error.message?.includes('fetch failed') ||
+                error.code === 'ECONNRESET' ||
+                error.code === 'ETIMEDOUT';
+            if (!isRetryable) {
+                // e.g. 400 Bad Request, 401 Unauthorized, 403 Forbidden shouldn't be retried
+                throw error;
+            }
+            const delay = baseDelayMs * Math.pow(2, attempt - 1);
+            process.stderr.write(`  ⚠ Operation failed. Retrying in ${delay}ms (Attempt ${attempt}/${maxRetries})...\n`);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+}
+//# sourceMappingURL=retry.js.map

package/dist/utils/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,SAA2B,EAC3B,aAAqB,CAAC,EACtB,cAAsB,IAAI;IAE1B,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,OAAO,IAAI,EAAE,CAAC;QACZ,IAAI,CAAC;YACH,OAAO,MAAM,SAAS,EAAE,CAAC;QAC3B,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,OAAO,EAAE,CAAC;YACV,IAAI,OAAO,GAAG,UAAU,EAAE,CAAC;gBACzB,MAAM,KAAK,CAAC;YACd,CAAC;YAED,mCAAmC;YACnC,6FAA6F;YAC7F,MAAM,WAAW,GACf,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC;gBAC9B,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC;gBAC9B,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC;gBAC9B,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC;gBAC9B,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,cAAc,CAAC;gBACvC,KAAK,CAAC,IAAI,KAAK,YAAY;gBAC3B,KAAK,CAAC,IAAI,KAAK,WAAW,CAAC;YAE7B,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjB,6EAA6E;gBAC7E,MAAM,KAAK,CAAC;YACd,CAAC;YAED,MAAM,KAAK,GAAG,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;YACrD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qCAAqC,KAAK,eAAe,OAAO,IAAI,UAAU,QAAQ,CAAC,CAAC;YAC7G,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;AACH,CAAC"}

package/docs/README.md

@@ -0,0 +1,13 @@
+# docs
+
+Markdown documentation for Conductor.
+
+## Contents
+
+- `getting-started.md` - Installation and initial setup guide
+- `api.md` - API reference documentation
+- `plugins.md` - Plugin development guide
+
+## Architecture
+
+These are raw markdown docs for local reference. For the rendered documentation site, see `docs-site/` (VitePress). Keep docs in sync with code changes — update API docs when interfaces change and plugin docs when the plugin system evolves.

package/docs/api.md

@@ -0,0 +1,210 @@
+# Conductor Dashboard API
+
+All API routes are served by the Express dashboard on `http://127.0.0.1:4242`.
+
+## Authentication
+
+Every `/api/*` request (except `/api/auth/google/callback`) must include:
+
+```
+Authorization: Bearer <token>
+```
+
+The token is generated on first startup and stored at `~/.conductor/dashboard.token` (mode 0600).
+It is also injected into the served HTML as `<meta name="dashboard-token" content="...">`.
+
+---
+
+## Status
+
+### GET /api/status
+Returns server version and environment info.
+
+**Response**
+```json
+{
+  "version": "1.0.0",
+  "configDir": "/Users/alex/.conductor",
+  "nodeVersion": "v20.11.0",
+  "platform": "darwin"
+}
+```
+
+---
+
+## Config
+
+### GET /api/config
+Returns the full config object (all keys).
+
+### POST /api/config
+Set a config value by dot-notation key.
+
+**Body**
+```json
+{ "key": "ai.provider", "value": "claude" }
+```
+
+---
+
+## Plugins
+
+### GET /api/plugins
+Returns plugin registry state.
+
+**Response**
+```json
+{
+  "installed": ["gmail", "github"],
+  "enabled": ["gmail"],
+  "all": ["calculator", "gmail", ...],
+  "requiredCreds": { "gmail": [{"service": "google", "key": "access_token"}] }
+}
+```
+
+### POST /api/plugins/toggle
+Enable or disable a plugin. Returns 400 if required credentials are missing.
+
+**Body**
+```json
+{ "plugin": "gmail", "enabled": true }
+```
+
+---
+
+## Credentials
+
+### GET /api/credentials
+Returns credential status (does NOT return values).
+
+**Response**
+```json
+[
+  { "service": "claude", "key": "api_key", "hasValue": true },
+  { "service": "github", "key": "token", "hasValue": false }
+]
+```
+
+### POST /api/credentials
+Store an encrypted credential.
+
+**Body**
+```json
+{ "service": "github", "key": "token", "value": "ghp_..." }
+```
+
+### DELETE /api/credentials/:service/:key
+Delete a credential.
+
+---
+
+## Google OAuth
+
+### GET /api/auth/google/status
+Returns `{ "connected": true/false }`.
+
+### GET /api/auth/google/url
+Returns the Google OAuth authorization URL.
+
+**Response**
+```json
+{ "url": "https://accounts.google.com/o/oauth2/auth?..." }
+```
+
+### GET /api/auth/google/callback
+OAuth redirect endpoint — must be accessible without auth token (browser redirect).
+
+### DELETE /api/auth/google
+Revoke stored Google tokens.
+
+---
+
+## Conversations
+
+### GET /api/conversations
+Returns recent messages from the database.
+
+**Response**
+```json
+{
+  "messages": [
+    {
+      "user_id": "123456",
+      "role": "user",
+      "content": "What's the weather?",
+      "timestamp": "2026-03-12 10:00:00"
+    }
+  ]
+}
+```
+
+---
+
+## Live Logs
+
+### GET /api/logs/stream
+Server-Sent Events stream of log output.
+
+**Response** (SSE)
+```
+data: {"level":"info","message":"Dashboard started","timestamp":"2026-03-12T10:00:00.000Z"}
+
+data: {"level":"error","message":"Plugin error: ...","timestamp":"..."}
+```
+
+Levels: `info`, `warn`, `error`
+
+---
+
+## Activity
+
+### GET /api/activity
+Returns recent activity log entries (up to 20).
+
+---
+
+## Lumen API Key
+
+### POST /api/lumen/key
+Generate and store a new Lumen API key. Returns the plaintext key once.
+
+**Response**
+```json
+{ "ok": true, "key": "cnd_..." }
+```
+
+### GET /api/lumen/key/status
+Returns `{ "hasKey": true/false }`.
+
+### DELETE /api/lumen/key
+Revoke the current API key.
+
+---
+
+## Lumen Agent
+
+### POST /api/lumen/ask
+Forward a task to the local Lumen/Ollama agent.
+
+**Auth**: `Authorization: Bearer <lumen-api-key>` (uses the Lumen API key, not the dashboard token)
+
+**Body**
+```json
+{ "task": "Show git status", "max_iterations": 5 }
+```
+
+---
+
+## Todoist Proxy
+
+All routes require `todoist / api_token` to be set in the keychain.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | /api/todoist/status | Check if configured |
+| GET | /api/todoist/projects | List all projects |
+| GET | /api/todoist/tasks | List tasks (query: project_id, label, filter) |
+| POST | /api/todoist/tasks | Create a task |
+| POST | /api/todoist/tasks/:id | Update a task |
+| POST | /api/todoist/tasks/:id/close | Complete a task |
+| DELETE | /api/todoist/tasks/:id | Delete a task |