Sync dev from Fork

.env.example

@@ -1,2 +1,2 @@
-JULES_API_KEY=your_api_key_here
+JULES_API_KEY=<YOUR_JULES_API_KEY>
 DASHBOARD_PORT=4444

AGENTS.md

@@ -28,7 +28,7 @@ Package manager is **pnpm** (`pnpm@10.33.0`), Node **22+**. Use `pnpm`, not `npm
 - `pnpm run typecheck` / `pnpm run lint`: strict `tsc --noEmit` (the two are the same command).
 - `pnpm run test`: full Vitest run. `pnpm run test:backend` / `pnpm run test:dashboard`: scoped suites.
 - `pnpm run test:watch`: watch mode. `pnpm run test:coverage`: coverage with threshold enforcement.
-- `pnpm run ci`: local CI equivalent (`lint` → `test:backend:coverage` → `test:dashboard` → `build`).
+- `pnpm run ci`: local CI equivalent (`quality:guardrails -> audit -> lint -> test:backend:coverage -> test:dashboard -> build`).
 - `pnpm run audit`: `pnpm audit --audit-level=high`.
 - `pnpm start`: run compiled `dist/index.js`. `node dist/index.js --help`: list CLI flags / env vars.
 - Electron: `pnpm run electron:dev`, `pnpm run electron:dist[:linux|:mac|:win]`.
@@ -75,7 +75,7 @@ Package manager is **pnpm** (`pnpm@10.33.0`), Node **22+**. Use `pnpm`, not `npm
   - `dev` is the integration branch. Always create and work from a feature branch off `dev` (never commit directly to `dev` or `main`).
   - Use descriptive branch names such as `feat/<scope>`, `fix/<scope>`, or `chore/<scope>`.
   - Merge changes into `dev` only via pull requests after required CI checks pass (not into `main`).
-  - Push branches to `origin` (`codeux-ai/codeux`) and target it for PRs.
+  - Push branches to `origin` (the `numnx/codeux` fork) and target it for PRs. `upstream` is `codeux-ai/codeux`.
   - Use GitHub CLI (`gh`) for PR workflow when available (for example `gh pr create --base dev`, `gh pr view`, `gh pr merge`).
 - PRs should include:
   - What changed and why.
@@ -165,7 +165,7 @@ Release note rules:
 - Default working flow for our collaboration:
   - Start every change on a new feature branch off `dev`.
   - Implement and validate locally (`pnpm run build` minimum; `pnpm run ci` preferred).
-  - Open a PR into `dev` against `origin` (`codeux-ai/codeux`) using GitHub CLI.
+  - Open a PR into `dev` against `origin` (the `numnx/codeux` fork) using GitHub CLI.
   - Monitor CI continuously after opening the PR.
   - Merge only through PR after all required CI checks pass without errors.
   - Delete merged feature branches to keep the branch list clean.

CLAUDE.md

@@ -33,15 +33,15 @@ pnpm run test:watch     # Vitest watch mode
 pnpm test tests/backend/smoke.test.ts   # Single test file
 pnpm run test:coverage  # Coverage with threshold enforcement
 pnpm run typecheck      # tsc --noEmit (alias: lint — same command)
-pnpm run ci             # lint + test:backend:coverage + test:dashboard + build
+pnpm run ci             # quality:guardrails -> audit -> lint -> test:backend:coverage -> test:dashboard -> build
 pnpm run audit          # pnpm audit --audit-level=high
 ```
 
 Electron: `pnpm run electron:dev`, `pnpm run electron:dist[:linux|:mac|:win]`.
 
 Coverage thresholds (vitest.config.ts, ratchet-only — never lower): lines 77.4%, functions 71.5%,
 branches 66.1%, statements 76.0%. `src/server/activity-cache-service.ts` has a separate 80% line
-gate. CI runs on Node 22: lint → backend coverage → dashboard tests → build.
+gate. CI runs on Node 22: lint -> test:backend:coverage -> test:dashboard -> build.
 
 ## Architecture
 
@@ -152,7 +152,8 @@ In this working environment you have broad latitude to operate the running syste
 
 - Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`). **`dev` is the integration branch** —
   branch off `dev` and open PRs **into `dev`** (not `main`) after CI passes; use `gh` for PR workflow.
