npm - agentdev-webui - Versions diffs - 1.0.0 - Mend

agentdev-webui 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (39) hide show

package/lib/agent-api.js +530 -0
package/lib/auth.js +127 -0
package/lib/config.js +53 -0
package/lib/database.js +762 -0
package/lib/device-flow.js +257 -0
package/lib/email.js +420 -0
package/lib/encryption.js +112 -0
package/lib/github.js +339 -0
package/lib/history.js +143 -0
package/lib/pwa.js +107 -0
package/lib/redis-logs.js +226 -0
package/lib/routes.js +680 -0
package/migrations/000_create_database.sql +33 -0
package/migrations/001_create_agentdev_schema.sql +135 -0
package/migrations/001_create_agentdev_schema.sql.old +100 -0
package/migrations/001_create_agentdev_schema_fixed.sql +135 -0
package/migrations/002_add_github_token.sql +17 -0
package/migrations/003_add_agent_logs_table.sql +23 -0
package/migrations/004_remove_oauth_columns.sql +11 -0
package/migrations/005_add_projects.sql +44 -0
package/migrations/006_project_github_token.sql +7 -0
package/migrations/007_project_repositories.sql +12 -0
package/migrations/008_add_notifications.sql +20 -0
package/migrations/009_unified_oauth.sql +153 -0
package/migrations/README.md +97 -0
package/package.json +37 -0
package/public/css/styles.css +1140 -0
package/public/device.html +384 -0
package/public/docs.html +862 -0
package/public/docs.md +697 -0
package/public/favicon.svg +5 -0
package/public/index.html +271 -0
package/public/js/app.js +2379 -0
package/public/login.html +224 -0
package/public/profile.html +394 -0
package/public/register.html +392 -0
package/public/reset-password.html +349 -0
package/public/verify-email.html +177 -0
package/server.js +1450 -0

package/public/docs.html ADDED Viewed

