cc-viewer 1.6.182 → 1.6.183

package/concepts/en/Tool-Read.md

@@ -1,56 +1,41 @@
 # Read
 
-## Definition
+Loads the contents of a single file from the local filesystem. Supports plain text, source code, images, PDFs, and Jupyter notebooks, returning results with 1-based line numbers in `cat -n` style.
 
-Reads file contents from the local filesystem. Supports text files, images, PDFs, and Jupyter notebooks.
+## When to Use
+
+- Reading a source file at a known path before editing or analysis
+- Inspecting configuration files, lockfiles, logs, or generated artifacts
+- Viewing screenshots or diagrams the user pasted into the conversation
+- Extracting a specific page range from a long PDF manual
+- Opening a `.ipynb` notebook to review code cells, markdown, and cell outputs together
 
 ## Parameters
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `file_path` | string | Yes | Absolute path of the file |
-| `offset` | number | No | Starting line number (for reading large files in segments) |
-| `limit` | number | No | Number of lines to read (for reading large files in segments) |
-| `pages` | string | No | PDF page range (e.g., "1-5", "3", "10-20"), only applicable to PDFs |
+- `file_path` (string, required): Absolute path to the target file. Relative paths are rejected.
+- `offset` (integer, optional): 1-based line number to start reading from. Useful for large files when paired with `limit`.
+- `limit` (integer, optional): Maximum number of lines to return starting at `offset`. Defaults to 2000 lines from the top of the file when omitted.
+- `pages` (string, optional): Page range for PDF files, for example `"1-5"`, `"3"`, or `"10-20"`. Required for PDFs longer than 10 pages; maximum 20 pages per request.
+
+## Examples
+
+### Example 1: Read an entire small file
+Call `Read` with only `file_path` set to `/Users/me/project/src/index.ts`. Up to 2000 lines are returned with line numbers, which is usually sufficient for editing context.
 
-## Use Cases
+### Example 2: Page through a long log
+Use `offset: 5001` and `limit: 500` on a multi-thousand-line log file to retrieve a narrow window without wasting context tokens.
 
-**Good for:**
-- Reading code files, configuration files, and other text files
-- Viewing image files (Claude is a multimodal model)
-- Reading PDF documents
-- Reading Jupyter notebooks (returns all cells with outputs)
-- Reading multiple files in parallel to gather context
+### Example 3: Extract specific PDF pages
+For a 120-page PDF at `/tmp/spec.pdf`, set `pages: "8-15"` to pull only the chapter you need. Omitting `pages` on a large PDF produces an error.
 
-**Not good for:**
-- Reading directories — use the `ls` command in Bash instead
-- Open-ended codebase exploration — use Task (Explore type) instead
+### Example 4: View an image
+Pass the absolute path of a PNG or JPG screenshot. The image is rendered visually so Claude Code can reason about it directly.
 
 ## Notes
 
-- The path must be an absolute path, not a relative path
-- Reads the first 2000 lines of a file by default
-- Lines exceeding 2000 characters will be truncated
-- Output uses `cat -n` format, with line numbers starting at 1
-- Large PDFs (over 10 pages) must specify the `pages` parameter, max 20 pages per call
-- Reading a non-existent file returns an error (does not crash)
-- Multiple Read calls can be issued in parallel within a single message
-
-## Original Text
-
-<textarea readonly>Reads a file from the local filesystem. You can access any file directly by using this tool.
-Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
-
-Usage:
-- The file_path parameter must be an absolute path, not a relative path
-- By default, it reads up to 2000 lines starting from the beginning of the file
-- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters
-- Any lines longer than 2000 characters will be truncated
-- Results are returned using cat -n format, with line numbers starting at 1
-- This tool allows Claude Code to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Claude Code is a multimodal LLM.
-- This tool can read PDF files (.pdf). For large PDFs (more than 10 pages), you MUST provide the pages parameter to read specific page ranges (e.g., pages: "1-5"). Reading a large PDF without the pages parameter will fail. Maximum 20 pages per request.
-- This tool can read Jupyter notebooks (.ipynb files) and returns all cells with their outputs, combining code, text, and visualizations.
-- This tool can only read files, not directories. To read a directory, use an ls command via the Bash tool.
-- You can call multiple tools in a single response. It is always better to speculatively read multiple potentially useful files in parallel.
-- You will regularly be asked to read screenshots. If the user provides a path to a screenshot, ALWAYS use this tool to view the file at the path. This tool will work with all temporary file paths.
-- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.</textarea>
+- Always prefer absolute paths. If the user provides one, trust it as-is.
+- Lines longer than 2000 characters are truncated; treat the returned content as possibly clipped for extremely wide data.
+- Reading multiple independent files? Issue several `Read` calls in the same response so they run in parallel.
+- `Read` cannot list directories. Use a `Bash` `ls` call or the `Glob` tool instead.
+- Reading an existing but empty file returns a system reminder rather than file bytes, so handle that signal explicitly.
+- A successful `Read` is required before you can use `Edit` on the same file in the current session.

