Docs: add runtime/TUI milestone and provider onboarding ADR

README.md

@@ -15,6 +15,7 @@ agent007 runs as an MCP server that gives your AI editor a broad orchestration t
 - **Learning** — passive feedback recording → future PromptOptimizer
 - **Git agent** — AI-powered branch, commit, PR, and impact analysis
 - **Web dashboard** — live run/task/memory inspector at `http://localhost:8007`, with standalone task execution when a local provider such as Ollama is configured
+- **Dashboard-first provider UX (planned)** — provider health, setup validation, and onboarding will be centered in the web dashboard while preserving config/env-based setup for headless use
 - **LSP context controls** — configure LSP servers + category injection from config and dashboard (`/api/lsp/config`)
 - **ETR built-ins** — low-latency deterministic extraction/query/metrics tools to reduce shell+parsing overhead
 

docs/adr/008-dashboard-first-provider-onboarding.md

@@ -0,0 +1,90 @@
+# ADR-008: Dashboard-First Provider Onboarding
+
+**Date:** 2026-05-16  
+**Status:** Accepted  
+**Deciders:** agent007 core team
+
+## Context
+
+agent007 currently supports standalone model execution through:
+
+1. `ANTHROPIC_API_KEY`
+2. `OPENAI_API_KEY`
+3. `[models.ollama]` in `~/.agent007/config.toml`
+
+If none of those are configured, agent007 runs in **hosted-MCP** mode and depends on the host editor/LLM session.
+
+This works, but the current setup model is still operator-heavy:
+
+- users must understand environment variables and config layout
+- provider health is not surfaced clearly enough
+- local/self-hosted endpoint setup is not guided
+- there is no unified place to understand why standalone mode is unavailable
+
+At the same time, agent007 already has a web dashboard and runtime status surface. That dashboard is the natural place to make provider setup more discoverable.
+
+## Decision
+
+Provider onboarding in agent007 will be **dashboard-first**, while preserving file/env compatibility.
+
+This means:
+
+1. The primary user-facing setup flow will live in the web dashboard.
+2. Dashboard actions will write or validate the same underlying configuration model (`config.toml`, env-backed provider detection) rather than creating a separate secrets/config system.
+3. Manual configuration remains supported and documented for headless, scripted, and advanced setups.
+4. OAuth/account-backed login flows are **not** the first slice. The first slice focuses on:
+   - status/health visibility
+   - guided setup for current providers
+   - OpenAI-compatible/local endpoint configuration
+   - better error reporting and validation
+
+## Rationale
+
+- **Matches current product shape**: agent007 already has a dashboard; users should not need a separate auth-only CLI surface for the first usability improvement.
+- **Reduces duplicate configuration paths**: the dashboard should not invent a second provider model. It should manage the same provider configuration the runtime already reads.
+- **Keeps automation intact**: CI, remote boxes, and power users still need env/config-based setup.
+- **Safer first implementation**: health checks, config writing, and explicit validation are much smaller and lower-risk than implementing many provider-specific OAuth/device flows.
+- **Supports future expansion**: if selected OAuth providers are later added, the dashboard can host them cleanly without invalidating config-based setups.
+
+## Consequences
+
+### Positive
+
+- Users get a visible provider status surface tied to runtime mode.
+- Local/self-hosted endpoint setup becomes easier to validate.
+- Hosted-MCP vs standalone mode becomes easier to understand.
+- The same configuration remains usable from CLI, files, and dashboard.
+
+### Negative / Trade-offs
+
+- agent007 will still lag tools like jcode on multi-provider OAuth breadth in the short term.
+- Dashboard-first onboarding increases dependence on the web surface for the best UX.
+- Provider-specific OAuth support, if added later, will still require careful credential storage and revocation design.
+
+## First Slice
+
+1. Provider status panel in dashboard
+2. Guided validation/setup for:
+   - Claude env/API-key path
+   - OpenAI/Codex env/API-key path
+   - Ollama local endpoint
+   - OpenAI-compatible endpoint
+3. Health and failure explanations
+4. Documentation updates that clearly state:
+   - dashboard-first onboarding
+   - config/env compatibility remains
+   - hosted-MCP remains a first-class mode
+
+## Alternatives Considered
+
+| Alternative | Reason Not Chosen |
+|-------------|------------------|
+| **CLI-first provider login (`agent007 login --provider ...`)** | Adds a second setup UX before the dashboard/provider-state UX is mature; less aligned with agent007’s existing operator surface |
+| **OAuth-first implementation** | Higher complexity, provider-specific maintenance, and secret/session handling burden before basic setup visibility is solved |
+| **Keep config/env only** | Lowest implementation cost, but continues the current usability gap and hides runtime/provider problems from normal users |
+
+## Related ADRs
+
+- ADR-002 — MCP stdio transport
+- ADR-004 — Hosted-MCP workflow execution mode
+- ADR-005 — Skills as Markdown with frontmatter

