Feature: UI Overhaul, Help Documentation, and PyPI Publishing

.github/workflows/release.yml

@@ -34,6 +34,8 @@ jobs:
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
 
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2

PYPI_README.md

@@ -0,0 +1,86 @@
+# AutoWeave: Multi-Agent Orchestration Library
+
+**AutoWeave** is the robust execution engine for multi-agent software engineering teams. It orchestrates specialized AI agents as a coherent team, managing workflow compilation, task graphs, queue-backed durable execution, and human-in-the-loop approvals.
+
+## Core Features
+
+- **Workflow Orchestration**: Define, compile, and execute Directed Acyclic Graphs (DAGs) of agentic tasks.
+- **Durable State**: Resume paused runs, track individual attempts, and safely persist context to PostgreSQL.
+- **Human-in-the-Loop**: Built-in primitives to pause execution and request approvals or clarifications from a human.
+- **Queue Dispatch**: Offload long-running autonomous tasks to Celery workers backed by Redis.
+- **Local Monitoring**: Inspect active and historic runs via a beautiful, lightweight local developer dashboard.
+
+## Installation
+
+Install AutoWeave directly from PyPI using pip or uv:
+
+```bash
+pip install autoweave
+```
+
+## Quick Start (CLI)
+
+AutoWeave provides a comprehensive CLI for local orchestration.
+
+1. **Initialize a new project** in a fresh directory:
+```bash
+autoweave new-project
+```
+
+2. **Bootstrap the local environment** and configuration files:
+```bash
+autoweave bootstrap
+```
+
+3. **Start the control plane UI** and background Celery worker:
+```bash
+autoweave start
+```
+
+4. **Execute a workflow** from the terminal:
+```bash
+autoweave run-workflow --root . --request "Create a Python script that calculates Fibonacci numbers"
+```
+
+## Programmatic Usage
+
+AutoWeave exposes a clean Python API for integrating orchestration into your own applications.
+
+### 1. Launching a Workflow
+```python
+from autoweave.orchestration.runtime import build_local_runtime
+
+# Initialize the runtime for your project directory
+runtime = build_local_runtime(root_path="./my-weave-project")
+
+# Dispatch a new workflow to the agents
+workflow_run = runtime.launch_workflow(
+    request="Review the backend contract and propose next steps"
+)
+print(f"Successfully started workflow run: {workflow_run.id}")
+```
+
+### 2. Inspecting the State
+```python
+from autoweave.monitoring.service import MonitoringService
+
+service = MonitoringService(db_path="./my-weave-project/autoweave.db")
+
+# Fetch a snapshot of all active runs
+state_snapshot = service.snapshot(limit=5)
+print(state_snapshot)
+```
+
+## Dashboard & Monitoring
+
+AutoWeave includes a built-in monitoring dashboard to trace agent executions, view generated artifacts, and resolve human-in-the-loop approvals.
+
+To start it independently:
+```bash
+autoweave ui --root ./my-weave-project
+```
+Then navigate to `http://localhost:8766` in your browser.
+
+## Support & Architecture
+
+For comprehensive architecture specs, deployment instructions, and advanced configuration options, visit our [GitHub Repository Documentation](https://github.com/hypnoastic/Autoweave-Library).

README.md

@@ -33,13 +33,13 @@ AutoWeave is the **execution engine** for multi-agent software engineering teams
 
 ### Key Features
 
-- 🔀 **Workflow Orchestration** — Define, compile, and execute DAGs of agentic tasks with dependency-aware dynamic scheduling
-- 💾 **Durable State** — Resume paused runs, track attempts, persist context safely across PostgreSQL
-- 🤝 **Human-in-the-Loop** — Native primitives for pausing execution to request approvals or clarifications
-- 📋 **Queue Dispatch** — Offload long-running tasks to Celery workers backed by Redis
-- 🔍 **Local Monitoring** — Inspect runs via a lightweight local dashboard and playground
-- 🧠 **Context Layered Resolution** — Workspace → Postgres → pgvector → Artifact Store → Neo4j → Redis → typed miss escalation
-- 📊 **Observability** — OpenTelemetry-compatible spans, metrics, and domain events
+- **Workflow Orchestration** — Define, compile, and execute DAGs of agentic tasks with dependency-aware dynamic scheduling
+- **Durable State** — Resume paused runs, track attempts, persist context safely across PostgreSQL
+- **Human-in-the-Loop** — Native primitives for pausing execution to request approvals or clarifications
+- **Queue Dispatch** — Offload long-running tasks to Celery workers backed by Redis
+- **Local Monitoring** — Inspect runs via a lightweight local dashboard and playground
+- **Context Layered Resolution** — Workspace → Postgres → pgvector → Artifact Store → Neo4j → Redis → typed miss escalation
+- **Observability** — OpenTelemetry-compatible spans, metrics, and domain events
 
 ---
 
@@ -69,7 +69,7 @@ flowchart TD
 4. **Human intervention is first-class** — Clarifications, approvals, and overrides are formal workflow objects
 5. **One sandbox per task attempt** — Isolated worktree per execution
 
-> 📖 See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the complete architecture specification.
+> See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the complete architecture specification.
 
 ---
 
@@ -207,7 +207,7 @@ See [`.env.example`](.env.example) for all configuration options. Key variables:
 | `NEO4J_URL` | Neo4j connection URL | — |
 | `OPENHANDS_AGENT_SERVER_BASE_URL` | OpenHands server URL | `http://127.0.0.1:8000` |
 
-> 📖 See [DEVELOPMENT.md](DEVELOPMENT.md) for the complete development guide.
+> See [DEVELOPMENT.md](DEVELOPMENT.md) for the complete development guide.
 
 ---
 
@@ -241,7 +241,7 @@ make test:integration
 make test:ui
 ```
 
-> 📖 See [TESTING.md](TESTING.md) for the full testing philosophy and guidelines.
+> See [TESTING.md](TESTING.md) for the full testing philosophy and guidelines.
 
 ---
 

autoweave/monitoring/dashboard_page.py

@@ -878,12 +878,16 @@ def render_dashboard_page() -> str:
                 <div class="docs-sidebar">
                     <div style="font-weight: 600; font-size: 14px; margin-bottom: 8px;">Documentation</div>
                     <input type="text" id="docs-search" placeholder="Search docs..." />
-                    <div class="nav-group" style="padding-top: 8px;" id="docs-nav-group">
+                                        <div class="nav-group" style="padding-top: 8px;" id="docs-nav-group">
                         <a class="nav-item active" data-doc="ARCHITECTURE">Architecture</a>
                         <a class="nav-item" data-doc="DEPLOYMENT">Deployment</a>
                         <a class="nav-item" data-doc="autoweave_diagrams_source">Diagrams Source</a>
                         <a class="nav-item" data-doc="autoweave_high_level_architecture">High Level Architecture</a>
                         <a class="nav-item" data-doc="autoweave_implementation_spec">Implementation Spec</a>
+                        <div style="font-weight: 600; font-size: 14px; margin: 16px 0 8px 0; color: var(--text-secondary);">Help & Guides</div>
+                        <a class="nav-item" data-doc="help_cli_reference">Cli Reference</a>
+                        <a class="nav-item" data-doc="help_quick_start">Quick Start</a>
+                        <a class="nav-item" data-doc="help_troubleshooting">Troubleshooting</a>
                     </div>
                 </div>
                 <div class="docs-content">
@@ -1054,8 +1058,7 @@ def render_dashboard_page() -> str:
 
         /* --- Content Store --- */
         const docs = {
-            'ARCHITECTURE': `
-# AutoWeave High-Level Architecture
+            'ARCHITECTURE': `# AutoWeave High-Level Architecture
 
 Version: 2.0  
 Status: frozen architecture baseline  
@@ -1183,10 +1186,8 @@ def render_dashboard_page() -> str:
     G -->|miss| R[Redis]
     R -->|miss| M[Typed miss / escalate]
 \`\`\`
-
-            `,
-            'DEPLOYMENT': `
-# Deployment Guide
+`,
+            'DEPLOYMENT': `# Deployment Guide
 
 AutoWeave Library is designed to be embedded into applications, but it requires several backing services to operate reliably in a production or local development environment.
 
@@ -1236,10 +1237,8 @@ def render_dashboard_page() -> str:
 ### 5. Secrets Management
 - Do not hardcode credentials in \`.env\` files for production.
 - Inject \`VERTEXAI_SERVICE_ACCOUNT_FILE\`, \`POSTGRES_URL\`, and other secrets via a secrets manager (e.g., HashiCorp Vault, AWS Secrets Manager, Kubernetes Secrets).
-
-            `,
-            'autoweave_diagrams_source': `
-# AutoWeave Diagrams Source
+`,
+            'autoweave_diagrams_source': `# AutoWeave Diagrams Source
 
 Version: 2.0
 Purpose: text-first diagrams for coding agents and PDF generation.
@@ -1486,10 +1485,8 @@ class StorageUnitOfWork
     O->>DB: finalize attempt state
     O->>RD: release lease
 \`\`\`
-
-            `,
-            'autoweave_high_level_architecture': `
-# AutoWeave High-Level Architecture
+`,
+            'autoweave_high_level_architecture': `# AutoWeave High-Level Architecture
 
 Version: 2.0  
 Status: frozen architecture baseline  
@@ -2177,10 +2174,8 @@ class StorageUnitOfWork
 ## 17. Final architecture conclusion
 
 AutoWeave should be implemented as a **Vertex-AI-backed multi-agent control plane** on top of **OpenHands remote workers**, with **Postgres as truth**, **Redis/Celery as coordination**, **Neo4j as graph retrieval/projection**, **isolated worktrees per attempt**, **dynamic DAG scheduling**, and **normalized observability export** for the main product.
-
-            `,
-            'autoweave_implementation_spec': `
-# AutoWeave Implementation Specification
+`,
+            'autoweave_implementation_spec': `# AutoWeave Implementation Specification
 
 Version: 2.0  
 Status: implementation baseline  
@@ -3329,8 +3324,94 @@ class StorageUnitOfWork
 ## 20. Final implementation conclusion
 
 Build AutoWeave as a **Vertex-AI-backed, OpenHands-powered multi-agent orchestration library** with **canonical Postgres truth**, **Redis coordination**, **Neo4j graph projection/retrieval**, **worker-isolated worktrees**, **typed context and artifact services**, and **library-owned observability export**.
+`,
+            'help_cli_reference': `# CLI Reference
+
+The AutoWeave CLI is the primary way to interact with the orchestration engine locally. You can access it by running \`autoweave\` or \`uv run autoweave\`.
+
+## Commands
+
+- \`autoweave status\`: Show a minimal repository status summary.
+- \`autoweave validate\`: Validate docs, configs, and sample agent fixtures.
+- \`autoweave bootstrap\`: Create missing sample agents and config fixtures.
+- \`autoweave migrate-project\`: Refresh packaged AutoWeave project-managed files to the latest library templates.
+- \`autoweave create-agent\`: Create a new agent bundle with soul, playbook, config, and skills.
+- \`autoweave doctor\`: Inspect local env, configs, and the OpenHands bootstrap path.
+- \`autoweave run-example\`: Run the notifications example against the composed local runtime.
+- \`autoweave run-workflow\`: Run the current workflow from a user request instead of the fixed sample brief.
+- \`autoweave worker\`: Run a real Celery worker for queued AutoWeave workflow execution.
+- \`autoweave ui\`: Launch the lightweight local monitoring UI.
+- \`autoweave start\`: Start the entire local execution environment: UI and Celery worker.
+- \`autoweave cleanup-local-state\`: Purge stale canonical runs and local generated runtime residue.
+- \`autoweave new-project\`: Initialize a new AutoWeave project.
+`,
+            'help_quick_start': `# Quick Start
+
+Welcome to AutoWeave! This guide will help you get your first agent workflow running locally.
+
+## 1. Initialization
+First, initialize a new AutoWeave project in a fresh directory:
+\`\`\`bash
+autoweave new-project
+\`\`\`
+
+## 2. Bootstrapping
+Create the required agent configurations and bootstrap the local environment:
+\`\`\`bash
+autoweave bootstrap
+\`\`\`
+
+## 3. Starting the Control Plane
+Start the AutoWeave UI and Celery worker using the \`start\` command. This will spin up the local dashboard on \`http://127.0.0.1:8766\`:
+\`\`\`bash
+autoweave start
+\`\`\`
+
+## 4. Running a Workflow (CLI)
+To execute a workflow, you can either trigger a pre-configured example or run a custom workflow:
+\`\`\`bash
+autoweave run-workflow --root . --request "Create a React component for a login page"
+\`\`\`
+
+## 5. Running a Workflow (Python)
+You can also trigger runs natively from your own Python code:
+
+\`\`\`python
+from autoweave.orchestration.runtime import build_local_runtime
+
+runtime = build_local_runtime(root_path=".")
+
+workflow_run = runtime.launch_workflow(
+    request="Review the backend contract and propose next steps"
+)
+print(f"Successfully started workflow run: {workflow_run.id}")
+\`\`\`
+`,
+            'help_troubleshooting': `# Troubleshooting
+
+Common issues and their resolutions when operating AutoWeave.
 
-            `
+## Database Locks (SQLite)
+If you see "database is locked" errors, it usually means the Celery worker and the UI server are competing for database writes. 
+**Solution:** Stop both processes and restart them cleanly using \`autoweave start\`.
+
+## Missing OpenHands Runtime
+If \`autoweave doctor\` reports a missing OpenHands bootstrap path, ensure you have correctly installed the required Docker dependencies or pulled the latest OpenHands image.
+
+## Stale Runs Showing in Dashboard
+If the UI dashboard is showing stale runs or incomplete executions that are no longer active in the Celery queue:
+**Solution:** Run the cleanup command to purge stale state:
+\`\`\`bash
+autoweave cleanup-local-state
+\`\`\`
+
+## UI Fails to Bind Port
+If starting the UI throws an "Address already in use" error for port 8766:
+**Solution:** Kill any existing processes bound to that port:
+\`\`\`bash
+kill -9 \$(lsof -t -i :8766)
+\`\`\`
+`,
         };
 
         /* --- SPA State & Logic --- */
