@pixelbyte-software/pixcode 1.51.8 → 1.52.0

package/README.zh-CN.md

@@ -1,167 +1,167 @@
-<div align="center">
-  <img src="public/logo.png" alt="Pixcode logo" width="96" height="96" />
-  <h1>Pixcode</h1>
-  <p><strong>面向 AI coding agent 的 self-hosted control room。</strong></p>
-  <p>
-    在一个 Web UI 中使用 Claude Code、Cursor CLI、Codex、Gemini CLI、Qwen Code 和 OpenCode，并集成 chat、shell、files、Git、orchestration、API keys、plugins、notifications、Telegram、desktop/server deployment。
-  </p>
-  <p>
-    <a href="https://buymeacoffee.com/alicomert" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/Buy%20me%20a%20coffee-support%20Pixcode-ffdd00?style=for-the-badge&logo=buymeacoffee&logoColor=000000" alt="Buy me a coffee" /></a>
-  </p>
-  <p>
-    <a href="README.md">English</a> ·
-    <a href="README.tr.md">Türkçe</a> ·
-    <a href="README.de.md">Deutsch</a> ·
-    <a href="README.ru.md">Русский</a> ·
-    <a href="README.ja.md">日本語</a> ·
-    <a href="README.ko.md">한국어</a>
-  </p>
-</div>
-
-## Pixcode 是什么？
-
-Pixcode 可以把你的本机、工作站或 Linux 服务器变成浏览器里的 AI development cockpit。你不需要在多个 terminal、CLI logs、file explorer、Git UI、provider settings 之间切换，Pixcode 把 coding-agent workflow 放在一个本地 Web App 里。
-
-常见使用方式：
-
-- **Local workstation**：在自己的电脑上运行 Pixcode，用更好的 UI 操作已有 CLI。
-- **Always-on server**：在 Linux/VDS 上以 daemon 方式运行，从 laptop、tablet、phone 访问。
-- **Desktop app**：使用 GitHub Releases 中的 Windows `.exe`、macOS `.dmg`、Linux build。
-
-Pixcode 不是 hosted cloud IDE。Projects、credentials、CLI sessions、local files、Git state、MCP config 默认都保留在你的机器上。
-
-## Screenshots
-
-| Workspace | Mobile chat |
-| --- | --- |
-| <img src="public/screenshots/desktop-main.png" alt="Pixcode desktop workspace" width="480" /> | <img src="public/screenshots/mobile-chat.png" alt="Pixcode mobile chat" width="260" /> |
-
-| CLI selection | Tools and MCP |
-| --- | --- |
-| <img src="public/screenshots/cli-selection.png" alt="Pixcode CLI selection" width="420" /> | <img src="public/screenshots/tools-modal.png" alt="Pixcode tools modal" width="420" /> |
-
-## 功能亮点
-
-### 多个 CLI，一个界面
-
-- Claude Code、Cursor CLI、Codex、Gemini CLI、Qwen Code、OpenCode。
-- Settings 中管理 provider auth、API key credentials、OAuth paste、install status、model list、CLI version status。
-- Pixcode 不替代 native CLI，而是在其上增加 session management、WebSocket streaming、notifications、file context、project controls。
-- UI 会显示 CLI 是在 thinking、tool execution、approval waiting 还是 output streaming。
-
-### Chat、files、shell、source control
-
-- Project-aware chat sessions 和 history。
-- Prompt composer 固定在 chat/project screen 底部。
-- Shell panel 在 desktop 上可作为 split panel 或 full panel 打开。
-- File browser 支持 edit、upload、rename、delete、detailed view。
-- Source Control 支持 Git status、diff、branch、commit、changed files。
-- Split panels 提供 icon controls、close button、mobile-friendly responsive behavior。
-
-### Changed files Command Center
-
-Pixcode 会跟踪 local working tree 的变化。Quick Settings 中的 Command Center 可以即时显示 changed files，高亮新的改动，并跳转到相关 file/line。这样 AI agent 修改文件时，你可以看到它改了什么，同时保持 chat/orchestration view 不被关闭。
-
-### Multi-agent orchestration
-
-Orchestration 可以让多个 CLI agents 围绕同一个 goal 协作。
-
-- **Agent Team**：按 frontend、backend、review、docs、custom role 拆分任务。
-- **Multi-model Review**：用多个 provider/model 检查同一改动。
-- **Sequential Handoff**：按阶段交接任务。
-- **Decision Debate**：实现前比较不同 approach。
-
-Controls:
-
-- 按 run enable/disable agents，
-- 同一个 provider 可创建多个 worker，
-- agent 级 role、stage、label、instruction，
-- agent 级 model selection，包含 OpenCode model，
-- failed step 的 fallback CLI agent，
-- workflow DAG preview，
-- event streaming 和 cancel，
-- resizable orchestration panes。
-
-### API、Telegram、notifications
-
-Pixcode frontend 本身使用 REST/WebSocket API。External automation 也可以用 Pixcode API key 使用同一个 control plane。新的 API keys 以 `px_` 开头，旧的 `ck_` keys 仍然兼容。
-
-```bash
-curl http://localhost:3001/api/projects \
-  -H "Authorization: Bearer px_your_key_here"
-```
-
-- `POST /api/agent` for one-shot agent runs.
-- `/api/orchestration/workflows/*` for preview, start, stream, cancel.
-- Browser push notifications.
-- Telegram pairing、task notifications、optional prompt bridge。
-
-OpenAPI: [`public/openapi.yaml`](public/openapi.yaml)
-
-### Themes、plugins、MCP
-
-- Dark/light mode。
-- Emerald、VS Code-like accent palettes。
-- Custom light/dark accent colors。
-- Token-based styling for buttons、focus rings、navigation、active states。
-- MCP server management。
-- Plugin system with frontend tabs and optional backend services。
-
-## Installation
-
-需要 Node.js 22+。
-
-```bash
-npx @pixelbyte-software/pixcode
-```
-
-Global install:
-
-```bash
-npm install -g @pixelbyte-software/pixcode
-pixcode
-```
-
-Open:
-
-```text
-http://localhost:3001
-```
-
-Desktop installers are available in GitHub Releases: Windows `.exe`, macOS `.dmg`, Linux AppImage/packages.
-
-## Linux daemon
-
-```bash
-pixcode daemon install --mode auto --port 3001
-pixcode daemon status --mode auto
-pixcode daemon logs --mode auto
-pixcode daemon restart --mode auto
-```
-
-Foreground:
-
-```bash
-pixcode --no-daemon
-```
-
-## Development
-
-```bash
-npm install
-npm run typecheck
-npm run lint
-npm run build
-```
-
-Notes:
-
-- `npm run dev` uses the daemon manager on Linux.
-- Use `npm run client` only for Vite frontend development.
-- Normal runtime uses port `3001`; `5173` is for separate Vite dev.
-
-## Links
-
-- npm: <https://www.npmjs.com/package/@pixelbyte-software/pixcode>
-- GitHub: <https://github.com/alicomert/pixcode>
-- Releases: <https://github.com/alicomert/pixcode/releases/latest>
+<div align="center">
+  <img src="public/logo.png" alt="Pixcode logo" width="96" height="96" />
+  <h1>Pixcode</h1>
+  <p><strong>面向 AI coding agent 的 self-hosted control room。</strong></p>
+  <p>
+    在一个 Web UI 中使用 Claude Code、Cursor CLI、Codex、Gemini CLI、Qwen Code 和 OpenCode，并集成 chat、shell、files、Git、orchestration、API keys、plugins、notifications、Telegram、desktop/server deployment。
+  </p>
+  <p>
+    <a href="https://buymeacoffee.com/alicomert" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/Buy%20me%20a%20coffee-support%20Pixcode-ffdd00?style=for-the-badge&logo=buymeacoffee&logoColor=000000" alt="Buy me a coffee" /></a>
+  </p>
+  <p>
+    <a href="README.md">English</a> ·
+    <a href="README.tr.md">Türkçe</a> ·
+    <a href="README.de.md">Deutsch</a> ·
+    <a href="README.ru.md">Русский</a> ·
+    <a href="README.ja.md">日本語</a> ·
+    <a href="README.ko.md">한국어</a>
+  </p>
+</div>
+
+## Pixcode 是什么？
+
+Pixcode 可以把你的本机、工作站或 Linux 服务器变成浏览器里的 AI development cockpit。你不需要在多个 terminal、CLI logs、file explorer、Git UI、provider settings 之间切换，Pixcode 把 coding-agent workflow 放在一个本地 Web App 里。
+
+常见使用方式：
+
+- **Local workstation**：在自己的电脑上运行 Pixcode，用更好的 UI 操作已有 CLI。
+- **Always-on server**：在 Linux/VDS 上以 daemon 方式运行，从 laptop、tablet、phone 访问。
+- **Desktop app**：使用 GitHub Releases 中的 Windows `.exe`、macOS `.dmg`、Linux build。
+
+Pixcode 不是 hosted cloud IDE。Projects、credentials、CLI sessions、local files、Git state、MCP config 默认都保留在你的机器上。
+
+## Screenshots
+
+| Workspace | Mobile chat |
+| --- | --- |
+| <img src="public/screenshots/desktop-main.png" alt="Pixcode desktop workspace" width="480" /> | <img src="public/screenshots/mobile-chat.png" alt="Pixcode mobile chat" width="260" /> |
+
+| CLI selection | Tools and MCP |
+| --- | --- |
+| <img src="public/screenshots/cli-selection.png" alt="Pixcode CLI selection" width="420" /> | <img src="public/screenshots/tools-modal.png" alt="Pixcode tools modal" width="420" /> |
+
+## 功能亮点
+
+### 多个 CLI，一个界面
+
+- Claude Code、Cursor CLI、Codex、Gemini CLI、Qwen Code、OpenCode。
+- Settings 中管理 provider auth、API key credentials、OAuth paste、install status、model list、CLI version status。
+- Pixcode 不替代 native CLI，而是在其上增加 session management、WebSocket streaming、notifications、file context、project controls。
+- UI 会显示 CLI 是在 thinking、tool execution、approval waiting 还是 output streaming。
+
+### Chat、files、shell、source control
+
+- Project-aware chat sessions 和 history。
+- Prompt composer 固定在 chat/project screen 底部。
+- Shell panel 在 desktop 上可作为 split panel 或 full panel 打开。
+- File browser 支持 edit、upload、rename、delete、detailed view。
+- Source Control 支持 Git status、diff、branch、commit、changed files。
+- Split panels 提供 icon controls、close button、mobile-friendly responsive behavior。
+
+### Changed files Command Center
+
+Pixcode 会跟踪 local working tree 的变化。Quick Settings 中的 Command Center 可以即时显示 changed files，高亮新的改动，并跳转到相关 file/line。这样 AI agent 修改文件时，你可以看到它改了什么，同时保持 chat/orchestration view 不被关闭。
+
+### Multi-agent orchestration
+
+Orchestration 可以让多个 CLI agents 围绕同一个 goal 协作。
+
+- **Agent Team**：按 frontend、backend、review、docs、custom role 拆分任务。
+- **Multi-model Review**：用多个 provider/model 检查同一改动。
+- **Sequential Handoff**：按阶段交接任务。
+- **Decision Debate**：实现前比较不同 approach。
+
+Controls:
+
+- 按 run enable/disable agents，
+- 同一个 provider 可创建多个 worker，
+- agent 级 role、stage、label、instruction，
+- agent 级 model selection，包含 OpenCode model，
+- failed step 的 fallback CLI agent，
+- workflow DAG preview，
+- event streaming 和 cancel，
+- resizable orchestration panes。
+
+### API、Telegram、notifications
+
+Pixcode frontend 本身使用 REST/WebSocket API。External automation 也可以用 Pixcode API key 使用同一个 control plane。新的 API keys 以 `px_` 开头，旧的 `ck_` keys 仍然兼容。
+
+```bash
+curl http://localhost:3001/api/projects \
+  -H "Authorization: Bearer px_your_key_here"
+```
+
+- `POST /api/agent` for one-shot agent runs.
+- `/api/orchestration/workflows/*` for preview, start, stream, cancel.
+- Browser push notifications.
+- Telegram pairing、task notifications、optional prompt bridge。
+
+OpenAPI: [`public/openapi.yaml`](public/openapi.yaml)
+
+### Themes、plugins、MCP
+
+- Dark/light mode。
+- Emerald、VS Code-like accent palettes。
+- Custom light/dark accent colors。
+- Token-based styling for buttons、focus rings、navigation、active states。
+- MCP server management。
+- Plugin system with frontend tabs and optional backend services。
+
+## Installation
+
+需要 Node.js 22+。
+
+```bash
+npx @pixelbyte-software/pixcode
+```
+
+Global install:
+
+```bash
+npm install -g @pixelbyte-software/pixcode
+pixcode
+```
+
+Open:
+
+```text
+http://localhost:3001
+```
+
+Desktop installers are available in GitHub Releases: Windows `.exe`, macOS `.dmg`, Linux AppImage/packages.
+
+## Linux daemon
+
+```bash
+pixcode daemon install --mode auto --port 3001
+pixcode daemon status --mode auto
+pixcode daemon logs --mode auto
+pixcode daemon restart --mode auto
+```
+
+Foreground:
+
+```bash
+pixcode --no-daemon
+```
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm run lint
+npm run build
+```
+
+Notes:
+
+- `npm run dev` uses the daemon manager on Linux.
+- Use `npm run client` only for Vite frontend development.
+- Normal runtime uses port `3001`; `5173` is for separate Vite dev.
+
+## Links
+
+- npm: <https://www.npmjs.com/package/@pixelbyte-software/pixcode>
+- GitHub: <https://github.com/alicomert/pixcode>
+- Releases: <https://github.com/alicomert/pixcode/releases/latest>

package/SECURITY.md

@@ -1,46 +1,46 @@
-# Security Policy
-
-Pixcode is a self-hosted control plane for local projects, provider CLIs, API
-keys, Telegram pairing, shell access, files, Git state, and agent sessions. Treat
-it like sensitive developer infrastructure.
-
-## Supported Versions
-
-Security fixes are targeted at the latest published release and the current
-`main` branch.
-
-| Version | Supported |
-| --- | --- |
-| Latest release | Yes |
-| Older releases | Best effort |
-
-## Reporting a Vulnerability
-
-Please do not open a public issue for private vulnerabilities, leaked tokens, or
-exploit details.
-
-Use GitHub Security Advisories for this repository when available. If advisory
-reporting is not available, contact the repository owner privately through
-GitHub and include:
-
-- affected Pixcode version or commit,
-- operating system and deployment mode,
-- reproduction steps,
-- expected impact,
-- relevant logs with secrets removed.
-
-## Deployment Guidance
-
-- Do not expose Pixcode directly to the public internet without a trusted reverse
-  proxy, VPN, firewall, or equivalent access control.
-- Use strong local account credentials.
-- Rotate `px_` API keys and provider tokens if they are exposed.
-- Do not paste production provider tokens into public issues or screenshots.
-- Keep desktop installers and npm packages updated from official Pixcode
-  releases.
-
-## Scope
-
-Reports are most useful when they involve Pixcode application code, API
-authorization, session isolation, secret handling, desktop packaging, update
-behavior, or unsafe shell/file access.
+# Security Policy
+
+Pixcode is a self-hosted control plane for local projects, provider CLIs, API
+keys, Telegram pairing, shell access, files, Git state, and agent sessions. Treat
+it like sensitive developer infrastructure.
+
+## Supported Versions
+
+Security fixes are targeted at the latest published release and the current
+`main` branch.
+
+| Version | Supported |
+| --- | --- |
+| Latest release | Yes |
+| Older releases | Best effort |
+
+## Reporting a Vulnerability
+
+Please do not open a public issue for private vulnerabilities, leaked tokens, or
+exploit details.
+
+Use GitHub Security Advisories for this repository when available. If advisory
+reporting is not available, contact the repository owner privately through
+GitHub and include:
+
+- affected Pixcode version or commit,
+- operating system and deployment mode,
+- reproduction steps,
+- expected impact,
+- relevant logs with secrets removed.
+
+## Deployment Guidance
+
+- Do not expose Pixcode directly to the public internet without a trusted reverse
+  proxy, VPN, firewall, or equivalent access control.
+- Use strong local account credentials.
+- Rotate `px_` API keys and provider tokens if they are exposed.
+- Do not paste production provider tokens into public issues or screenshots.
+- Keep desktop installers and npm packages updated from official Pixcode
+  releases.
+
+## Scope
+
+Reports are most useful when they involve Pixcode application code, API
+authorization, session isolation, secret handling, desktop packaging, update
+behavior, or unsafe shell/file access.

package/dist/api-automation.html

@@ -1,110 +1,110 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Pixcode API Automation - px_ API Keys, Agent Runs and Workflow Control</title>
-    <meta
-      name="description"
-      content="Use Pixcode API automation with px_ API keys to list projects, run Claude Code, Codex, Cursor CLI, Gemini CLI, Qwen Code, and OpenCode tasks, preview orchestration workflows, start runs, stream events, cancel runs, and integrate Telegram or external tools."
-    />
-    <meta
-      name="keywords"
-      content="Pixcode API, px API key, AI coding agent API, Codex API automation, Claude Code automation, OpenCode automation, orchestration REST API, self-hosted developer automation, coding agent webhook"
-    />
-    <meta name="robots" content="index,follow,max-image-preview:large,max-snippet:-1" />
-    <link rel="canonical" href="https://alicomert.github.io/pixcode/api-automation.html" />
-    <link rel="icon" href="favicon.png" />
-    <link rel="stylesheet" href="site.css" />
-  </head>
-  <body>
-    <nav class="site-nav" aria-label="Main navigation">
-      <a class="brand" href="landing.html">
-        <img src="logo.png" alt="" />
-        <span>Pixcode</span>
-      </a>
-      <div class="nav-links">
-        <a href="docs.html">Documentation</a>
-        <a href="features.html">Features</a>
-        <a href="orchestration.html">Orchestration</a>
-        <a href="api-automation.html">API</a>
-        <a href="https://github.com/alicomert/pixcode">GitHub</a>
-      </div>
-    </nav>
-
-    <header class="hero docs-hero">
-      <div>
-        <div class="eyebrow">API automation</div>
-        <h1>Control Pixcode from scripts, dashboards, CI, and remote tools.</h1>
-        <p class="lead">
-          Pixcode exposes REST and WebSocket-powered workflows. Generate a `px_` API key, then trigger provider tasks, inspect projects, preview orchestration, start workflow runs, stream output, and cancel work from external clients.
-        </p>
-      </div>
-      <div class="image-slot">
-        <span><strong>API dashboard slot</strong>Recommended: 1400 x 1000. Show API keys, OpenAPI docs, and an automation request/result.</span>
-      </div>
-    </header>
-
-    <main>
-      <section class="section">
-        <h2>Authentication</h2>
-        <p class="sublead">
-          New Pixcode API keys start with `px_`. Older `ck_` keys remain accepted for compatibility, but new documentation and examples should use `px_`.
-        </p>
-        <div class="grid two">
-          <div class="code-panel"><pre><code>curl http://localhost:3001/api/projects \
-  -H "Authorization: Bearer px_your_key_here"</code></pre></div>
-          <div class="code-panel"><pre><code>curl http://localhost:3001/api/projects \
-  -H "X-API-Key: px_your_key_here"</code></pre></div>
-        </div>
-      </section>
-
-      <section class="section alt">
-        <h2>Run a one-shot agent task</h2>
-        <p class="sublead">
-          `POST /api/agent` is the external REST entry point for non-interactive automation. It can run a provider against a project path, optionally stream events, and optionally return buffered JSON with `stream: false`.
-        </p>
-        <div class="code-panel"><pre><code>curl http://localhost:3001/api/agent \
-  -H "Authorization: Bearer px_your_key_here" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "provider": "codex",
-    "projectPath": "/home/me/project",
-    "message": "Review the current diff and list release risks.",
-    "stream": false
-  }'</code></pre></div>
-      </section>
-
-      <section class="section warm">
-        <h2>Workflow automation</h2>
-        <p class="sublead">
-          Orchestration endpoints can list workflow modes, preview expanded DAGs, start runs, read run state, stream events, and cancel active work.
-        </p>
-        <div class="grid two">
-          <div class="card"><strong>Preview</strong><p>Validate agent metadata and inspect the node graph before running child agents.</p></div>
-          <div class="card"><strong>Run</strong><p>Start the workflow and track node runs, Hermes task IDs, status, events, and output.</p></div>
-          <div class="card"><strong>Stream</strong><p>Use run event endpoints to follow progress in dashboards or CLI scripts.</p></div>
-          <div class="card"><strong>Cancel</strong><p>Stop active orchestration runs when the user changes direction or detects bad output.</p></div>
-        </div>
-      </section>
-
-      <section class="section">
-        <h2>Common integration ideas</h2>
-        <ul class="feature-list">
-          <li>Ask Codex or Claude Code to review a Git diff from a CI job before release.</li>
-          <li>Trigger OpenCode or Gemini CLI from a custom internal dashboard.</li>
-          <li>Build a Telegram command that starts a Pixcode agent run on an always-on server.</li>
-          <li>Run multi-agent review on a branch before creating a tag or npm publish.</li>
-          <li>Expose a safe internal tool that lists projects and starts approved workflows.</li>
-        </ul>
-        <p>
-          Full OpenAPI reference: <a href="openapi.yaml">openapi.yaml</a>.
-        </p>
-      </section>
-    </main>
-
-    <footer class="footer">
-      <strong>Pixcode API automation</strong> · <a href="docs.html">Documentation</a> · <a href="openapi.yaml">OpenAPI</a> · <a href="llms.txt">llms.txt</a>
-    </footer>
-  </body>
-</html>
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Pixcode API Automation - px_ API Keys, Agent Runs and Workflow Control</title>
+    <meta
+      name="description"
+      content="Use Pixcode API automation with px_ API keys to list projects, run Claude Code, Codex, Cursor CLI, Gemini CLI, Qwen Code, and OpenCode tasks, preview orchestration workflows, start runs, stream events, cancel runs, and integrate Telegram or external tools."
+    />
+    <meta
+      name="keywords"
+      content="Pixcode API, px API key, AI coding agent API, Codex API automation, Claude Code automation, OpenCode automation, orchestration REST API, self-hosted developer automation, coding agent webhook"
+    />
+    <meta name="robots" content="index,follow,max-image-preview:large,max-snippet:-1" />
+    <link rel="canonical" href="https://alicomert.github.io/pixcode/api-automation.html" />
+    <link rel="icon" href="favicon.png" />
+    <link rel="stylesheet" href="site.css" />
+  </head>
+  <body>
+    <nav class="site-nav" aria-label="Main navigation">
+      <a class="brand" href="landing.html">
+        <img src="logo.png" alt="" />
+        <span>Pixcode</span>
+      </a>
+      <div class="nav-links">
+        <a href="docs.html">Documentation</a>
+        <a href="features.html">Features</a>
+        <a href="orchestration.html">Orchestration</a>
+        <a href="api-automation.html">API</a>
+        <a href="https://github.com/alicomert/pixcode">GitHub</a>
+      </div>
+    </nav>
+
+    <header class="hero docs-hero">
+      <div>
+        <div class="eyebrow">API automation</div>
+        <h1>Control Pixcode from scripts, dashboards, CI, and remote tools.</h1>
+        <p class="lead">
+          Pixcode exposes REST and WebSocket-powered workflows. Generate a `px_` API key, then trigger provider tasks, inspect projects, preview orchestration, start workflow runs, stream output, and cancel work from external clients.
+        </p>
+      </div>
+      <div class="image-slot">
+        <span><strong>API dashboard slot</strong>Recommended: 1400 x 1000. Show API keys, OpenAPI docs, and an automation request/result.</span>
+      </div>
+    </header>
+
+    <main>
+      <section class="section">
+        <h2>Authentication</h2>
+        <p class="sublead">
+          New Pixcode API keys start with `px_`. Older `ck_` keys remain accepted for compatibility, but new documentation and examples should use `px_`.
+        </p>
+        <div class="grid two">
+          <div class="code-panel"><pre><code>curl http://localhost:3001/api/projects \
+  -H "Authorization: Bearer px_your_key_here"</code></pre></div>
+          <div class="code-panel"><pre><code>curl http://localhost:3001/api/projects \
+  -H "X-API-Key: px_your_key_here"</code></pre></div>
+        </div>
+      </section>
+
+      <section class="section alt">
+        <h2>Run a one-shot agent task</h2>
+        <p class="sublead">
+          `POST /api/agent` is the external REST entry point for non-interactive automation. It can run a provider against a project path, optionally stream events, and optionally return buffered JSON with `stream: false`.
+        </p>
+        <div class="code-panel"><pre><code>curl http://localhost:3001/api/agent \
+  -H "Authorization: Bearer px_your_key_here" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "provider": "codex",
+    "projectPath": "/home/me/project",
+    "message": "Review the current diff and list release risks.",
+    "stream": false
+  }'</code></pre></div>
+      </section>
+
+      <section class="section warm">
+        <h2>Workflow automation</h2>
+        <p class="sublead">
+          Orchestration endpoints can list workflow modes, preview expanded DAGs, start runs, read run state, stream events, and cancel active work.
+        </p>
+        <div class="grid two">
+          <div class="card"><strong>Preview</strong><p>Validate agent metadata and inspect the node graph before running child agents.</p></div>
+          <div class="card"><strong>Run</strong><p>Start the workflow and track node runs, Hermes task IDs, status, events, and output.</p></div>
+          <div class="card"><strong>Stream</strong><p>Use run event endpoints to follow progress in dashboards or CLI scripts.</p></div>
+          <div class="card"><strong>Cancel</strong><p>Stop active orchestration runs when the user changes direction or detects bad output.</p></div>
+        </div>
+      </section>
+
+      <section class="section">
+        <h2>Common integration ideas</h2>
+        <ul class="feature-list">
+          <li>Ask Codex or Claude Code to review a Git diff from a CI job before release.</li>
+          <li>Trigger OpenCode or Gemini CLI from a custom internal dashboard.</li>
+          <li>Build a Telegram command that starts a Pixcode agent run on an always-on server.</li>
+          <li>Run multi-agent review on a branch before creating a tag or npm publish.</li>
+          <li>Expose a safe internal tool that lists projects and starts approved workflows.</li>
+        </ul>
+        <p>
+          Full OpenAPI reference: <a href="openapi.yaml">openapi.yaml</a>.
+        </p>
+      </section>
+    </main>
+
+    <footer class="footer">
+      <strong>Pixcode API automation</strong> · <a href="docs.html">Documentation</a> · <a href="openapi.yaml">OpenAPI</a> · <a href="llms.txt">llms.txt</a>
+    </footer>
+  </body>
+</html>