package/concepts/en/Tool-RemoteTrigger.md

@@ -0,0 +1,73 @@
+# RemoteTrigger
+
+Call the claude.ai remote-trigger API to manage scheduled and on-demand trigger execution. The OAuth token is handled internally and is never exposed to the model or shell.
+
+## When to Use
+
+- Managing scheduled remote agents (triggers) on claude.ai, including listing, inspecting, and updating existing ones
+- Creating a new cron-based automated task that runs a Claude agent on a recurring schedule
+- Firing an existing trigger on demand without waiting for its next scheduled run
+- Listing or auditing all current triggers to review their configuration and status
+- Updating trigger settings such as schedule, payload, or description without recreating the trigger
+
+## Parameters
+
+- `action` (string, required): the operation to perform — one of `list`, `get`, `create`, `update`, or `run`
+- `trigger_id` (string, required for `get`, `update`, and `run`): the identifier of the trigger to operate on; must match the pattern `^[\w-]+$` (word characters and dashes only)
+- `body` (object, required for `create` and `update`; optional for `run`): the request payload sent to the API
+
+## Examples
+
+### Example 1: list all triggers
+
+```json
+{
+  "action": "list"
+}
+```
+
+This calls `GET /v1/code/triggers` and returns a JSON array of all triggers associated with the authenticated account.
+
+### Example 2: create a new trigger that runs every weekday morning
+
+```json
+{
+  "action": "create",
+  "body": {
+    "name": "weekday-morning-report",
+    "schedule": "0 8 * * 1-5",
+    "description": "Generate a daily summary every weekday at 08:00 UTC"
+  }
+}
+```
+
+This calls `POST /v1/code/triggers` with the provided body and returns the newly created trigger object, including its assigned `trigger_id`.
+
+### Example 3: fire a trigger on demand
+
+```json
+{
+  "action": "run",
+  "trigger_id": "my-report-trigger"
+}
+```
+
+This calls `POST /v1/code/triggers/my-report-trigger/run` immediately, bypassing the scheduled time.
+
+### Example 4: fetch a single trigger
+
+```json
+{
+  "action": "get",
+  "trigger_id": "my-report-trigger"
+}
+```
+
+This calls `GET /v1/code/triggers/my-report-trigger` and returns the full trigger configuration.
+
+## Notes
+
+- The OAuth token is injected in-process by the tool — never copy, paste, or log tokens manually; doing so creates a security risk and is unnecessary when using this tool.
+- Prefer this tool over raw `curl` or other HTTP clients for all trigger API calls; using direct HTTP bypasses the secure token injection and may expose credentials.
+- The tool returns the raw JSON response from the API; the caller is responsible for parsing the response and handling error status codes.
+- The `trigger_id` value must match the pattern `^[\w-]+$` — only alphanumeric characters, underscores, and dashes are permitted; spaces or special characters will cause the request to fail.

package/concepts/en/Tool-ScheduleWakeup.md