@@ -3397,7 +3478,7 @@ class StorageUnitOfWork
 
             // Docs routing handles sub-routes implicitly
             let mainRoute = route;
-            if (["ARCHITECTURE", "DEPLOYMENT", "autoweave_diagrams_source", "autoweave_high_level_architecture", "autoweave_implementation_spec"].includes(route)) {
+            if (["ARCHITECTURE", "DEPLOYMENT", "autoweave_diagrams_source", "autoweave_high_level_architecture", "autoweave_implementation_spec", "help_cli_reference", "help_quick_start", "help_troubleshooting"].includes(route)) {
                 mainRoute = 'docs';
             }
 

docs/help/cli_reference.md

@@ -0,0 +1,19 @@
+# CLI Reference
+
+The AutoWeave CLI is the primary way to interact with the orchestration engine locally. You can access it by running `autoweave` or `uv run autoweave`.
+
+## Commands
+
+- `autoweave status`: Show a minimal repository status summary.
+- `autoweave validate`: Validate docs, configs, and sample agent fixtures.
+- `autoweave bootstrap`: Create missing sample agents and config fixtures.
+- `autoweave migrate-project`: Refresh packaged AutoWeave project-managed files to the latest library templates.
+- `autoweave create-agent`: Create a new agent bundle with soul, playbook, config, and skills.
+- `autoweave doctor`: Inspect local env, configs, and the OpenHands bootstrap path.
+- `autoweave run-example`: Run the notifications example against the composed local runtime.
+- `autoweave run-workflow`: Run the current workflow from a user request instead of the fixed sample brief.
+- `autoweave worker`: Run a real Celery worker for queued AutoWeave workflow execution.
+- `autoweave ui`: Launch the lightweight local monitoring UI.
+- `autoweave start`: Start the entire local execution environment: UI and Celery worker.
+- `autoweave cleanup-local-state`: Purge stale canonical runs and local generated runtime residue.
+- `autoweave new-project`: Initialize a new AutoWeave project.

docs/help/quick_start.md

@@ -0,0 +1,41 @@
+# Quick Start
+
+Welcome to AutoWeave! This guide will help you get your first agent workflow running locally.
+
+## 1. Initialization
+First, initialize a new AutoWeave project in a fresh directory:
+```bash
+autoweave new-project
+```
+
+## 2. Bootstrapping
+Create the required agent configurations and bootstrap the local environment:
+```bash
+autoweave bootstrap
+```
+
+## 3. Starting the Control Plane
+Start the AutoWeave UI and Celery worker using the `start` command. This will spin up the local dashboard on `http://127.0.0.1:8766`:
+```bash
+autoweave start
+```
+
+## 4. Running a Workflow (CLI)
+To execute a workflow, you can either trigger a pre-configured example or run a custom workflow:
+```bash
+autoweave run-workflow --root . --request "Create a React component for a login page"
+```
+
+## 5. Running a Workflow (Python)
+You can also trigger runs natively from your own Python code:
+
+```python
+from autoweave.orchestration.runtime import build_local_runtime
+
+runtime = build_local_runtime(root_path=".")
+
+workflow_run = runtime.launch_workflow(
+    request="Review the backend contract and propose next steps"
+)
+print(f"Successfully started workflow run: {workflow_run.id}")
+```