Skip to content

πŸ™Œ OpenHands: AI-Driven Development

docs: remove the unwanted specs directory (#18820)

🐾 smolpaws9508e7246825
diff --git a/.agents/skills/frontend-development/references/guide.md b/.agents/skills/frontend-development/references/guide.md
index 9730125298..23d53f86fe 100644
--- a/.agents/skills/frontend-development/references/guide.md
+++ b/.agents/skills/frontend-development/references/guide.md
@@ -29,7 +29,7 @@ Bundled catalog skills use the persisted `enabled_skills` allow-list defaulted f
## Workspace files
-Local Files discovery preferences belong to `misc_settings.app_preferences.workspace_file_discovery`, keyed by working directory on the active backend. `useWorkspaceFileDiscovery` reads the settings cache and saves sparse workspace patches. Preserve default exclusions and the 2,000-file cap when no configuration exists. Fetch one extra result to distinguish truncation from an exact-size list. Cloud keeps its server-side listing contract without these controls. See `specs/workspace-file-discovery.md`.
+Local Files discovery preferences belong to `misc_settings.app_preferences.workspace_file_discovery`, keyed by working directory on the active backend. `useWorkspaceFileDiscovery` reads the settings cache and saves sparse workspace patches. Preserve default exclusions and the 2,000-file cap when no configuration exists. Fetch one extra result to distinguish truncation from an exact-size list. Cloud keeps its server-side listing contract without these controls.
## Caret appearance contracts
@@ -134,7 +134,7 @@ When adding code that needs a new string, decide up front which rule it falls un
- Theme/customization tokens for the embedded shell are exposed as `--oh-*` CSS variables. Override them through `styleOverrides`, `style`, or host CSS targeting `[data-agent-server-ui]`; Tailwind theme tokens in `src/tailwind.css` should continue to reference those variables with `@theme inline` so host apps can restyle the UI without reworking component class names.
- Small form feedback uses the `feedback-error` / `feedback-success` text roles (`--oh-feedback-error` / `--oh-feedback-success`), separately from the general danger/success control palette. Their built-in values must meet 4.5:1 on modal surfaces; host overrides remain owned by the embedding root. See `src/themes/README.md` and the theme contrast tests when migrating raw feedback colors.
- Regression coverage for the CSS isolation work lives in `__tests__/agent-server-ui-providers.test.tsx`, `__tests__/agent-server-ui-style-scope.test.ts`, and the browser-level CSS-isolation test in `tests/e2e/mock-llm/regressions/mock-llm-ui-regressions.spec.ts`.
-- MCP credential selection: `SaveAsSecretToggle` keeps its native checkbox as the semantic control and uses `ToggleSwitchVisual` for the decorative track. Selection uses contrast/surface tokens. Keep both states' labels readable, allow long secret names to wrap with their help control, and preserve visible keyboard focus. See `specs/mcp-secret-selection.md` (MCP-005).
+- MCP credential selection: `SaveAsSecretToggle` keeps its native checkbox as the semantic control and uses `ToggleSwitchVisual` for the decorative track. Selection uses contrast/surface tokens. Keep both states' labels readable, allow long secret names to wrap with their help control, and preserve visible keyboard focus.
- Conversation history is loaded lazily, REST-first then WebSocket:
- `useConversationHistory` (in `src/hooks/query/use-conversation-history.ts`) fetches only the most recent `INITIAL_HISTORY_PAGE_SIZE` (default 50) events using `sort_order='TIMESTAMP_DESC'`, then reverses to chronological order. Older pages are paginated in via `useLoadOlderEvents` when the user scrolls near the top of the chat.
@@ -161,7 +161,7 @@ When adding code that needs a new string, decide up front which rule it falls un
- `ManageWorkspacesModal` should require a confirmation step before removing either a saved workspace or a workspace parent; parent removals should mention the child-workspace impact, and tests should assert both the confirmation flow and that removing the selected workspace clears the launch selection.
- In `useWorkspacesStore`, keep `clearWorkspaces()` scoped to literal workspaces only; use explicit helpers like `clearWorkspaceParents()` / `clearAll()` for broader resets so future callers do not accidentally wipe parent registrations.
-- Default LLM model β€” `DEFAULT_SETTINGS.llm_model` (`"openhands/glm-5.2"`, defined in `src/services/settings.ts`) is the canonical frontend default. `buildConfiguredOpenHandsAgentSettings` in `src/api/agent-server-adapter.ts` **always** sends this value explicitly when the resolved `llm.model` is absent, empty, or whitespace-only β€” the frontend never relies on the agent-server SDK's own default (`gpt-5.5`). If you change the default model, update `DEFAULT_SETTINGS.llm_model` in `src/services/settings.ts` **and** the checklist in `specs/llm-defaults.md`. Spec: `@spec LLD-001`.
+- Default LLM model β€” `DEFAULT_SETTINGS.llm_model` (`"openhands/glm-5.2"`, defined in `src/services/settings.ts`) is the canonical frontend default. `buildConfiguredOpenHandsAgentSettings` in `src/api/agent-server-adapter.ts` **always** sends this value explicitly when the resolved `llm.model` is absent, empty, or whitespace-only β€” the frontend never relies on the agent-server SDK's own default (`gpt-5.5`). If you change the default model, update `DEFAULT_SETTINGS.llm_model` in `src/services/settings.ts`.
- Custom secrets are NOT auto-attached by the agent-server. `POST /api/conversations` only persists what the client sends in `request.secrets`; the persisted secrets store (`/api/settings/secrets`) is never read at conversation start. `buildStartConversationRequestWithEncryptedSettings` enumerates `SecretsService.getSecrets()` and turns each entry into a `LookupSecret` whose `url` points back at `/api/settings/secrets/{name}` and whose `headers` carry `X-Session-API-Key` for auth.
diff --git a/.agents/skills/local-stack-runtime/SKILL.md b/.agents/skills/local-stack-runtime/SKILL.md
index d1720e1b45..8f8b4574db 100644
--- a/.agents/skills/local-stack-runtime/SKILL.md
+++ b/.agents/skills/local-stack-runtime/SKILL.md
@@ -18,4 +18,4 @@ Maintain the shared configuration and launch plumbing across Vite/static develop
## Reference
-- **`references/guide.md`** β€” Runtime-services schema and prompt plumbing, launcher environment variables, ingress routes, version synchronization, security, Docker build architecture, README synchronization, and spec-tag conventions.
+- **`references/guide.md`** β€” Runtime-services schema and prompt plumbing, launcher environment variables, ingress routes, version synchronization, security, Docker build architecture, and README synchronization.
diff --git a/.agents/skills/local-stack-runtime/references/guide.md b/.agents/skills/local-stack-runtime/references/guide.md
index ee9950ac29..0ff6d95dbd 100644
--- a/.agents/skills/local-stack-runtime/references/guide.md
+++ b/.agents/skills/local-stack-runtime/references/guide.md
@@ -124,5 +124,3 @@ you are running inside of β€” NOT the automation backend.
- Dockerfile ARG defaults are kept as fallbacks for local `docker build` without the CI workflow; CI always passes `--build-arg` overrides from the JSON.
- To bump a version, edit `config/defaults.json` only β€” the JS scripts, Docker build, and CI workflow all derive their values from it.
- Docker all-in-one image: `.github/workflows/docker.yml` builds and publishes `ghcr.io/openhands/agent-canvas` β€” a combined image that bundles the agent-server (from `ghcr.io/openhands/agent-server`), the automation server (`openhands-automation` via pip), and the agent-canvas frontend (static build). The Dockerfile lives at `docker/Dockerfile`, the entrypoint at `docker/entrypoint.sh`. The workflow structure mirrors the SDK repo's `server.yml`: a `build-and-push-image` matrix job (2 Γ— arch: amd64 on `ubuntu-24.04`, arm64 on `ubuntu-24.04-arm`) pushes arch-suffixed tags, then `merge-manifests` creates multi-arch manifests via `docker buildx imagetools create`, then `consolidate-build-info` aggregates artifacts, and `update-pr-description` updates the PR body (using `<!-- AGENT_CANVAS_DOCKER_START -->` / `<!-- AGENT_CANVAS_DOCKER_END -->` markers). The workflow triggers on push to main, `v*` tags (releases), PRs, and `workflow_dispatch`. On release tags it also pushes semver tags (e.g. `1.2.3`, `1.2`, `1`, `latest`). Fork PRs are skipped (no GHCR auth). On PRs that link an `OpenHands/software-agent-sdk` PR in the description, the Docker workflow uses that SDK PR's published branch image (`ghcr.io/openhands/agent-server:<branch-with-slashes-as-dashes>-python`) as the agent-server base image unless a `workflow_dispatch` input explicitly overrides it. The image exposes port 8000 as a unified entry point: `/api/automation/*` β†’ automation (:18001), `/api/*` β†’ agent-server (:18000), `/*` β†’ static frontend. The Dockerfile accepts the public `VITE_POSTHOG_API_KEY` build arg; CI passes staging for PR/main images and production for tagged releases. The npm release workflow passes the same production key to both the app and library builds. The entrypoint auto-generates **both** the session API key and `OH_SECRET_KEY` (persisted to `~/.openhands/agent-canvas/session-api-key.txt` and `secret-key.txt` respectively) when none is provided, so the image runs secure by default. Users can override either via env var (`OH_SECRET_KEY`, `SESSION_API_KEY` / `OH_SESSION_API_KEYS_0`). `scripts/dev-safe.mjs` uses the same `secret-key.txt` file, so dev mode and Docker share the same key when both use the same `~/.openhands` directory.
-
-- Spec files live under `specs/`. Spec IDs are stable β€” never renumber. Mark deprecated specs with ~~strikethrough~~. Tag implementation code and tests with `// @spec BM-002 β€” Short title` comments so specs are grep-able across the codebase (`grep -rn '@spec BM-' src/ __tests__/`). Place the comment on the line immediately above the relevant code block or test. When multiple tests cover the same spec, use `it.each` if the test structure is identical.
diff --git a/.agents/skills/verify-openhands/references/feature-map/F25-backends-and-cloud.md b/.agents/skills/verify-openhands/references/feature-map/F25-backends-and-cloud.md
index 32cffee49b..6801110e9b 100644
--- a/.agents/skills/verify-openhands/references/feature-map/F25-backends-and-cloud.md
+++ b/.agents/skills/verify-openhands/references/feature-map/F25-backends-and-cloud.md
@@ -17,7 +17,7 @@ token and turns a Managed Agents session into a backend.
Everything except the Cloud and DigitalOcean accounts themselves can be driven
locally with a second `control-openhands` stack as the extra backend.
-Source: `src/components/features/backends/`, `src/contexts/active-backend-context.tsx`, `src/api/backend-registry/`, `src/hooks/query/use-backends-health.ts`, `src/routes/device-verify.tsx`, `src/routes/shared-conversation.tsx`, `src/components/features/conversation/conversation-name-context-menu.tsx`, `src/api/cloud/`, `src/api/mars/`, `src/hooks/use-mars-*.ts`, `src/hooks/use-connect-mars-session.ts`, `src/hooks/use-launch-mars-session.ts`, `src/hooks/query/use-mars-agents.ts`, `src/components/features/sidebar/mars-session-panel.tsx`, `src/assets/branding/digitalocean-logo.svg`, `scripts/mars-web-bridge.mjs`, `scripts/mars-tunnel-bridge.mjs`, `specs/backend-management.md`.
+Source: `src/components/features/backends/`, `src/contexts/active-backend-context.tsx`, `src/api/backend-registry/`, `src/hooks/query/use-backends-health.ts`, `src/routes/device-verify.tsx`, `src/routes/shared-conversation.tsx`, `src/components/features/conversation/conversation-name-context-menu.tsx`, `src/api/cloud/`, `src/api/mars/`, `src/hooks/use-mars-*.ts`, `src/hooks/use-connect-mars-session.ts`, `src/hooks/use-launch-mars-session.ts`, `src/hooks/query/use-mars-agents.ts`, `src/components/features/sidebar/mars-session-panel.tsx`, `src/assets/branding/digitalocean-logo.svg`, `scripts/mars-web-bridge.mjs`, `scripts/mars-tunnel-bridge.mjs`.
## Sub-features
diff --git a/.agents/skills/verify-openhands/references/mapping.md b/.agents/skills/verify-openhands/references/mapping.md
index 3f5a80a49c..66ba7c0c44 100644
--- a/.agents/skills/verify-openhands/references/mapping.md
+++ b/.agents/skills/verify-openhands/references/mapping.md
@@ -47,7 +47,7 @@ candidate. Sources, roughly in order of yield:
6. **Backends and modes**: local vs Cloud backend, public vs local auth, ACP
agents, partial stacks (`agent-canvas --help`), Electron, Docker, and the
embeddable library (`src/index.ts` / `build:lib`).
-7. **Docs, specs and tests**: `README.md`, `docs/*.md`, `specs/*.md` describe
+7. **Docs and tests**: `README.md`, `docs/*.md` describe
intended behavior. The Playwright suites under `tests/e2e/` (mock-LLM, live,
bind-policy, live-acp) assert behaviors a user sees too: read them for
selectors and for behaviors the map lacks, then map those behaviors as
diff --git a/AGENTS.md b/AGENTS.md
index 119dce3b9b..6622369d24 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -86,10 +86,8 @@ Create TDD tests for behavioral changes. Keep tests focused on user behavior and
Use the `e2e-testing` skill for suite selection and E2E-specific requirements.
-## Specifications and Releases
+## Releases
-- Spec files live under `specs/`. Keep spec IDs stable and mark deprecated specs with strikethrough rather than renumbering them.
-- Tag implementation code and tests with `// @spec BM-002 β€” Short title` comments immediately above the relevant block so coverage remains grep-able.
- Follow `.agents/skills/release.md` for release automation. Never hand-edit a release-please branch.
## DigitalOcean Managed Agents
diff --git a/docs/CANVAS_EXTENSIONS_TESTING.md b/docs/CANVAS_EXTENSIONS_TESTING.md
index 8f9030f19e..06b45c5c3d 100644
--- a/docs/CANVAS_EXTENSIONS_TESTING.md
+++ b/docs/CANVAS_EXTENSIONS_TESTING.md
@@ -89,6 +89,3 @@ contract lands. That test must additionally verify:
- persistence across Agent Server and browser restarts;
- session-authenticated bundle delivery;
- isolation when switching between active backends.
-
-The backend contract and acceptance criteria are documented in
-[`specs/canvas-extensions.md`](../specs/canvas-extensions.md).
diff --git a/specs/backend-management.md b/specs/backend-management.md
deleted file mode 100644
index 8c18705ea5..0000000000
--- a/specs/backend-management.md
+++ /dev/null
@@ -1,15 +0,0 @@
-# Backend Management Specs
-
----
-
-### BM-001: Auto-switch on connect
-- [x] Adding a backend shall automatically switch the active selection to it.
-
-### BM-002: Switching backends keeps the user on the same page
-- [x] Switching backends shall redirect to the same section but on the new backend. The user shall never see stale data from the previous backend.
-
-### BM-003: Fallback on active backend removal
-- [x] Removing the currently active backend shall fall back to a remaining local backend. The user shall never be left without an active backend.
-
-### BM-004: Theme-aware connection feedback
-- [x] Connection errors, disabled-backend diagnostics, and connected/disconnected status text shall use the host-overridable feedback roles in all five themes. Small feedback text shall remain readable on its actual surface, including tinted error panels.
diff --git a/specs/canvas-extensions.md b/specs/canvas-extensions.md
deleted file mode 100644
index 145b9e46ed..0000000000
--- a/specs/canvas-extensions.md
+++ /dev/null
@@ -1,321 +0,0 @@
-# Canvas Extensions
-
-## Status
-
-Implementation plan and v1 contract. The frontend vertical slice may ship behind
-Agent Server capability detection while the backend endpoints are implemented.
-
-## Product definition
-
-Canvas Extensions are installable packages that change Agent Canvas itself.
-They contribute UI and local product behavior such as routed pages, conversation
-panels, renderers, slots, and themes. Skills and plugins change the agent;
-Canvas Extensions change the app.
-
-The Customize area remains the single inventory for Skills, Plugins, MCP, and
-Canvas Extensions. The UI calls Canvas Extensions **Apps**: the inventory item is
-**Customize > Apps** at `/apps`, installed with **Add app**; "addon" is an
-informal alias only.
-
-## Decisions
-
-1. **The active Agent Server owns extensions.** An extension is installed on the
- computer or container running the Agent Server. Its source, resolved revision,
- files, manifest, and enabled state live there. Canvas only discovers and loads
- extensions from the currently active backend. Switching backends replaces the
- active extension set.
-2. **Extension code is trusted, same-realm code.** There is no iframe, worker
- sandbox, or granular permission system. Once enabled, an extension has the
- same ambient browser authority as Canvas code. Shadow DOM may be offered later
- as optional style isolation, but never as a security boundary.
-3. **Install and enable are separate.** Installation always produces a disabled
- extension. An agent may install or update an extension, but the user returns
- to Customize > Apps and explicitly enables it. In v1 this is a product
- consent invariant, not proof of human presence against an agent that can call
- the same authenticated APIs. A future backend policy may allow agent-driven
- enablement.
-4. **Enablement is hot.** Enabling loads and activates the extension without an
- app or Agent Server restart. Disabling unmounts registered surfaces and calls
- lifecycle cleanup. Because code is trusted same-realm JavaScript, cleanup is
- best-effort; an extension can create global effects the host cannot revoke.
-5. **Distribution follows plugins, not their runtime.** Install coordinates are
- `source`, optional `ref`, and optional `repo_path`, resolved and pinned by the
- Agent Server. A repository may contain multiple extensions and other artifact
- types under subpaths. Backend-local paths are interpreted on the backend
- machine, never in the frontend process.
-6. **Updates preserve enablement.** Refresh resolves and installs a new revision
- atomically and keeps the prior enabled state. The UI shows the resulting
- resolved revision. Since v1 is a trusted-code model, there is no misleading
- permission-diff approval gate. The staged check/apply flow currently exists
- only at the Agent Server service layer; until it is exposed over HTTP, the
- app card's **Update** action re-installs from the recorded source, ref, and
- path with `force: true`, and the Agent Server keeps the enabled state.
-
-## Trust disclosure
-
-Before enabling, Canvas says plainly that the extension can access and modify the
-Canvas page and can make authenticated requests available to the current browser
-session. The review screen shows source, requested ref, resolved revision,
-manifest metadata, and contributed surfaces. It does not show fictitious
-fine-grained permissions.
-
-Install and update are still meaningful trust actions because they select the
-code revision stored by the backend. Enable is the explicit point at which Canvas
-executes that code.
-
-## Package contract
-
-The manifest filename is `canvas-extension.json`.
-
-```json
-{
- "schema_version": 1,
- "name": "example-dashboard",
- "display_name": "Example dashboard",
- "version": "0.1.0",
- "description": "A backend-specific project dashboard.",
- "entrypoint": "dist/extension.js",
- "contributes": {
- "pages": [
- {
- "id": "dashboard",
- "title": "Dashboard",
- "path": "/dashboard",
- "nav_label": "Dashboard"
- }
- ]
- }
-}
-```
-
-Rules for v1:
-
-- `name` and contribution IDs use lowercase letters, digits, and hyphens.
-- Page `path` values are absolute kebab-case routes (leading `/`); Canvas
- mounts them relative to `/extensions/{name}`.
-- `entrypoint` is a path inside the installed package.
-- The entrypoint is one self-contained browser ESM bundle. It must not contain
- unresolved bare imports or external chunks; dependencies, CSS, and small
- assets are bundled or embedded by the authoring template.
-- The backend validates that the manifest, entrypoint, and any future asset path
- remain inside the installed extension root.
-- Host compatibility fields will be added before marketplace distribution. The
- initial schema is intentionally small while the page ABI is proven by a
- separately built sample extension.
-
-The v1 module exports `activate`:
-
-```ts
-export function activate(host: CanvasExtensionHost): void | (() => void) {
- return host.registerPage("dashboard", ({ container, path, navigate }) => {
- container.textContent = `Extension route: ${path}`;
- return () => container.replaceChildren();
- });
-}
-```
-
-`CanvasExtensionHost` is versioned independently from the manifest. The first
-host API contains:
-
-- `apiVersion: "1"`
-- immutable extension/backend metadata
-- `registerPage(id, mount)` for page factories declared by the manifest
-- `navigate(path)` using Canvas base-path-aware routing
-- `agentServer.request(...)`, an authenticated request helper targeting the
- extension's owning backend
-
-The runtime fetches the bundle as authenticated text and imports it through a
-temporary Blob URL. A direct `<script src>` or `import(backendUrl)` cannot carry
-`X-Session-API-Key`, so it is not the v1 loading path. Importing the bundle does
-not activate it; Canvas calls `activate` only for an enabled installation.
-
-### Optional app backend views
-
-Schema 1 routed pages may embed an app-owned HTTP UI through the optional
-`host.appBackendView` helper. The helper is present only when all parts of the
-Agent Server bridge contract are available:
-
-- `/server_info.capabilities` contains `canvas_app_backend_bridge_v1`;
-- `/server_info.app_backend_ingress_url` is a valid HTTP(S) URL; and
-- the installed `@openhands/typescript-client` exports
- `CanvasExtensionsClient.createAppBackendSession()` and
- `revokeAppBackendSession()`.
-
-Extensions call `host.appBackendView.mount({ container })`; they never receive
-an Agent Server session key, inspect local storage, construct an ingress origin,
-or derive one from `window.location`. Canvas requests a short-lived session from
-the discovered ingress, validates that the returned URL has the same origin,
-and renders it in an iframe using only the server-provided allowlisted sandbox
-tokens. `allow-same-origin` is required so authenticated fetch, WebSocket, and
-Worker APIs retain the app ingress origin and partitioned session cookie; the
-separate ingress origin is the authority boundary. Top-navigation, downloads,
-and storage-access tokens remain rejected. The host owns loading, safe errors,
-retry, a validated new-tab fallback, session revocation, and disposal on page
-unmount or backend switch.
-
-This remains additive to schema 1. Self-contained ESM loading, routed page
-registration, and the native editor are unchanged. There is no generic runtime,
-VS Code app, arbitrary URL proxy, mandatory sidecar, or frontend tarball loader.
-
-The pinned `@openhands/typescript-client` `1.53.0` ships the bridge API
-(first defined in draft `OpenHands/software-agent-sdk#5272`), so the client
-export requirement above is satisfied by a released client. The helper is
-feature-detected at runtime on the live Agent Server: `server_info.capabilities`
-must advertise `canvas_app_backend_bridge_v1` and `app_backend_ingress_url`
-must be a valid HTTP(S) URL. Canvas requires Agent Server `1.51.0` or newer,
-which is above the first release exposing this bridge contract.
-
-## Agent Server API
-
-The API deliberately mirrors plugin distribution management while remaining a
-separate runtime:
-
-| Method | Path | Purpose |
-| -------- | ------------------------------------------------ | --------------------------------------------------------- |
-| `GET` | `/api/canvas-extensions/installed` | List installed extensions and parsed manifests |
-| `POST` | `/api/canvas-extensions/install` | Install from git or a backend-local path; always disabled |
-| `GET` | `/api/canvas-extensions/installed/{name}` | Read one installation |
-| `PATCH` | `/api/canvas-extensions/installed/{name}` | Set enabled state |
-| `DELETE` | `/api/canvas-extensions/installed/{name}` | Uninstall |
-| `GET` | `/api/canvas-extensions/installed/{name}/bundle` | Return the entrypoint as JavaScript text |
-
-A refresh endpoint (`POST /api/canvas-extensions/installed/{name}/refresh`) is
-planned but not part of the current router; the service-layer staged check/apply
-flow backs it and is tracked separately.
-
-The list endpoint wraps its results in a `canvas_extensions` array.
-
-Install request:
-
-```json
-{
- "source": "github:owner/repository",
- "ref": "main",
- "repo_path": "extensions/example-dashboard",
- "force": false
-}
-```
-
-Installed response:
-
-```json
-{
- "name": "example-dashboard",
- "version": "0.1.0",
- "description": "A backend-specific project dashboard.",
- "enabled": false,
- "source": "github:owner/repository",
- "resolved_ref": "6f5f9a...",
- "repo_path": "extensions/example-dashboard",
- "installed_at": "2026-08-01T12:00:00Z",
- "install_path": "/home/user/.openhands/canvas-extensions/installed/example-dashboard",
- "manifest": {}
-}
-```
-
-The `manifest` field (parsed `canvas-extension.json`, including
-`contributes.pages`) is not returned by the current router yet; until it ships,
-Canvas treats it as optional and renders installations without page
-contributions or a display name.
-
-The backend must prevent install requests from setting `enabled: true`. The
-frontend's enable control calls the patch endpoint. Backend authorization and
-multi-user installation scope follow the Agent Server deployment's existing
-session trust model; v1 does not introduce a separate approval credential.
-
-Until the API exists, Canvas treats HTTP 404 as "this backend does not support
-Canvas Extensions". Customize shows an upgrade message, while the global runtime
-stays silent. It must not collapse unsupported, unreachable, and an empty
-inventory into the same state.
-
-## Frontend runtime
-
-The runtime is keyed by backend ID, organization scope, and connection revision.
-This prevents an enabled bundle or cached inventory from one backend appearing
-on another after a switch or reconnect.
-
-For each enabled installation:
-
-1. Fetch the authenticated entrypoint text from the owning backend.
-2. Import the self-contained ESM bundle from a Blob URL.
-3. Validate `activate` and its host API version.
-4. Create an extension-scoped registry and call `activate`.
-5. Admit registrations only when their IDs were declared in the manifest.
-6. Render each surface inside an error boundary owned by Canvas.
-7. On disable, uninstall, update, or backend switch, unmount every surface,
- invoke the extension disposer, and remove its registry entries.
-
-The initial route shape is
-`/extensions/{extension-name}/{declared-page-path}`. The Customize inventory is
-`/apps`; there is no bare `/extensions` page. All routing goes through React
-Router so `VITE_BASE_PATH` continues to work.
-
-## Delivery plan
-
-### Slice 1: contract and management
-
-- Land this spec and shared TypeScript manifest/installation types.
-- Add a backend-keyed service and query hooks for list, install, enable/disable,
- uninstall, and authenticated bundle fetch.
-- Add Customize > Apps with an unsupported-backend state, source install
- form, source/revision/contribution review, and explicit enable control.
-- Keep the global runtime silent when the active backend returns 404.
-
-### Slice 2: routed page proof
-
-- Add the versioned host API, module loader, lifecycle registry, and error
- boundary.
-- Add dynamic page routes and left-rail navigation for enabled page
- contributions.
-- Build a standalone fixture extension with the same scaffold authors will use.
-- Verify enable, hot activation, navigation, disable cleanup, update, backend
- switching, session-key-authenticated bundle loading, and `VITE_BASE_PATH`.
-
-### Slice 3: theme proof
-
-- Define a code-free theme contribution with a strict Canvas token schema.
-- Validate theme manifests on the backend and surface installed themes in
- Settings.
-- Keep theme selection browser/user scoped while availability follows the active
- backend; fall back cleanly when switching away from the providing backend.
-
-### Slice 4: conversation surfaces
-
-- Replace the closed conversation tab union with namespaced runtime IDs and
- centralized persistence admission.
-- Add extension tabs/panels, then host-owned header/footer/badge slots.
-- Define mobile behavior, ordering, conflicts, missing-extension fallback, and
- per-conversation lifecycle context before opening each surface to authors.
-
-### Slice 5: visualizers and authoring loop
-
-- Add augment/replace visualizer registrations with explicit event matching,
- precedence, and built-in fallback.
-- Publish the stable extension SDK types, bundler template, validation command,
- and sample repository.
-- Only then ship `/build-canvas-extension`, including backend-local versus remote
- workspace guidance, temporary install, manual enable instructions, and git
- publication/update flow.
-
-## Verification
-
-Each slice adds service and runtime unit tests. The routed page slice also adds a
-mock-LLM end-to-end spec (`tests/e2e/mock-llm/canvas-extensions/`) that drives
-the production build through install β†’ enable β†’ page render β†’ disable β†’
-uninstall. Until the pinned agent-server ships the endpoints, the spec serves
-the API contract from `src/fixtures/canvas-extensions/demo-page` through
-Playwright route interception; once it does, the stub is removed and the same
-steps run against the real backend.
-Changing the mock-LLM feature layout or mapping requires updating
-`.agents/skills/e2e-testing/references/guide.md` in the same change. Before merge,
-run `npm run lint`, `npm test`, `npm run build`, and `npm run build:lib`.
-
-## Explicit non-goals for v1
-
-- iframe/worker isolation or enforceable fine-grained permissions
-- arbitrary lifecycle scripts during installation
-- automatic enablement by agents
-- marketplace ranking or publisher signing
-- conversation tabs, slots, or visualizer replacement in the first vertical
- slice
-- treating `@openhands/extensions` as an installable runtime format
diff --git a/specs/form-feedback.md b/specs/form-feedback.md
deleted file mode 100644
index 0627ac6412..0000000000
--- a/specs/form-feedback.md
+++ /dev/null
@@ -1,4 +0,0 @@
-# Form feedback theme contract
-
-### FF-001: Theme-aware validation and load errors
-- [x] Form validation, profile load failures, missing-model guidance, and inline service errors shall use the host-overridable feedback-error text role. Invalid manifest control borders shall use semantic danger. Preserve messages, ARIA state, validation, retries, save behavior, and transport contracts; small error text must remain readable in all five themes.
diff --git a/specs/home-launcher.md b/specs/home-launcher.md
deleted file mode 100644
index 0147c7a051..0000000000
--- a/specs/home-launcher.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# Home launcher specs
-
-### HL-001: Readable Code/Automate mode toggle
-
-- [x] The selected mode label, and an unselected label while hovered, shall use the `contrast` high-emphasis ink on the `--oh-interactive-hover` pill. The built-in palettes keep that pairing at 4.5:1 or better: white in dark palettes, dark ink in Light+ and Solarized Light. Embedding roots may override `--oh-contrast`, and the toggle follows the nearest `[data-agent-server-ui]` scope. Mode selection, keyboard and radio semantics, and the pill animation are unchanged.
-
-### HL-002: Dismissible Recommended automations rail
-
-- [x] Home's Recommended automations rail shall show an X named "Hide Recommended automations" in its header. On fine-pointer devices the X appears while the rail is hovered or holds keyboard focus; on touch and coarse-pointer devices it is always visible.
-- [x] Clicking the X shall remove the whole rail from Home at once (heading, cards and bottom inset) and turn **Show Recommended automations** in Application settings off without a reload. Turning that switch back on shall restore the rail on the next Home render.
-- [x] The X and the switch shall share one browser-scoped preference that defaults to shown and survives a reload. The rails in the automations empty state and the onboarding say-hello step shall never show the X and shall ignore the preference.
diff --git a/specs/llm-defaults.md b/specs/llm-defaults.md
deleted file mode 100644
index ac520d02e6..0000000000
--- a/specs/llm-defaults.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# LLM Defaults Specs
-
----
-
-### LLD-001: Frontend always sends its chosen default model
-
-- [x] When the agent-server returns an absent or empty `llm.model` (e.g. because the user has never saved settings), the frontend adapter shall substitute `DEFAULT_SETTINGS.llm_model` (`"openai/gpt-5.6-sol"`) before sending a conversation-start request that carries a raw agent spec (the local planner). Agent Profile launches take the model from the referenced LLM profile.
-- [x] The frontend shall never rely on the agent-server SDK's own default model (`gpt-5.5`); it shall always send an explicit model value.
-- [x] Whitespace-only model strings shall be treated as absent and fall back to the default.
-- [x] The same guard applies when LLM settings arrive via `encryptedAgentSettings` (the planner's encrypted payload path).
diff --git a/specs/mcp-secret-selection.md b/specs/mcp-secret-selection.md
deleted file mode 100644
index c9b5e29b11..0000000000
--- a/specs/mcp-secret-selection.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# MCP credential selection
-
-### MCP-005: Credential selection stays readable in every theme
-
-- [x] The catalog's **Also save as secret** row follows the active palette,
- with readable labels and secret names in both checked and unchecked states.
-- [x] The selected switch uses Canvas's shared toggle appearance; color alone
- does not communicate the checkbox state.
-- [x] Long secret names and the help control remain inside the row on phones.
-- [x] Label clicks and Space operate the native checkbox. Keyboard focus is
- visible, and opening help does not change the selection.
diff --git a/specs/mcp-settings.md b/specs/mcp-settings.md
deleted file mode 100644
index c199ae9f48..0000000000
--- a/specs/mcp-settings.md
+++ /dev/null
@@ -1,53 +0,0 @@
-# MCP Settings Specs
-
----
-
-### MCP-001: Sparse mutations preserve sibling servers
-
-- [x] Adding, updating, or deleting an MCP server shall issue exactly one
- dedicated MCP settings request containing only the affected server.
- On a cloud backend, an add or update first reads the stored catalog and
- writes it back in full, because the cloud replaces the whole catalog for
- an `mcp_config` map without `null` entries (OHE-3248).
-- [x] An MCP mutation shall never use redacted or encrypted settings snapshots
- as its mutation base. On a cloud backend, untouched sibling servers are
- resent verbatim from the redacted settings read (the cloud restores their
- secrets by key); redacted values are still never used as input for the
- mutated server.
-- [x] Untouched sibling servers and credentials shall survive add, update,
- delete, concurrent different-key updates, and failed mutations.
-
-### MCP-002: Secret patches preserve user intent
-
-- [x] Omitting an unchanged secret shall preserve its stored value.
-- [x] Supplying a secret shall replace its stored value.
-- [x] Explicitly clearing a supported secret field shall send `null`.
-- [x] The display-only redaction sentinel shall never be sent as mutation data.
-
-### MCP-003: Settings map keys are stable MCP identities
-
-- [x] Rendering order and transport grouping shall not change persistence
- identity.
-- [x] Deletion shall address the settings map key without matching URL, command,
- or arguments.
-- [x] Rename shall use one atomic map patch, reject collisions, and reject
- hidden-secret renames that could lose credentials.
-
-### MCP-004: Form feedback follows readable theme text roles
-
-- [x] Custom-server validation and connection feedback, and catalog-install
- errors, use the selected theme's error/success text roles.
-- [x] Both text roles meet 4.5:1 against the modal surface in every built-in
- palette, independently of the danger/success control colors.
-- [x] Embedded host overrides for those roles survive palette changes.
-
-### MCP-006: Library installs never dead-end
-
-- [x] An entry keeps its preferred installable option, such as an API-key
- fallback, when one exists.
-- [x] When an entry's only remote option is OAuth, including an option that
- names provider OAuth endpoints, Install connects through the MCP server's
- own OAuth discovery. The catalog's provider endpoints, scopes and client
- authentication are not sent.
-- [x] When no option can be installed, the dialog says so and Install is
- disabled. Install never does nothing silently.
diff --git a/specs/settings-switches.md b/specs/settings-switches.md
deleted file mode 100644
index 67965ccf66..0000000000
--- a/specs/settings-switches.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# Settings switch contracts
-
-### SSW-001: Settings switches expose native checkbox interaction
-
-- [x] Enabled settings switches participate in Tab order and expose their
- label and checked state through the native checkbox accessibility role.
-- [x] Space and label clicks toggle the same value. Keyboard focus is visible
- on the displayed control and label.
-- [x] Disabled switches remain disabled, are skipped by Tab, and preserve their
- controlled checked state. Toggle position does not change these behaviors.
diff --git a/specs/toast-notifications.md b/specs/toast-notifications.md
deleted file mode 100644
index 08da72dff0..0000000000
--- a/specs/toast-notifications.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# Toast notification specs
-
-### TN-001: Readable toast text in every theme
-
-- [x] Success, warning, loading and error toasts shall draw their text in the `contrast` high-emphasis ink on the `--oh-color-tertiary` toast surface. The built-in palettes keep that pairing at 4.5:1 or better: white in dark palettes, dark ink in Light+ and Solarized Light. Error toasts keep the status-error icon as their error cue. Embedding roots may override `--oh-contrast`, and toasts follow the nearest `[data-agent-server-ui]` scope. Toast copy, icons, placement, duration and links are unchanged.
diff --git a/specs/warning-feedback.md b/specs/warning-feedback.md
deleted file mode 100644
index 41d4c3c483..0000000000
--- a/specs/warning-feedback.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# WN-001 β€” Readable warning feedback
-
-**Spec ID:** WN-001
-**Status:** Implemented
-
-Small warning text and warning icons use the `feedback-warning` text role, backed by `--oh-feedback-warning`. The built-in role meets 4.5:1 on the theme surfaces used by the Home no-LLM banner, Canvas Apps trust notice, ACP conflict messages, and required-secret onboarding warning. Light+ and Solarized Light use darker text shades while retaining the existing brand warning color for controls and tint.
-
-Embedding roots may override the role. The UI follows the nearest `[data-agent-server-ui]` scope. Changing the role does not change warning copy, validation, routing, credential state, or trust controls.
-
-Real browser coverage verifies the Home icon and Apps trust notice follow the host override. The theme contract checks every built-in palette.
diff --git a/specs/workspace-file-discovery.md b/specs/workspace-file-discovery.md
deleted file mode 100644
index cc427d8bf9..0000000000
--- a/specs/workspace-file-discovery.md
+++ /dev/null
@@ -1,20 +0,0 @@
-# Workspace File Discovery
-
-### WFD-001: Configurable local workspace discovery
-
-- With no saved configuration, list at most 2,000 regular files using the existing directory exclusions.
-- Users can replace directory exclusions with name or workspace-relative path patterns. `*/bin` excludes nested `bin` directories while preserving root `bin`.
-- Quote every configured pattern as shell data. Patterns cannot execute commands.
-- A zero file limit means unlimited. A positive integer bounds the returned paths.
-- Optional symlink inclusion lists links to regular files without traversing directory links.
-- Read one extra path for a finite limit. Show an incomplete-tree message only when more paths exist than the configured limit.
-- Cloud file listing keeps its existing request and behavior.
-
-### WFD-002: Workspace-scoped server persistence
-
-- The local backend owns `misc_settings.app_preferences.workspace_file_discovery`, keyed by working directory.
-- Save a sparse map containing only the edited workspace so other workspace preferences survive the server's deep merge.
-- Conversations sharing a workspace use its configuration. A different workspace or backend uses its own configuration or defaults.
-- Saved preferences survive reload. Missing or invalid values fall back to conservative defaults.
-- Reset prepares the defaults for Save; Cancel discards the form draft. Failed saves keep the dialog open with an error.
-- Switching workspace or backend discards the open editor. Cloud never displays the editor or saves these settings.
diff --git a/specs/workspace-upload-path.md b/specs/workspace-upload-path.md
deleted file mode 100644
index ebcf480d09..0000000000
--- a/specs/workspace-upload-path.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# Workspace Upload Path Specs
-
----
-
-### WUP-001: Relative working dirs are resolved against `/api/file/home`, not the filesystem root
-- [x] When the frontend creates a conversation and the resolved working dir is **relative** (e.g. the `DEFAULT_WORKING_DIR = "workspace/project"` fallback), `AgentServerConversationService.createConversation` shall resolve it to an **absolute** path before sending `workspace.working_dir` to the agent-server, by prefixing the agent-server's home directory as returned by `GET /api/file/home`.
-- [x] When the frontend uploads a file, `buildWorkspaceUploadPath` shall resolve the conversation's working dir through the same home-directory anchor, so the upload destination always matches the conversation's worktree location.
-- [x] When the working dir is already absolute (e.g. POSIX `/foo`, Windows `C:\foo`, or the explicit selection from `search_subdirs`), the resolver shall pass it through unchanged.
-- [x] The home-directory lookup shall be cached per backend host so concurrent uploads share a single in-flight `/api/file/home` request, and a cached value is reused for subsequent uploads.
-- [x] A failed lookup shall not be cached so the next call retries fresh.
-- [x] Upload paths shall never be constructed by naively prepending `/`; the legacy `toAbsoluteWorkspacePath` helper that did so was removed once its last callers disappeared (recoverable from git history), and the home-anchored resolver is the only sanctioned mechanism.
-
-### Why this exists
-- The agent-server's `/api/file/upload` endpoint requires an absolute path and `mkdir -p`s the parent of the destination. Naively prepending `/` to the default `workspace/project/<hex>` produces `/workspace/project/<hex>`. On macOS and on fresh Docker images that mount only `/home/<user>` as writable, the filesystem root is read-only, so the upload fails with `OSError: [Errno 30] Read-only file system: '/workspace'`.
-- The agent-server otherwise interprets a relative `workspace.working_dir` against its process CWD (which is whichever directory the launcher used), so absent this resolver, the conversation's worktree lands in one place and the upload tries to land in a totally different place.
-- `/api/file/home` is the most reliable absolute, writable anchor the agent-server API currently exposes; `/server_info` does not include the CWD.