@@ -0,0 +1,56 @@
+# ScheduleWakeup
+
+Schedule when to resume work in `/loop` dynamic mode. The tool lets Claude self-pace iterations of a task by sleeping for a chosen interval, then firing again with the same loop prompt.
+
+## When to Use
+
+- Self-pacing a `/loop` dynamic task where the iteration interval depends on work state rather than a fixed clock
+- Waiting for a long build, deploy, or test run to finish before checking results
+- Inserting idle ticks between iterations when there is no specific signal to watch right now
+- Running an autonomous loop with no user prompt — pass the literal sentinel `<<autonomous-loop-dynamic>>` as `prompt`
+- Polling a process that is about to change state soon (stay cache-warm with a short delay)
+
+## Parameters
+
+- `delaySeconds` (number, required): Seconds from now to resume. The runtime clamps the value to `[60, 3600]`, so you do not need to clamp it yourself.
+- `reason` (string, required): One short sentence explaining the chosen delay. Shown to the user and recorded in telemetry. Be specific — "checking long bun build" is more useful than "waiting."
+- `prompt` (string, required): The `/loop` input to fire on wake-up. Pass the same string on every turn so the next firing repeats the task. For an autonomous loop with no user prompt, pass the literal sentinel `<<autonomous-loop-dynamic>>`.
+
+## Examples
+
+### Example 1: short delay to re-check a fast-changing signal (stay cache-warm)
+
+A build was just started and typically finishes in two to three minutes.
+
+```json
+{
+  "delaySeconds": 120,
+  "reason": "checking bun build expected to finish in ~2 min",
+  "prompt": "check build status and report any errors"
+}
+```
+
+120 seconds keeps the conversation context in the Anthropic prompt cache (TTL 5 min), so the next wake-up is faster and cheaper.
+
+### Example 2: long idle tick (accept cache miss, amortize over longer wait)
+
+A database migration is running and typically takes 20–40 minutes.
+
+```json
+{
+  "delaySeconds": 1200,
+  "reason": "migration typically takes 20–40 min; checking back in 20 min",
+  "prompt": "check migration status and continue if done"
+}
+```
+
+The cache will be cold on wake-up, but the 20-minute wait more than amortizes the single cache miss. Polling every 5 minutes would pay the same miss cost 4× for no benefit.
+
+## Notes
+
+- **5-minute cache TTL**: The Anthropic prompt cache expires after 300 seconds. Delays under 300 s keep context warm; delays over 300 s incur a cache miss on the next wake-up.
+- **Avoid exactly 300 s**: It is the worst of both worlds — you pay the cache miss without getting a meaningfully longer wait. Either drop to 270 s (stay in cache) or commit to 1200 s or more (one miss buys a much longer wait).
+- **Default for idle ticks**: When there is no specific signal to watch, use **1200–1800 s** (20–30 min). This lets the loop check back periodically without burning cache 12× per hour for no reason.
+- **Automatic clamping**: The runtime clamps `delaySeconds` to `[60, 3600]`. Values below 60 become 60; values above 3600 become 3600. You do not need to guard these bounds yourself.
+- **Omit the call to end the loop**: Do not call ScheduleWakeup if you intend to stop iterating. Simply omitting the call ends the loop.
+- **Pass the same `prompt` each turn**: The `prompt` field must carry the original `/loop` instruction on every invocation so the next wake-up knows what task to resume.

package/concepts/en/Tool-SendMessage.md

@@ -1,41 +1,68 @@
 # SendMessage
 
-## Definition
+Delivers a message from one team member to another within an active team, or broadcasts to every teammate at once. This is the only channel teammates can hear — anything written to normal text output is invisible to them.
 
-Sends messages between agents within a team. Used for direct communication, broadcasting, and protocol messages (shutdown requests/responses, plan approval).
+## When to Use
+
+- Assigning a task or handing off a subproblem to a named teammate during team collaboration.
+- Requesting status, intermediate findings, or a code review from another agent.
+- Broadcasting a decision, shared constraint, or shutdown announcement to the full team via `*`.
+- Replying to a protocol prompt such as a shutdown request or a plan-approval request from the team leader.
+- Closing the loop at the end of a delegated task so the leader can mark the item complete.
 
 ## Parameters
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `to` | string | Yes | Recipient: teammate name, or `"*"` for broadcast to all |
-| `message` | string / object | Yes | Plain text message or structured protocol object |
-| `summary` | string | No | A 5-10 word preview shown in the UI |
+- `to` (string, required): The target teammate's `name` as registered in the team, or `*` to broadcast to all teammates at once.
+- `message` (string or object, required): Plain text for normal communication, or a structured object for protocol responses like `shutdown_response` and `plan_approval_response`.
+- `summary` (string, optional): A 5–10 word preview shown in the team activity log for plain-text messages. Required for long string messages; ignored when `message` is a protocol object.
+
+## Examples
+
+### Example 1: Direct task handoff
+
+```
+SendMessage(
+  to="db-lead",
+  message="Please audit prisma/schema.prisma and list any model missing createdAt/updatedAt timestamps. Reply when done.",
+  summary="Audit schema for missing timestamps"
+)
+```
 
