@qwen-code/qwen-code 0.18.0-preview.2 → 0.18.0

package/bundled/qc-helper/docs/_meta.ts

@@ -15,6 +15,7 @@ export default {
   'integration-jetbrains': 'JetBrains IDEs',
   'integration-github-action': 'GitHub Actions',
   'qwen-serve': 'Daemon mode (qwen serve)',
+  'qwen-serve-deploy-local': 'Daemon mode — local launch templates',
   'Code with Qwen Code': {
     type: 'separator',
     title: 'Code with Qwen Code', // Title is optional

package/bundled/qc-helper/docs/configuration/settings.md

@@ -108,18 +108,16 @@ Settings are organized into categories. Most settings should be placed within th
 | `ui.customBannerTitle`                  | string           | Replace the default `>_ Qwen Code` title in the banner info panel. The `(vX.Y.Z)` version suffix is always appended; auth, model, and path lines are not affected. Sanitized; capped at 80 characters.                                                                                                                                                                                                                                                                                                                                             | `""`        |
 | `ui.customBannerSubtitle`               | string           | Optional subtitle line rendered between the banner title and the auth/model line, in place of the blank spacer row. Sanitized; capped at 160 characters. Empty (default) keeps the original blank spacer.                                                                                                                                                                                                                                                                                                                                          | `""`        |
 | `ui.customAsciiArt`                     | string \| object | Replace the QWEN ASCII logo in the banner. Accepts an inline string (used for both width tiers), `{ "path": "./brand.txt" }` (relative paths resolve against the owning settings file's directory; read once at startup with `O_NOFOLLOW` on POSIX, capped at 64 KB), or `{ "small": ..., "large": ... }` for width-aware selection. Sanitized; capped at 200 lines × 200 columns per tier.                                                                                                                                                        | `undefined` |
-| `ui.hideFooter`                         | boolean          | Hide the footer from the UI.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `false`     |
-| `ui.showMemoryUsage`                    | boolean          | Display memory usage information in the UI.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `false`     |
 | `ui.showLineNumbers`                    | boolean          | Show line numbers in code blocks in the CLI output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `true`      |
 | `ui.renderMode`                         | string           | Default Markdown display mode. Use `"render"` for rich visual previews or `"raw"` to show source-oriented Markdown by default. Toggle during a session with `Alt/Option+M`; on macOS the terminal must send Option as Meta. See [Markdown Rendering](../features/markdown-rendering).                                                                                                                                                                                                                                                              | `"render"`  |
-| `ui.showCitations`                      | boolean          | Show citations for generated text in the chat.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `true`      |
+| `ui.showCitations`                      | boolean          | Show citations for generated text in the chat.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `false`     |
 | `ui.compactMode`                        | boolean          | Hide tool output and thinking for a cleaner view. Toggle with `Ctrl+O` during a session or via the Settings dialog. Tool approval prompts are never hidden, even in compact mode. The setting persists across sessions.                                                                                                                                                                                                                                                                                                                            | `false`     |
 | `ui.shellOutputMaxLines`                | number           | Max number of shell output lines shown inline. Set to `0` to disable the cap and show full output. Hidden lines are surfaced via the `+N lines` indicator. Errors, `!`-prefix user-initiated commands, confirming tools, and focused embedded shells always show full output.                                                                                                                                                                                                                                                                      | `5`         |
-| `enableWelcomeBack`                     | boolean          | Show welcome back dialog when returning to a project with conversation history. When enabled, Qwen Code will automatically detect if you're returning to a project with a previously generated project summary (`.qwen/PROJECT_SUMMARY.md`) and show a dialog allowing you to continue your previous conversation or start fresh. If you choose **Start new chat session**, that choice is remembered for the current project until the project summary changes. This feature integrates with the `/summary` command and quit confirmation dialog. | `true`      |
+| `ui.enableWelcomeBack`                  | boolean          | Show welcome back dialog when returning to a project with conversation history. When enabled, Qwen Code will automatically detect if you're returning to a project with a previously generated project summary (`.qwen/PROJECT_SUMMARY.md`) and show a dialog allowing you to continue your previous conversation or start fresh. If you choose **Start new chat session**, that choice is remembered for the current project until the project summary changes. This feature integrates with the `/summary` command and quit confirmation dialog. | `true`      |
 | `ui.accessibility.enableLoadingPhrases` | boolean          | Enable loading phrases (disable for accessibility).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `true`      |
 | `ui.accessibility.screenReader`         | boolean          | Enables screen reader mode, which adjusts the TUI for better compatibility with screen readers.                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `false`     |
 | `ui.customWittyPhrases`                 | array of strings | A list of custom phrases to display during loading states. When provided, the CLI will cycle through these phrases instead of the default ones.                                                                                                                                                                                                                                                                                                                                                                                                    | `[]`        |
-| `ui.enableFollowupSuggestions`          | boolean          | Enable [followup suggestions](../features/followup-suggestions) that predict what you want to type next after the model responds. Suggestions appear as ghost text and can be accepted with Tab, Enter, or Right Arrow.                                                                                                                                                                                                                                                                                                                            | `true`      |
+| `ui.enableFollowupSuggestions`          | boolean          | Enable [followup suggestions](../features/followup-suggestions) that predict what you want to type next after the model responds. Suggestions appear as ghost text and can be accepted with Tab, Enter, or Right Arrow.                                                                                                                                                                                                                                                                                                                            | `false`     |
 | `ui.enableCacheSharing`                 | boolean          | Use cache-aware forked queries for suggestion generation. Reduces cost on providers that support prefix caching (experimental).                                                                                                                                                                                                                                                                                                                                                                                                                    | `true`      |
 | `ui.enableSpeculation`                  | boolean          | Speculatively execute accepted suggestions before submission. Results appear instantly when you accept (experimental).                                                                                                                                                                                                                                                                                                                                                                                                                             | `false`     |
 | `experimental.emitToolUseSummaries`     | boolean          | Generate short LLM-based labels summarizing each tool-call batch. See [Tool-Use Summaries](../features/tool-use-summaries). Requires `fastModel` to be configured; silently skipped otherwise. Can be overridden per-session with `QWEN_CODE_EMIT_TOOL_USE_SUMMARIES=0` or `=1`.                                                                                                                                                                                                                                                                   | `true`      |

package/bundled/qc-helper/docs/features/approval-mode.md

@@ -94,8 +94,8 @@ How should we handle database migration?
 ```json
 // .qwen/settings.json
 {
-  "permissions": {
-    "defaultMode": "plan"
+  "tools": {
+    "approvalMode": "plan"
   }
 }
 ```
@@ -157,8 +157,8 @@ You can review each proposed change and approve or reject it individually.
 ```bash
 // .qwen/settings.json
 {
-  "permissions": {
-"defaultMode": "default"
+  "tools": {
+    "approvalMode": "default"
   }
 }
 ```
@@ -340,10 +340,8 @@ YOLO Mode grants Qwen Code the highest permissions, automatically approving all
 ```bash
 // .qwen/settings.json
 {
-  "permissions": {
-"defaultMode": "yolo",
-"confirmShellCommands": false,
-"confirmFileEdits": false
+  "tools": {
+    "approvalMode": "yolo"
   }
 }
 ```
@@ -364,10 +362,10 @@ qwen --prompt "Run the test suite, fix all failing tests, then commit changes"
 
 ### Keyboard Shortcut Switching
 
-During a Qwen Code session, use **Shift+Tab**​ (or **Tab** on Windows) to quickly cycle through the four modes:
+During a Qwen Code session, use **Shift+Tab**​ (or **Tab** on Windows) to quickly cycle through the five modes:
 
 ```
-Ask Permissions Mode → Auto-Edit Mode → YOLO Mode → Plan Mode → Ask Permissions Mode
+Plan Mode → Ask Permissions Mode → Auto-Edit Mode → Auto Mode → YOLO Mode → Plan Mode
 ```
 
 ### Persistent Configuration
@@ -376,10 +374,8 @@ Ask Permissions Mode → Auto-Edit Mode → YOLO Mode → Plan Mode → Ask Perm
 // Project-level: ./.qwen/settings.json
 // User-level: ~/.qwen/settings.json
 {
-  "permissions": {
-"defaultMode": "auto-edit",  // or "plan" or "yolo"
-"confirmShellCommands": true,
-"confirmFileEdits": true
+  "tools": {
+    "approvalMode": "auto-edit"  // or "plan", "default", "auto", "yolo"
   }
 }
 ```

package/bundled/qc-helper/docs/features/commands.md

@@ -18,14 +18,21 @@ Slash commands are used to manage Qwen Code sessions, interface, and basic behav
 
 These commands help you save, restore, and summarize work progress.
 
-| Command     | Description                                               | Usage Examples                       |
-| ----------- | --------------------------------------------------------- | ------------------------------------ |
-| `/init`     | Analyze current directory and create initial context file | `/init`                              |
-| `/summary`  | Generate project summary based on conversation history    | `/summary`                           |
-| `/compress` | Replace chat history with summary to save Tokens          | `/compress`                          |
-| `/resume`   | Resume a previous conversation session                    | `/resume`                            |
-| `/recap`    | Generate a one-line session recap now                     | `/recap`                             |
-| `/restore`  | Restore files to state before tool execution              | `/restore` (list) or `/restore <ID>` |
+| Command          | Description                                                              | Usage Examples                                                |
+| ---------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------- |
+| `/init`          | Analyze current directory and create initial context file                | `/init`                                                       |
+| `/summary`       | Generate project summary based on conversation history                   | `/summary`                                                    |
+| `/compress`      | Replace chat history with summary to save Tokens                         | `/compress`                                                   |
+| `/compress-fast` | Fast compression without AI — strips old tool outputs and thinking parts | `/compress-fast`                                              |
+| `/resume`        | Resume a previous conversation session                                   | `/resume`                                                     |
+| `/recap`         | Generate a one-line session recap now                                    | `/recap`                                                      |
+| `/restore`       | Revert project files to the checkpoint before a tool call ran            | `/restore` (list) or `/restore <ID>`                          |
+| `/delete`        | Delete a previous session                                                | `/delete`                                                     |
+| `/branch`        | Fork the current conversation into a new session                         | `/branch`                                                     |
+| `/fork`          | Spawn a background agent that inherits the full conversation             | `/fork <directive>`                                           |
+| `/rewind`        | Rewind conversation to a previous turn                                   | `/rewind` or `/rollback`                                      |
+| `/export`        | Export session history to file                                           | `/export html`, `/export md`, `/export json`, `/export jsonl` |
+| `/rename`        | Rename or tag the current session                                        | `/rename My Feature` or `/tag`                                |
 
 ### 1.2 Interface and Workspace Control
 
@@ -43,6 +50,7 @@ Commands for adjusting interface appearance and work environment.
 | `/editor`            | Open dialog to select supported editor                                                                                                                                            | `/editor`                               |
 | `/statusline`        | Open interactive [status line](./status-line.md) preset dialog                                                                                                                    | `/statusline`                           |
 | `/statusline <text>` | Generate a command-mode [status line](./status-line.md) via agent                                                                                                                 | `/statusline show model and git branch` |
+| `/terminal-setup`    | Configure terminal keybindings for multiline input                                                                                                                                | `/terminal-setup`                       |
 
 ### 1.3 Language Settings
 
@@ -71,6 +79,7 @@ Commands for managing AI tools and models.
 | →`plan`          | Analysis only, no execution                   | Secure review                                 |
 | →`default`       | Require approval for edits                    | Daily use                                     |
 | →`auto-edit`     | Automatically approve edits                   | Trusted environment                           |
+| →`auto`          | Classifier-evaluated approval                 | Autonomous sessions with safety guardrails    |
 | →`yolo`          | Automatically approve all                     | Quick prototyping                             |
 | `/model`         | Switch model used in current session          | `/model`                                      |
 | `/model --fast`  | Set a lighter model for prompt suggestions    | `/model --fast qwen3-coder-flash`             |
@@ -79,6 +88,14 @@ Commands for managing AI tools and models.
 | `/remember`      | Save a durable memory                         | `/remember Prefer terse responses`            |
 | `/forget`        | Remove matching entries from auto-memory      | `/forget <query>`                             |
 | `/dream`         | Manually run auto-memory consolidation        | `/dream`                                      |
+| `/hooks`         | Manage Qwen Code hooks                        | `/hooks`, `/hooks list`                       |
+| `/permissions`   | Manage permission rules                       | `/permissions`                                |
+| `/agents`        | Manage subagents                              | `/agents manage`, `/agents create`            |
+| `/arena`         | Manage Arena sessions                         | `/arena start`, `/arena status`               |
+| `/goal`          | Set a goal — keep working until condition met | `/goal <condition>`, `/goal clear`            |
+| `/tasks`         | List background tasks                         | `/tasks`                                      |
+| `/lsp`           | Show LSP server status                        | `/lsp`                                        |
+| `/trust`         | Manage folder trust settings                  | `/trust`                                      |
 
 ### 1.5 Built-in Skills
 
@@ -192,7 +209,7 @@ progress; otherwise it waits for the current turn to finish and then fires).
 Unlike the manual command, the auto-trigger is fully silent on failure: if
 generation errors or there is nothing to summarize, no message is added to
 the history. Controlled by the `general.showSessionRecap` setting
-(default: `true`); the manual `/recap` command always works regardless of
+(default: `false`); the manual `/recap` command always works regardless of
 this setting.
 
 **Example:**
@@ -209,8 +226,8 @@ this setting.
 >
 > Configure a fast model via `/model --fast <model>` (e.g.
 > `qwen3-coder-flash`) to make `/recap` fast and cheap. Set
-> `general.showSessionRecap` to `false` to opt out of the auto-trigger
-> while keeping the manual command available.
+> `general.showSessionRecap` to `true` to enable the auto-trigger; the
+> manual `/recap` command always works regardless of this setting.
 
 ### 1.8 Diff Viewer (`/diff`)
 
@@ -278,6 +295,11 @@ Commands for obtaining information and performing system settings.
 | `/stats tools`  | Show per-tool call counts                                                                                                                                                                                                                                                                       | `/stats tools`                   |
 | `/settings`     | Open settings editor                                                                                                                                                                                                                                                                            | `/settings`                      |
 | `/auth`         | Change authentication method                                                                                                                                                                                                                                                                    | `/auth`                          |
+| `/doctor`       | Run installation and environment diagnostics                                                                                                                                                                                                                                                    | `/doctor`, `/doctor memory`      |
+| `/docs`         | Open full Qwen Code documentation in browser                                                                                                                                                                                                                                                    | `/docs`                          |
+| `/ide`          | Manage IDE integration                                                                                                                                                                                                                                                                          | `/ide status`, `/ide install`    |
+| `/insight`      | Generate programming insights from chat history                                                                                                                                                                                                                                                 | `/insight`                       |
+| `/setup-github` | Set up GitHub Actions                                                                                                                                                                                                                                                                           | `/setup-github`                  |
 | `/bug`          | Submit issue about Qwen Code                                                                                                                                                                                                                                                                    | `/bug Button click unresponsive` |
 | `/copy`         | Copy AI output to clipboard (`/copy N` = Nth-last AI message)                                                                                                                                                                                                                                   | `/copy` or `/copy 2`             |
 | `/quit`         | Exit Qwen Code immediately                                                                                                                                                                                                                                                                      | `/quit` or `/exit`               |

package/bundled/qc-helper/docs/features/followup-suggestions.md

@@ -32,7 +32,7 @@ Suggestions are generated when all of the following conditions are met:
 - There are no errors in the most recent response
 - No confirmation dialogs are pending (e.g., shell confirmation, permissions)
 - The approval mode is not set to `plan`
-- The feature is enabled in settings (enabled by default)
+- The feature is enabled in settings (disabled by default — set `ui.enableFollowupSuggestions` to `true` to turn it on)
 
 Suggestions will not appear in non-interactive mode (e.g., headless/SDK mode).
 
@@ -72,7 +72,7 @@ These settings can be configured in `settings.json`:
 
 | Setting                        | Type    | Default | Description                                                        |
 | ------------------------------ | ------- | ------- | ------------------------------------------------------------------ |
-| `ui.enableFollowupSuggestions` | boolean | `true`  | Enable or disable followup suggestions                             |
+| `ui.enableFollowupSuggestions` | boolean | `false` | Enable or disable followup suggestions                             |
 | `ui.enableCacheSharing`        | boolean | `true`  | Use cache-aware forked queries to reduce cost (experimental)       |
 | `ui.enableSpeculation`         | boolean | `false` | Speculatively execute suggestions before submission (experimental) |
 | `fastModel`                    | string  | `""`    | Model for prompt suggestions and speculative execution             |

package/bundled/qc-helper/docs/features/sub-agents.md

@@ -282,13 +282,15 @@ can drop a CC agent file into `.qwen/agents/` and have the supported fields
 parse identically. Optional fields with invalid values are silently dropped
 at parse time rather than rejected — the same lenient posture CC uses.
 
-| Field            | Type             | Notes                                                                                                                                                                                                                                         |
-| ---------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `permissionMode` | enum string      | `acceptEdits`, `auto`, `bypassPermissions`, `default`, `dontAsk`, `plan`. Mapped to `approvalMode` at parse time; when both are set, the explicit `approvalMode` wins.                                                                        |
-| `maxTurns`       | positive integer | Caps the agent's turn budget. Wired into `runConfig.max_turns` at runtime; when both are set, the top-level field wins.                                                                                                                       |
-| `color`          | enum string      | Display color. Allowlist: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan` (mirrors CC's `_Y`). The legacy qwen sentinel `auto` is also preserved for backward compatibility. Other values are silently dropped on parse. |
+| Field            | Type             | Notes                                                                                                                                                                                                                                                                            |
+| ---------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `permissionMode` | enum string      | `acceptEdits`, `auto`, `bypassPermissions`, `default`, `dontAsk`, `plan`. Mapped to `approvalMode` at parse time; when both are set, the explicit `approvalMode` wins.                                                                                                           |
+| `maxTurns`       | positive integer | Caps the agent's turn budget. Wired into `runConfig.max_turns` at runtime; when both are set, the top-level field wins. The legacy nested value is pruned from the on-disk file on save to avoid two sources of truth.                                                           |
+| `color`          | enum string      | Display color. Allowlist: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan` (mirrors CC's `_Y`). The legacy qwen sentinel `auto` is preserved for backward compatibility. Other values are silently dropped on parse.                                         |
+| `mcpServers`     | record of specs  | Per-agent MCP server overrides. Merged with the session-level MCP server set when the agent spawns; on key collision the agent's spec wins (matching CC's `scope: 'agent'` semantics). Malformed entries are dropped per-key with a warning rather than failing the whole agent. |
+| `hooks`          | record of arrays | Per-agent hooks. Keys are CC hook event names (`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, …); values are arrays of `{ matcher?, hooks: [...] }` definitions in the same shape as `settings.json`'s `hooks` field. Registered while the agent runs, removed when it stops.  |
 
-Example:
+Example with all of the above:
 
 ```
 ---
@@ -301,6 +303,17 @@ tools:
   - read_file
   - grep_search
   - glob
+mcpServers:
+  filesystem:
+    type: stdio
+    command: node
+    args: [/usr/local/lib/mcp-fs/server.js]
+hooks:
+  PreToolUse:
+    - matcher: Bash
+      hooks:
+        - type: command
+          command: echo "review-agent about to run a shell command"
 ---
 
 You are a code reviewer. Analyze the code thoroughly and report findings
@@ -308,11 +321,19 @@ ordered by severity.
 ```
 
 The remaining CC frontmatter fields — `effort`, `skills`, `initialPrompt`,
-`memory`, `isolation`, `mcpServers`, `hooks` — are documented in the
-declarative-agent design doc and land in follow-up PRs once the prerequisite
-infrastructure exists (`effort` needs a model-layer parameter; `memory`
-needs a scoped memory subsystem; `mcpServers` / `hooks` need a nested-aware
-YAML parser; `--agent` CLI flag enables `initialPrompt`; etc.).
+`memory`, `isolation` — are documented in the declarative-agent design doc
+and land in follow-up PRs once the prerequisite infrastructure exists
+(`effort` needs a model-layer parameter; `memory` needs a scoped memory
+subsystem; `--agent` CLI flag enables `initialPrompt`; etc.).
+
+> **`hooks` v1 limitation.** While a subagent declaring `hooks` is running,
+> its hook entries fire for every matching event in the session, not only
+> for that subagent's own tool calls. If two subagents with different
+> per-agent hook sets run concurrently, both sets fire for both agents.
+> Per-agent scope filtering at hook-firing time is left to a follow-up;
+> for v1, prefer per-agent hooks that are safe to fire globally for the
+> duration of the agent's run (e.g. logging) over hooks that mutate
+> behavior.
 
 #### Example Usage
 

package/bundled/qc-helper/docs/qwen-serve-deploy-local.md

@@ -0,0 +1,221 @@
+# Local launch templates for `qwen serve` (v0.16-alpha)
+
+Reference templates for running `qwen serve` as a long-lived background process on a developer workstation. Pairs with the [v0.16-alpha known limits](./qwen-serve.md#v016-alpha-known-limits) — local-only, single-user, BYO bearer token. Containerized / multi-host / TLS-fronted deployments defer to v0.16.x.
+
+> **Audience**: dogfooding developers who want the daemon up across reboots, with logs going somewhere durable, and a clean `restart-on-failure` story. If you only need the daemon for the duration of a single shell session, plain `qwen serve` (foreground, Ctrl-C to stop) is fine.
+
+## Generate a bearer token (once)
+
+```bash
+openssl rand -hex 32 > ~/.qwen-serve-token  # user-managed, NOT a built-in path
+chmod 600 ~/.qwen-serve-token
+export QWEN_SERVER_TOKEN="$(cat ~/.qwen-serve-token)"
+```
+
+The path / filename is yours to choose; v0.16-alpha does not auto-generate or auto-locate a token file (deferred to v0.16.x). See the [Authentication](./qwen-serve.md#authentication) section of the user guide for the canonical BYO setup.
+
+> **Scope this `export` to the current shell session only.** Don't add it to `~/.bashrc` / `~/.zshrc` — a profile-level export exposes the bearer token to every process spawned from that shell (IDE subprocesses, browser debuggers, `npm` scripts from unrelated projects). For long-running setups, use the systemd `EnvironmentFile=` / launchd `EnvironmentVariables` mechanisms below — both scope the token to just the daemon process.
+
+The daemon reads the bearer token from either `--token <value>` on the CLI or the `QWEN_SERVER_TOKEN` env var (whitespace stripped from both). The TypeScript SDK's `DaemonClient` constructor falls back to `QWEN_SERVER_TOKEN` when no `token` option is passed (PR 27 fallback — clients with the env var set never need to thread the value through their script).
+
+One shell-level `export` covers both server boot and SDK client construction (just keep it scoped to the session, per the note above).
+
+## Linux: systemd user unit
+
+> **Find your `qwen` binary first.** The unit file's `ExecStart=` must hold an **absolute path** — service managers don't read your shell's `PATH`. Run `which qwen` to discover it. Common locations: `/usr/local/bin/qwen` (Linuxbrew, manual installs), `~/.nvm/versions/node/vX.Y.Z/bin/qwen` (nvm), `~/.fnm/aliases/default/bin/qwen` (fnm), `~/.volta/bin/qwen` (Volta). Substitute the actual path everywhere the templates below show `/PATH/TO/qwen`.
+
+`~/.config/systemd/user/qwen-serve.service`:
+
+```ini
+[Unit]
+Description=Qwen Code daemon (loopback HTTP + SSE)
+After=network.target
+
+[Service]
+Type=simple
+# Replace with your project; %h expands to $HOME under user units.
+WorkingDirectory=%h/your-project
+# Run `which qwen` to find the absolute path. systemd does NOT read $PATH.
+ExecStart=/PATH/TO/qwen serve --hostname 127.0.0.1 --port 4170
+# Read the bearer token from a chmod 600 file rather than inlining it
+# in the unit. `Environment=` would expose the token in the unit file
+# (typically 644 = world-readable). EnvironmentFile keeps the token in
+# the user-owned secret file you already created with `chmod 600`.
+EnvironmentFile=%h/.qwen-serve-token-env
+Restart=on-failure
+RestartSec=5
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=default.target
+```
+
+Build the env file once (the token file from the setup step holds the raw value; this wraps it in `KEY=value` form so systemd reads it as an env assignment):
+
+```bash
+echo "QWEN_SERVER_TOKEN=$(cat ~/.qwen-serve-token)" > ~/.qwen-serve-token-env
+chmod 600 ~/.qwen-serve-token-env
+```
+
+Manage:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now qwen-serve.service
+loginctl enable-linger "$(whoami)"               # keep the user manager running after logout / across reboot
+journalctl --user -u qwen-serve -f               # tail logs
+systemctl --user restart qwen-serve.service     # after token rotation
+systemctl --user disable --now qwen-serve.service
+```
+
+Without `loginctl enable-linger`, the user-level systemd instance shuts down when the user logs out and only restarts on next login — on a headless dev box the daemon would not survive an SSH session ending. `enable-linger` is what makes "across reboots" actually work.
+
+**System-wide alternative** (shared dev hosts, less common): drop the unit at `/etc/systemd/system/qwen-serve@.service` with `User=%i`, manage via `sudo systemctl enable --now qwen-serve@<username>.service`. Same `[Service]` body otherwise — but world-readable `Environment=` exposure is even more problematic at this level, so always use `EnvironmentFile=` pointing at the user's `chmod 600` file. Pick user-level + linger for single-user workstations.
+
+## macOS: launchd user agent
+
+> **Find your `qwen` binary first.** Same constraint as systemd — `ProgramArguments` must hold an **absolute path**. Run `which qwen` to discover it. Common locations on macOS: `/opt/homebrew/bin/qwen` (Homebrew on Apple Silicon), `/usr/local/bin/qwen` (Homebrew on Intel, manual installs), `~/.nvm/versions/node/vX.Y.Z/bin/qwen` (nvm), `~/.volta/bin/qwen` (Volta). Substitute below where the template shows `/PATH/TO/qwen`.
+
+`~/Library/LaunchAgents/com.qwenlm.qwen-serve.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.qwenlm.qwen-serve</string>
+  <key>ProgramArguments</key>
+  <array>
+    <!-- Run `which qwen` to find the absolute path; launchd does NOT read $PATH. -->
+    <string>/PATH/TO/qwen</string>
+    <string>serve</string>
+    <string>--hostname</string>
+    <string>127.0.0.1</string>
+    <string>--port</string>
+    <string>4170</string>
+  </array>
+  <!-- launchd does NOT expand `~` or `$HOME` — use absolute paths. -->
+  <key>WorkingDirectory</key>
+  <string>/Users/YOUR-USERNAME/your-project</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <!-- DO NOT COMMIT this file with a real token. Also chmod 600 the
+         plist itself so the inlined token is not world-readable. -->
+    <key>QWEN_SERVER_TOKEN</key>
+    <string>PASTE-YOUR-TOKEN-HERE</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <!-- Restart only on non-zero exits (matches systemd Restart=on-failure).
+       A bare `<true/>` would respawn even after a clean SIGTERM, making
+       `kill <pid>` impossible to use as a stop signal — operator would
+       have to `launchctl unload`. SuccessfulExit=false fixes that. -->
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <!-- Throttle restart storms on persistent failures (mirrors systemd
+       RestartSec=5; launchd's default would respawn every <1s). -->
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <!-- Log into the user's Library, not /tmp. /tmp is world-writable
+       (symlink-attack risk on shared workstations) and gets cleaned by
+       periodic-daily after 3 days; `~/Library/Logs/qwen-serve/` is
+       user-scoped and survives. launchd truncates these on every
+       `load`, so the unload→load token-rotation cycle wipes prior
+       diagnostic logs — back them up if you need post-incident
+       inspection. -->
+  <key>StandardOutPath</key>
+  <string>/Users/YOUR-USERNAME/Library/Logs/qwen-serve/out.log</string>
+  <key>StandardErrorPath</key>
+  <string>/Users/YOUR-USERNAME/Library/Logs/qwen-serve/err.log</string>
+</dict>
+</plist>
+```
+
+Manage:
+
+```bash
+mkdir -p ~/Library/Logs/qwen-serve                                       # first time only
+chmod 600 ~/Library/LaunchAgents/com.qwenlm.qwen-serve.plist             # plist holds the inline token
+launchctl load   ~/Library/LaunchAgents/com.qwenlm.qwen-serve.plist
+launchctl unload ~/Library/LaunchAgents/com.qwenlm.qwen-serve.plist      # to stop
+tail -f ~/Library/Logs/qwen-serve/out.log ~/Library/Logs/qwen-serve/err.log
+```
+
+After editing the plist (e.g., rotating the token) you must `unload` then `load` again — `launchctl` does not auto-reload on plist changes the way `systemd daemon-reload` does. Note: each `load` truncates the log files, so save them off if you're investigating an incident before rotating.
+
+## tmux session (interactive supervision)
+
+Assumes `QWEN_SERVER_TOKEN` is already exported in your shell (see the setup section above):
+
+```bash
+tmux new -d -s qwen-serve "cd ~/your-project && qwen serve --hostname 127.0.0.1"
+tmux attach -t qwen-serve   # see live logs; Ctrl-b d to detach
+tmux kill-session -t qwen-serve
+```
+
+`tmux new -d` inherits the parent shell's environment, so `QWEN_SERVER_TOKEN` flows through automatically. Best when you want to occasionally watch the daemon's stdout (auth warnings, MCP discovery progress, slow-client warnings) without committing to a service unit. Survives terminal close but not host reboot.
+
+## nohup one-liner (quick + dirty)
+
+Assumes `QWEN_SERVER_TOKEN` is already exported in your shell:
+
+```bash
+nohup bash -c 'cd ~/your-project && qwen serve --hostname 127.0.0.1' > qwen-serve.log 2>&1 &
+echo $!  # daemon PID; capture if you want to `kill` cleanly later
+```
+
+The wrapping `bash -c '...'` ensures the daemon binds to `~/your-project` rather than wherever you happened to run the command. Without that `cd`, `qwen serve` defaults to `process.cwd()` and a `POST /session` from a client expecting your project workspace returns `400 workspace_mismatch` — silent foot-gun.
+
+OK for one-off "let me run this in the background while I poke at the API" workflows. **Not recommended** for anything beyond a single session — no restart-on-crash, log file grows unbounded, no clean way to find the daemon if you forget the PID. Prefer tmux for interactive supervision or systemd / launchd for anything you want to outlast a reboot.
+
+## Verifying the daemon is up
+
+```bash
+curl http://127.0.0.1:4170/health                                   # → {"status":"ok"}
+curl -H "Authorization: Bearer $QWEN_SERVER_TOKEN" \
+  http://127.0.0.1:4170/capabilities | jq .protocolVersions         # daemon's feature set
+```
+
+When auth is configured (i.e., the daemon was started with `--token` / `QWEN_SERVER_TOKEN` set, OR `--require-auth=true`), every route except `/health` on loopback binds requires `Authorization: Bearer <token>`. If you started the daemon without a token on the loopback default (the `qwen serve` zero-config path), neither call requires a header. The templates above all configure a token, so the `Authorization` header is needed in practice. If `/capabilities` returns `401`, the unit / plist token doesn't match the env-exported token your `curl` is using.
+
+## Token rotation
+
+1. Generate a new token + write the env file the unit references:
+   ```bash
+   openssl rand -hex 32 > ~/.qwen-serve-token
+   chmod 600 ~/.qwen-serve-token
+   echo "QWEN_SERVER_TOKEN=$(cat ~/.qwen-serve-token)" > ~/.qwen-serve-token-env
+   chmod 600 ~/.qwen-serve-token-env
+   ```
+   (For the launchd / nohup / tmux templates: edit the plist's `<string>` value or re-`export QWEN_SERVER_TOKEN`. Don't forget `chmod 600` on the plist if you regenerate it.)
+2. Restart the daemon:
+   - **systemd**: `systemctl --user restart qwen-serve.service`
+   - **launchd**: `launchctl unload ~/Library/LaunchAgents/com.qwenlm.qwen-serve.plist && launchctl load ~/Library/LaunchAgents/com.qwenlm.qwen-serve.plist`
+   - **tmux / nohup**: `kill <pid>` then re-run with the new token in env
+3. Update any client SDKs / scripts. The TypeScript SDK's `DaemonClient` reads `QWEN_SERVER_TOKEN` automatically (PR 27 fallback) — re-`export` the new value in any client shell and reconstruct the client.
+
+## Restart and crash behavior
+
+Service-manager restart semantics differ across the templates:
+
+- **systemd `Restart=on-failure`** — restart only on non-zero exit / signal. A clean SIGTERM (`systemctl stop`) does **not** trigger a restart loop.
+- **launchd `KeepAlive` with `SuccessfulExit=false`** (the template above) — matches systemd behavior. A bare `<true/>` would have respawned even after a clean exit. `ThrottleInterval=10` rate-limits restart storms on persistent failures, mirroring systemd's `RestartSec=5`.
+- **tmux / nohup** — no automatic restart. A daemon crash leaves you with a dead PID until you re-run.
+
+Within a **single daemon process lifetime**, client disconnects recover via SSE `Last-Event-ID` resume per the [Durability model](./qwen-serve.md#durability-model) section of the user guide — the replay ring is in-memory.
+
+A daemon **restart** drops all in-memory sessions; clients reconnect and start fresh. Cross-restart durability of session content (prompts, tool calls, conversation history) is **NOT** in v0.16-alpha.
+
+## Out of scope (defers to v0.16.x or later)
+
+- **Containerized deployment** — Dockerfile, docker-compose, Kubernetes manifests, nginx + TLS reverse proxy, multi-instance token isolation. Defers to v0.16.x once an enterprise pilot is committed; the doc would otherwise rot from no-one-validating.
+- **Cross-host federation / multi-daemon coordination on one host** — `1 daemon = 1 workspace × N sessions` is enforced. Instance-path token keying + stale-token cleanup defer to v0.16.x.
+- **Auto-generated daemon tokens** — alpha is BYO-token. Auto-gen + token-store infrastructure defers to v0.16.x.
+- **Windows native service** (`nssm`, Service Control Manager wrapper) — for now use [WSL2](https://learn.microsoft.com/en-us/windows/wsl/) and follow the systemd section above.
+
+See the [v0.16-alpha known limits](./qwen-serve.md#v016-alpha-known-limits) callout in the main user guide for the full deferred-features list, and [#4175](https://github.com/QwenLM/qwen-code/issues/4175) for the v0.16-alpha rollout tracking issue.