docs: refresh README and realign published docs with current features

docs/changelog.md

@@ -12,8 +12,19 @@ For the **full changelog**, see [CHANGELOG.md](../CHANGELOG.md) in the repositor
 ## Unreleased
 
 #### Added
-- **CI quality gate** (`.github/workflows/ci.yml`): Go `build`/`vet`/`test` + golangci-lint (new-issue gating) and web type-check/lint/build run on every push to `main` and every pull request.
-- **Desktop bundles in the release pipeline.** `release.yml` now builds the Tauri desktop app for **macOS (Intel + Apple Silicon), Windows, and Linux** on native runners and attaches the `.dmg` / `.msi` / `.exe` / `.deb` / `.AppImage` installers (with checksums) to each GitHub Release alongside the CLI binaries. macOS code-signing/notarization is wired through optional `APPLE_*` secrets (unset → unsigned build). See [Release & CI](release.html).
+- **Built-in color themes, unified across terminal and web.** A new single source of truth (`internal/theme`) defines 7 themes — 4 dark (jcode Dark, Midnight, Dracula, Nord) and 3 light (jcode Light, GitHub Light, Solarized Light) — as a typed semantic palette. `go generate` emits the web CSS (`[data-theme]` blocks) and the picker registry from that one Go file, so the two renderers can never drift.
+- **`/theme` command** in the TUI opens a live-preview selector: arrow keys repaint the whole UI, Enter applies and persists to `config.theme`, Esc reverts. When no theme is persisted, the startup default is auto-selected from the terminal background. New `theme` config field.
+- **Appearance settings tab** in the web UI: a System (follow-OS) option plus dark/light swatch grids that render a true mini-preview of each theme. Themes apply via `html[data-theme]`; the legacy light/dark/system localStorage values migrate automatically.
+- **Docker container workspaces (web).** The remote-connect wizard can now bind a task to a Docker container, alongside SSH. A new `DockerExecutor` (Docker Go SDK, `client.FromEnv` → honors `DOCKER_HOST`) runs all agent file/command operations inside the container via `docker exec`, mirroring the SSH executor. A stopped container is started on connect and stopped again (ref-counted) once no task is using it; a one-shot container that exits immediately is reported with its logs rather than failing silently. The embedded terminal opens a real TTY *inside* the bound container (`docker exec`, bash→sh). Container-bound tasks are keyed `docker://<container>/<path>`, and the `switch_env` tool plus saved Docker aliases (`docker_aliases` in config) cover reconnects.
+
+#### Changed
+- Renamed the session modes to **Ask for approval / Plan / Full access** across the web UI, terminal UI, and ACP. Their canonical IDs are now `approval` / `plan` / `full_access`; the old `ask`, `agent`, and `autopilot` IDs are no longer accepted.
+- The terminal palette was de-frozen: the ~50 lipgloss styles that were baked in at import time are now rebuilt from the active theme by `ApplyTheme`, and previously-hardcoded colors (subagent purple, on-primary text, team-panel and context-bar colors) are now semantic tokens. Markdown (glamour) follows the theme's light/dark appearance.
+
+#### Fixed
+- TUI: pressing **Esc** while viewing a teammate now returns to the leader (the handler matched a key string that bubbletea never emits, so it was dead code).
+- TUI: the Cancel-agent confirmation now defaults to the non-destructive **Wait** button, matching the Quit dialog — `Ctrl+C` then `Enter` no longer aborts a running agent by reflex.
+- TUI: **`?`** opens the keyboard-shortcuts help when the input is empty, and the help panel's slash-command list is now generated from the command registry (so `/goal`, skill commands, and `/theme` always appear).
 
 ---
 
@@ -589,4 +600,4 @@ All releases maintain backward compatibility with existing configurations and wo
 
 ---
 
-*Last updated: May 23, 2026*
+*Last updated: June 13, 2026*

docs/commands.md

@@ -20,6 +20,16 @@ nav_order: 8
 | `jcode sessions` | List recorded sessions for this project |
 | `jcode mcp add <name> <url>` | Add an MCP server |
 | `jcode mcp list` | List configured MCP servers |