docs/configuration.md

@@ -4,6 +4,12 @@
 
 Main config at `~/.agent007/config.toml`. Created by `agent007 init`.
 
+Provider onboarding direction:
+
+- **Current:** direct config/env setup is supported and remains valid
+- **Planned:** dashboard-first provider onboarding/validation will manage the same runtime configuration model instead of replacing it
+- **Always supported:** headless/manual setups via `config.toml` and environment variables
+
 ```toml
 [core]
 max_agents = 8              # Maximum concurrent agents
@@ -33,6 +39,22 @@ default         = "claude"     # Fallback
 
 All fields are optional — agent007 uses sensible defaults if omitted.
 
+## Provider setup modes
+
+Today, real provider-backed standalone runtime availability is determined from:
+
+1. `ANTHROPIC_API_KEY`
+2. `OPENAI_API_KEY`
+3. reachable `[models.ollama]` config
+
+If none are available, agent007 remains usable in **hosted-MCP** mode, where the connected host/editor LLM executes reasoning and tool orchestration through MCP. For tests and demos, `AGENT007_DRY_RUN=1` can also enable standalone execution with the mock provider; it is not a real model provider setup.
+
+Planned UX direction:
+
+- the **web dashboard** becomes the primary setup and validation surface for providers
+- manual config/env setup remains compatible
+- future OpenAI-compatible endpoint setup should also be manageable from dashboard
+
 ---
 
 ## hooks.toml

docs/milestones.md

@@ -4,13 +4,15 @@
 1. M1 Core Runtime Reliability
 2. M2 Visibility and Productization
 3. M3 Controlled Rollout and Quality Gate
+4. M4 Runtime Sessions, Agent Collaboration, and TUI Usability
 
 ## Milestone Table
 | Milestone | Status | Goal | Key Features | Dependencies | Exit Criteria |
 |---|---|---|---|---|---|
 | M1 | ✅ Complete | Consistent retrieval + execution behavior | Warmup indexing bounds, shared skill executor path, telemetry artifact generation, persona policy enforcement | none | core paths green + artifacts persisted |
 | M2 | ✅ Complete | User-facing observability | run-detail API extension, dashboard telemetry/policy/token cards, docs updates | M1 | artifacts visible in UI and validated |
 | M3 | 📋 Planned | Safe rollout | strict-mode rollout matrix, KPI baseline tracking, rollback playbook | M2 | measured rollout decision gates |
+| M4 | 📋 Planned | Stronger long-lived runtime and operator UX | session lifecycle model, compact runtime status, usable TUI, mock/diagram viewer, agent messaging, provider/browser health UX, memory lifecycle improvements | M2 | sessions resumable, runtime visible in dashboard/TUI, first operator-grade terminal flow usable, visual artifacts reviewable in dashboard |
 
 ## Parallel Workstreams
 1. Backend: retriever/executor/policy and artifact persistence.