-## Message Types
+### Example 2: Broadcast a shared constraint
 
-### Plain Text
-Direct messages between teammates for coordination, status updates, and task discussions.
+```
+SendMessage(
+  to="*",
+  message="Reminder: do not touch files under legacy/ — that subtree is frozen until the migration PR lands.",
+  summary="Freeze legacy/ during migration"
+)
+```
 
-### Shutdown Request
-Asks a teammate to gracefully shut down: `{ type: "shutdown_request", reason: "..." }`
+### Example 3: Protocol response
 
-### Shutdown Response
-Teammate approves or rejects a shutdown: `{ type: "shutdown_response", approve: true/false }`
+Respond to a shutdown request from the leader using a structured message:
 
-### Plan Approval Response
-Approves or rejects a teammate's plan: `{ type: "plan_approval_response", approve: true/false }`
+```
+SendMessage(
+  to="leader",
+  message={ "type": "shutdown_response", "ready": true, "final_report": "All assigned diff chunks committed on branch refactor-crew/db-lead." }
+)
+```
 
-## Broadcast vs Direct
+### Example 4: Plan approval response
 
-- **Direct** (`to: "teammate-name"`): Send to a specific teammate — preferred for most communication
-- **Broadcast** (`to: "*"`): Send to all teammates — use sparingly, only for critical team-wide announcements
+```
+SendMessage(
+  to="leader",
+  message={ "type": "plan_approval_response", "approved": true, "notes": "LGTM, but please split step 4 into migration + backfill." }
+)
+```
 
-## Related Tools
+## Notes
 
-| Tool | Purpose |
-|------|---------|
-| `TeamCreate` | Create a new team |
-| `TeamDelete` | Remove team when done |
-| `Agent` | Spawn teammates that join the team |
-| `TaskCreate` / `TaskUpdate` / `TaskList` | Manage the shared task list |
+- Your regular assistant text output is NOT transmitted to teammates. If you want another agent to see something, it must go through `SendMessage`. This is the single most common mistake in team workflows.
+- Broadcast (`to: "*"`) is expensive — it wakes every teammate and consumes their context. Reserve it for announcements that genuinely affect everyone. Prefer targeted sends.
+- Keep messages concise and action-oriented. Include the file paths, constraints, and expected reply format the recipient needs; remember they have no shared memory with you.
+- Protocol message objects (`shutdown_response`, `plan_approval_response`) have fixed shapes. Do not mix protocol fields into plain-text messages or vice versa.
+- Messages are asynchronous. The recipient will receive yours on their next turn; do not assume they have read or acted on it until they reply.
+- A well-written `summary` makes the team activity log scannable for the leader — treat it like a commit subject line.

package/concepts/en/Tool-Skill.md

@@ -1,56 +1,47 @@
 # Skill
 
-## Definition
+Invokes a named skill inside the current conversation. Skills are pre-packaged capability bundles — domain knowledge, workflows, and sometimes tool access — that the harness exposes to the assistant through system reminders.
 
-Executes a skill within the main conversation. Skills are specialized capabilities that users can invoke via slash commands (e.g., `/commit`, `/review-pr`).
+## When to Use
 
-## Parameters
+- The user types a slash command such as `/review` or `/init` — slash commands are skills and must be executed through this tool.
+- The user describes a task that matches an advertised skill's trigger conditions (for example, asking to scan transcripts for repeated permission prompts matches `fewer-permission-prompts`).
+- A skill's stated purpose is a direct match for the current file, request, or conversation context.
+- Specialized, repeatable workflows are available as skills and the canonical procedure is preferable to an ad-hoc approach.
+- The user asks "what skills are available" — list the advertised names, and invoke only when they confirm.
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `skill` | string | Yes | Skill name (e.g., "commit", "review-pr", "pdf") |
-| `args` | string | No | Skill arguments |
+## Parameters
 
-## Use Cases
+- `skill` (string, required): The exact name of a skill listed in the current available-skills system reminder. For plugin-namespaced skills, use the fully qualified `plugin:skill` form (for example `skill-creator:skill-creator`). Do not include a leading slash.
+- `args` (string, optional): Free-form arguments passed to the skill. Format and semantics are defined by each skill's own documentation.
 
