docs: refresh to current state (9 tools, 35 MCP/33 enabled, 45 skills, v1.1.2, VDD, registry)

AGENTS.md

@@ -13,8 +13,9 @@ offloaded to a compute box (`cs run "pnpm test"`) or CI — do not run them loca
 ## Repo structure
 
 - `mcp-server/` — the `opencode-workbench` MCP server + connector (TypeScript).
-  Tools: `inspect_target`, `plan_clone`, `apply_clone`, `verify_clone`,
-  `install_component`, `bootstrap_host`, `workbench_info`. Local + SSH transports.
+  Tools: `workbench_info`, `inspect_target`, `plan_clone`, `apply_clone`,
+  `verify_clone`, `install_component`, `list_required_credentials`,
+  `run_auth_flow`, `bootstrap_host`. Local + SSH transports.
   See `mcp-server/README.md` and `docs/architecture/clone-mcp.md`.
 - `connector.json` — connector manifest / registration snippet.
 - `plugins/` — the `memory.ts` + `doc-tools.ts` OpenCode plugins (portable,
@@ -58,7 +59,7 @@ bash scripts/recovery/validate-recovery.sh        # verify workstation is in goo
 |---|---|
 | `DATABASE_URL` | `postgres://opencode:opencode@localhost:5432/memory` |
 | `BROWSERLESS_HOST/PORT/PROTOCOL` | `localhost:3000/http` |
-| `DB_PATH` | `/workspaces/workbench/.saga/.tracker.db` |
+| `DB_PATH` | `/workspaces/opencode-workbench/.saga/.tracker.db` |
 | `DEEPSEEK_API_KEY` | primary model: `deepseek/deepseek-v4-pro` |
 | `OPENCODE_API_KEY` | OpenCode Zen + Console Go providers |
 | `SIMONPLMAK_CLOUD_PAT` | GitHub MCP (binary) + shadcn MCP + `gh` auth |
@@ -90,7 +91,7 @@ bash .devcontainer/start-browserless.sh
   `~/.local/bin/browserless-mcp/dist/index.js` (on the build box: `/home/node/.local/bin/`).
 - Model `deepseek/deepseek-v4-pro` (small: `deepseek/deepseek-v4-flash`);
   `default_agent` is `vdd` (the only subagent defined in `opencode.json`).
-- 28 repo skills in `.opencode/skills/`; global skills live under
+- 45 repo skills in `.opencode/skills/`; global skills live under
   `~/.config/opencode/skills/` (not this repo).
 - Plugins: `./plugins/memory.ts` + `./plugins/doc-tools.ts` (plus npm
   `opencode-env-protect`, `opencode-sentry-monitor`).

README.md

@@ -107,7 +107,7 @@ opencode-workbench/
 
 | Category | Details |
 |----------|---------|
-| **OpenCode** | CLI v1.18.5, DeepSeek V4 Pro model, LSP enabled |
+| **OpenCode** | Latest stable CLI, DeepSeek V4 Pro model, LSP enabled |
 | **MCP Servers** | 35 configured (33 enabled, 2 disabled), 9 remote + 26 local |
 | **Agent Skills** | 45 reusable skills in `.opencode/skills/` |
 | **Infrastructure** | PostgreSQL 16 (Docker), Browserless Chromium (Docker) |
@@ -150,9 +150,9 @@ gh SWAS create --repo simonmak-ascent/opencode-workbench --machine basicLinux32g
 
 # 2. Wait for automation (3-5 min)
 
-# 3. Two manual steps:
-npx playwright install chrome
-opencode mcp auth vercel     # only if Vercel MCP needed
+# 3. If needed (usually done by setup.sh):
+npx playwright install chromium
+# Vercel MCP uses VERCEL_ACCESS_TOKEN (token auth — no OAuth step)
 
 # 4. Validate recovery
 bash scripts/recovery/validate-recovery.sh
@@ -178,13 +178,18 @@ All secrets stored in the build box Secrets. Never in repository files.
 | # | Secret | Used By |
 |---|--------|---------|
 | 1 | `DEEPSEEK_API_KEY` | OpenCode (primary model) |
-| 2 | `SIMONPLMAK_CLOUD_PAT` | GitHub MCP, shadcn MCP |
-| 3 | `PERPLEXITY_API_KEY` | Perplexity MCP |
-| 4 | `BRAVE_API_KEY` | Brave Search MCP |
-| 5 | `BROWSERLESS_TOKEN` | Browserless MCP + container |
-| 6 | `FIGMA_TOKEN` | Figma MCP |
+| 2 | `OPENCODE_API_KEY` | OpenCode Zen / Console Go providers |
+| 3 | `SIMONPLMAK_CLOUD_PAT` | GitHub MCP, shadcn MCP, `gh` |
+| 4 | `PERPLEXITY_API_KEY` | Perplexity MCP |
+| 5 | `BRAVE_API_KEY` | Brave Search MCP |
+| 6 | `BROWSERLESS_TOKEN` | Browserless MCP + container |
 | 7 | `SENTRY_AUTH_TOKEN` | Sentry MCP |
-| 8 | `KIMI_API_KEY` | Alternate provider (legacy) |
+| 8 | `VERCEL_ACCESS_TOKEN` | Vercel MCP (token auth) |
+
+Additional keys for opt-in servers (`EXA_API_KEY`, `CLOUDFLARE_API_TOKEN`,
+`STRIPE_SECRET_KEY`, `SURREAL_*`, `ALIBABA_CLOUD_*`, `AZURE_*`, `FIRECRAWL_API_KEY`,
+`FRED_API_KEY`, `COMPANIES_HOUSE_API_KEY`) are catalogued in
+[`docs/architecture/secrets.md`](docs/architecture/secrets.md) — never by value.
 
 See: [`docs/architecture/secrets.md`](docs/architecture/secrets.md)
 
@@ -209,7 +214,7 @@ See: [`docs/architecture/secrets.md`](docs/architecture/secrets.md)
 4. **Prompt**: Create in `docs/prompts/`, update `prompt-index.md`
 5. After any change: Update `CHANGELOG_WORKBENCH.md`, run master backup
 
-## Recovery Score: 92/100
+## Recovery Score: 94/100
 
 Validated disaster recovery within < 10 minutes using repository + build box Secrets alone.
 

WORKFLOW_STATE.md

@@ -1,76 +1,72 @@
 # Workflow State
 
-> Auto-generated and auto-updated. Read FIRST on every session start.
-> Last updated: 2026-07-27T00:00:00Z
+> Auto-updated. Read FIRST on every session start.
+> Last updated: 2026-10-03
 
 ## Current Status
 
 | Item | Status |
 |------|--------|
-| Phase #0 — Verify Docs | **COMPLETED** 2026-07-27 |
-| Phase #1 — Research | **COMPLETED** 2026-07-27 |
-| Phase #2 — Architecture | **COMPLETED** 2026-07-27 |
-| Phase #3 — Implementation | **IN PROGRESS** 2026-07-27 |
+| Phase #0 — Verify Docs | **COMPLETED** |
+| Phase #1 — Research | **COMPLETED** |
+| Phase #2 — Architecture | **COMPLETED** |
+| Phase #3 — Implementation | **COMPLETED** (clone MCP + bootstrap_host shipped) |
+| VDD chain (Phase 0–8) | **COMPLETED** — `constitution.md` + `vdd/` (gates G1–G7 PASS) |
+| Distribution | In progress — npm published; Vercel live; registry publish prepared |
 
 ## Last Checkpoint
 
 ```
-Phase: #3 — Implementation
-Status: Infrastructure + config complete; app/MCP/scraper source pending
-Timestamp: 2026-07-27
-Correlation ID: workflow-init-2026-07-27
+Phase: #3 — Implementation (complete)
+Status: opencode-workbench v1.1.2 shipped; VDD chain complete; docs refreshed
+Timestamp: 2026-10-03
 ```
 
-## Track Status
+## Tracks
 
-### AI-Enabled Web App
-| Step | Agent | Status | Output |
-|------|-------|--------|--------|
-| 1 | ResearchAgent | NOT STARTED | — |
-| 2 | DesignAgent | NOT STARTED | — |
-| 3 | PromptAgent | NOT STARTED | — |
-| 4 | ConfigAgent | NOT STARTED | — |
-| 5 | ToolingAgent | NOT STARTED | — |
-| 6 | BuildAgent | NOT STARTED | — |
-| 7 | TestAgent | NOT STARTED | — |
-| 8 | DeployAgent | NOT STARTED | — |
+### opencode-workbench (clone MCP) — DELIVERED
+| Item | Status | Output |
+|------|--------|--------|
+| Clone engine (inspect/plan/apply/verify) | DONE | `mcp-server/src/clone.ts` |
+| Consent gate + value-blind credentials | DONE | `apply_clone`/`install_component` `confirm:true`; `list_required_credentials`, `run_auth_flow` |
+| One-call provisioning | DONE | `bootstrap_host` (platform scan + upgrade plan + OpenCode pin + verify + `help`) |
+| Tests + CI | DONE | 49 tests; `mcp-server.yml` |
 
-### MCP Server / Agent Skills
-| Step | Agent | Status | Output |
-|------|-------|--------|--------|
-| 1 | SkillAuthorAgent | NOT STARTED | — |
-| 2 | SkillValidatorAgent | NOT STARTED | — |
-| 3 | SkillPublisherAgent | NOT STARTED | — |
+### VDD chain — DELIVERED
+| Phase | Artifact |
+|-------|----------|
+| 0 Init | `constitution.md` |
+| 1 Vision | `vdd/vision.md` (V-001; I-001…I-007) |
+| 2 Strategy | `vdd/strategy.md` (S-002) |
+| 3 Tactics | `vdd/tactics.md` (T-003; A-001…A-011) |
+| 4–6 Spec/Plan/Tasks | `vdd/specs/bootstrap-bare-host/`, `vdd/specs/mcp-quality-and-registry/` |
+| 7 Implement | `mcp-server/src/{platform,bootstrap,version}.ts` |
+| 8 Validate | `vdd/impact-report.generated.md`, `vdd/gates/G1–G7.md` |
 
-### Web Scraper
-| Step | Agent | Status | Output |
-|------|-------|--------|--------|
-| 1 | ScrapeConfigAgent | NOT STARTED | — |
-| 2 | ScrapeExecutorAgent | NOT STARTED | — |
-| 3 | ScrapeStorageAgent | NOT STARTED | — |
-| 4 | ScrapeAlertAgent | NOT STARTED | — |
+### Registry distribution
+| Registry | Status |
+|----------|--------|
+| npm | ✅ `@simonmak-ascent/[email protected]` |
+| Vercel (hosted connector) | ✅ live at `https://opencode-workbench.simonmak.com/mcp` |
+| Official MCP Registry | manifest ready (`server.json`) + OIDC workflow |
+| Glama | ✅ claim file live |
+| Smithery / PulseMCP / mcp.so | prepared (`docs/publishing/registry-listing.md`) |
 
 ## Infrastructure Status
 
-| Component | Status | Verified |
-|-----------|--------|----------|
-| Docker (pg-memory) | Running | 2026-07-27 |
-| Docker (browserless) | Running | 2026-07-27 |
-| MCP servers (18 enabled) | Connected | 2026-07-27 |
-| SurrealDB | Not yet provisioned | — |
-| Vercel project | Not yet created | — |
-| Sentry project | Not yet created | — |
+| Component | Status |
+|-----------|--------|
+| Docker (pg-memory, browserless) | Running (build box) |
+| MCP servers | 35 configured, 33 enabled (2 disabled: `google-search`, `google-workspace`) |
+| Vercel project | `opencode-workbench` (AP Team) — production live |
+| npm package | `@simonmak-ascent/[email protected]` |
 
 ## Instructions
 
 ### On Session Start
-1. Read this file FIRST
-2. Check current phase and last checkpoint
-3. Resume from the first incomplete agent
-4. Update this file after each agent completion
+1. Read this file FIRST.
+2. Check phase/tracks above.
+3. For repo facts, treat `opencode.json` and `package.json` as source of truth.
 
-### On Agent Completion
-Update the corresponding track status above and move to next checkpoint.
-
-### On Infrastructure Change
-Update the Infrastructure Status table above.
+### On Change
+Update the relevant track and `docs/CHANGELOG_WORKBENCH.md`.

connector.json

@@ -3,7 +3,7 @@
   "name": "opencode-workbench",
   "title": "OpenCode Workbench",
   "description": "Clones the OpenCode workbench installation onto Linux machines, locally or over SSH.",
-  "version": "1.0.0",
+  "version": "1.1.2",
   "transport": {
     "type": "stdio",
     "command": "npx",

context7.json

@@ -1,15 +1,16 @@
 {
   "$schema": "https://context7.com/schema/context7.json",
   "projectTitle": "OpenCode Workbench (opencode-workbench)",
-  "description": "Clones the OpenCode workbench onto Linux machines — locally or over SSH — reproducing the config, MCP servers, agent skills, plugins and Docker tooling. Exposes 6 tools over stdio.",
+  "description": "Provisions and clones the OpenCode workbench onto Linux machines — locally or over SSH — reproducing the config, MCP servers (35), agent skills (45), plugins and Docker tooling. Exposes 9 tools over stdio, including bootstrap_host for one-call provisioning.",
   "folders": [
     "mcp-server",
     "docs",
     "configs"
   ],
   "rules": [
     "Run locally with `npx -y @simonmak-ascent/opencode-workbench` (Node stdio MCP server; no API key).",
-    "Drive a clone with the tool order `workbench_info` → `inspect_target` → `plan_clone` → `apply_clone` → `verify_clone`; use `install_component` to install a single component by id.",
+    "Drive a clone with the tool order `workbench_info` → `inspect_target` → `plan_clone` → `apply_clone` → `verify_clone`; use `install_component` to install a single component by id, and `bootstrap_host` for a one-call end-to-end provision (platform scan + OpenCode + apply + verify; `help:true` documents parameters).",
+    "`apply_clone` and `install_component` are consent-gated: without `confirm:true` they return a plan and change nothing.",
     "Every tool takes a `target` of `{mode: \"local\"}` or `{mode: \"ssh\", host, user, port?, identityFile?}`.",
     "The connector never reads, transmits or writes secret values; `apply_clone` writes an empty `~/.env.workbench` template (mode 600) listing the `{env:VAR}` names to fill in.",
     "`apply_clone` is idempotent; pass `dryRun: true` to preview the plan without making changes."

docs/architecture/clone-mcp.md

@@ -45,6 +45,7 @@ mcp-server/src/
 | `verify_clone` | Re-check config, env template, and every component. |
 | `list_required_credentials` | Value-blind: which keys are missing and how to acquire each. |
 | `run_auth_flow` | Emit-and-verify acquisition guidance for one credential. |
+| `bootstrap_host` | One-call provisioning: kernel-up platform scan + dry-run upgrade plan, latest-stable OpenCode with recorded version, apply + verify; `help:true` documents every parameter without touching the target. Consent-gated. |
 
 ### Connector model
 

docs/architecture/opencode-runtime-config.md

@@ -1,63 +1,72 @@
 # OpenCode Runtime Configuration
 
-> Generated: 2026-07-27
-> Source: `~/.config/opencode/opencode.json` (synced from repo `opencode.json`)
+> Updated: 2026-10-03
+> Source of truth: repo `opencode.json`, copied to `~/.config/opencode/opencode.json`
+> on the build box. Counts below are derived from `opencode.json`.
 
 ## Active Configuration
 
 | Item | Value |
 |------|-------|
 | **Primary Model** | `deepseek/deepseek-v4-pro` |
-| **Small Model** | `deepseek/deepseek-v4-pro` |
+| **Small Model** | `deepseek/deepseek-v4-flash` |
+| **Default agent** | `vdd` |
 | **LSP** | Enabled |
 | **Schema** | `https://opencode.ai/config.json` |
 
 ## Provider Configuration
 
-### DeepSeek
-- **API**: `https://api.deepseek.com/v1`
-- **Key env**: `DEEPSEEK_API_KEY`
-- **Source**: build box Secret
-
-## MCP Server Assignments (19 configured, 18 enabled, 1 disabled)
-
-### Remote MCPs (5)
-| Server | URL | Auth Method |
-|--------|-----|-------------|
-| context7 | `https://mcp.context7.com/mcp` | None |
-| gh_grep | `https://mcp.grep.app` | None |
-| clerk | `https://mcp.clerk.com/mcp` | None |
-| vercel | `https://mcp.vercel.com` | OAuth |
-
-### Local MCPs (14, 1 disabled)
-| Server | Binary/Entry Point | Secrets |
-|--------|-------------------|---------|
-| github | `/home/node/.local/bin/github-mcp-server` | `SIMONPLMAK_CLOUD_PAT` |
-| perplexity | `vendor/perplexity-agent-mcp/index.js` | `PERPLEXITY_API_KEY` |
-| brave-search | `@modelcontextprotocol/server-brave-search` | `BRAVE_API_KEY` |
-| postgres | `@modelcontextprotocol/server-postgres` | `DATABASE_URL` |
-| browserless | `vendor/browserless-mcp/dist/index.js` | `BROWSERLESS_TOKEN` |
-| playwright | `@playwright/mcp/cli.js` | None |
-| figma | `figma-developer-mcp` | `FIGMA_TOKEN` (mapped to `FIGMA_API_KEY`) |
-| mermaid | `mcp-mermaid` | None |
-| saga | `saga-mcp` | `DB_PATH` |
-| echarts | `mcp-echarts` | None |
-| shadcn | `@jpisnice/shadcn-ui-mcp-server` | `SIMONPLMAK_CLOUD_PAT` |
-| swagger-testcase | `swagger-testcase-mcp` | None |
-| design-system | `mcp-design-system-extractor` | None (needs `STORYBOOK_URL`) |
-| sentry | `@sentry/mcp-server` | `SENTRY_AUTH_TOKEN` |
+- **DeepSeek** — `https://api.deepseek.com`, key `DEEPSEEK_API_KEY`.
+- **OpenCode Zen / Console Go** — key `OPENCODE_API_KEY`.
+- Additional optional providers are documented in
+  `docs/architecture/ai-provider-inventory.md`.
+
+## MCP Servers (35 configured · 33 enabled · 2 disabled)
+
+> Full per-server table (entry point + auth env) is the generated inventory:
+> [`mcp-inventory.md`](./mcp-inventory.md). Disabled by default: `google-search`,
+> `google-workspace`. Opt-in add-ons (dropped unless enabled): see
+> `OPTIONAL_MCP_IDS` in `mcp-server/src/render.ts`.
+
+### Remote MCPs (9, all enabled)
+| Server | URL | Auth |
+|--------|-----|------|
+| context7 | `https://mcp.context7.com/mcp` | none |
+| gh_grep | `https://mcp.grep.app` | none |
+| clerk | `https://mcp.clerk.com/mcp` | none |
+| vdd | `https://vdd.simonmak.com/api/mcp` | none |
+| exa | `https://mcp.exa.ai/mcp` | `EXA_API_KEY` |
+| cloudflare | `https://mcp.cloudflare.com/mcp` | `CLOUDFLARE_API_TOKEN` |
+| sentry | `https://mcp.sentry.dev/mcp` | `SENTRY_AUTH_TOKEN` |
+| stripe | `https://mcp.stripe.com` | `STRIPE_SECRET_KEY` |
+| vercel | `https://mcp.vercel.com` | `VERCEL_ACCESS_TOKEN` (token auth) |
+
+### Local MCPs (26: 24 enabled, 2 disabled)
+Includes github (binary), perplexity + browserless (vendored), brave-search,
+postgres, playwright, mermaid, echarts, shadcn, swagger-testcase, design-system,
+saga, arxiv, paper-search, firecrawl, primary-sources, ms-365, alibaba-cloud-ops,
+surrealdb, designlang, difflens, browser-mcp, esg-hub, humanity4ai; plus the two
+disabled local servers `google-search` and `google-workspace`.
+
+> `figma` was removed from the profile (superseded by the v0 workflow).
 
 ## Recovery Method
 
-1. Clone this repository
-2. build box secrets auto-propagate via `devcontainer.json` `remoteEnv`
-3. `.devcontainer/setup.sh` installs MCP servers and copies config
-4. `opencode.json` is the single source of truth for MCP configuration
-5. Runtime copy at `~/.config/opencode/opencode.json` is synced from repo
+1. Clone this repository.
+2. Build-box secrets propagate via `.devcontainer/devcontainer.json` `remoteEnv`.
+3. `.devcontainer/setup.sh` installs the OpenCode CLI, npm/vendored MCP servers,
+   Playwright Chromium, and copies config.
+4. `opencode.json` is the single source of truth; the runtime copy is synced from it.
+5. Validate with `bash scripts/recovery/validate-recovery.sh`.
 
-## Custom Skills
+## Custom Skills (45 in `.opencode/skills/`)
 
-28 custom agent skills defined in `.opencode/skills/` across three domains:
-- **Research** (10): spec-writer, competitive-analysis, api-research, tech-stack-eval, codebase-explorer, dependency-audit, architecture-review, content-research, benchmark-research, security-audit
-- **Development** (10): component-builder, api-builder, db-schema, auth-flow, responsive-design, state-management, test-writer, perf-optimizer, error-handling, cicd-setup
-- **Publishing** (8): changelog-generator, release-manager, cloud-deploy, docker-builder, npm-publisher, docs-generator, semantic-release, post-deploy-monitor
+Ported skill families include: research (spec-writer, competitive-analysis,
+api-research, tech-stack-eval, codebase-explorer, dependency-audit,
+architecture-review, content-research, benchmark-research, security-audit,
+web-research); development (component-builder, api-builder, db-schema, auth-flow,
+responsive-design, state-management, test-writer, perf-optimizer, error-handling,
+cicd-setup); publishing (changelog-generator, release-manager, cloud-deploy,
+docker-builder, npm-publisher, docs-generator, semantic-release,
+post-deploy-monitor); plus VDD/spec-driven, data/analysis, scientific-computing,
+frontend-design, browser-automation, accessibility and workbench-compute.