-- Remotes: `origin` is `codeux-ai/codeux` — push feature branches there and target it for PRs.
+- Remotes: `origin` is the **`numnx/codeux` fork** — push branches there and target it for PRs.
+  `upstream` is `codeux-ai/codeux`; do not push or PR there unless explicitly asked.
 - 2-space indent, `camelCase` vars/functions, `PascalCase` types/components. Strict typing — avoid
   `any`. No new plain-JS modules. Tailwind is the only styling approach; don't add UI frameworks.
 - Documentation source of truth is `docs/` (entrypoint `docs/index.md`, index `docs/SUMMARY.md`).

GEMINI.md

@@ -118,11 +118,7 @@ All UI work must meet the quality gate in `STYLEGUIDE.md`:
   `vi.spyOn()` for verification.
 
 ### Validation Workflow (`pnpm run ci`)
-Before a task is complete, all of these MUST pass (`ci` = lint → backend coverage → dashboard → build):
-1. `pnpm run lint` (alias of `typecheck`: strict `tsc --noEmit`).
-2. `pnpm run test:backend:coverage`.
-3. `pnpm run test:dashboard`.
-4. `pnpm run build` (server `tsc` + dashboard typecheck + `vite build`).
+Before a task is complete, all of these MUST pass (`ci` = quality:guardrails -> audit -> lint -> test:backend:coverage -> test:dashboard -> build).
 
 - Do not validate changes visually with Browser automation Tools unless explicitly told to
 ---

README.md

@@ -141,7 +141,7 @@ Docker-backed execution provides:
 
 - Hermetic task workspaces and snapshot-based QA reviews.
 - Reusable runtime caches for package managers and provider CLIs.
-- Auth-copy support for provider credentials such as `~/.codex`, `~/.claude`, `~/.gemini`, `~/.qwen`, and OpenCode auth.
+- Isolated credential mounts for provider auth (such as `~/.codex`, `~/.claude`, `~/.gemini`, `~/.qwen`, and OpenCode) rather than broad workspace root exposure.
 - Short-lived execution containers that are cleaned up after runs instead of becoming permanent agent environments.
 - Isolated merge-conflict repair and CI autofix flows.
 - Startup cleanup for stale containers, workspaces, and preview sessions.
@@ -289,6 +289,8 @@ start planning sprint work without rebuilding the same agent setup for every CLI
 
 ## Documentation
 
+Canonical repository documentation lives in the `docs/` directory, while `docs-web/` serves as the sole publication and reference mirror. The use of a `docs-release/` directory is explicitly forbidden.
+
 - [User quickstart](./docs-web/user/quickstart.md)
 - [Installation](./docs-web/user/installation.md)
 - [Providers and models](./docs-web/user/providers-and-models.md)
@@ -329,6 +331,7 @@ Codex, Claude Code, Qwen Code, OpenCode, and Antigravity CLI.
 
 ```bash
 pnpm run dev
+pnpm run dev:server-only
 ```
 
 Then open `http://localhost:4444`.
@@ -343,9 +346,11 @@ pnpm start
 ### Validate locally
 
 ```bash
+pnpm run quality:guardrails
+pnpm run audit
 pnpm run lint
-pnpm run typecheck
-pnpm run test
+pnpm run test:backend:coverage
+pnpm run test:dashboard
 pnpm run build
 ```
 

docs-web/architecture/configuration-resolution.md

@@ -65,10 +65,10 @@ After bootstrap, Code UX loads the settings tree from the database. Three tables
 For any field, the effective value at sprint scope is:
 
 ```
-defaults  →  system  →  project  →  sprint
+system  →  project  →  sprint
 ```
 
