Refresh docs accuracy, terminology, and roadmap status.

Align public docs and settings recovery copy with current UI labels, HTTP streaming behavior, npm/platform claims, and completed roadmap milestones for D1.5.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Alexey Perov

CONTRIBUTING.md

@@ -8,10 +8,13 @@ Prerequisites: Node.js (LTS), Rust (stable), and system `git` on `PATH`.
 
 ```sh
 cd app
-npm install
+npm ci
 npm run tauri dev
 ```
 
+Use `npm ci` for a reproducible checkout. Use `npm install` when intentionally
+changing dependencies or updating `package-lock.json`.
+
 See the root [README.md](./README.md) for build, port **1430**, and CI release notes.
 
 ## Checks

README.md

@@ -1,6 +1,8 @@
 # <img src="app/static/favicon.png" alt="" width="32" height="32" align="top"> SpecOps
 
-Desktop workspace for notes, specs, and project files — with a built-in editor and **OpenCode**-powered workspace agents. Built with [Tauri](https://tauri.app/) and [SvelteKit](https://kit.svelte.dev/).
+Desktop workspace for notes, specs, and project files — with a built-in editor
+and **OpenCode**-powered workspace sessions. Built with
+[Tauri](https://tauri.app/) and [SvelteKit](https://kit.svelte.dev/).
 
 > Under active development. APIs, settings, and on-disk formats may change without migration.
 
@@ -13,7 +15,7 @@ Desktop workspace for notes, specs, and project files — with a built-in editor
 - **Version Control** — per-workspace git tab (history, branches, tags, changes, fetch/pull/push) via system `git`
 - **Themes**, **multi-window**, **image** preview
 - **Console** — resizable bottom panel with logs
-- **Workspace agents** — sessions powered by [OpenCode](https://opencode.ai/) (tools, permissions, streaming)
+- **Workspace sessions** — OpenCode-powered conversations with tools, permissions, and streaming
 - **Chat (beta)** — experimental HTTP chat context, off by default; see [`docs/beta/`](./docs/beta/)
 
 ## Screenshots
@@ -27,14 +29,14 @@ Desktop workspace for notes, specs, and project files — with a built-in editor
 - **Releases** — download macOS / Windows installers from [GitHub Releases](https://github.com/AlexeyPerov/spec-ops/releases) (published when a semver tag is pushed; see [CI releases](#ci-releases)).
 - **From source** — see [Development](#development) below.
 
-## Workspace agents (OpenCode)
+## Workspace sessions (OpenCode)
 
 SpecOps is the UI; **OpenCode** runs models, tools, and session logic. Configure providers and API keys in OpenCode — not in SpecOps HTTP settings.
 
 | Context | Runtime | Configure models / keys |
 | --- | --- | --- |
-| Workspace agents (`ws-*`) | OpenCode (sidecar or URL) | OpenCode (`/connect`, `opencode.json`, `auth.json`) |
-| Chat (beta) — `chat-http` | OpenAI-compatible HTTP (off by default) | **Settings → Dev → Chat (beta)** → Providers |
+| Workspace sessions | OpenCode (sidecar or URL) | OpenCode (`/connect`, `opencode.json`, `auth.json`) |
+| Chat (beta) — `chat-http` (internal context id) | OpenAI-compatible HTTP (off by default) | Enable at **Settings → Dev → Enable Chat (beta)**, then configure **Settings → Dev → Providers** |
 
 ### Quick start
 
@@ -57,7 +59,7 @@ Chat (beta): **[docs/beta/chat-http-providers.md](./docs/beta/chat-http-provider
 
 - Further UI / UX polish
 - Extended AI support
-- Git post-MVP features (see [`specs/git/backlog.md`](./specs/git/backlog.md))
+- Git post-MVP features
 
 ## Prerequisites
 
@@ -67,13 +69,16 @@ Chat (beta): **[docs/beta/chat-http-providers.md](./docs/beta/chat-http-provider
 
 ## Development
 
-From the `app/` directory:
+From the `app/` directory, use `npm ci` for a reproducible clean-clone setup:
 
 ```sh
-npm install
+npm ci
 npm run tauri dev
 ```
 
+Use `npm install` instead when intentionally changing dependencies or refreshing
+`app/package-lock.json`.
+
 This starts the Vite dev server and opens the desktop app. Type-check the frontend with:
 
 ```sh
@@ -109,25 +114,40 @@ npm run tauri dev
 
 ## Build
 
-From the `app/` directory:
+From the `app/` directory after installing dependencies, ensure the matching
+OpenCode sidecar binary exists (see
+[`app/src-tauri/binaries/README.md`](./app/src-tauri/binaries/README.md)), then:
 
 ```sh
-npm install
 npm run tauri build
 ```
 
 Installers and bundles are written to `app/src-tauri/target/release/bundle/`.
 
+### Platform support
+
+| Platform | GitHub release downloads | Test CI | Local source builds |
+| --- | --- | --- | --- |
+| macOS (Apple silicon and Intel) | Yes — universal build | Yes | Supported |
+| Windows (x64) | Yes | Yes | Supported |
+| Linux | No published installers | Yes | Buildable with Tauri's Linux prerequisites, but not a supported release target |
+
+The test workflow runs the Vitest suite on macOS, Windows, and Linux. The release
+workflow publishes artifacts only for macOS and Windows; Tauri's `targets: "all"`
+controls bundle formats for the current build host and does not add a Linux release job.
+
 ### CI releases
 
-Pushing a semver tag (for example `v1.0.0`) triggers the [Release](.github/workflows/release.yml) workflow. It builds macOS (universal binary) and Windows installers and publishes them as assets on the GitHub release for that tag.
+Pushing any tag beginning with `v` (for example `v1.0.0`) triggers the
+[Release](.github/workflows/release.yml) workflow. It builds a universal macOS
+bundle and Windows x64 installers and publishes them as assets on that GitHub release.
 
 ## Docs
 
 | Doc | Audience |
 | --- | --- |
 | [docs/README.md](./docs/README.md) | Index — users vs contributors |
-| [docs/opencode-integration.md](./docs/opencode-integration.md) | Workspace agents / OpenCode setup |
+| [docs/opencode-integration.md](./docs/opencode-integration.md) | Workspace sessions / OpenCode setup |
 | [docs/architecture.md](./docs/architecture.md) | Codebase map for contributors |
 | [docs/beta/](./docs/beta/) | Experimental Chat (HTTP) lane |
 | [CONTRIBUTING.md](./CONTRIBUTING.md) | How to contribute |

app/src-tauri/binaries/README.md

@@ -46,10 +46,14 @@ After the script writes new binaries:
 4. Consider aligning `@opencode-ai/sdk` in `app/package.json` to the same
    release version (the script does not touch the SDK lockfile).
 
-## Asset → Tauri triple mapping
-
-The script hard-codes the mapping below; if `anomalyco/opencode` publishes
-new asset names, edit `PLATFORM_MAP` in `update-opencode-sidecar.sh` first.
+## Sidecar asset → Tauri triple mapping
+
+The script hard-codes the downloadable sidecar mapping below; if the upstream
+project publishes new asset names, edit `PLATFORM_MAP` in
+`update-opencode-sidecar.sh` first. This table describes sidecars that the
+maintainer script can prepare, not SpecOps release targets: GitHub releases
+currently publish SpecOps only for macOS and Windows. Linux is test-CI and
+local-build coverage only.
 
 | Release asset                       | Tauri target triple          |
 | ----------------------------------- | ---------------------------- |

app/src/lib/ai/chatErrorCopy.ts

@@ -38,7 +38,7 @@ export const DEBUG_AI_PROVIDER_DISABLED_MESSAGE =
   "Debug Provider is turned off in Settings.";
 
 export const DEBUG_AI_PROVIDER_DISABLED_RECOVERY =
-  "Open Settings → Dev, enable Chat (beta), then turn on the Debug Provider under Chats.";
+  "Open Settings → Dev, enable Chat (beta), then turn on Debug Provider.";
 
 export const DEBUG_AGENT_PROVIDER_DISABLED_MESSAGE =
   "Debug Provider is turned off in Settings.";
@@ -98,13 +98,13 @@ export const STREAM_TRUNCATED_FAILURE_RECOVERY =
   "The stream ended before completion. Retry now; if this repeats, check provider/proxy stability.";
 
 export const HTTP_UNAUTHORIZED_FAILURE_MESSAGE =
-  "Invalid API key for the configured HTTP provider. Check Settings → Providers.";
+  "Invalid API key for the configured HTTP provider. Check Settings → Dev → Providers.";
 
 export const HTTP_RATE_LIMIT_FAILURE_MESSAGE =
   "HTTP provider rate limit reached. Wait a moment and try again.";
 
 export const HTTP_UNAUTHORIZED_FAILURE_RECOVERY =
-  "Open Settings → Providers, update the API key, and retry.";
+  "Open Settings → Dev → Providers, update the API key, and retry.";
 
 export const HTTP_RATE_LIMIT_FAILURE_RECOVERY =
   "Wait a short time and retry. If this happens often, lower request volume or change provider limits.";

app/src/lib/components/ChatBlockedState.svelte

@@ -47,7 +47,7 @@
       The HTTP chat context is an experimental beta feature and is disabled by default.
     </p>
     <p class="chat-blocked-hint">
-      Enable Chat (beta) in Settings → Dev, then configure HTTP providers or Debug Provider under Chats.
+      Enable Chat (beta), then configure Providers, Chat modes, or Debug Provider under Dev.
     </p>
     <button type="button" class="btn btn-primary chat-setup-button" onclick={() => openSettingsDialog("dev")}>
       Open Settings → Dev

app/src/lib/components/settings/DevSettingsPanel.svelte

@@ -15,8 +15,8 @@
   <h3>Chat (beta)</h3>
   <p class="settings-section-note">
     Experimental HTTP chat context. When enabled, the activity rail shows a
-    Chat button and the Chats subtree appears under Dev for HTTP provider
-    configuration. Workspace agents (OpenCode) are unaffected.
+    Chat button and Dev gains Providers, Chat modes, and Debug Provider tabs
+    for HTTP configuration. Workspace sessions (OpenCode) are unaffected.
   </p>
   <div class="settings-subsection">
     <label class="settings-toggle" title="Enable Chat (beta) for the HTTP chat context">
@@ -31,8 +31,8 @@
     </label>
     {#if !chatHttpEnabled}
       <p class="settings-section-note">
-        Chat (beta) is off. The activity rail Chat button and Chats settings
-        tabs (Providers, Chat modes, Debug Provider) are hidden.
+        Chat (beta) is off. The activity rail Chat button and the Dev tabs for
+        Providers, Chat modes, and Debug Provider are hidden.
       </p>
     {:else}
       <p class="settings-section-note">

app/src/lib/domain/settings.ts

@@ -19,7 +19,7 @@ export interface ProviderSettingsBase {
   enabled: boolean;
 }
 
-/** Settings-gated development provider; disabled by default (see M5-3). */
+/** Settings-gated development provider; scoped by chat context. */
 export interface DebugProviderSettings extends ProviderSettingsBase {
   simulationSeed: number | null;
   delayMsMin: number;
@@ -127,9 +127,8 @@ export interface OpencodeSettings {
  * Master toggle for the experimental `chat-http` context (phase-3.5 M13).
  *
  * Disabled by default. When false, the activity-rail Chat button is hidden
- * and the Settings → Dev → Chats subtree (Providers, Chat modes, Debug
- * Provider) is removed from the sidebar; persisted provider configuration
- * is untouched.
+ * and the Settings → Dev gated tabs (Providers, Chat modes, Debug Provider)
+ * are removed from the sidebar; persisted provider configuration is untouched.
  */
 export interface ChatHttpSettings {
   enabled: boolean;

docs/README.md

@@ -7,9 +7,9 @@ Stable documentation for users and contributors. Product plans, execution checkl
 | Doc | When to read it |
 | --- | --- |
 | [../README.md](../README.md) | Product overview, install, quick start |
-| [opencode-integration.md](./opencode-integration.md) | Workspace agents: first session, sidecar/URL, providers, troubleshooting |
+| [opencode-integration.md](./opencode-integration.md) | Workspace sessions (OpenCode): first session, sidecar/URL, providers, troubleshooting |
 | [beta/README.md](./beta/README.md) | Experimental features (opt-in) |
-| [beta/chat-http-providers.md](./beta/chat-http-providers.md) | Chat (beta) HTTP providers — only if you enable **Settings → Dev → Chat (beta)** |
+| [beta/chat-http-providers.md](./beta/chat-http-providers.md) | Chat (beta) HTTP providers — only if you turn on **Settings → Dev → Enable Chat (beta)** |
 
 **Recommended AI path:** Open a workspace folder and use **Sessions** with OpenCode. Do not start with Chat (beta) unless you already need an OpenAI-compatible HTTP lane.
 

docs/architecture.md

@@ -25,7 +25,10 @@ Unit tests are colocated as `*.test.ts` next to source. Run them from `app/` wit
 
 ### Module size conventions (M6)
 
-Production modules should stay **≤500 lines** where practical; **≤600** is acceptable for cohesive UI shells (`+page.svelte`, `SettingsDialog.svelte`). Test files should stay **≤600 lines** and mirror the production module they cover.
+Production modules should stay **≤500 lines** where practical; **≤600** is
+acceptable for cohesive UI shells such as `+page.svelte` and
+`SettingsView.svelte`. Test files should stay **≤600 lines** and mirror the
+production module they cover.
 
 When a file grows past those limits, split along existing domain boundaries and colocate new files next to the parent module:
 
@@ -101,7 +104,7 @@ File open/save flows go through `appState` and services (`fileSystem`, `openFile
 - Threads persist under the app data dir (see [Persistence](#persistence)).
 - Modes: **`ask`** and **`review`** (system prompts in `app/src/lib/ai/modes/builtins.ts`).
 
-HTTP Chat (beta) provider integration is documented in [beta/chat-http-providers.md](./beta/chat-http-providers.md). Workspace agents use OpenCode — see [opencode-integration.md](./opencode-integration.md).
+HTTP Chat (beta) provider integration is documented in [beta/chat-http-providers.md](./beta/chat-http-providers.md). Workspace sessions use OpenCode — see [opencode-integration.md](./opencode-integration.md).
 
 ## State layer
 
@@ -110,7 +113,7 @@ HTTP Chat (beta) provider integration is documented in [beta/chat-http-providers
 Single source of truth for:
 
 - Active context, documents, tabs, editor chrome (zoom, wrap, find/replace)
-- **`AppSettingsState`** (including Connections/HTTP settings and in-memory API key)
+- **`AppSettingsState`** (including HTTP provider settings and in-memory API key)
 - Theme (builtin + custom), recent files
 
 Mutations are methods on the exported store object (e.g. `openDocument`, `setProviderApiKey`, workspace close with dirty prompts).
@@ -199,20 +202,34 @@ Custom commands include `take_pending_opened_paths`, `sync_file_watcher_paths`,
 - Activity rail (notepad / workspaces)
 - Project panel, editor + tab bar, **sessions** sidebar, chat panel
 - Version Control view tab (per workspace; system `git`)
-- Settings dialog, theme pane, console (logs only)
+- Settings view tab, theme pane, console (logs only)
 
-### Settings dialog
+### Settings view
 
 Tab ids and sidebar labels live in **`SETTINGS_TABS`** / `buildSettingsSidebar` (`app/src/lib/services/settingsDialogUi.ts`). Treat that module as the source of truth for tab inventory — do not duplicate the full list here.
 
 High-level layout:
 
 - Top-level: **Editor**, **Shortcuts**, **Appearance**, **Version Control**
-- **Dev** — Chat (beta) master toggle, **Logs**; **Chats** subtree only when `chatHttp.enabled`
-- **Workspaces** — OpenCode (connection, config, providers, MCP, agents, permissions, …)
+- **Dev** — **Enable Chat (beta)** master toggle and **Logs**; **Providers**, **Chat modes**, and **Debug Provider** tabs appear in this section only when `chatHttp.enabled`
+- **Workspaces** — **OpenCode**, **Config**, **Providers**, **MCP servers**, **Agents**, **Permissions**, **Commands**, **Instructions**, and **Debug Provider**
 
 `openSettingsDialog(tab)` resolves the requested tab against the chat-http beta gate — gated tabs redirect to `dev` when the beta is off.
 
+The two **Providers** tabs are distinct: **Settings → Dev → Providers** manages
+HTTP connections for Chat beta, while **Settings → Workspaces → Providers**
+manages OpenCode providers for the active workspace.
+
+#### Settings and context glossary
+
+| Internal id | User-visible term | Location |
+| --- | --- | --- |
+| `chat-http` | Chat (beta) context | Enable at **Settings → Dev → Enable Chat (beta)** |
+| `ws-*` | Workspace context id pattern | Workspace sessions use **Settings → Workspaces → OpenCode** |
+| `connections` | Providers (HTTP) tab | **Settings → Dev → Providers** |
+| `providers` | Providers (OpenCode) tab | **Settings → Workspaces → Providers** |
+| `agents` | Agents (personas/config) tab | **Settings → Workspaces → Agents** |
+
 Routing helpers: `editorRouting.ts` (file vs session vs view tabs), `workspaceAgentSession.ts` (session tab lifecycle).
 
 Editor: CodeMirror via `EditorSurface.svelte` (Svelte 5 runes), language detection in `editorLanguage.ts`, optional minimap via `editor/editorMinimap.ts`.
@@ -231,7 +248,10 @@ Tab bar: `TabBarContextMenu.svelte`, `tabDragController.ts` (reorder / tear-off)
 
 - **Vitest** for TypeScript; tests assert real behavior (persistence codecs, send pipeline, provider adapters).
 - Reset helpers exist for global singletons: `resetChatProvidersForTests`, `resetChatProviderRegistryForTests`, `resetSessionManagerForTests`, etc.
-- Validation suites under `app/src/lib/state/chatM*.validation.test.ts` encode milestone acceptance criteria.
+- Milestone-specific validation suites use the `*.validation.test.ts` suffix and
+  are colocated with the relevant source under `app/src/lib/` (for example,
+  `state/chatM5-2.validation.test.ts` and
+  `services/optimizationsP7.validation.test.ts`).
 
 After structural changes, run `npm test` and `npm run check` from `app/`.
 
@@ -277,8 +297,9 @@ These extend [AGENTS.md](../AGENTS.md) with architecture-specific guidance.
 ### Related docs
 
 - [README.md](./README.md) — docs index (users vs contributors)
-- [opencode-integration.md](./opencode-integration.md) — workspace agents / OpenCode
+- [opencode-integration.md](./opencode-integration.md) — workspace sessions / OpenCode
 - [beta/chat-http-providers.md](./beta/chat-http-providers.md) — HTTP Chat (beta) providers
 - [../README.md](../README.md) — product scope and dev commands
 - [../CONTRIBUTING.md](../CONTRIBUTING.md) — contribution workflow
-- `specs/` — execution plans, [`specs/backlog/`](../specs/backlog/) (deferred items), changelog
+- [`../specs/text-editor-parity-v3/README.md`](../specs/text-editor-parity-v3/README.md) — current public editor roadmap
+- [`../specs/changelog.md`](../specs/changelog.md) — dated implementation history; other local planning material is not part of a clean clone

docs/beta/README.md

@@ -8,15 +8,15 @@ required, and behavior / location may change between releases.
 
 | Feature | Doc | How to enable |
 | --- | --- | --- |
-| **Chat (beta)** — HTTP chat context (`chat-http`) with OpenAI-compatible providers and Debug Provider | [chat-http-providers.md](./chat-http-providers.md) | **Settings → Dev → Enable Chat (beta)** |
+| **Chat (beta)** — HTTP chat context (internal id `chat-http`) with OpenAI-compatible providers and Debug Provider | [chat-http-providers.md](./chat-http-providers.md) | **Settings → Dev → Enable Chat (beta)** |
 
 ## Why these are beta
 
-The product's stable AI story is **workspace agents** powered by
-[OpenCode](../opencode-integration.md). The HTTP chat context (`chat-http`)
-predates that move and is preserved as a beta lane for users who already
-configured an HTTP connection. It is not part of the recommended setup for
-new users; see the [main README](../../README.md) for the current AI story.
+The product's stable AI story is **workspace sessions** powered by
+[OpenCode](../opencode-integration.md). The HTTP chat context (internal id
+`chat-http`) predates that move and is preserved as a beta lane for users who
+already configured an HTTP connection. It is not part of the recommended setup
+for new users; see the [main README](../../README.md) for the current AI story.
 
 ## Reporting issues