-**Good for:**
-- When the user enters a slash command in the `/<skill-name>` format
-- When the user's request matches the functionality of a registered skill
+## Examples
 
-**Not good for:**
-- Built-in CLI commands (e.g., `/help`, `/clear`)
-- A skill that is already running
-- Skill names not in the available skills list
+### Example 1: Run a review skill on the current branch
 
-## Notes
+```
+Skill(skill="review")
+```
 
-- Once invoked, the skill expands into a full prompt
-- Supports fully qualified names (e.g., `ms-office-suite:pdf`)
-- The available skills list is provided in system-reminder messages
-- When you see a `<command-name>` tag, it means the skill is already loaded — execute it directly rather than calling this tool again
-- Do not mention a skill without actually calling the tool
+The `review` skill packages the steps for reviewing a pull request against the current base branch. Invoking it loads the harness-defined review procedure into the turn.
 
-## Original Text
+### Example 2: Invoke a plugin-namespaced skill with arguments
 
-<textarea readonly>Execute a skill within the main conversation
+```
+Skill(
+  skill="skill-creator:skill-creator",
+  args="create a skill that summarizes git log for a given date range"
+)
+```
 
-When users ask you to perform tasks, check if any of the available skills match. Skills provide specialized capabilities and domain knowledge.
+Routes the request through the `skill-creator` plugin's entry point so the authoring workflow kicks in.
 
-When users reference a "slash command" or "/<something>" (e.g., "/commit", "/review-pr"), they are referring to a skill. Use this tool to invoke it.
-
-How to invoke:
-- Use this tool with the skill name and optional arguments
-- Examples:
-  - `skill: "pdf"` - invoke the pdf skill
-  - `skill: "commit", args: "-m 'Fix bug'"` - invoke with arguments
-  - `skill: "review-pr", args: "123"` - invoke with arguments
-  - `skill: "ms-office-suite:pdf"` - invoke using fully qualified name
+## Notes
 
-Important:
-- Available skills are listed in system-reminder messages in the conversation
-- When a skill matches the user's request, this is a BLOCKING REQUIREMENT: invoke the relevant Skill tool BEFORE generating any other response about the task
-- NEVER mention a skill without actually calling this tool
-- Do not invoke a skill that is already running
-- Do not use this tool for built-in CLI commands (like /help, /clear, etc.)
-- If you see a <command-name> tag in the current conversation turn, the skill has ALREADY been loaded - follow the instructions directly instead of calling this tool again
-</textarea>
+- Only invoke skills whose names appear verbatim in the available-skills system reminder, or skills the user typed directly as `/name` in their message. Never guess or invent skill names from memory or training data — if the skill is not advertised, do not call this tool.
+- When a user's request matches an advertised skill, calling `Skill` is a blocking prerequisite: invoke it before generating any other response about the task. Do not describe what the skill would do — run it.
+- Never mention a skill by name without actually invoking it. Announcing a skill without calling the tool is misleading.
+- Do not use `Skill` for built-in CLI commands such as `/help`, `/clear`, `/model`, or `/exit`. Those are handled by the harness directly.
+- Do not re-invoke a skill that is already running in the current turn. If you see a `<command-name>` tag in the current turn, the skill has already been loaded — follow its instructions in place instead of calling the tool again.
+- If several skills could apply, choose the most specific one. For configuration changes such as adding permissions or hooks, prefer `update-config` over a generic settings approach.
+- Skill execution can introduce new system reminders, tools, or constraints for the remainder of the turn. Re-read the conversation state after a skill completes before proceeding.

package/concepts/en/Tool-TaskCreate.md

@@ -1,78 +1,56 @@
 # TaskCreate
 
-## Definition
+Creates a new task in the current team's task list (or the session's task list when no team is active). Use it to capture work items that should be tracked, delegated, or revisited later.
 
-Creates a structured task list entry for tracking progress, organizing complex tasks, and demonstrating work progress to the user.
+## When to Use
 
-## Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `subject` | string | Yes | Short task title in imperative form (e.g., "Fix authentication bug") |
-| `description` | string | Yes | Detailed description including context and acceptance criteria |
-| `activeForm` | string | No | Present continuous text displayed when in progress (e.g., "Fixing authentication bug") |
-| `metadata` | object | No | Arbitrary metadata attached to the task |
-
-## Use Cases
-
-**Good for:**
-- Complex multi-step tasks (more than 3 steps)
-- When the user provides multiple to-do items
-- Tracking work in plan mode
-- When the user explicitly requests a todo list
-
-**Not good for:**
-- A single simple task
-- Simple operations with 3 or fewer steps
-- Pure conversation or information queries
+- The user describes a multi-step piece of work that benefits from explicit tracking.
+- You are breaking a large request into smaller, separately-completable units.
+- A follow-up is discovered mid-task and should not be forgotten.
+- You need a durable record of intent before handing work to a teammate or subagent.
+- You are operating in plan mode and want each plan step represented as a concrete task.
 
-## Notes
-
-- All newly created tasks have an initial status of `pending`
-- `subject` uses imperative form ("Run tests"), `activeForm` uses present continuous ("Running tests")
-- After creating a task, use TaskUpdate to set dependencies (blocks/blockedBy)
-- Before creating, call TaskList first to check for duplicate tasks
-
-## Original Text
+Skip `TaskCreate` for trivial one-shot actions, pure conversation, or anything completable in two or three direct tool calls.
 
-<textarea readonly>Use this tool to create a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
-It also helps the user understand the progress of the task and overall progress of their requests.
+## Parameters
 
-## When to Use This Tool
+- `subject` (string, required): Short imperative title, e.g. `Fix login redirect on Safari`. Keep it under roughly eighty characters.
+- `description` (string, required): Detailed context — the problem, the constraints, acceptance criteria, and any files or links a future reader will need. Write as if a teammate will pick this up cold.
+- `activeForm` (string, optional): Present-continuous spinner text shown while the task is `in_progress`, e.g. `Fixing login redirect on Safari`. Mirror the `subject` but in -ing form.
+- `metadata` (object, optional): Arbitrary structured data attached to the task. Common uses: labels, priority hints, external ticket IDs, or agent-specific configuration.
 
-Use this tool proactively in these scenarios:
+Newly created tasks always start with status `pending` and no owner. Dependencies (`blocks`, `blockedBy`) are not set at creation time — apply them afterwards with `TaskUpdate`.
 
-- Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
-- Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
-- Plan mode - When using plan mode, create a task list to track the work
-- User explicitly requests todo list - When the user directly asks you to use the todo list
-- User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
-- After receiving new instructions - Immediately capture user requirements as tasks
-- When you start working on a task - Mark it as in_progress BEFORE beginning work
-- After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation
+## Examples
 
-## When NOT to Use This Tool
+### Example 1
 
-Skip using this tool when:
-- There is only a single, straightforward task
-- The task is trivial and tracking it provides no organizational benefit
-- The task can be completed in less than 3 trivial steps
-- The task is purely conversational or informational
+Capture a bug report the user just filed.
 
-NOTE that you should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.
+```
+TaskCreate(
+  subject: "Repair broken PDF export on Windows",
+  description: "Users on Windows 11 report the export button produces a 0-byte file. Reproduce with sample doc in test/fixtures/export/, then fix the code path in src/export/pdf.ts. Acceptance: export writes a valid PDF and the existing export test suite passes.",
+  activeForm: "Repairing broken PDF export on Windows"
+)
+```
 
-## Task Fields
+### Example 2
 
-- **subject**: A brief, actionable title in imperative form (e.g., "Fix authentication bug in login flow")
-- **description**: Detailed description of what needs to be done, including context and acceptance criteria
-- **activeForm**: Present continuous form shown in spinner when task is in_progress (e.g., "Fixing authentication bug"). This is displayed to the user while you work on the task.
+Split an epic into tracked units at the start of a session.
 
-**IMPORTANT**: Always provide activeForm when creating tasks. The subject should be imperative ("Run tests") while activeForm should be present continuous ("Running tests"). All tasks are created with status `pending`.
+```
+TaskCreate(
+  subject: "Draft migration plan for auth service",
+  description: "Produce a written plan covering rollout stages, rollback strategy, and monitoring. Output: docs/auth-migration.md.",
+  activeForm: "Drafting migration plan for auth service",
+  metadata: { "priority": "P1", "linearId": "AUTH-214" }
+)
+```
 