-A field unspecified at higher scopes inherits from lower scopes. The merge is **deep** for object-valued fields (e.g. `aiProvider.providers.codex` only overrides the keys you set, not the whole object).
+System settings act as the base (with built-in defaults folded into them). A field unspecified at higher scopes inherits from lower scopes. The merge is **deep** for object-valued fields (e.g. `aiProvider.providers.codex` only overrides the keys you set, not the whole object).
 
 ### Where defaults live
 
@@ -83,7 +83,7 @@ System settings on a fresh install are the merge of these defaults plus any exte
 
 ### Live reload
 
-Settings changes via `manage_code_ux` → `settings` → `patch_*_setting` (or the corresponding REST endpoints) trigger:
+Settings changes via `manage_settings` → `patch_*_setting` (or the corresponding REST endpoints) trigger:
 
 - A WebSocket event broadcasting the change.
 - Hot-reload of the relevant subscribers (e.g. the orchestrator picks up new `watchLoopIntervalSeconds` on the next cycle).
@@ -96,9 +96,9 @@ There is no need to restart the process for settings changes.
 
 - `GET /api/projects/:projectId/settings/effective` — merged at project scope.
 - `GET /api/projects/:projectId/sprints/:sprintId/settings/effective` — merged at sprint scope.
-- `manage_code_ux` → `settings` → `resolve_project_effective` / `resolve_sprint_effective`.
+- `manage_settings` → `resolve_project_effective` / `resolve_sprint_effective`.
 
-These return the full merged tree, useful for debugging "why is this setting taking that value?".
+These endpoints return an `EffectiveSettingsResponse` which includes both the merged tree (`settings`) and field-level provenance metadata (`sources` mapping each path to `system`, `project`, or `sprint`), useful for debugging "why is this setting taking that value?".
 
 ## External hints
 
@@ -132,7 +132,7 @@ The default backend is **SQLite** at `~/.code-ux/database.sqlite`. A migration p
 
 ## Reset semantics
 
-- **Per-project reset** (`reset_project_settings`) clears the project's override row; effective values revert to `system → defaults`.
-- **Per-sprint reset** (`reset_sprint_settings`) clears the sprint's override; effective values revert to `project → system → defaults`.
+- **Per-project reset** (`DELETE /api/projects/:projectId/settings` or `reset_project_settings`) clears the project's override row; effective values revert to `system`.
+- **Per-sprint reset** (`DELETE /api/sprints/:sprintId/settings` or `reset_sprint_settings`) clears the sprint's override; effective values revert to `project → system`.
 - **System reset** (no dedicated action; use `replace_system_settings` with a default tree) requires explicit replacement.
 - **Database reset** (`POST /api/system/reset-database`) wipes everything; use only as a last resort.

docs-web/architecture/dashboard-architecture.md

