feat: add VS Code extension with sidebar, dashboard webview, status bar, and deep linking

- Introduce `vscode-extension/` package with activity-bar sidebar, status bar integration, and dashboard webview
- Implement commands for REPL, run task, run selection/file, dashboard lifecycle, doctor, settings, and task deep linking
- Read stats and recent tasks directly from local SQLite index for offline support
- Update docs, README, ARCHITECTURE.md, and index.html to document and showcase the new extension
- Add .vscodeignore, tsconfig, tasks, and supporting files for extension build and packaging

Author: hoangsonww

.gitignore

@@ -1,6 +1,8 @@
 node_modules/
 dist/
 coverage/
+vscode-extension/node_modules/
+vscode-extension/out/
 *.log
 .env
 .env.local

.vscode/extensions.json

@@ -1,6 +1,4 @@
 {
-  // Recommended extensions for contributors. VS Code prompts to install
-  // these the first time the workspace is opened.
   "recommendations": [
     "dbaeumer.vscode-eslint",
     "esbenp.prettier-vscode",

.vscode/launch.json

@@ -1,6 +1,4 @@
 {
-  // Debug configurations for Forge. Each one uses an isolated FORGE_HOME
-  // so debugging never touches the developer's real ~/.forge state.
   "version": "0.2.0",
   "configurations": [
     {

.vscode/settings.json

@@ -1,7 +1,4 @@
 {
-  // -------------------------------------------------------------------------
-  // Editor — match the prettier + eslint contract enforced in CI.
-  // -------------------------------------------------------------------------
   "editor.formatOnSave": true,
   "editor.defaultFormatter": "esbenp.prettier-vscode",
   "editor.codeActionsOnSave": {
@@ -18,28 +15,15 @@
   "files.trimTrailingWhitespace": true,
   "files.trimFinalNewlines": true,
   "files.eol": "\n",
-
-  // -------------------------------------------------------------------------
-  // TypeScript — use the workspace's own tsc, not the one bundled with VS Code.
-  // Keeps error messages aligned with `npm run typecheck` in CI.
-  // -------------------------------------------------------------------------
   "typescript.tsdk": "node_modules/typescript/lib",
   "typescript.enablePromptUseWorkspaceTsdk": true,
   "typescript.preferences.importModuleSpecifier": "relative",
   "typescript.updateImportsOnFileMove.enabled": "always",
   "typescript.inlayHints.parameterNames.enabled": "literals",
   "typescript.inlayHints.functionLikeReturnTypes.enabled": false,
   "javascript.preferences.importModuleSpecifier": "relative",
-
-  // -------------------------------------------------------------------------
-  // ESLint — run on .ts files; flat config is not used here.
-  // -------------------------------------------------------------------------
   "eslint.validate": ["typescript", "typescriptreact", "javascript"],
   "eslint.workingDirectories": [{ "mode": "auto" }],
-
-  // -------------------------------------------------------------------------
-  // Per-language overrides
-  // -------------------------------------------------------------------------
   "[typescript]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
@@ -66,10 +50,6 @@
   "[github-actions-workflow]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
-
-  // -------------------------------------------------------------------------
-  // Search + explorer — hide build and native-module churn from the tree.
-  // -------------------------------------------------------------------------
   "files.exclude": {
     "**/.DS_Store": true,
     "**/Thumbs.db": true,
@@ -97,24 +77,12 @@
     ".gitignore": ".gitattributes, .editorconfig, .prettierrc*, .eslintrc*, .prettierignore, .eslintignore",
     "vitest.config.ts": "vitest.config.*.ts"
   },
-
-  // -------------------------------------------------------------------------
-  // Testing — Vitest extension integration (auto-detects vitest.config.ts).
-  // -------------------------------------------------------------------------
   "vitest.commandLine": "npx vitest",
   "vitest.enable": true,
-
-  // -------------------------------------------------------------------------
-  // Terminal + Git
-  // -------------------------------------------------------------------------
   "terminal.integrated.scrollback": 10000,
   "git.autofetch": true,
   "git.confirmSync": false,
   "git.openRepositoryInParentFolders": "never",
-
-  // -------------------------------------------------------------------------
-  // Telemetry + UI noise
-  // -------------------------------------------------------------------------
   "npm.packageManager": "npm",
   "npm.enableRunFromFolder": true,
   "editor.minimap.enabled": false

CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to Forge are tracked here. Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.0.0] - 2026-04-27
+
+First stable release. The runtime, agentic loop, persistence model, permission system, sandbox, and provider abstractions are now considered stable surface area. Breaking changes from here on bump MAJOR.
+
+### Added
+- **VS Code extension** (`vscode-extension/`, published as `hoangsonw.forge-agentic-coding-cli`). First-class editor surface with an activity-bar webview, status-bar pill, command palette integration, deep-linking from any task into the dashboard's conversation view, integrated terminals for REPL / `forge run` / `forge ui start` / `forge doctor`, and an embedded dashboard webview. Reads stats directly from `~/.forge/global/index.db` so token, call, and task counts stay accurate even with no Forge process running. Onboarding flow when the runtime is missing: install via npm, custom-path override, docs link.
+- **Dashboard URL deep-linking** — `?task=<id>` (or `#task=<id>`) opens the task detail view on load; `?view=<name>` jumps directly to a named view. Used by the VS Code extension's "view all" and per-task click-through, but available to any caller.
+- **Plan-edit modal** in the dashboard — JSON editor pops up when you choose Edit on a plan approval; edited plans flow back through the same `interactive-host` channel as terminal edits.
+- **Live markdown streaming in the dashboard** — `model.delta` events render via `requestAnimationFrame`-coalesced markdown reflow so headings, fences, and lists form up as tokens arrive instead of dumping at the end.
+- **Per-task delta replay buffer** so a WebSocket client that connects mid-stream sees the tokens that were already emitted, not just future ones.
+- **Cross-project task detail lookup** — `/api/tasks/:id` resolves the project automatically via the global index, with a fallback chain (explicit `?projectPath=` → `getTask().project_id` → `findProjectRoot()` → `process.cwd()`). 404 responses now include the list of paths that were tried.
+- **Demos page** in the docs site (`#demos`) and a dedicated **VS Code section** (`#vscode`) on the landing page.
+- **Demo recordings** for REPL, CLI, and dashboard surfaces, plus a screenshot of the VS Code extension. Drive overlay buttons on every video for users who can't load embedded MP4s.
+
+### Changed
+- Tightened dashboard markdown renderer: inline triple-backtick fences now normalised to multi-line; ordered lists honor source numbering via `<ol start="N">` and tolerate blank lines between items; per-line borders inside `<pre><code>` removed; chat-bubble whitespace tightened.
+- REPL launch banner and completion block now render with the same divider/breadcrumb/summary treatment as `forge run`, so REPL turns and one-shot CLI runs look identical.
+- Status-bar dashboard reachability indicator now probes `/api/status` over HTTP before flipping to "offline", eliminating false-offline blips during heavy task streams.
+- Plan auto-approval bug: plans now wait for the user's decision in the UI before execution. Previously some plans were silently approved.
+- Conversation rendering: TASK_COMPLETED events carry a short message; the streamed reply is no longer duplicated in the DONE block.
+
+### Fixed
+- Streaming dropping deltas due to a task-id mismatch between the UI runner and the orchestrator. Both sides now agree on the canonical `task_<hex>` id.
+- "Spend $0.000" stat tile removed for local providers (Ollama / llama.cpp), where cost is always zero by design. Token totals still shown.
+- Tokens stat now reflects the real lifetime sum from `model_cost_ledger` instead of the in-memory delta.
+- Recent-task rows weren't clickable / showed every task as `pending` because the API field is `status` (not `state`) and `title` (not `prompt`). Field names corrected and the entire row is now the click target.
+- Sidebar layout overflowed on narrow widths. Action grid uses `repeat(auto-fit, minmax(96px, 1fr))`; stats grid uses `minmax(78px, 1fr)`. Workspace card uses RTL truncation so long paths show their tail.
+- VS Code "view all" button now opens the dashboard's Tasks page, not the home view.
+
 ## [0.1.0] - 2026-04-18
 
 Initial public release. Includes the full planning spec surface area.

README.md

@@ -256,7 +256,7 @@ See [`docs/INSTALL.md`](docs/INSTALL.md) for per-OS notes and [`docs/SETUP.md`](
 
 ### See it running
 
-Three surfaces, one runtime.
+Four surfaces, one runtime.
 
 **REPL (Interactive Terminal) Mode**
 
@@ -270,6 +270,14 @@ https://github.com/user-attachments/assets/bc3b3204-fd87-436f-9467-604535edb4e2
 
 https://github.com/user-attachments/assets/218cd64f-40fe-4836-9c62-c7a08538056b
 
+**VS Code Extension**
+
+The same workflow, embedded in your editor. A live activity-bar sidebar with status, stats, recent tasks, and quick actions; deep-linking from any task into its conversation view; one-click dashboard webview; selection-as-task and file-as-task commands. Stats read straight from `~/.forge/global/index.db` so they stay accurate even when no server is running.
+
+![Forge for VS Code](vscode-extension/vscode.png)
+
+Install: `code --install-extension hoangsonw.forge-agentic-coding-cli` or [open it on the Marketplace](https://marketplace.visualstudio.com/items?itemName=hoangsonw.forge-agentic-coding-cli). See [`vscode-extension/README.md`](vscode-extension/README.md) for the full command reference.
+
 ---
 
 ## The agentic loop

RELEASES.md

@@ -443,10 +443,10 @@ FROM ghcr.io/hoangsonw/forge-agentic-coding-cli:0.2.0
 
 ```bash
 # npm — downgrade explicitly.
-npm install -g @hoangsonw/forge@0.1.1
+npm install -g @hoangsonw/forge@1.0.0
 
 # Docker — swap the tag.
-docker pull ghcr.io/hoangsonw/forge-agentic-coding-cli:0.1.1
+docker pull ghcr.io/hoangsonw/forge-agentic-coding-cli:1.0.0
 
 # Tell the built-in updater to stop nagging about a broken version.
 forge update ignore 0.2.0
@@ -644,6 +644,32 @@ Stable within a MAJOR. Migrations under [`src/migrations/runner.ts`](src/migrati
 <!-- Newest at the top. Keep the template from
      "Release-notes template" above. -->
 
+### v1.0.0 — 2026-04-27
+
+#### Highlights
+- First stable release. Runtime, agentic loop, persistence, permissions, sandbox, and provider abstractions are now stable surface area; future breaking changes bump MAJOR.
+- New first-class **VS Code extension** (`hoangsonw.forge-agentic-coding-cli`) with activity-bar webview, stats grid, recent tasks, and deep-linking from any task into the dashboard's conversation view.
+- **Dashboard URL deep-linking** — `?task=<id>` opens task detail; `?view=<name>` jumps to a named view. Used by the VS Code extension and any other surface that links into the dashboard.
+- Cross-project task detail lookup via `/api/tasks/:id` — resolves the project automatically from the global index.
+
+#### Added
+- VS Code extension surface (separate npm package + Marketplace listing).
+- `?task=` / `?view=` deep-link routing in the dashboard SPA.
+- Plan-edit modal in the dashboard (JSON editor for plan approval).
+- Per-task delta replay buffer so late-connecting WebSocket clients see prior tokens.
+- Demo recordings + VS Code screenshot on the landing page.
+
+#### Changed
+- Live markdown streaming uses rAF-coalesced reflow instead of dump-at-end.
+- REPL completion summary now matches `forge run` formatting.
+- Status-bar reachability indicator HTTP-probes before flipping to offline.
+- Plans wait for explicit user decision in the UI; no silent auto-approval.
+
+#### Fixed
+- Streaming previously dropped deltas due to a task-id mismatch between the UI runner and the orchestrator.
+- Recent-task rows in the VS Code sidebar are now clickable and show the right status.
+- Cross-project task detail lookups no longer 404.
+
 ### v0.1.1 — 2026-04-20
 
 #### Highlights

docs/ARCHITECTURE.md

@@ -18,6 +18,7 @@
 - [7. Permission + sandbox model](#7-permission--sandbox-model)
 - [8. Conversation & persistence](#8-conversation--persistence)
 - [9. UI topology](#9-ui-topology)
+  - [9.1 VS Code extension](#91-vs-code-extension)
 - [10. CI/CD pipeline](#10-cicd-pipeline)
 - [11. Deployment topologies](#11-deployment-topologies)
 - [12. Runtime metrics at a glance](#12-runtime-metrics-at-a-glance)
@@ -42,6 +43,7 @@ flowchart TB
     CLI["CLI (commander)"]:::surface
     REPL["REPL (raw-mode editor)"]:::surface
     UI["Dashboard (HTTP + WS)"]:::surface
+    VSCX["VS Code extension<br/>(vscode-extension/)"]:::surface
   end
 
   ORCH["Orchestrator<br/>src/core/orchestrator.ts"]:::core
@@ -105,6 +107,7 @@ Code it maps to:
 | CLI surface | `src/cli/` (24 commands) |
 | REPL | `src/cli/repl.ts` + `src/cli/repl-input.ts` |
 | UI | `src/ui/server.ts` + `src/ui/public/` |
+| VS Code extension | `vscode-extension/` (separate npm package, ships to the VS Code Marketplace) |
 | Orchestrator | `src/core/orchestrator.ts` |
 | Agentic loop | `src/core/loop.ts` |
 | Agents | `src/agents/{planner,architect,executor,reviewer,debugger,memory}.ts` |
@@ -494,6 +497,57 @@ flowchart LR
   for path-traversal safety.
 - Healthcheck endpoint `/api/status` used by the Docker HEALTHCHECK.
 
+### 9.1 VS Code extension
+
+The extension at `vscode-extension/` is a sibling surface — its own npm package, its own version, its own publish pipeline. It does not import any runtime code from `src/`; instead it talks to a Forge install the user already has on `PATH` and reads from the same persisted state.
+
+```mermaid
+flowchart LR
+  classDef b fill:#0f172a,stroke:#38bdf8,color:#f1f5f9,rx:4,ry:4
+  classDef s fill:#082f49,stroke:#38bdf8,color:#e0f2fe,rx:4,ry:4
+  classDef d fill:#18181b,stroke:#f59e0b,color:#fef3c7,rx:4,ry:4
+
+  EDITOR[VS Code editor]:::b
+  EXT["forge-agentic-coding-cli<br/>extension host"]:::s
+  TERM[integrated terminals]:::s
+  WV["webview (iframe)"]:::s
+  SIDEBAR["activity-bar webview<br/>(stats / tasks / actions)"]:::s
+  FORGE[forge binary on $PATH]:::s
+  UISERVER[forge ui server]:::s
+  DB[(~/.forge/global/index.db)]:::d
+
+  EDITOR --> EXT
+  EXT -->|spawn forge / forge run / forge ui start| TERM
+  EXT -->|sqlite3 read-only| DB
+  EXT --> SIDEBAR
+  EXT --> WV
+  WV -->|iframe src + ?task=id| UISERVER
+  TERM --> FORGE
+  UISERVER --> DB
+```
+
+What the extension owns:
+
+- **Activity-bar webview** with status pill, workspace meta, live stats grid, action buttons, recent tasks, and providers. Polls every 4 s when visible.
+- **Status-bar item** that flips between *live* and *idle* based on `/api/status` reachability.
+- **Commands** for REPL, run-task / run-selection / run-file, dashboard lifecycle, doctor, settings, copy URL, change cwd, kill all.
+- **Deep linking** — clicking a recent task opens the dashboard webview with `?task=<id>`, which the SPA picks up at boot and routes straight to the conversation view.
+
+Data sources, in order of preference:
+
+1. The dashboard REST API (`/api/status`, `/api/tasks`, `/api/models`) when `forge ui` is running.
+2. The local SQLite index (`$FORGE_HOME/global/index.db`) read in read-only mode via the system `sqlite3` CLI. This is what makes lifetime stats (tokens, calls, task counts) work even with no Forge process running.
+
+The runtime exposes one piece of code specifically for this surface: `src/ui/server.ts → /api/tasks/:id` resolves the task's project automatically (index → projects → cwd fallback chain) so cross-project task detail lookups from the extension don't 404.
+
+Build and publish:
+
+```bash
+cd vscode-extension && npm install && npm run build
+npx @vscode/vsce package --no-dependencies   # produces .vsix
+npx @vscode/vsce publish --no-dependencies   # marketplace
+```
+
 ---
 
 ## 10. CI/CD pipeline

docs/CLI-REFERENCE.md

@@ -1,6 +1,6 @@
 # CLI reference
 
-Full surface as of v0.1.0. `forge help <command>` for any sub-command.
+Full surface as of v1.0.0. `forge help <command>` for any sub-command.
 
 ## Root