@@ -0,0 +1,862 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta name="theme-color" content="#1a1a2e">
+  <meta name="apple-mobile-web-app-capable" content="yes">
+  <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
+  <meta name="description" content="AgentDev client documentation">
+  <meta property="og:title" content="AgentDev Client Documentation">
+  <meta property="og:description" content="AgentDev client documentation">
+  <meta property="og:type" content="website">
+  <meta property="og:image" content="/og-image.svg">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="AgentDev Client Documentation">
+  <meta name="twitter:description" content="AgentDev client documentation">
+  <meta name="twitter:image" content="/og-image.svg">
+  <title>AgentDev Client Documentation</title>
+  <link rel="icon" type="image/svg+xml" href="/favicon.svg">
+  <link rel="apple-touch-icon" href="/icon-192.png">
+  <link rel="manifest" href="/manifest.json">
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #0d1117; color: #c9d1d9; min-height: 100vh; display: flex; flex-direction: column; }
+    /* Top bar */
+    .topbar { background: #161b22; border-bottom: 1px solid #30363d; padding: 12px 24px; display: flex; align-items: center; gap: 16px; position: fixed; top: 0; left: 0; right: 0; z-index: 100; height: 56px; }
+    .topbar-logo { color: #e94560; font-weight: bold; font-size: 18px; text-decoration: none; }
+    .topbar-title { color: #8b949e; font-size: 14px; }
+    .topbar-links { margin-left: auto; display: flex; gap: 16px; }
+    .topbar-links a { color: #58a6ff; text-decoration: none; font-size: 13px; }
+    .topbar-links a:hover { text-decoration: underline; }
+    /* Layout */
+    .layout { display: flex; margin-top: 56px; min-height: calc(100vh - 56px); }
+    /* Sidebar nav */
+    .sidebar-nav { width: 280px; background: #161b22; border-right: 1px solid #30363d; position: fixed; top: 56px; bottom: 0; left: 0; overflow-y: auto; padding: 20px 0; flex-shrink: 0; }
+    .sidebar-nav::-webkit-scrollbar { width: 6px; }
+    .sidebar-nav::-webkit-scrollbar-thumb { background: #30363d; border-radius: 3px; }
+    .nav-section { margin-bottom: 8px; }
+    .nav-section-title { padding: 8px 20px; font-size: 11px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.5px; color: #8b949e; }
+    .nav-link { display: block; padding: 6px 20px 6px 28px; font-size: 13px; color: #c9d1d9; text-decoration: none; border-left: 2px solid transparent; transition: all 0.15s; }
+    .nav-link:hover { background: #1c2128; color: #f0f6fc; }
+    .nav-link.active { border-left-color: #e94560; color: #f0f6fc; background: #1c2128; }
+    .nav-link.sub { padding-left: 40px; font-size: 12px; color: #8b949e; }
+    .nav-link.sub:hover { color: #c9d1d9; }
+    /* Content area */
+    .content { margin-left: 280px; flex: 1; max-width: 860px; padding: 40px 48px 80px; }
+    /* Typography */
+    h1 { font-size: 32px; color: #f0f6fc; margin-bottom: 8px; font-weight: 600; }
+    .subtitle { font-size: 16px; color: #8b949e; margin-bottom: 32px; }
+    h2 { font-size: 24px; color: #f0f6fc; margin-top: 48px; margin-bottom: 16px; padding-bottom: 8px; border-bottom: 1px solid #21262d; font-weight: 600; }
+    h2:first-of-type { margin-top: 0; }
+    h3 { font-size: 18px; color: #f0f6fc; margin-top: 32px; margin-bottom: 12px; font-weight: 600; }
+    h4 { font-size: 15px; color: #c9d1d9; margin-top: 24px; margin-bottom: 8px; font-weight: 600; }
+    p { line-height: 1.7; margin-bottom: 16px; font-size: 14px; }
+    ul, ol { margin-bottom: 16px; padding-left: 24px; }
+    li { line-height: 1.7; margin-bottom: 6px; font-size: 14px; }
+    /* Code */
+    code { background: #1c2128; padding: 2px 6px; border-radius: 4px; font-family: 'SFMono-Regular', Consolas, monospace; font-size: 13px; color: #e6edf3; border: 1px solid #30363d; }
+    pre { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 16px 20px; overflow-x: auto; margin: 12px 0 20px; }
+    pre code { background: none; padding: 0; border: none; font-size: 13px; line-height: 1.5; }
+    /* Tables */
+    table { width: 100%; border-collapse: collapse; margin: 12px 0 20px; font-size: 13px; }
+    th { background: #161b22; color: #f0f6fc; text-align: left; padding: 10px 14px; border: 1px solid #30363d; font-weight: 600; }
+    td { padding: 10px 14px; border: 1px solid #21262d; vertical-align: top; }
+    tr:hover { background: #161b2244; }
+    /* Callouts */
+    .callout { padding: 12px 16px; border-radius: 6px; margin: 16px 0; font-size: 13px; line-height: 1.6; border-left: 3px solid; }
+    .callout-info { background: #0d419d22; border-color: #58a6ff; }
+    .callout-warn { background: #9e6a0322; border-color: #d29922; }
+    .callout-success { background: #23863622; border-color: #3fb950; }
+    .callout strong { display: block; margin-bottom: 4px; }
+    .callout-info strong { color: #58a6ff; }
+    .callout-warn strong { color: #d29922; }
+    .callout-success strong { color: #3fb950; }
+    /* Diagram */
+    .diagram { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 20px 24px; font-family: 'SFMono-Regular', Consolas, monospace; font-size: 13px; line-height: 1.6; margin: 16px 0 20px; overflow-x: auto; white-space: pre; color: #8b949e; }
+    /* Badges */
+    .badge { display: inline-block; padding: 2px 8px; border-radius: 12px; font-size: 11px; font-weight: 600; }
+    .badge-get { background: #23863622; color: #3fb950; }
+    .badge-post { background: #0d419d22; color: #58a6ff; }
+    /* Section anchor links */
+    .section { scroll-margin-top: 72px; }
+    /* Mobile */
+    @media (max-width: 768px) {
+      .sidebar-nav { display: none; }
+      .content { margin-left: 0; padding: 24px 16px 60px; }
+      .topbar { padding: 12px 16px; }
+    }
+    /* Footer */
+    .footer { margin-top: 64px; padding-top: 24px; border-top: 1px solid #21262d; color: #484f58; font-size: 12px; text-align: center; }
+    .footer a { color: #58a6ff; text-decoration: none; }
+  </style>
+</head>
+<body>
+<div class="topbar">
+  <a href="/" class="topbar-logo"><img src="/favicon.svg" alt="" style="width:24px;height:24px;vertical-align:middle;margin-right:8px;">AgentDev</a>
+  <span class="topbar-title">Client Documentation</span>
+  <div class="topbar-links">
+    <a href="/">Dashboard</a>
+    <a href="/profile">Profile</a>
+    <a href="/device">Device Auth</a>
+  </div>
+</div>
+<div class="layout">
+  <nav class="sidebar-nav" id="sidebarNav">
+    <div class="nav-section">
+      <div class="nav-section-title">Getting Started</div>
+      <a href="#overview" class="nav-link">Overview</a>
+      <a href="#architecture" class="nav-link">Architecture</a>
+      <a href="#installation" class="nav-link">Installation</a>
+      <a href="#quickstart" class="nav-link">Quick Start</a>
+    </div>
+    <div class="nav-section">
+      <div class="nav-section-title">Registration</div>
+      <a href="#register" class="nav-link">Agent Registration</a>
+      <a href="#device-flow" class="nav-link">Device Flow Auth</a>
+      <a href="#config" class="nav-link">Configuration</a>
+    </div>
+    <div class="nav-section">
+      <div class="nav-section-title">CLI Commands</div>
+      <a href="#cmd-register" class="nav-link">agentdev register</a>
+      <a href="#cmd-start" class="nav-link">agentdev start</a>
+      <a href="#cmd-cron" class="nav-link">agentdev cron</a>
+      <a href="#cmd-status" class="nav-link">agentdev status</a>
+      <a href="#cmd-config" class="nav-link">agentdev config</a>
+      <a href="#cmd-ticket" class="nav-link">agentdev ticket</a>
+      <a href="#cmd-gh" class="nav-link">agentdev gh</a>
+      <a href="#cmd-openspec" class="nav-link">agentdev openspec</a>
+      <a href="#cmd-onboard" class="nav-link">agentdev onboard</a>
+    </div>
+    <div class="nav-section">
+      <div class="nav-section-title">Agent Work Cycle</div>
+      <a href="#work-cycle" class="nav-link">How Agents Work</a>
+      <a href="#heartbeat" class="nav-link">Heartbeat</a>
+      <a href="#ticket-execution" class="nav-link">Ticket Execution</a>
+      <a href="#log-streaming" class="nav-link">Log Streaming</a>
+    </div>
+    <div class="nav-section">
+      <div class="nav-section-title">API Reference</div>
+      <a href="#api-device" class="nav-link">Device Flow API</a>
+      <a href="#api-agent" class="nav-link">Agent API</a>
+      <a href="#api-github" class="nav-link">GitHub Integration</a>
+    </div>
+    <div class="nav-section">
+      <div class="nav-section-title">Advanced</div>
+      <a href="#workspace" class="nav-link">Workspace Setup</a>
+      <a href="#skills" class="nav-link">Claude Skills</a>
+      <a href="#env-vars" class="nav-link">Environment Variables</a>
+      <a href="#troubleshooting" class="nav-link">Troubleshooting</a>
+    </div>
+  </nav>
+  <main class="content">
+    <!-- Overview -->
+    <div class="section" id="overview">
+      <h1>AgentDev Client</h1>
+      <p class="subtitle">Distributed agent system for automated GitHub ticket processing with Claude CLI</p>
+      <p>AgentDev is a distributed agent management platform that connects local machines running Claude CLI to a central server. Agents automatically pick up GitHub tickets tagged with <code>@claude</code>, execute the work, and stream logs back to the web dashboard in real-time.</p>
+      <ul>
+        <li>Run automated agents on any machine with Claude CLI installed</li>
+        <li>Agents poll the server for available tickets and execute them autonomously</li>
+        <li>Real-time log streaming to the web dashboard via SSE</li>
+        <li>GitHub project board integration for ticket status tracking</li>
+        <li>Multi-project support with per-agent project assignment</li>
+        <li>Device flow authentication for secure agent registration</li>
+      </ul>
+    </div>
+    <!-- Architecture -->
+    <div class="section" id="architecture">
+      <h2>Architecture</h2>
+      <div class="diagram">
+┌──────────────────────────────────┐
+│  Agent Machine (your laptop/VM)  │
+│                                  │
+│  $ agentdev start                │
+│    ├── Polls for tickets (10s)   │
+│    ├── Runs Claude CLI           │
+│    └── Streams logs back         │
+│                                  │
+│  ~/agentdev-workspace/           │
+│    ├── repo-a/                   │
+│    ├── repo-b/                   │
+│    └── repo-c/                   │
+└──────────────┬───────────────────┘
+               │ HTTPS (Bearer JWT)
+               ▼
+┌──────────────────────────────────┐
+│  AgentDev Server                 │
+│  agentdev.datatamer.ai           │
+│                                  │
+│  ├── Assign tickets to agents    │
+│  ├── Store OAuth tokens (enc)    │
+│  ├── Aggregate & broadcast logs  │
+│  └── GitHub project board sync   │
+└──────────────┬───────────────────┘
+               │
+               ▼
+┌──────────────────────────────────┐
+│  GitHub                          │
+│  ├── Issues (tickets)            │
+│  ├── Project Board (statuses)    │
+│  └── Repositories (code)         │
+└──────────────────────────────────┘</div>
+    </div>
+    <!-- Installation -->
+    <div class="section" id="installation">
+      <h2>Installation</h2>
+      <h3>Prerequisites</h3>
+      <table>
+        <tr><th>Requirement</th><th>Version</th><th>Check</th></tr>
+        <tr><td>Node.js</td><td>18+</td><td><code>node --version</code></td></tr>
+        <tr><td>Claude CLI</td><td>latest</td><td><code>claude --version</code></td></tr>
+        <tr><td>Git</td><td>any</td><td><code>git --version</code></td></tr>
+      </table>
+      <h3>Install via npm</h3>
+      <pre><code>npm install -g @datatamer/agentdev</code></pre>
+      <h3>Verify Installation</h3>
+      <pre><code>agentdev --version
+# 1.0.0</code></pre>
+      <div class="callout callout-info">
+        <strong>Note</strong>
+        The GitHub CLI (<code>gh</code>) is optional. AgentDev includes its own GitHub API integration via <code>agentdev gh</code>.
+      </div>
+    </div>
+    <!-- Quick Start -->
+    <div class="section" id="quickstart">
+      <h2>Quick Start</h2>
+      <pre><code># 1. Register your agent with the server
+agentdev register
+# 2. Approve the device code in your browser
+#    Visit the URL shown and enter the code
+# 3. Start processing tickets
+agentdev start
+# 4. Check status
+agentdev status</code></pre>
+      <p>That's it. Your agent will poll for tickets, execute them with Claude CLI, and stream logs to the dashboard.</p>
+    </div>
+    <!-- Registration -->
+    <div class="section" id="register">
+      <h2>Agent Registration</h2>
+      <p>Each agent must be registered with the server before it can claim work. Registration uses the OAuth 2.0 Device Authorization Grant flow.</p>
+      <h3>Step 1: Run Register</h3>
+      <pre><code>agentdev register
+# or with options:
+agentdev register --url https://agentdev.datatamer.ai --name my-agent</code></pre>
+      <table>
+        <tr><th>Option</th><th>Default</th><th>Description</th></tr>
+        <tr><td><code>-u, --url</code></td><td><code>https://agentdev.datatamer.ai</code></td><td>Server URL</td></tr>
+        <tr><td><code>-n, --name</code></td><td>System hostname</td><td>Agent display name</td></tr>
+      </table>
+      <h3>Step 2: Approve in Browser</h3>
+      <p>The terminal will display a user code and verification URL:</p>
+      <pre><code>✓ Device code obtained
+  Code: ABCD-EFGH
+  Visit: https://agentdev.datatamer.ai/device
+  Waiting for approval...</code></pre>
+      <ol>
+        <li>Open the verification URL in your browser</li>
+        <li>Log in to AgentDev if not already signed in</li>
+        <li>Enter the user code displayed in your terminal</li>
+        <li>Select the project to assign the agent to</li>
+        <li>Click "Approve Agent"</li>
+      </ol>
+      <h3>Step 3: Confirmation</h3>
+      <pre><code>✓ Agent registered successfully!
+  Agent ID: agent-1704067200-abc123
+  Project: DataTamer (#1)</code></pre>
+      <div class="callout callout-success">
+        <strong>Done</strong>
+        Your agent token and project configuration are saved to <code>~/.config/agentdev/config.json</code>.
+      </div>
+    </div>
+    <!-- Device Flow -->
+    <div class="section" id="device-flow">
+      <h2>Device Flow Authentication</h2>
+      <p>AgentDev uses the OAuth 2.0 Device Authorization Grant (RFC 8628) for agent authentication. This is ideal for headless servers and CLI tools that can't open a browser.</p>
+      <h3>How It Works</h3>
+      <ol>
+        <li>Agent requests a device code from the server</li>
+        <li>Server returns a short user code (e.g., <code>ABCD-EFGH</code>) and verification URL</li>
+        <li>User visits the URL in a browser and enters the code</li>
+        <li>User approves and selects a project for the agent</li>
+        <li>Agent polls the server until the code is approved (every 5 seconds)</li>
+        <li>Server returns a JWT token valid for 90 days</li>
+      </ol>
+      <h3>JWT Token</h3>
+      <p>The token contains:</p>
+      <table>
+        <tr><th>Field</th><th>Description</th></tr>
+        <tr><td><code>agent_id</code></td><td>Unique agent identifier</td></tr>
+        <tr><td><code>user_id</code></td><td>ID of the user who approved the agent</td></tr>
+        <tr><td><code>project_id</code></td><td>Assigned project ID</td></tr>
+        <tr><td><code>type</code></td><td>Always <code>"agent"</code></td></tr>
+        <tr><td><code>exp</code></td><td>Expires in 90 days</td></tr>
+      </table>
+    </div>
+    <!-- Configuration -->
+    <div class="section" id="config">
+      <h2>Configuration</h2>
+      <p>Configuration is stored at <code>~/.config/agentdev/config.json</code> and managed via the <code>agentdev config</code> command or set automatically during registration.</p>
+      <h3>Config File</h3>
+      <pre><code>{
+  "api_url": "https://agentdev.datatamer.ai",
+  "agent_token": "eyJhbGciOi...",
+  "agent_id": "agent-1704067200-abc123",
+  "agent_name": "my-laptop",
+  "max_concurrent": 1,
+  "github_org": "data-tamer",
+  "project_id": "PVT_kwDOCJIWbs4AnuSZ",
+  "project_number": 1,
+  "status_field_id": "PVTSSF_lADOCJIWbs4AnuSZzgfaWGs",
+  "status_options": {
+    "TODO": "f75ad846",
+    "IN_PROGRESS": "47fc9ee4",
+    "TEST": "c48bc058",
+    "DONE": "98236657"
+  }
+}</code></pre>
+      <h3>Managing Config</h3>
+      <pre><code># View all settings
+agentdev config get
+# View a specific key
+agentdev config get api_url
+# Update a setting
+agentdev config set api_url https://agentdev.datatamer.ai</code></pre>
+    </div>
+    <!-- CLI Commands -->
+    <div class="section" id="cmd-register">
+      <h2>CLI Commands</h2>
+      <h3>agentdev register</h3>
+      <p>Register this agent with the AgentDev server using device flow authentication.</p>
+      <pre><code>agentdev register [--url &lt;url&gt;] [--name &lt;name&gt;]</code></pre>
+      <table>
+        <tr><th>Option</th><th>Default</th><th>Description</th></tr>
+        <tr><td><code>-u, --url</code></td><td><code>https://agentdev.datatamer.ai</code></td><td>Server URL</td></tr>
+        <tr><td><code>-n, --name</code></td><td>hostname</td><td>Agent name</td></tr>
+      </table>
+    </div>
+    <div class="section" id="cmd-start">
+      <h3>agentdev start</h3>
+      <p>Start the agent in daemon mode. Continuously polls for work and executes tickets.</p>
+      <pre><code>agentdev start [--concurrent &lt;number&gt;]</code></pre>
+      <table>
+        <tr><th>Option</th><th>Default</th><th>Description</th></tr>
+        <tr><td><code>-c, --concurrent</code></td><td><code>1</code></td><td>Max concurrent tickets</td></tr>
+      </table>
+      <p>Behavior:</p>
+      <ul>
+        <li>Polls for work every <strong>10 seconds</strong></li>
+        <li>Sends heartbeat every <strong>30 seconds</strong></li>
+        <li>Syncs Claude skills to <code>~/.claude/commands/</code></li>
+        <li>Fetches GitHub OAuth tokens from server</li>
+        <li>30-second backoff on errors</li>
+        <li>Graceful shutdown on SIGINT/SIGTERM</li>
+      </ul>
+    </div>
+    <div class="section" id="cmd-cron">
+      <h3>agentdev cron</h3>
+      <p>Run in batch/cron mode. Processes all available tickets in cycles with a configurable interval.</p>
+      <pre><code>agentdev cron [--interval &lt;minutes&gt;] [--max-tickets &lt;number&gt;]</code></pre>
+      <table>
+        <tr><th>Option</th><th>Default</th><th>Description</th></tr>
+        <tr><td><code>-i, --interval</code></td><td><code>5</code></td><td>Minutes between cycles</td></tr>
+        <tr><td><code>-m, --max-tickets</code></td><td><code>10</code></td><td>Max tickets per cycle</td></tr>
+      </table>
+      <p>Ideal for CI/CD pipelines or scheduled batch processing.</p>
+    </div>
+    <div class="section" id="cmd-status">
+      <h3>agentdev status</h3>
+      <p>Display the agent's registration status and configuration.</p>
+      <pre><code>agentdev status</code></pre>
+      <p>Shows: agent ID, name, API URL, registration status, config file location.</p>
+    </div>
+    <div class="section" id="cmd-config">
+      <h3>agentdev config</h3>
+      <p>View and modify configuration values.</p>
+      <pre><code># View all config
+agentdev config get
+# View single key
+agentdev config get api_url
+# Set a value
+agentdev config set max_concurrent 2</code></pre>
+    </div>
+    <div class="section" id="cmd-ticket">
+      <h3>agentdev ticket</h3>
+      <p>Create and manage tickets from the command line.</p>
+      <pre><code># Create a ticket
+agentdev ticket create -R my-repo \
+  --title "Fix login bug" \
+  --body "The login form crashes on submit" \
+  --claude
+# Output (JSON)
+agentdev ticket create -R my-repo --title "..." --json</code></pre>
+      <table>
+        <tr><th>Option</th><th>Description</th></tr>
+        <tr><td><code>-R &lt;repo&gt;</code></td><td>Repository name (under the org)</td></tr>
+        <tr><td><code>--title</code></td><td>Issue title</td></tr>
+        <tr><td><code>--body</code></td><td>Issue body text</td></tr>
+        <tr><td><code>--body-file</code></td><td>Read body from file</td></tr>
+        <tr><td><code>--claude / --no-claude</code></td><td>Append <code>@claude</code> tag (default: true)</td></tr>
+        <tr><td><code>--json</code></td><td>Output as JSON</td></tr>
+      </table>
+      <p>Creates the GitHub issue, adds it to the project board, and sets status to "Todo".</p>
+    </div>
+    <div class="section" id="cmd-gh">
+      <h3>agentdev gh</h3>
+      <p>GitHub CLI replacement with pre-configured authentication. Uses the agent's OAuth token.</p>
+      <h4>Issues</h4>
+      <pre><code># View an issue
+agentdev gh issue view 42 -R owner/repo
+# Create an issue
+agentdev gh issue create -R owner/repo --title "Bug" --body "Details"
+# Comment on an issue
+agentdev gh issue comment 42 -R owner/repo --body "Fixed in PR #43"
+# Reopen an issue
+agentdev gh issue reopen 42 -R owner/repo</code></pre>
+      <h4>Pull Requests</h4>
+      <pre><code># Create a PR
+agentdev gh pr create -R owner/repo \
+  --title "Fix bug" --body "Description" \
+  --head feature-branch --base main
+# View a PR
+agentdev gh pr view 43 -R owner/repo --json state,title
+# Merge a PR
+agentdev gh pr merge 43 -R owner/repo --squash</code></pre>
+      <h4>Project Board</h4>
+      <pre><code># Update project item status
+agentdev gh project item-edit \
+  --id ITEM_ID \
+  --project-id PROJECT_ID \
+  --field-id FIELD_ID \
+  --single-select-option-id OPTION_ID</code></pre>
+      <h4>Raw API</h4>
+      <pre><code># GraphQL
+agentdev gh api graphql -f query='{ viewer { login } }'
+# REST
+agentdev gh api rest /repos/owner/repo/issues -X GET</code></pre>
+    </div>
+    <div class="section" id="cmd-openspec">
+      <h3>agentdev openspec</h3>
+      <p>Spec-driven development commands. Wraps the <code>@fission-ai/openspec</code> CLI.</p>
+      <pre><code># Initialize openspec in a repo
+agentdev openspec init
+# List artifacts
+agentdev openspec list --specs --sort recent
+# Show artifact details
+agentdev openspec show my-feature --json
+# Validate artifacts
+agentdev openspec validate --all --strict
+# Get implementation instructions
+agentdev openspec instructions my-artifact --change feature-x
+# Archive a completed change
+agentdev openspec archive my-change --yes</code></pre>
+    </div>
+    <div class="section" id="cmd-onboard">
+      <h3>agentdev onboard</h3>
+      <p>Interactive repository discovery and environment skill generation.</p>
+      <pre><code>agentdev onboard [--workspace &lt;path&gt;] [--no-claude] [--force]</code></pre>
+      <table>
+        <tr><th>Option</th><th>Default</th><th>Description</th></tr>
+        <tr><td><code>-w, --workspace</code></td><td>current dir</td><td>Workspace root to scan</td></tr>
+        <tr><td><code>--no-claude</code></td><td>false</td><td>Use templates instead of Claude generation</td></tr>
+        <tr><td><code>--force</code></td><td>false</td><td>Overwrite existing skills</td></tr>
+      </table>
+      <p>The onboard command:</p>
+      <ol>
+        <li>Scans the workspace for git repositories</li>
+        <li>Detects language, framework, databases, test runner, Docker setup</li>
+        <li>Prompts you to select repos to onboard</li>
+        <li>Asks for environment details (deploy method, test commands, DB connections)</li>
+        <li>Generates Claude skill files at <code>.claude/commands/env-&lt;name&gt;.md</code></li>
+        <li>Saves structured metadata to <code>.claude/repo-spec.json</code></li>
+      </ol>
+      <h4>Detected Technologies</h4>
+      <table>
+        <tr><th>Category</th><th>Detected</th></tr>
+        <tr><td>Languages</td><td>JavaScript, TypeScript, Python</td></tr>
+        <tr><td>Frameworks</td><td>Next.js, Express, Fastify, FastAPI, Django, Flask</td></tr>
+        <tr><td>Databases</td><td>PostgreSQL, MySQL, MongoDB, Redis, SQLite</td></tr>
+        <tr><td>ORMs</td><td>Prisma, SQLAlchemy, Mongoose</td></tr>
+        <tr><td>Test Runners</td><td>Jest, Vitest, Mocha, pytest, Playwright</td></tr>
+        <tr><td>Package Managers</td><td>npm, yarn, pnpm, pip, poetry, uv</td></tr>
+      </table>
+    </div>
+    <!-- Work Cycle -->
+    <div class="section" id="work-cycle">
+      <h2>How Agents Work</h2>
+      <div class="diagram">
+Agent starts: agentdev start
+        │
+        ├── Sync Claude skills to ~/.claude/commands/
+        ├── Fetch OAuth tokens (GitHub) from server
+        ├── Start heartbeat (every 30s)
+        │
+        ▼
+┌─── Poll Loop (every 10s) ──────────────────────────┐
+│                                                      │
+│  GET /api/agent/work                                 │
+│    ├── No ticket → print "." → wait 10s → loop      │
+│    └── Ticket found ↓                                │
+│                                                      │
+│  Execute Ticket                                      │
+│    ├── Set GH_TOKEN in env                           │
+│    ├── Spawn: claude -p --dangerously-skip-perms     │
+│    │         /auto-ticket-workflow                    │
+│    ├── Stream logs → POST /api/agent/logs (2s batch) │
+│    ├── Check stop signal (every 5s)                  │
+│    └── On exit → POST /api/agent/complete            │
+│                                                      │
+│  Loop back ↑                                         │
+└──────────────────────────────────────────────────────┘</div>
+    </div>
+    <div class="section" id="heartbeat">
+      <h3>Heartbeat</h3>
+      <p>Every <strong>30 seconds</strong>, the agent sends a heartbeat to keep its status updated on the server.</p>
+      <pre><code>POST /api/agent/heartbeat
+Authorization: Bearer &lt;token&gt;
+{
+  "status": "idle",        // or "busy"
+  "current_ticket": null   // or ticket ID
+}</code></pre>
+      <p>If the server doesn't receive a heartbeat for an extended period, the agent is considered offline.</p>
+    </div>
+    <div class="section" id="ticket-execution">
+      <h3>Ticket Execution</h3>
+      <p>When an agent claims a ticket, it:</p>
+      <ol>
+        <li>Sets <code>GH_TOKEN</code> environment variable from the server's OAuth tokens</li>
+        <li>Creates a temp file for Claude output (avoids pipe buffering)</li>
+        <li>Spawns Claude CLI:
+          <pre><code>claude -p --dangerously-skip-permissions \
+  --output-format stream-json --verbose</code></pre>
+        </li>
+        <li>Sends the <code>/auto-ticket-workflow</code> skill as the prompt</li>
+        <li>Tails the output file and parses stream-json in real-time</li>
+        <li>Batches parsed logs to the server every 2 seconds</li>
+        <li>Polls <code>/api/agent/should-stop</code> every 5 seconds (kills process if requested)</li>
+        <li>On process exit, reports completion via <code>/api/agent/complete</code></li>
+      </ol>
+    </div>
+    <div class="section" id="log-streaming">
+      <h3>Log Streaming</h3>
+      <p>Logs are batched and uploaded to the server in real-time:</p>
+      <ul>
+        <li><strong>Batch interval:</strong> every 2 seconds</li>
+        <li><strong>Batch size:</strong> up to 10 log entries</li>
+        <li><strong>Parsed content:</strong> text output, tool calls, tool results, cost info</li>
+      </ul>
+      <p>The server stores logs in PostgreSQL and broadcasts them to the web dashboard via SSE (Server-Sent Events).</p>
+    </div>
+    <!-- API Reference -->
+    <div class="section" id="api-device">
+      <h2>API Reference</h2>
+      <h3>Device Flow Endpoints</h3>
+      <h4><span class="badge badge-post">POST</span> /api/agent/device/code</h4>
+      <p>Request a new device code for agent registration.</p>
+      <pre><code>// Request
+{
+  "agent_name": "my-agent",
+  "capabilities": {
+    "cpu_cores": 8,
+    "memory_gb": 16,
+    "platform": "linux",
+    "arch": "x64",
+    "tools": ["git", "node", "claude"]
+  }
+}
+// Response (200)
+{
+  "device_code": "a1b2c3d4...",
+  "user_code": "ABCD-EFGH",
+  "verification_uri": "https://agentdev.datatamer.ai/device",
+  "expires_in": 600,
+  "interval": 5
+}</code></pre>
+      <h4><span class="badge badge-post">POST</span> /api/agent/device/token</h4>
+      <p>Poll for token after user approves the device code.</p>
+      <pre><code>// Request
+{ "device_code": "a1b2c3d4..." }
+// Response (200 - approved)
+{
+  "access_token": "eyJhbGciOi...",
+  "token_type": "Bearer",
+  "expires_in": 7776000,
+  "agent_id": "agent-1704067200-abc123",
+  "project_id": 1
+}
+// Response (428 - still pending)
+{ "error": "authorization_pending" }</code></pre>
+    </div>
+    <div class="section" id="api-agent">
+      <h3>Agent API Endpoints</h3>
+      <p>All endpoints require <code>Authorization: Bearer &lt;token&gt;</code>.</p>
+      <table>
+        <tr><th>Method</th><th>Endpoint</th><th>Description</th></tr>
+        <tr><td><span class="badge badge-post">POST</span></td><td><code>/api/agent/heartbeat</code></td><td>Send agent heartbeat with status</td></tr>
+        <tr><td><span class="badge badge-get">GET</span></td><td><code>/api/agent/work</code></td><td>Claim the next available ticket</td></tr>
+        <tr><td><span class="badge badge-get">GET</span></td><td><code>/api/agent/oauth</code></td><td>Get GitHub OAuth token</td></tr>
+        <tr><td><span class="badge badge-post">POST</span></td><td><code>/api/agent/logs</code></td><td>Upload log entries</td></tr>
+        <tr><td><span class="badge badge-post">POST</span></td><td><code>/api/agent/complete</code></td><td>Mark ticket as complete/failed</td></tr>
+        <tr><td><span class="badge badge-get">GET</span></td><td><code>/api/agent/should-stop</code></td><td>Check for stop signal</td></tr>
+        <tr><td><span class="badge badge-get">GET</span></td><td><code>/api/agent/project-config</code></td><td>Get project board configuration</td></tr>
+      </table>
+      <h4><span class="badge badge-get">GET</span> /api/agent/work</h4>
+      <p>Claims the next available ticket for the agent's assigned project.</p>
+      <pre><code>// Response (ticket available)
+{
+  "ticket": {
+    "id": "ticket-uuid",
+    "github_issue_number": 42,
+    "github_repo": "agentdev-webui",
+    "title": "Implement dark mode",
+    "description": "Add dark theme support"
+  }
+}
+// Response (no tickets)
+{ "ticket": null }</code></pre>
+      <h4><span class="badge badge-post">POST</span> /api/agent/logs</h4>
+      <p>Upload log entries. Batched by the client.</p>
+      <pre><code>// Request
+{
+  "logs": ["Log line 1", "Log line 2"],
+  "ticket_id": "ticket-uuid"
+}
+// Response
+{ "success": true, "count": 2 }</code></pre>
+      <h4><span class="badge badge-post">POST</span> /api/agent/complete</h4>
+      <p>Report ticket completion or failure.</p>
+      <pre><code>// Request
+{
+  "ticket_id": "ticket-uuid",
+  "success": true,
+  "error_message": null
+}
+// Response
+{ "success": true }</code></pre>
+      <h4><span class="badge badge-get">GET</span> /api/agent/should-stop?ticket_id=ID</h4>
+      <p>Check if the user has requested to stop this ticket's execution.</p>
+      <pre><code>// Response
+{ "should_stop": false }</code></pre>
+    </div>
+    <div class="section" id="api-github">
+      <h3>GitHub Integration</h3>
+      <p>The client includes a built-in GitHub API module (<code>agentdev gh</code>) that supports:</p>
+      <ul>
+        <li><strong>REST API</strong> &mdash; Issues, PRs, file uploads, generic REST calls</li>
+        <li><strong>GraphQL API</strong> &mdash; Project board operations, custom queries</li>
+        <li><strong>Token resolution</strong> &mdash; CLI arg &rarr; <code>GH_TOKEN</code> env &rarr; server OAuth</li>
+      </ul>
+      <p>This eliminates the dependency on the <code>gh</code> CLI while providing full GitHub API access.</p>
+    </div>
+    <!-- Advanced -->
+    <div class="section" id="workspace">
+      <h2>Workspace Setup</h2>
+      <h3>Default Workspace</h3>
+      <p>When you run <code>agentdev start</code>, the agent uses <code>~/agentdev-workspace/</code> by default.</p>
+      <h3>Custom Workspace</h3>
+      <pre><code># Set for current session
+export AGENTDEV_WORKSPACE=/path/to/your/repos
+agentdev start
+# Set permanently
+echo 'export AGENTDEV_WORKSPACE=/path/to/repos' >> ~/.bashrc</code></pre>
+      <div class="callout callout-info">
+        <strong>Tip</strong>
+        Using a custom workspace lets agents work with your existing cloned repos, avoiding redundant clones.
+      </div>
+    </div>
+    <div class="section" id="skills">
+      <h3>Claude Skills</h3>
+      <p>On startup, the agent syncs skill files from the package to <code>~/.claude/commands/</code>:</p>
+      <table>
+        <tr><th>Skill File</th><th>Purpose</th></tr>
+        <tr><td><code>agentdev-gh.md</code></td><td>GitHub CLI command reference for Claude</td></tr>
+        <tr><td><code>agentdev-openspec.md</code></td><td>OpenSpec workflow reference for Claude</td></tr>
+        <tr><td><code>auto-ticket.md</code></td><td>Full ticket workflow (proposal &rarr; implement &rarr; test &rarr; deploy)</td></tr>
+      </table>
+      <p>These skills are used as prompts when Claude executes tickets.</p>
+    </div>
+    <div class="section" id="env-vars">
+      <h3>Environment Variables</h3>
+      <table>
+        <tr><th>Variable</th><th>Description</th><th>Default</th></tr>
+        <tr><td><code>GH_TOKEN</code></td><td>GitHub personal access token</td><td>From server OAuth</td></tr>
+        <tr><td><code>AGENTDEV_WORKSPACE</code></td><td>Workspace directory path</td><td><code>~/agentdev-workspace</code></td></tr>
+        <tr><td><code>CLAUDE_BIN</code></td><td>Path to Claude CLI binary</td><td><code>claude</code></td></tr>
+        <tr><td><code>TICKET_NUMBER</code></td><td>Current ticket (set by executor)</td><td>&mdash;</td></tr>
+        <tr><td><code>REPO</code></td><td>Current repository (set by executor)</td><td>&mdash;</td></tr>
+        <tr><td><code>AGENT_ID</code></td><td>Agent identifier (set by executor)</td><td>&mdash;</td></tr>
+      </table>
+    </div>
+    <div class="section" id="troubleshooting">
+      <h3>Troubleshooting</h3>
+      <h4>Agent not picking up tickets</h4>
+      <ul>
+        <li>Verify the agent is running: <code>agentdev status</code></li>
+        <li>Check that tickets exist on the project board with status "Todo"</li>
+        <li>Ensure tickets have <code>@claude</code> in the description</li>
+        <li>Verify GitHub OAuth is configured in your <a href="/profile">Profile</a></li>
+        <li>Check that the agent is assigned to the correct project</li>
+      </ul>
+      <h4>Registration fails</h4>
+      <ul>
+        <li>Ensure the server URL is reachable: <code>curl https://agentdev.datatamer.ai</code></li>
+        <li>The device code expires after 10 minutes &mdash; re-run <code>agentdev register</code></li>
+        <li>Make sure you're logged into the web dashboard when approving</li>
+      </ul>
+      <h4>"claude: command not found"</h4>
+      <p>Install Claude CLI from <a href="https://claude.ai/download" target="_blank">claude.ai/download</a> and ensure it's in your PATH.</p>
+      <h4>Token expired</h4>
+      <p>Agent tokens expire after 90 days. Re-register:</p>
+      <pre><code>agentdev register</code></pre>
+      <h4>Check config file</h4>
+      <pre><code>cat ~/.config/agentdev/config.json</code></pre>
+    </div>
+    <div class="footer">
+      <p>AgentDev Client v1.0.0 &mdash; <a href="/">Dashboard</a> &mdash; Last updated February 2026</p>
+    </div>
+  </main>
+</div>
+<script>
+// Highlight active nav link on scroll
+const sections = document.querySelectorAll('.section');
+const navLinks = document.querySelectorAll('.nav-link');
+function updateActiveLink() {
+  let current = '';
+  sections.forEach(s => {
+    if (window.scrollY >= s.offsetTop - 80) current = s.id;
+  });
+  navLinks.forEach(l => {
+    l.classList.toggle('active', l.getAttribute('href') === '#' + current);
+  });
+}
+window.addEventListener('scroll', updateActiveLink);
+updateActiveLink();
+// Smooth scroll for nav links
+navLinks.forEach(link => {
+  link.addEventListener('click', e => {
+    e.preventDefault();
+    const target = document.querySelector(link.getAttribute('href'));
+    if (target) target.scrollIntoView({ behavior: 'smooth' });
+  });
+});
+</script>
+</body>
+</html>