@protolabsai/proto 0.14.0

package/dist/bundled/qc-helper/docs/features/mcp.md

@@ -0,0 +1,281 @@
+# Connect Qwen Code to tools via MCP
+
+Qwen Code can connect to external tools and data sources through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction). MCP servers give Qwen Code access to your tools, databases, and APIs.
+
+## What you can do with MCP
+
+With MCP servers connected, you can ask Qwen Code to:
+
+- Work with files and repos (read/search/write, depending on the tools you enable)
+- Query databases (schema inspection, queries, reporting)
+- Integrate internal services (wrap your APIs as MCP tools)
+- Automate workflows (repeatable tasks exposed as tools/prompts)
+
+> [!tip]
+>
+> If you’re looking for the “one command to get started”, jump to [Quick start](#quick-start).
+
+## Quick start
+
+Qwen Code loads MCP servers from `mcpServers` in your `settings.json`. You can configure servers either:
+
+- By editing `settings.json` directly
+- By using `qwen mcp` commands (see [CLI reference](#qwen-mcp-cli))
+
+### Add your first server
+
+1. Add a server (example: remote HTTP MCP server):
+
+```bash
+qwen mcp add --transport http my-server http://localhost:3000/mcp
+```
+
+2. Open MCP management dialog to view and manage servers:
+
+```bash
+qwen mcp
+```
+
+3. Restart Qwen Code in the same project (or start it if it wasn’t running yet), then ask the model to use tools from that server.
+
+## Where configuration is stored (scopes)
+
+Most users only need these two scopes:
+
+- **Project scope (default)**: `.qwen/settings.json` in your project root
+- **User scope**: `~/.qwen/settings.json` across all projects on your machine
+
+Write to user scope:
+
+```bash
+qwen mcp add --scope user --transport http my-server http://localhost:3000/mcp
+```
+
+> [!tip]
+>
+> For advanced configuration layers (system defaults/system settings and precedence rules), see [Settings](../configuration/settings).
+
+## Configure servers
+
+### Choose a transport
+
+| Transport | When to use                                                       | JSON field(s)                               |
+| --------- | ----------------------------------------------------------------- | ------------------------------------------- |
+| `http`    | Recommended for remote services; works well for cloud MCP servers | `httpUrl` (+ optional `headers`)            |
+| `sse`     | Legacy/deprecated servers that only support Server-Sent Events    | `url` (+ optional `headers`)                |
+| `stdio`   | Local process (scripts, CLIs, Docker) on your machine             | `command`, `args` (+ optional `cwd`, `env`) |
+
+> [!note]
+>
+> If a server supports both, prefer **HTTP** over **SSE**.
+
+### Configure via `settings.json` vs `qwen mcp add`
+
+Both approaches produce the same `mcpServers` entries in your `settings.json`—use whichever you prefer.
+
+#### Stdio server (local process)
+
+JSON (`.qwen/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "pythonTools": {
+      "command": "python",
+      "args": ["-m", "my_mcp_server", "--port", "8080"],
+      "cwd": "./mcp-servers/python",
+      "env": {
+        "DATABASE_URL": "$DB_CONNECTION_STRING",
+        "API_KEY": "${EXTERNAL_API_KEY}"
+      },
+      "timeout": 15000
+    }
+  }
+}
+```
+
+CLI (writes to project scope by default):
+
+```bash
+qwen mcp add pythonTools -e DATABASE_URL=$DB_CONNECTION_STRING -e API_KEY=$EXTERNAL_API_KEY \
+  --timeout 15000 python -m my_mcp_server --port 8080
+```
+
+#### HTTP server (remote streamable HTTP)
+
+JSON:
+
+```json
+{
+  "mcpServers": {
+    "httpServerWithAuth": {
+      "httpUrl": "http://localhost:3000/mcp",
+      "headers": {
+        "Authorization": "Bearer your-api-token"
+      },
+      "timeout": 5000
+    }
+  }
+}
+```
+
+CLI:
+
+```bash
+qwen mcp add --transport http httpServerWithAuth http://localhost:3000/mcp \
+  --header "Authorization: Bearer your-api-token" --timeout 5000
+```
+
+#### SSE server (remote Server-Sent Events)
+
+JSON:
+
+```json
+{
+  "mcpServers": {
+    "sseServer": {
+      "url": "http://localhost:8080/sse",
+      "timeout": 30000
+    }
+  }
+}
+```
+
+CLI:
+
+```bash
+qwen mcp add --transport sse sseServer http://localhost:8080/sse --timeout 30000
+```
+
+## Safety and control
+
+### Trust (skip confirmations)
+
+- **Server trust** (`trust: true`): bypasses confirmation prompts for that server (use sparingly).
+
+### Tool filtering (allow/deny tools per server)
+
+Use `includeTools` / `excludeTools` to restrict tools exposed by a server (from Qwen Code’s perspective).
+
+Example: include only a few tools:
+
+```json
+{
+  "mcpServers": {
+    "filteredServer": {
+      "command": "python",
+      "args": ["-m", "my_mcp_server"],
+      "includeTools": ["safe_tool", "file_reader", "data_processor"],
+      "timeout": 30000
+    }
+  }
+}
+```
+
+### Global allow/deny lists
+
+The `mcp` object in your `settings.json` defines global rules for all MCP servers:
+
+- `mcp.allowed`: allow-list of MCP server names (keys in `mcpServers`)
+- `mcp.excluded`: deny-list of MCP server names
+
+Example:
+
+```json
+{
+  "mcp": {
+    "allowed": ["my-trusted-server"],
+    "excluded": ["experimental-server"]
+  }
+}
+```
+
+## Troubleshooting
+
+- **Server shows “Disconnected” in `qwen mcp list`**: verify the URL/command is correct, then increase `timeout`.
+- **Stdio server fails to start**: use an absolute `command` path, and double-check `cwd`/`env`.
+- **Environment variables in JSON don’t resolve**: ensure they exist in the environment where Qwen Code runs (shell vs GUI app environments can differ).
+
+## Reference
+
+### `settings.json` structure
+
+#### Server-specific configuration (`mcpServers`)
+
+Add an `mcpServers` object to your `settings.json` file:
+
+```json
+// ... file contains other config objects
+{
+  "mcpServers": {
+    "serverName": {
+      "command": "path/to/server",
+      "args": ["--arg1", "value1"],
+      "env": {
+        "API_KEY": "$MY_API_TOKEN"
+      },
+      "cwd": "./server-directory",
+      "timeout": 30000,
+      "trust": false
+    }
+  }
+}
+```
+
+Configuration properties:
+
+Required (one of the following):
+
+| Property  | Description                                            |
+| --------- | ------------------------------------------------------ |
+| `command` | Path to the executable for Stdio transport             |
+| `url`     | SSE endpoint URL (e.g., `"http://localhost:8080/sse"`) |
+| `httpUrl` | HTTP streaming endpoint URL                            |
+
+Optional:
+
+| Property               | Type/Default                 | Description                                                                                                                                                                                                                                                       |
+| ---------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `args`                 | array                        | Command-line arguments for Stdio transport                                                                                                                                                                                                                        |
+| `headers`              | object                       | Custom HTTP headers when using `url` or `httpUrl`                                                                                                                                                                                                                 |
+| `env`                  | object                       | Environment variables for the server process. Values can reference environment variables using `$VAR_NAME` or `${VAR_NAME}` syntax                                                                                                                                |
+| `cwd`                  | string                       | Working directory for Stdio transport                                                                                                                                                                                                                             |
+| `timeout`              | number<br>(default: 600,000) | Request timeout in milliseconds (default: 600,000ms = 10 minutes)                                                                                                                                                                                                 |
+| `trust`                | boolean<br>(default: false)  | When `true`, bypasses all tool call confirmations for this server (default: `false`)                                                                                                                                                                              |
+| `includeTools`         | array                        | List of tool names to include from this MCP server. When specified, only the tools listed here will be available from this server (allowlist behavior). If not specified, all tools from the server are enabled by default.                                       |
+| `excludeTools`         | array                        | List of tool names to exclude from this MCP server. Tools listed here will not be available to the model, even if they are exposed by the server.<br>Note: `excludeTools` takes precedence over `includeTools` - if a tool is in both lists, it will be excluded. |
+| `targetAudience`       | string                       | The OAuth Client ID allowlisted on the IAP-protected application you are trying to access. Used with `authProviderType: 'service_account_impersonation'`.                                                                                                         |
+| `targetServiceAccount` | string                       | The email address of the Google Cloud Service Account to impersonate. Used with `authProviderType: 'service_account_impersonation'`.                                                                                                                              |
+
+<a id="qwen-mcp-cli"></a>
+
+### Manage MCP servers with `qwen mcp`
+
+You can always configure MCP servers by manually editing `settings.json`, but the CLI is usually faster.
+
+#### Adding a server (`qwen mcp add`)
+
+```bash
+qwen mcp add [options] <name> <commandOrUrl> [args...]
+```
+
+| Argument/Option     | Description                                                         | Default            | Example                                   |
+| ------------------- | ------------------------------------------------------------------- | ------------------ | ----------------------------------------- |
+| `<name>`            | A unique name for the server.                                       | —                  | `example-server`                          |
+| `<commandOrUrl>`    | The command to execute (for `stdio`) or the URL (for `http`/`sse`). | —                  | `/usr/bin/python` or `http://localhost:8` |
+| `[args...]`         | Optional arguments for a `stdio` command.                           | —                  | `--port 5000`                             |
+| `-s`, `--scope`     | Configuration scope (user or project).                              | `project`          | `-s user`                                 |
+| `-t`, `--transport` | Transport type (`stdio`, `sse`, `http`).                            | `stdio`            | `-t sse`                                  |
+| `-e`, `--env`       | Set environment variables.                                          | —                  | `-e KEY=value`                            |
+| `-H`, `--header`    | Set HTTP headers for SSE and HTTP transports.                       | —                  | `-H "X-Api-Key: abc123"`                  |
+| `--timeout`         | Set connection timeout in milliseconds.                             | —                  | `--timeout 30000`                         |
+| `--trust`           | Trust the server (bypass all tool call confirmation prompts).       | — (`false`)        | `--trust`                                 |
+| `--description`     | Set the description for the server.                                 | —                  | `--description "Local tools"`             |
+| `--include-tools`   | A comma-separated list of tools to include.                         | all tools included | `--include-tools mytool,othertool`        |
+| `--exclude-tools`   | A comma-separated list of tools to exclude.                         | none               | `--exclude-tools mytool`                  |
+
+#### Removing a server (`qwen mcp remove`)
+
+```bash
+qwen mcp remove <name>
+```

package/dist/bundled/qc-helper/docs/features/sandbox.md

@@ -0,0 +1,241 @@
+# Sandbox
+
+This document explains how to run Qwen Code inside a sandbox to reduce risk when tools execute shell commands or modify files.
+
+## Prerequisites
+
+Before using sandboxing, you need to install and set up Qwen Code:
+
+```bash
+npm install -g @qwen-code/qwen-code
+```
+
+To verify the installation
+
+```bash
+qwen --version
+```
+
+## Overview of sandboxing
+
+Sandboxing isolates potentially dangerous operations (such as shell commands or file modifications) from your host system, providing a security barrier between the CLI and your environment.
+
+The benefits of sandboxing include:
+
+- **Security**: Prevent accidental system damage or data loss.
+- **Isolation**: Limit file system access to project directory.
+- **Consistency**: Ensure reproducible environments across different systems.
+- **Safety**: Reduce risk when working with untrusted code or experimental commands.
+
+> [!note]
+>
+> **Naming note:** Some sandbox-related environment variables may have used the `GEMINI_*` prefix historically. All new environment variables use the `QWEN_*` prefix.
+
+## Sandboxing methods
+
+Your ideal method of sandboxing may differ depending on your platform and your preferred container solution.
+
+### 1. macOS Seatbelt (macOS only)
+
+Lightweight, built-in sandboxing using `sandbox-exec`.
+
+**Default profile**: `permissive-open` - restricts writes outside the project directory, but allows most other operations and outbound network access.
+
+**Best for**: Fast, no Docker required, strong guardrails for file writes.
+
+### 2. Container-based (Docker/Podman)
+
+Cross-platform sandboxing with complete process isolation.
+
+By default, Qwen Code uses a published sandbox image (configured in the CLI package) and will pull it as needed.
+
+The container sandbox mounts your workspace and your `~/.qwen` directory into the container so auth and settings persist between runs.
+
+**Best for**: Strong isolation on any OS, consistent tooling inside a known image.
+
+### Choosing a method
+
+- **On macOS**:
+  - Use Seatbelt when you want lightweight sandboxing (recommended for most users).
+  - Use Docker/Podman when you need a full Linux userland (e.g., tools that require Linux binaries).
+- **On Linux/Windows**:
+  - Use Docker or Podman.
+
+## Quickstart
+
+```bash
+# Enable sandboxing with command flag
+qwen -s -p "analyze the code structure"
+
+# Or enable sandboxing for your shell session (recommended for CI / scripts)
+export QWEN_SANDBOX=true   # true auto-picks a provider (see notes below)
+qwen -p "run the test suite"
+
+# Configure in settings.json
+{
+  "tools": {
+    "sandbox": true
+  }
+}
+```
+
+> [!tip]
+>
+> **Provider selection notes:**
+>
+> - On **macOS**, `QWEN_SANDBOX=true` typically selects `sandbox-exec` (Seatbelt) if available.
+> - On **Linux/Windows**, `QWEN_SANDBOX=true` requires `docker` or `podman` to be installed.
+> - To force a provider, set `QWEN_SANDBOX=docker|podman|sandbox-exec`.
+
+## Configuration
+
+### Enable sandboxing (in order of precedence)
+
+1. **Environment variable**: `QWEN_SANDBOX=true|false|docker|podman|sandbox-exec`
+2. **Command flag / argument**: `-s`, `--sandbox`, or `--sandbox=<provider>`
+3. **Settings file**: `tools.sandbox` in your `settings.json` (e.g., `{"tools": {"sandbox": true}}`).
+
+> [!important]
+>
+> If `QWEN_SANDBOX` is set, it **overrides** the CLI flag and `settings.json`.
+
+### Configure the sandbox image (Docker/Podman)
+
+- **CLI flag**: `--sandbox-image <image>`
+- **Environment variable**: `QWEN_SANDBOX_IMAGE=<image>`
+
+If you don’t set either, Qwen Code uses the default image configured in the CLI package (for example `ghcr.io/qwenlm/qwen-code:<version>`).
+
+### macOS Seatbelt profiles
+
+Built-in profiles (set via `SEATBELT_PROFILE` env var):
+
+- `permissive-open` (default): Write restrictions, network allowed
+- `permissive-closed`: Write restrictions, no network
+- `permissive-proxied`: Write restrictions, network via proxy
+- `restrictive-open`: Strict restrictions, network allowed
+- `restrictive-closed`: Maximum restrictions
+- `restrictive-proxied`: Strict restrictions, network via proxy
+
+> [!tip]
+>
+> Start with `permissive-open`, then tighten to `restrictive-closed` if your workflow still works.
+
+### Custom Seatbelt profiles (macOS)
+
+To use a custom Seatbelt profile:
+
+1. Create a file named `.qwen/sandbox-macos-<profile_name>.sb` in your project.
+2. Set `SEATBELT_PROFILE=<profile_name>`.
+
+### Custom Sandbox Flags
+
+For container-based sandboxing, you can inject custom flags into the `docker` or `podman` command using the `SANDBOX_FLAGS` environment variable. This is useful for advanced configurations, such as disabling security features for specific use cases.
+
+**Example (Podman)**:
+
+To disable SELinux labeling for volume mounts, you can set the following:
+
+```bash
+export SANDBOX_FLAGS="--security-opt label=disable"
+```
+
+Multiple flags can be provided as a space-separated string:
+
+```bash
+export SANDBOX_FLAGS="--flag1 --flag2=value"
+```
+
+### Network proxying (all sandbox methods)
+
+If you want to restrict outbound network access to an allowlist, you can run a local proxy alongside the sandbox:
+
+- Set `QWEN_SANDBOX_PROXY_COMMAND=<command>`
+- The command must start a proxy server that listens on `:::8877`
+
+This is especially useful with `*-proxied` Seatbelt profiles.
+
+For a working allowlist-style proxy example, see: [Example Proxy Script](/developers/examples/proxy-script).
+
+## Linux UID/GID handling
+
+On Linux, Qwen Code defaults to enabling UID/GID mapping so the sandbox runs as your user (and reuses the mounted `~/.qwen`). Override with:
+
+```bash
+export SANDBOX_SET_UID_GID=true   # Force host UID/GID
+export SANDBOX_SET_UID_GID=false  # Disable UID/GID mapping
+```
+
+## Troubleshooting
+
+### Common issues
+
+**"Operation not permitted"**
+
+- Operation requires access outside sandbox.
+- On macOS Seatbelt: try a more permissive `SEATBELT_PROFILE`.
+- On Docker/Podman: verify the workspace is mounted and your command doesn’t require access outside the project directory.
+
+**Missing commands**
+
+- Container sandbox: add them via `.qwen/sandbox.Dockerfile` or `.qwen/sandbox.bashrc`.
+- Seatbelt: your host binaries are used, but the sandbox may restrict access to some paths.
+
+**Java not available in Docker sandbox**
+
+The official Qwen Code Docker image is intentionally minimal to keep the image small, secure, and fast to pull. Different users require different language runtimes (Java, Python, Node.js, etc.), and bundling all environments into a single image is not practical. Therefore, Java is **not included by default** in the Docker sandbox.
+
+If your workflow requires Java, you can extend the base image by creating a `.qwen/sandbox.Dockerfile` in your project:
+
+```dockerfile
+FROM ghcr.io/qwenlm/qwen-code:latest
+
+RUN apt-get update && \
+    apt-get install -y openjdk-17-jre && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+```
+
+Then rebuild the sandbox image:
+
+```bash
+QWEN_SANDBOX=docker BUILD_SANDBOX=1 qwen -s
+```
+
+For more details on customizing the sandbox, see [Customizing the sandbox environment](/developers/tools/sandbox).
+
+**Network issues**
+
+- Check sandbox profile allows network.
+- Verify proxy configuration.
+
+### Debug mode
+
+```bash
+DEBUG=1 qwen -s -p "debug command"
+```
+
+**Note:** If you have `DEBUG=true` in a project's `.env` file, it won't affect the CLI due to automatic exclusion. Use `.qwen/.env` files for Qwen Code-specific debug settings.
+
+### Inspect sandbox
+
+```bash
+# Check environment
+qwen -s -p "run shell command: env | grep SANDBOX"
+
+# List mounts
+qwen -s -p "run shell command: mount | grep workspace"
+```
+
+## Security notes
+
+- Sandboxing reduces but doesn't eliminate all risks.
+- Use the most restrictive profile that allows your work.
+- Container overhead is minimal after the first pull/build.
+- GUI applications may not work in sandboxes.
+
+## Related documentation
+
+- [Configuration](../configuration/settings): Full configuration options.
+- [Commands](../features/commands): Available commands.
+- [Troubleshooting](../support/troubleshooting): General troubleshooting.

package/dist/bundled/qc-helper/docs/features/scheduled-tasks.md

@@ -0,0 +1,139 @@
+# Run Prompts on a Schedule
+
+> Use `/loop` and the cron scheduling tools to run prompts repeatedly, poll for status, or set one-time reminders within a Qwen Code session.
+
+Scheduled tasks let Qwen Code re-run a prompt automatically on an interval. Use them to poll a deployment, babysit a PR, check back on a long-running build, or remind yourself to do something later in the session.
+
+Tasks are session-scoped: they live in the current Qwen Code process and are gone when you exit. Nothing is written to disk.
+
+> **Note:** Scheduled tasks are an experimental feature. Enable them with `experimental.cron: true` in your [settings](../configuration/settings.md), or set `QWEN_CODE_ENABLE_CRON=1` in your environment.
+
+## Schedule a recurring prompt with /loop
+
+The `/loop` [bundled skill](skills.md) is the quickest way to schedule a recurring prompt. Pass an optional interval and a prompt, and Qwen Code sets up a cron job that fires in the background while the session stays open.
+
+```text
+/loop 5m check if the deployment finished and tell me what happened
+```
+
+Qwen Code parses the interval, converts it to a cron expression, schedules the job, and confirms the cadence and job ID. It then immediately executes the prompt once — you don't have to wait for the first cron fire.
+
+### Interval syntax
+
+Intervals are optional. You can lead with them, trail with them, or leave them out entirely.
+
+| Form                    | Example                               | Parsed interval              |
+| :---------------------- | :------------------------------------ | :--------------------------- |
+| Leading token           | `/loop 30m check the build`           | every 30 minutes             |
+| Trailing `every` clause | `/loop check the build every 2 hours` | every 2 hours                |
+| No interval             | `/loop check the build`               | defaults to every 10 minutes |
+
+Supported units are `s` for seconds, `m` for minutes, `h` for hours, and `d` for days. Seconds are rounded up to the nearest minute since cron has one-minute granularity. Intervals that don't divide evenly into their unit, such as `7m` or `90m`, are rounded to the nearest clean interval and Qwen Code tells you what it picked.
+
+### Loop over another command
+
+The scheduled prompt can itself be a command or skill invocation. This is useful for re-running a workflow you've already packaged.
+
+```text
+/loop 20m /review-pr 1234
+```
+
+Each time the job fires, Qwen Code runs `/review-pr 1234` as if you had typed it.
+
+### Manage loops
+
+`/loop` also supports two subcommands for managing existing jobs:
+
+```text
+/loop list
+```
+
+Lists all scheduled jobs with their IDs and cron expressions.
+
+```text
+/loop clear
+```
+
+Cancels all scheduled jobs at once.
+
+## Set a one-time reminder
+
+For one-shot reminders, describe what you want in natural language instead of using `/loop`. Qwen Code schedules a single-fire task that deletes itself after running.
+
+```text
+remind me at 3pm to push the release branch
+```
+
+```text
+in 45 minutes, check whether the integration tests passed
+```
+
+Qwen Code pins the fire time to a specific minute and hour using a cron expression and confirms when it will fire.
+
+## Manage scheduled tasks
+
+Ask Qwen Code in natural language to list or cancel tasks, or reference the underlying tools directly.
+
+```text
+what scheduled tasks do I have?
+```
+
+```text
+cancel the deploy check job
+```
+
+Under the hood, Qwen Code uses these tools:
+
+| Tool         | Purpose                                                                                                         |
+| :----------- | :-------------------------------------------------------------------------------------------------------------- |
+| `CronCreate` | Schedule a new task. Accepts a 5-field cron expression, the prompt to run, and whether it recurs or fires once. |
+| `CronList`   | List all scheduled tasks with their IDs, schedules, and prompts.                                                |
+| `CronDelete` | Cancel a task by ID.                                                                                            |
+
+Each scheduled task has an 8-character ID you can pass to `CronDelete`. A session can hold up to 50 scheduled tasks at once.
+
+## How scheduled tasks run
+
+The scheduler checks every second for due tasks and enqueues them when the session is idle. A scheduled prompt fires between your turns, not while Qwen Code is mid-response. If Qwen Code is busy when a task comes due, the prompt waits until the current turn ends.
+
+All times are interpreted in your local timezone. A cron expression like `0 9 * * *` means 9am wherever you're running Qwen Code, not UTC.
+
+### Jitter
+
+To avoid every session hitting the API at the same wall-clock moment, the scheduler adds a small deterministic offset to fire times:
+
+- **Recurring tasks** fire up to 10% of their period late, capped at 15 minutes. An hourly job might fire anywhere from `:00` to `:06`.
+- **One-shot tasks** scheduled for the top or bottom of the hour (minute `:00` or `:30`) fire up to 90 seconds early.
+
+The offset is derived from the task ID, so the same task always gets the same offset. If exact timing matters, pick a minute that is not `:00` or `:30`, for example `3 9 * * *` instead of `0 9 * * *`, and the one-shot jitter will not apply.
+
+### Three-day expiry
+
+Recurring tasks automatically expire 3 days after creation. The task fires one final time, then deletes itself. This bounds how long a forgotten loop can run. If you need a recurring task to last longer, cancel and recreate it before it expires.
+
+One-shot tasks do not expire on a timer — they simply delete themselves after firing once.
+
+## Cron expression reference
+
+`CronCreate` accepts standard 5-field cron expressions: `minute hour day-of-month month day-of-week`. All fields support wildcards (`*`), single values (`5`), steps (`*/15`), ranges (`1-5`), and comma-separated lists (`1,15,30`).
+
+| Example        | Meaning                      |
+| :------------- | :--------------------------- |
+| `*/5 * * * *`  | Every 5 minutes              |
+| `0 * * * *`    | Every hour on the hour       |
+| `7 * * * *`    | Every hour at 7 minutes past |
+| `0 9 * * *`    | Every day at 9am local       |
+| `0 9 * * 1-5`  | Weekdays at 9am local        |
+| `30 14 15 3 *` | March 15 at 2:30pm local     |
+
+Day-of-week uses `0` or `7` for Sunday through `6` for Saturday. When both day-of-month and day-of-week are constrained (neither is `*`), a date matches if either field matches — this follows standard vixie-cron semantics.
+
+Extended syntax like `L`, `W`, `?`, and name aliases such as `MON` or `JAN` is not supported.
+
+## Limitations
+
+Session-scoped scheduling has inherent constraints:
+
+- Tasks only fire while Qwen Code is running and idle. Closing the terminal or letting the session exit cancels everything.
+- No catch-up for missed fires. If a task's scheduled time passes while Qwen Code is busy on a long-running request, it fires once when Qwen Code becomes idle, not once per missed interval.
+- No persistence across restarts. Restarting Qwen Code clears all session-scoped tasks.