+| `jcode mcp login <name>` | Authenticate an existing http/sse MCP server via OAuth |
+| `jcode automation list` | List all automations |
+| `jcode automation show <id>` | Show an automation's definition and last run state |
+| `jcode automation templates` | List built-in automation templates |
+| `jcode automation enable <id>` | Enable an automation |
+| `jcode automation disable <id>` | Disable an automation |
+| `jcode automation delete <id>` | Delete an automation |
+
+{: .note }
+> `jcode automation` is also available as `jcode automations` or `jcode auto`. Definition management works standalone; periodic firing is owned by a running `jcode web` process.
 
 ### Flags
 
@@ -28,15 +38,14 @@ nav_order: 8
 | `--prompt <text>` | `-p` | One-shot mode: run a single prompt and exit |
 | `--resume <UUID>` | | Resume a previous session |
 | `--unsafe` | | Auto-approve all tool calls |
-| `--doctor` | | Run system health check |
-| `--version` | | Print version info |
 
 ### Web Server Flags
 
 | Flag | Default | Description |
 |---|---|---|
 | `--port` | 8080 | HTTP port for web interface |
 | `--host` | 127.0.0.1 | Server bind address |
+| `--open` | true | Open browser after server starts |
 
 ### MCP Add Flags
 
@@ -45,6 +54,11 @@ nav_order: 8
 | `--type` | `-t` | Server type: `sse`, `http`, or `stdio` (auto-detected) |
 | `--header` | | HTTP header in `Key: Value` format (repeatable) |
 | `--env` | | Environment variable in `KEY=VALUE` format (repeatable) |
+| `--scope` | `-s` | Config scope (`user`) |
+| `--oauth` | | Authenticate via OAuth after adding (http/sse only) |
+| `--client-id` | | OAuth client id (manual fallback when dynamic registration is unsupported) |
+| `--client-secret` | | OAuth client secret (confidential clients) |
+| `--scope-oauth` | | OAuth scope to request (repeatable) |
 
 ## Keyboard Shortcuts (TUI)
 
@@ -77,9 +91,13 @@ Type these in the TUI input area:
 | `/compact` | Compact conversation context |
 | `/goal` | Set a persistent objective the agent works toward ([Goals](goal.html)) |
 | `/bg` | Show background tasks |
+| `/channel` | Open the channel management panel (WeChat push/messaging) |
+| `/mcp` | List MCP servers and status; `/mcp login <name>` to authenticate via OAuth |
+| `/help` | Show keyboard shortcuts help |
 | `/review-pr` | Run PR review skill |
 | `/pr-comments` | Fetch PR comments |
 | `/security-review` | Run security review |
+| `/submit-pr` | Commit, push the branch, and open a GitHub pull request |
 | `/<custom-skill>` | Any skill with a slash command |
 
 ## One-Shot Mode

docs/configuration.md

@@ -55,12 +55,22 @@ jcode stores all configuration in a single JSON file at `~/.jcode/config.json`.
   "small_model": "openai/gpt-4o-mini",
   "fallback_model": "anthropic/claude-3-5-sonnet",
   "max_iterations": 1000,
-  "auto_approve": false,
+  "default_mode": "approval",
+
+  "context_limits": {
+    "openai/gpt-4o": 128000,
+    "my-custom-model": 256000
+  },
+  "default_context_limit": 200000,
 
   "ssh_aliases": [
     { "name": "prod", "addr": "deploy@10.0.1.5", "path": "/var/www/app" }
   ],
 