-## Tips
+## Notes
 
-- Create tasks with clear, specific subjects that describe the outcome
-- Include enough detail in the description for another agent to understand and complete the task
-- After creating tasks, use TaskUpdate to set up dependencies (blocks/blockedBy) if needed
-- Check TaskList first to avoid creating duplicate tasks
-</textarea>
+- Write the `subject` in the imperative voice and the `activeForm` in the present continuous so the UI reads naturally when the task transitions to `in_progress`.
+- Call `TaskList` before creating to avoid duplicates — the team list is shared with teammates and subagents.
+- Do not include secrets or credentials in `description` or `metadata`; task records are visible to anyone with access to the team.
+- After creation, move the task through its lifecycle with `TaskUpdate`. Do not leave work silently abandoned in `in_progress`.

package/concepts/en/Tool-TaskGet.md

@@ -1,56 +1,47 @@
 # TaskGet
 
-## Definition
+Fetches the full record for a single task by ID, including its description, current status, owner, metadata, and dependency edges. Use it when the summary returned by `TaskList` is not enough to act on the task.
 
-Retrieves the full details of a task by its task ID.
+## When to Use
 
-## Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `taskId` | string | Yes | The task ID to retrieve |
-
-## Return Content
+- You picked up a task from `TaskList` and need the full description before starting work.
+- You are about to mark a task `completed` and want to re-check the acceptance criteria.
+- You need to inspect which tasks this one `blocks` or is `blockedBy` to decide the next move.
+- You are investigating history — who owns it, what metadata was attached, when it changed state.
+- A teammate or prior session referenced a task ID and you need the context.
 
-- `subject` — Task title
-- `description` — Detailed requirements and context
-- `status` — Status: `pending`, `in_progress`, or `completed`
-- `blocks` — List of tasks blocked by this task
-- `blockedBy` — List of prerequisite tasks blocking this task
+Prefer `TaskList` when you only need a high-level scan; reserve `TaskGet` for the specific record you intend to read carefully or modify.
 
-## Use Cases
+## Parameters
 
-**Good for:**
-- Getting the full description and context of a task before starting work
-- Understanding task dependencies
-- Getting complete requirements after being assigned a task
+- `taskId` (string, required): The task identifier returned by `TaskCreate` or `TaskList`. IDs are stable for the life of the task.
 
-## Notes
+## Examples
 
-- After retrieving a task, check whether the `blockedBy` list is empty before starting work
-- Use TaskList to view summary information for all tasks
+### Example 1
 
-## Original Text
+Look up a task you just saw in the list.
 
-<textarea readonly>Use this tool to retrieve a task by its ID from the task list.
+```
+TaskGet(taskId: "t_01HXYZ...")
+```
 
-## When to Use This Tool
+Typical response fields: `id`, `subject`, `description`, `activeForm`, `status`, `owner`, `blocks`, `blockedBy`, `metadata`, `createdAt`, `updatedAt`.
 
-- When you need the full description and context before starting work on a task
-- To understand task dependencies (what it blocks, what blocks it)
-- After being assigned a task, to get complete requirements
+### Example 2
 
-## Output
+Resolve dependencies before starting.
 
-Returns full task details:
-- **subject**: Task title
-- **description**: Detailed requirements and context
-- **status**: 'pending', 'in_progress', or 'completed'
-- **blocks**: Tasks waiting on this one to complete
-- **blockedBy**: Tasks that must complete before this one can start
+```
+TaskGet(taskId: "t_01HXYZ...")
+# Inspect blockedBy — if any referenced task is still pending
+# or in_progress, work on the blocker first.
+```
 
-## Tips
+## Notes
 
-- After fetching a task, verify its blockedBy list is empty before beginning work.
-- Use TaskList to see all tasks in summary form.
-</textarea>
+- `TaskGet` is read-only and safe to call repeatedly; it does not change status or ownership.
+- If `blockedBy` is non-empty and contains tasks that are not `completed`, do not start this task — resolve the blockers first (or coordinate with their owner).
+- The `description` field can be long. Read it fully before acting; skimming leads to missed acceptance criteria.
+- An unknown or deleted `taskId` returns an error. Re-run `TaskList` to pick a current ID.
+- If you are about to edit a task, call `TaskGet` first to avoid overwriting fields a teammate just changed.