@@ -77,7 +77,10 @@ const routes = [
   { path: "/live",     component: LiveSessionPage },
   { path: "/chat",     component: ChatPage },
   { path: "/agents",   component: AgentsPage },
+  { path: "/scheduler", component: SchedulerPage },
   { path: "/memory",   component: MemoryPage },
+  { path: "/knowledge", component: KnowledgePage },
+  { path: "/files",    component: FileBrowserPage },
   { path: "/browser",  component: BrowserPage },
   { path: "/stats",    component: StatsPage },
   { path: "/config",   component: SettingsPage },
@@ -98,7 +101,7 @@ State is managed with a mix of:
 - **`@preact/signals`** for global and page-level reactive state.
 - **Custom data hooks** wrapping REST + WebSocket subscriptions:
   - `useDashboardRuntimeData()` — live execution data.
-  - `useRealTimeResource()` — generic WebSocket subscription wrapper.
+  - `useRealtimeResource()` — generic WebSocket subscription wrapper.
   - `useProjectData()` — active project / sprint.
   - `useSprints()`, `usePreviewSessions()`, `useChatPageData()`, `useSettingsPageState()`, `useMemoryPageData()`, `useOverviewPageData()`, `useExecutionTimeline()`, `useProgressiveList()`.
 

docs-web/architecture/data-model.md

@@ -227,7 +227,7 @@ Memories with mismatched `embeddingModelId` are excluded from search; trigger re
 | `id` | string | – |
 | `endpointKey` | string | Stable client-supplied ID. |
 | `displayName` | string | – |
-| `role` | enum | `project_manager`/`worker`/`listener`. |
+| `role` | enum | `project_manager`/`worker-host`. |
 | `transport` | enum | `stdio`/`http`/`internal`. |
 | `capabilities` | json | – |
 | `status` | enum | `connected`/`disconnected`. |

docs-web/architecture/index.md

@@ -8,7 +8,7 @@ It is for contributors and integrators who need to reason about *how* Code UX ma
 
 | # | Page | Topic |
 | --- | --- | --- |
-| 1 | [System overview](./system-overview.md) | Process model, runtime composition, top-level data flow |
+| 1 | [System overview](./system-overview.md) | Container-first process model, runtime composition, top-level data flow |
 | 2 | [MCP server](./mcp-server.md) | Tool dispatch, transports, authentication, session lifecycle |
 | 3 | [Sprint engine](./sprint-engine.md) | Cycle pipeline, watch loop state machine, dependency resolution, retries |
 | 4 | [Virtual workers](./virtual-workers.md) | Provisioning, lifecycle, Docker vs host execution, attention-item handling |

docs-web/architecture/system-overview.md

@@ -41,7 +41,7 @@ Code UX is a single Node process that hosts multiple cooperating services. This
 └────────────────────────────────────────────────────────────────────┘
 ```
 
-The process is started by `src/index.ts` → `CodeUxServer.run()`. Lifecycle:
+The primary CLI/management entrypoint is `src/index.ts`, which loads configuration and starts `CodeUxServer.run()`. `CodeUxServer` wires all backend services. The dashboard/API serves on a configured port (default 4444), while the worker host and Electron shell operate as separate entrypoints. Lifecycle:
 
 1. **Boot settings** — load and migrate the settings DB.
 2. **Refresh API key** — pull from CLI / env / settings.
@@ -112,7 +112,7 @@ Subtask data is *also* persisted as markdown files for portability — see [Spri
 ## Data flow: a sprint cycle
 
 ```
-Dashboard click "Orchestrate"            MCP client calls manage_code_ux:start
+Dashboard click "Orchestrate"            MCP client calls grouped tools (e.g., manage_sprints:start) (manage_code_ux is deprecated)
             │                                            │
             ▼                                            ▼
       POST /api/sprints/.../orchestrate        ToolRegistry → sprint-actions.ts

docs-web/architecture/virtual-workers.md

@@ -97,10 +97,11 @@ Per provider, `executionMode` is `DOCKER` (default) or `HOST`.
 
 ### DOCKER mode
 
-- Image: `node:24-bookworm` (override via `workers.dockerImage`).
+- Image: `node:24-bookworm` (override via `workers.dockerImage`). Images are cached across runs using a setup image cache.
 - Mounts:
-  - The worktree path read-write.
-  - The provider auth path (e.g. `~/.gemini`) read-only, if `mountAuth: true`.
+  - The workspace volume (`code-ux.workspace=true`) is mounted read-write.
+  - Runtime volumes (`code-ux.workspace-runtime=true`) are used for preserving package manager caches and the provider home directory outside of the main workspace.
+  - Provider credentials are conceptually mounted via dedicated, isolated credential mounts (e.g. `mountAuth: true` builds provider-specific mounts without exposing raw host tokens or keys to the workspace root or command arguments).
   - Optional setup script.
 - Network: default bridge.
 - The CLI runs as the container's default user (root, in the default image).
@@ -110,7 +111,7 @@ Per provider, `executionMode` is `DOCKER` (default) or `HOST`.
 
 - The CLI runs directly on the host as the Code UX process user.
 - No mount; the CLI uses its native auth.
-- Faster startup, no Docker dependency, but less hermetic.
+- Used *only* as a fallback for specific edge cases (such as degraded CI autofix runs when Docker is unrecoverably unavailable). Docker is the strict default and is required for merge conflict isolation.
 
 ## Worktree management
 
@@ -194,7 +195,7 @@ Each dispatch records:
 - PR URL on success.
 - Failure reason.
 
-Visible in the dashboard's **Tasks** detail panel and via `manage_code_ux` → `tasks` → `inspect_run` and `telemetry` → `list_task_dispatches`.
+Visible in the dashboard's **Tasks** detail panel and via `manage_tasks` → `inspect_run` and `manage_telemetry` → `list_task_dispatches`.
 
 ## Tuning
 

docs-web/developer/building-from-source.md

@@ -100,6 +100,7 @@ codeux --help
 ```
 src/
 ├── index.ts                  # CLI entry
+├── electron/                 # desktop shell entrypoint and policies (does not own orchestration)
 ├── app/                      # lifecycle, dependency factory
 ├── config/                   # CLI flag + env parsing
 ├── contracts/                # shared types, MCP tool definitions
@@ -110,11 +111,11 @@ src/
 ├── integrations/             # Jules API client
 ├── mcp/                      # MCP server, request router, tool handlers
 ├── repositories/             # settings, agents, memory, project
-├── server/                   # Express dashboard server, routes, websocket
+├── server/                   # Express dashboard server (default port 4444), routes, websocket
 ├── services/                 # virtual-worker-service, sprint-markdown-service, etc.
 ├── shared/                   # config search paths, common utils
 ├── sprint/                   # cycle steps (start-ready-tasks, etc.)
-└── worker/                   # worker-mode entry (reserved)
+└── worker/                   # worker-host mode entrypoint (separate from main server)
 
 dashboard/
 ├── index.html
@@ -149,13 +150,13 @@ tests/
 pnpm run typecheck             # tsc --noEmit (server)
 pnpm run typecheck:dashboard   # tsc --noEmit (dashboard)
 pnpm run lint                  # alias for typecheck (no eslint shipped)
-pnpm test                      # vitest run (full suite)
+pnpm run test                  # vitest run (full suite)
 pnpm run test:watch            # vitest watch mode
 pnpm run test:backend          # backend only
 pnpm run test:dashboard        # dashboard only
 pnpm run test:coverage         # full coverage report
 pnpm run test:backend:coverage # backend coverage with threshold gate
-pnpm run ci                    # local CI: guardrails + audit + lint + backend coverage + dashboard tests + build
+pnpm run ci                    # local CI: quality:guardrails -> audit -> lint -> test:backend:coverage -> test:dashboard -> build
 pnpm run audit                 # pnpm audit --audit-level=high
 pnpm run smoke-test            # node dist/index.js --help
 pnpm run dev:server-only       # boot just the server from source
@@ -194,6 +195,6 @@ The CI tag pipeline runs the full build, runs the audit, and publishes to npm.
 
 ## Development tips
 
-- Use `pnpm run dev` + `pnpm run dev:dashboard` in two terminals for the fastest iteration loop.
+- Use `pnpm run dev` in one terminal (which starts both the server and dashboard watcher) for the fastest iteration loop.
 - The MCP stdio server only activates if stdin is not a TTY. To exercise it locally, pipe a JSON-RPC request: `echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | node dist/index.js`.
 - For one-off MCP HTTP integration tests, the legacy `--mcp-https` flag plus `curl` is the simplest harness.

docs-web/developer/http-api.md

@@ -6,7 +6,7 @@ This page lists every endpoint, grouped by domain. Path parameters use `:name` n
 
 > **Authentication:** The dashboard REST API is intended for trusted local consumption. It is not authenticated. Bind only to loopback (default) or front it with a reverse proxy when exposing remotely.
 
-> **MCP HTTP gateway** (`--mcp-https`) is a *separate* listener for JSON-RPC and is documented in [MCP server](../architecture/mcp-server.md).
+> **MCP HTTP gateway** (`--mcp-http`) is a *separate* listener for JSON-RPC and is documented in [MCP server](../architecture/mcp-server.md).
 
 ---