+  "docker_aliases": [
+    { "name": "devbox", "container": "my-dev-container", "path": "/workspace" }
+  ],
+
   "mcp_servers": {
     "github": { "type": "stdio", "command": "gh-mcp" },
     "db": { "type": "http", "url": "http://localhost:3001/mcp" }
@@ -137,6 +147,36 @@ Active model in `"provider/model"` format.
 | `fallback_model` | Used when the primary model fails |
 | `max_iterations` | Maximum agent iterations per turn (default: 1000) |
 
+### context_limits
+
+Per-model overrides for the context window size (in tokens). Use this to teach
+jcode the window of a brand-new or custom model the registry doesn't know yet.
+Keys may be `"provider/model"` (preferred) or a bare model id; the
+`"provider/model"` form is checked first.
+
+```json
+{
+  "context_limits": {
+    "openai/gpt-4o": 128000,
+    "my-custom-model": 256000
+  }
+}
+```
+
+An explicit `context_limits` entry takes precedence over the models.dev registry
+and built-in tables. When no override matches and the limit is still unknown,
+jcode falls back to [`default_context_limit`](#default_context_limit).
+
+### default_context_limit
+
+Fallback context window (in tokens) assumed when a model's limit can't be
+determined from `context_limits`, the models.dev registry, or the built-in
+tables. Default: `200000`.
+
+```json
+{ "default_context_limit": 200000 }
+```
+
 ### ssh_aliases
 
 Named SSH connections for quick access.
@@ -147,6 +187,17 @@ Named SSH connections for quick access.
 | `addr` | Connection address (`user@host[:port]`) |
 | `path` | Remote working directory |
 
+### docker_aliases
+
+Named Docker container workspaces for quick access. Fields mirror
+[`ssh_aliases`](#ssh_aliases).
+
+| Field | Description |
+|---|---|
+| `name` | Alias name shown in the picker |
+| `container` | Container name or id |
+| `path` | Working directory inside the container |
+
 ### mcp_servers
 
 MCP server definitions. See [MCP Integration](mcp).
@@ -200,10 +251,13 @@ The session mode jcode starts in: `"approval"` (default), `"plan"`, or `"full_ac
 { "default_mode": "approval" }
 ```
 
+{: .note }
+**Migration:** the old mode IDs `ask`, `agent`, and `autopilot` are no longer accepted — use `approval`, `plan`, and `full_access` respectively. An unrecognized value falls back to `approval`.
+
 ### auto_approve
 
-{: .note }
-Deprecated — superseded by [`default_mode`](#default_mode). Still honored as a fallback when `default_mode` is unset: `true` maps to `full_access`.
+{: .warning }
+Deprecated — superseded by [`default_mode`](#default_mode) (`approval` / `plan` / `full_access`). Still honored only as a fallback when `default_mode` is unset: `true` maps to `full_access`. The old mode IDs `ask` / `agent` / `autopilot` are no longer accepted.
 
 Set to `true` to auto-approve all tool calls. Equivalent to running with the `--unsafe` flag.
 

docs/overview.md

@@ -26,6 +26,7 @@ jcode is an AI-powered coding agent that runs in your terminal. You describe tas
 | **Interactive Questions** | The agent can ask you for clarification mid-task |
 | **Plan Mode** | Explore read-only and present a plan before making changes |
 | **SSH Remote** | Work on any machine over SSH — same tools, same experience |
+| **Docker Workspaces** | Work inside a Docker container with the same tool coverage |
 | **Agent Teams** | Spawn parallel AI teammates for complex tasks |
 | **Subagents** | Delegate subtasks to independent child agents |
 | **MCP Integration** | Connect any MCP-compatible server for extended capabilities |
@@ -34,6 +35,7 @@ jcode is an AI-powered coding agent that runs in your terminal. You describe tas
 | **Channels** | Push notifications to WeChat when approval is needed or tasks complete |
 | **JCode Buddy** | Physical desktop companion with pixel cat that reacts to your coding activity |
 | **Skills** | Domain-specific skill packs loaded on demand |
+| **Color Themes** | 7 built-in themes (4 dark / 3 light) with live preview via `/theme` |
 
 ## Design Philosophy
 

docs/overview/models.md

@@ -78,10 +78,46 @@ jcode supports different models for different purposes:
 }
 ```
 
+## Reasoning & Extended Thinking
+
+For reasoning-capable models, jcode can control thinking depth via the OpenAI-compatible `reasoning_effort` parameter. Set it per provider in `~/.jcode/config.json`:
+
+```json
+{
+  "providers": {
+    "openai": {
+      "api_key": "sk-...",
+      "reasoning_effort": "medium"
+    }
+  }
+}
+```
+
+Accepted values are `"low"`, `"medium"`, and `"high"`. An empty string (or omitting the key) sends no effort parameter. The value is forwarded on every request; reasoning models honor it and others ignore it.
+
+For gateways that gate reasoning behind a chat-template flag (for example qwen3), set `thinking` to explicitly toggle extended reasoning. It is sent as the `chat_template_kwargs` `{"enable_thinking": <bool>}` extension:
+
+```json
+{
+  "providers": {
+    "my-gateway": {
+      "api_key": "...",
+      "base_url": "https://gateway.example.com/v1",
+      "thinking": true
+    }
+  }
+}
+```
+
+{: .note }
+Reasoning effort can also be chosen **per model** from the chat model picker. That choice is stored in `~/.jcode/model_state.json` (`effort_overrides`) and takes precedence over the provider-level `reasoning_effort`. It is applied consistently across the TUI, web, and ACP.
+
 ## Add a Provider at Runtime
 
 jcode includes a setup wizard. Run it from the TUI with `/setting` → "Add Model", or press Ctrl+L and select "Add new provider".
 
+In the web UI, providers and models are managed from a card-based **Settings** view: each provider is a card showing its brand, name, base URL, and a catalog of its models (built-in registry models toggle show/hide; custom models are editable or removable). Editing a provider or authoring a custom model opens a dedicated dialog. A custom model's editor exposes its ID, display name, context window, image-input toggle, and a reasoning-effort tier editor — when a custom model is flagged as reasoning, the standard `minimal` / `low` / `medium` / `high` effort levels are offered, or you can define your own tiers. Models advertising effort levels then expose the per-model reasoning-effort control in the chat input.
+
 ## Verify Model Connectivity
 
 ```bash

docs/overview/skills.md

@@ -17,7 +17,7 @@ Skills use a **two-layer** loading system:
 
 ## Built-in Skills
 
-jcode includes three built-in skills:
+jcode includes four built-in skills:
 
 ### PR Review (`/review-pr`)
 
@@ -42,6 +42,17 @@ Performs a security-focused code review of pending changes on the current branch
 - Remote code execution
 - Data exposure
 
+### Submit PR (`/submit-pr`)
+
+Commits the current working changes, pushes the branch, and opens a GitHub pull request. It:
+
+- Checks for changes to submit and stops if there are none
+- Creates a feature branch first if you are on the default branch (`main`/`master`)
+- Commits with a Conventional Commit message and pushes the branch
+- Opens the PR with `gh pr create` and reports the PR URL
+
+It never force-pushes or pushes directly to the default branch.
+
 {: .note }
 The PR-related skills require the `gh` CLI tool to be installed and authenticated. Run `gh auth login` if you haven't already.
 

docs/tools.md

@@ -34,12 +34,12 @@ Not all tool calls require your approval. jcode categorizes tools by risk:
 | Category | Tools | Approval |
 |---|---|---|
 | **Read-only** | `read`, `grep`, `glob` | Auto-approved (within project) |
-| **Safe commands** | `ls`, `pwd`, `git status`, `git log` | Auto-approved |
+| **Safe commands** | `ls`, `pwd`, `cat`, `echo`, `which`, bare `env`, `git status`, `git log`, `git diff`, `git show` | Auto-approved (foreground only, no shell operators) |
 | **Management** | `todowrite`, `todoread`, `ask_user` | Auto-approved |
-| **Delegation** | `subagent`, `check_background` | Auto-approved |
+| **Delegation** | `subagent`, `check_background`, `webfetch` | Auto-approved |
 | **Team** | `team_create`, `team_spawn`, `team_send_message`, `team_list`, `team_delete` | Auto-approved |
 | **File edits** | `edit`, `write` | **Require approval** |
-| **Commands** | `execute` (non-safe) | **Require approval** |
+| **Commands** | `execute` (non-safe, or any [background]({% link tools/execute.md %}) command) | **Require approval** |
 | **Environment** | `switch_env` | **Require approval** |
 
 When a tool requires approval (in **Ask for approval** mode), you see a dialog with the tool name and arguments. You can:

docs/tools/execute.md

@@ -12,10 +12,16 @@ Run shell commands on your machine (or remote SSH host).
 
 | Command Type | Approval |
 |---|---|
-| Safe commands (`ls`, `pwd`, `env`, `cat`, `echo`, `which`, `git status`, `git log`) | Auto-approved |
-| Background tasks | Auto-approved |
+| Safe commands (`ls`, `pwd`, `cat`, `echo`, `which`, bare `env`, `git status`, `git log`, `git diff`, `git show`) | Auto-approved |
+| Background tasks | **Requires approval** |
 | All other commands | **Requires approval** |
 
+{: .note }
+Safe commands are matched on the whole command word with no shell operators (`;`, `&`, `|`, `<`, `>`, `` ` ``, `$()`, `${}`, `()`). A "safe" prefix cannot smuggle a payload — e.g. `git status && rm -rf /` is **not** auto-approved. Bare `env` (printing the environment) is safe, but `env CMD ...` runs `CMD` and is **not** safe.
+
+{: .warning }
+Background tasks always require approval. The `background` flag is agent-controlled, so auto-approving it would let any command bypass the gate by setting `background=true`.
+
 ## Basic Usage
 
 ```

docs/tools/task-management.md

@@ -36,6 +36,29 @@ Read the current task list.
 
 Returns the current todos with a summary count.
 
+## Goals
+
+A goal is a persistent, cross-turn objective. Once set, the agent keeps working
+toward it across turns — when it would otherwise stop, it is automatically
+reminded to continue until the objective is verifiably complete or it hits the
+continuation cap. See [Goals]({% link goal.md %}) for the full workflow and the
+`/goal` command.
+
+These tools back the goal feature in every frontend (TUI, web, ACP):
+
+| Tool | What It Does |
+|---|---|
+| `goal_set` | Set or replace the session goal. Takes `objective` (a clear, self-contained description of the desired end state, max 4000 chars). Replacing a goal resets accounting. |
+| `goal_get` | Read the current goal — its objective, status, and token usage. Takes no parameters. Returns `No goal set.` when none exists. |
+| `goal_update` | Mark the goal `complete` (objective verifiably done) or `blocked` (cannot proceed). Takes `status`. Either value stops the automatic continuation. |
+
+**Approval:** Require approval (in **Ask for approval** mode).
+
+A goal carries one of three statuses: `active` (the agent keeps working),
+`complete`, or `blocked`. The agent is instructed to mark `complete` only when
+the objective is verified against the real state of files, command output, or
+tests — not its intent.
+
 ## Ask User
 
 The agent can ask you questions when it needs clarification or a decision.

docs/automations-prd.md → internal-doc/automations-prd.md

@@ -2,7 +2,7 @@
 
 > 状态：草案 **v2**（2026-06-23，关键决策已定，待实现）
 > 对标形态：Anthropic Claude Code 的 **Automations** —— 用 agent 处理「按节奏 / 手动触发」的重复性工作。
-> 关联：[[web 任务化架构]]（`docs/web-task-architecture.md`）、Goal（`docs/goal.md`）、Mode 选择器（Ask/Plan/Autopilot）、Skills、MCP。
+> 关联：[[web 任务化架构]]（`internal-doc/web-task-architecture.md`）、Goal（`docs/goal.md`）、Mode 选择器（Ask/Plan/Autopilot）、Skills、MCP。
 >
 > v1→v2 变更：①去掉事件/GitHub 触发（先不碰 gh）②去掉 Effort/推理力度 ③新增 agent 可调用的 `automation_create` 工具 + 渲染卡片 ④调度器定为「文件锁选主」⑤存储定为「flock 写锁 + 易变态分离」⑥运行时不加护栏（沿用既有哲学）。