{"id":"c731ab12-ecbc-4b68-a447-c54458b888cf","entityType":"agent","slug":"clawhub-camscanner-ai-cs-cli","name":"CamScanner Official Skill","canonicalUrl":"https://www.xpersona.co/agent/clawhub-camscanner-ai-cs-cli","canonicalPath":"/agent/clawhub-camscanner-ai-cs-cli","generatedAt":"2026-10-10T07:45:13.441Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T03:25:00.931Z","emptyReason":null},"description":"CamScanner Official Skill — intelligent document conversion and processing. Use when the user mentions CamScanner, format conversion (image/PDF to Word/Excel/Markdown, Word/Excel/PPT to PDF, Office document format conversion, images to PDF), image enhancement/upscaling/restoration, OCR, image translation, formula extraction, watermark add/remove, multi-image merge, document scanning/editing, invoice/receipt recognition, or cloud document search/download/move/folder management. Does not support merging existing PDFs into one file.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.7K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s173fgwczhaenp3btzq1h17qss84dnaa:cs-cli","sourceUrl":"https://clawhub.ai/camscanner-ai/cs-cli","homepage":"https://clawhub.ai/camscanner-ai/skills/cs-cli","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/camscanner-ai/cs-cli","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/camscanner-ai/skills/cs-cli","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":65,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"CamScanner Official Skill technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T03:25:00.931Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T03:25:00.931Z","emptyReason":null},"stars":null,"forks":null,"downloads":1737,"packageName":null,"latestVersion":"1.1.8","tractionLabel":"1.7K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T03:25:00.931Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T03:25:00.931Z","lastCrawledAt":"2026-10-10T03:25:00.931Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T03:25:00.931Z","lastVerifiedAt":null,"highlights":[{"version":"1.1.8","createdAt":"2026-09-17T06:50:50.847Z","changelog":"Publish 1.1.8","fileCount":19,"zipByteSize":53255},{"version":"1.1.4","createdAt":"2026-08-27T13:42:07.431Z","changelog":"Publish 1.1.4","fileCount":17,"zipByteSize":41686},{"version":"1.1.2","createdAt":"2026-08-21T06:24:31.124Z","changelog":"Version 1.1.2 - References reorganized: workflow documents removed and new single-reference files added for key features (batch convert, image enhance, OCR extract, translate, watermark protection). - Skill metadata updated: adds author, display_name(s), and multi-language descriptions. - Removed obsolete files including `.gitignore` and `skill-card.md`. - Internal structure streamlined; documentation and file layout now clearer and more maintainable.","fileCount":17,"zipByteSize":39075},{"version":"0.1.2","createdAt":"2026-08-13T13:48:38.674Z","changelog":"cs-cli v0.1.2 Changelog: - Added upgrade scripts for Linux/macOS (`upgrade.sh`), Windows (`upgrade.ps1`), and a cross-platform Node.js version (`upgrade.cjs`). - Introduced a new setup flow in SKILL.md, requiring stricter installation checks, a version upgrade step, and improved Windows handling. - Removed previous reference and workflow documentation files, along with the old `skill-card.md`. - Updated the skill guide to mandate saving to both local and cloud by default (with `-s`), clarify agent behaviors for saving, and provide detailed authentication and environment validation steps. - Enhanced instructions for cloud save title generation and outlined rollback support for upgrades.","fileCount":18,"zipByteSize":37506},{"version":"1.1.0","createdAt":"2026-08-13T13:08:19.168Z","changelog":"**This release introduces a new environment setup flow and upgrade scripts for the cs-cli skill.** - Added dedicated upgrade scripts (`scripts/upgrade.sh`, `scripts/upgrade.cjs`, `scripts/upgrade.ps1`) and a `.gitignore`. - Removed reference and workflow files, as well as the old scripts directory and skill card. - Overhauled the setup and usage documentation, introducing a mandatory, step-driven environment check and upgrade process for agents. - Introduced agent save policy: by default, results must be saved both locally and to CamScanner cloud unless the user specifies otherwise. - Detailed platform-specific install and upgrade steps, including special handling for Windows PATH issues. - Updated authentication behavior and clarified rules for handling user tokens securely.","fileCount":18,"zipByteSize":37504},{"version":"0.1.0","createdAt":"2026-08-07T11:24:35.632Z","changelog":"Initial release of the cs-cli CamScanner skill. - Introduces CamScanner document processing via the `camscanner-cli` tool. - Supports image enhancement, OCR, format conversions (image/PDF to Word/Excel/Markdown), watermark management, translation, merging, and photo restoration. - Enables saving processed results to user's CamScanner account with support for local/cloud output options. - Provides clear installation, authentication, and usage instructions. - Documents all available command groups, flags, and operating limits. - Includes reference routing for required command and workflow documentation.","fileCount":17,"zipByteSize":24717}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s173fgwczhaenp3btzq1h17qss84dnaa:cs-cli","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s173fgwczhaenp3btzq1h17qss84dnaa:cs-cli` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/camscanner-ai/cs-cli before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-camscanner-ai-cs-cli/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-camscanner-ai-cs-cli/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-camscanner-ai-cs-cli/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-camscanner-ai-cs-cli/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-camscanner-ai-cs-cli/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-camscanner-ai-cs-cli/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T07:45:13.438Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-camscanner-ai-cs-cli/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-camscanner-ai-cs-cli/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-camscanner-ai-cs-cli/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-camscanner-ai-cs-cli/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T03:25:00.931Z","emptyReason":null},"readme":"Skill: CamScanner Official Skill\n\nOwner: camscanner-ai\n\nSummary: CamScanner Official Skill — intelligent document conversion and processing. Use when the user mentions CamScanner, format conversion (image/PDF to Word/Excel/Markdown, Word/Excel/PPT to PDF, Office document format conversion, images to PDF), image enhancement/upscaling/restoration, OCR, image translation, formula extraction, watermark add/remove, multi-image merge, document scanning/editing, invoice/receipt recognition, or cloud document search/download/move/folder management. Does not support merging existing PDFs into one file.\n\nTags: latest:1.1.8\n\nVersion history:\n\nv1.1.8 | 2026-09-17T06:50:50.847Z | user\n\nPublish 1.1.8\n\nv1.1.4 | 2026-08-27T13:42:07.431Z | user\n\nPublish 1.1.4\n\nv1.1.2 | 2026-08-21T06:24:31.124Z | user\n\nVersion 1.1.2\n\n- References reorganized: workflow documents removed and new single-reference files added for key features (batch convert, image enhance, OCR extract, translate, watermark protection).\n- Skill metadata updated: adds author, display_name(s), and multi-language descriptions.\n- Removed obsolete files including `.gitignore` and `skill-card.md`.\n- Internal structure streamlined; documentation and file layout now clearer and more maintainable.\n\nv0.1.2 | 2026-08-13T13:48:38.674Z | user\n\ncs-cli v0.1.2 Changelog:\n\n- Added upgrade scripts for Linux/macOS (`upgrade.sh`), Windows (`upgrade.ps1`), and a cross-platform Node.js version (`upgrade.cjs`).\n- Introduced a new setup flow in SKILL.md, requiring stricter installation checks, a version upgrade step, and improved Windows handling.\n- Removed previous reference and workflow documentation files, along with the old `skill-card.md`.\n- Updated the skill guide to mandate saving to both local and cloud by default (with `-s`), clarify agent behaviors for saving, and provide detailed authentication and environment validation steps.\n- Enhanced instructions for cloud save title generation and outlined rollback support for upgrades.\n\nv1.1.0 | 2026-08-13T13:08:19.168Z | user\n\n**This release introduces a new environment setup flow and upgrade scripts for the cs-cli skill.**\n\n- Added dedicated upgrade scripts (`scripts/upgrade.sh`, `scripts/upgrade.cjs`, `scripts/upgrade.ps1`) and a `.gitignore`.\n- Removed reference and workflow files, as well as the old scripts directory and skill card.\n- Overhauled the setup and usage documentation, introducing a mandatory, step-driven environment check and upgrade process for agents.\n- Introduced agent save policy: by default, results must be saved both locally and to CamScanner cloud unless the user specifies otherwise.\n- Detailed platform-specific install and upgrade steps, including special handling for Windows PATH issues.\n- Updated authentication behavior and clarified rules for handling user tokens securely.\n\nv0.1.0 | 2026-08-07T11:24:35.632Z | auto\n\nInitial release of the cs-cli CamScanner skill.\n\n- Introduces CamScanner document processing via the `camscanner-cli` tool.\n- Supports image enhancement, OCR, format conversions (image/PDF to Word/Excel/Markdown), watermark management, translation, merging, and photo restoration.\n- Enables saving processed results to user's CamScanner account with support for local/cloud output options.\n- Provides clear installation, authentication, and usage instructions.\n- Documents all available command groups, flags, and operating limits.\n- Includes reference routing for required command and workflow documentation.\n\nArchive index:\n\nArchive v1.1.8: 19 files, 53255 bytes\n\nFiles: references/batch-convert.md (2476b), references/cloud-documents.md (14877b), references/image-enhance.md (1357b), references/image-processing.md (9423b), references/ocr-extract.md (1591b), references/office-processing.md (2754b), references/pdf-processing.md (3212b), references/tool-combos.md (7690b), references/translate.md (1151b), references/watermark-protection.md (1276b), scripts/setup.cjs (7335b), scripts/setup.ps1 (7515b), scripts/setup.sh (5602b), scripts/upgrade.cjs (16684b), scripts/upgrade.ps1 (13985b), scripts/upgrade.sh (12085b), skill-card.md (3167b), SKILL.md (36091b), _meta.json (125b)\n\nFile v1.1.8:SKILL.md\n\n---\nname: \"camscanner\"\ndisplay_name: \"CamScanner Official Skill\"\ndisplay_name_en: \"camscanner\"\ndescription: \"CamScanner Official Skill — intelligent document conversion and processing. Use when the user mentions CamScanner, format conversion (image/PDF to Word/Excel/Markdown, Word/Excel/PPT to PDF, Office document format conversion, images to PDF), image enhancement/upscaling/restoration, OCR, image translation, formula extraction, watermark add/remove, multi-image merge, document scanning/editing, invoice/receipt recognition, or cloud document search/download/move/folder management. Does not support merging existing PDFs into one file.\"\ndescription_en: \"CamScanner Official Skill — intelligent document conversion and processing. Use when the user mentions CamScanner, format conversion (image/PDF to Word/Excel/Markdown, Word/Excel/PPT to PDF, Office document format conversion, images to PDF), image enhancement/upscaling/restoration, OCR, image translation, formula extraction, watermark add/remove, multi-image merge, document scanning/editing, invoice/receipt recognition, or cloud document search/download/move/folder management. Does not support merging existing PDFs into one file.\"\nhomepage: \"https://www.camscanner.com\"\nversion: \"1.1.8\"\ncategory: \"productivity\"\nauthor: \"CamScanner\"\n---\n# CamScanner CLI Skill Guide\n\nThe CamScanner CLI Skill provides a complete document processing toolkit through the `camscanner-cli` command-line tool and the CamScanner AI Tools API. It supports image enhancement, OCR, format conversion, Office document conversion (Word/Excel/PPT to PDF or format upgrade), watermarking, translation, restoration, multi-image conversion to PDF/Word/Excel, receipt recognition, and other image/PDF processing operations, as well as cloud document search, download, move, and folder management.\n\n## Check Capability Before Execution\n\n1. Use the request, existing attachments, paths, and context to determine input types, count, order, and final artifacts. Ask only for missing information that affects the result; do not request files or an order already provided.\n2. **The current CLI cannot merge existing PDFs into one file.** `image merge-pdf` accepts images only, up to 100. For PDF merging, clearly state this limitation; do not collect paths, require login, or promise a merged file and cloud link. `pdf to-images` followed by `image merge-pdf` is lossy image reconstruction, not a supported PDF merge workaround in this Skill.\n3. Once a complete supported execution path and the required inputs are available, complete the initial environment checks, read the relevant references, choose save options, and execute. Capability questions and known unsupported requests require no installation, upgrade, or authentication.\n4. Apply the save policy only to final artifacts of supported operations; keep intermediate files locally as needed by the next step. Do not change the requested format, order, or number of artifacts to satisfy a save rule.\n5. After execution, verify actual artifacts and task-specific requirements such as page count and order, then follow “Execution Results and Delivery.” Plans, command examples, and temporary file IDs are not completion evidence.\n\n## Environment Setup\n\nBefore the first supported CLI business operation in a session, the agent **must** complete the following decision flow once. Reading documentation or local help does not trigger installation, upgrades, or login.\n\n**Once the business execution prerequisites above are met, follow this flow:**\n\n```\nStep 1: camscanner-cli --version\n         │\n         ├─ Command exists (outputs version) → Step 2\n         │\n         └─ Command not found → [Windows?] Double-check with Test-Path ↓\n                          │\n                          ├─ Test-Path \"$env:LOCALAPPDATA\\camscanner-cli\\camscanner-cli.exe\" = True\n                          │   → Refresh PATH → Step 2 (no install needed)\n                          │\n                          └─ False / Non-Windows → Run install script → Step 3 (skip upgrade)\n\nStep 2: Run upgrade script\n         │\n         └─ Done → Step 3\n\nStep 3: camscanner-cli auth status\n         │\n         ├─ Logged in → ✅ Environment ready, proceed with user task\n         │\n         └─ Not logged in / expired → Run camscanner-cli auth login → Verify → ✅\n```\n\n### Step 1. Check Installation\n\nRun `camscanner-cli --version`:\n\n- **Command exists** (outputs version) → Already installed, continue to Step 2\n- **Command not found** (command not found / not recognized) → **On Windows, you must perform the double-check below first**. If confirmed not installed, run the install script. After installation, **skip directly to Step 3**.\n\n**Windows double-check (mandatory)**:\n\n`camscanner-cli --version` failing on Windows does not necessarily mean it is not installed — the PATH may not be refreshed or ConPTY may swallow output. **Before running the install script**, check whether the file exists:\n\n```powershell\nTest-Path \"$env:LOCALAPPDATA\\camscanner-cli\\camscanner-cli.exe\"\n```\n\n- Returns **True** → CLI is installed, just missing from PATH. Refresh PATH then continue to Step 2:\n  ```powershell\n  $env:PATH = \"$env:LOCALAPPDATA\\camscanner-cli;$env:PATH\"\n  ```\n- Returns **False** → Confirmed not installed, run the install script → Step 3\n\n| Platform | Install Command |\n|----------|-----------------|\n| Linux/macOS | `bash scripts/setup.sh` |\n| Windows | `powershell -ExecutionPolicy Bypass -File scripts/setup.ps1` |\n\n### Step 2. Version Upgrade Check (installed users only)\n\nRun the upgrade script to check for a new version (the script handles detection internally; exits silently if no update is available; network failures do not block usage):\n\n| Platform | Upgrade Command |\n|----------|-----------------|\n| Linux/macOS | `bash scripts/upgrade.sh` |\n| Windows | `node scripts/upgrade.cjs` |\n| Fallback (any platform) | `node scripts/upgrade.cjs` |\n\n> The upgrade script updates both the CLI binary and Skill files (SKILL.md, references/, scripts/) to keep them in sync. On failure it auto-rolls back; manual rollback: `bash scripts/upgrade.sh --rollback` or `node scripts/upgrade.cjs --rollback`.\n\nAfter an upgrade changes the Skill, reread `SKILL.md` and the references needed for this task, then recheck capabilities and parameters. Record the actual CLI/Skill versions to avoid mixing old and new rules.\n\n### Step 3. Authentication Check\n\n```bash\ncamscanner-cli auth status\n```\n\n- **Logged in** → Environment ready, proceed with user task\n- **Not logged in or token expired** → Run `camscanner-cli auth login`, then verify again\n\n> **Agent login behavior rules (mandatory)**:\n> - Must run `camscanner-cli auth login` in the **foreground** (no `&` backgrounding). The command blocks until the user completes browser OAuth and returns automatically.\n> - After login, verify with `camscanner-cli auth status`; on failure, inform the user to retry.\n\n| Action | Command |\n|--------|---------|\n| Check status | `camscanner-cli auth status` |\n| Browser login | `camscanner-cli auth login` |\n| Log out | `camscanner-cli auth logout` |\n\n> **Token safety**: Never display token plaintext to the user or write it to an unsafe location.\n\n---\n\n## Operating Limits\n\n1. **Do not leak credentials**: Tokens must only be obtained through `camscanner-cli auth login` and stored in the system keychain.\n2. **File size limit**: Uploaded files must not exceed 40 MB.\n3. **Supported image formats**: JPG, JPEG, PNG.\n4. **Supported document formats**: PDF, TXT, Markdown.\n5. **Supported Office formats**: DOC, DOCX, XLS, XLSX, PPT, PPTX.\n\n---\n\n## Command Format\n\n```bash\ncamscanner-cli <group> <command> [file...] [flags]\n```\n\n**Groups**: `image` (image processing), `pdf` (PDF processing), `office` (Office document processing), `txt` (text processing), `doc` (cloud document management), `auth` (authentication management).\n\n**Common processing flags (availability depends on the command; `pdf to-images` uses `-d`, not `-o`)**:\n\n| Flag | Description |\n|------|-------------|\n| `-o, --output <path>` | Output file path. If omitted, the CLI derives one automatically. |\n| `-s, --save` | Save the result to the user's CamScanner account and skip local download unless local output is explicitly specified. |\n| `--save-title <title>` | Cloud document title. If omitted, the CLI generates one in the form `{feature}{time}`. |\n| `--save-dir <name>` | Save to a specific folder (by name; falls back to root directory with a warning if not found). |\n| `--save-dir-id <id>` | Save to a specific folder (by ID; use `doc dirs` to get IDs). |\n| `-h, --help` | Show help. |\n\n### Interaction Between `-o` and `-s`\n\n| Arguments | Behavior |\n|-----------|----------|\n| No `-o`, no `-s` | Save locally to an automatically derived path. |\n| `-o path` | Save only to the specified local path. |\n| `-s` | **Save only to the cloud** and skip local download unless local output is explicitly specified. |\n| `-o path -s` | Save both locally **and** to the cloud. |\n\n### Agent Default Save Policy\n\nThis policy applies only to final processing artifacts when the command and target format support saving. Explicit user requirements override defaults. Satisfy both local and cloud requests when both are present; ask only if explicit requirements conflict.\n\n| User Intent | Agent Behavior (commands supporting file output and cloud saving) |\n|-------------|----------------|\n| No save preference | Save both: `-o <derived local path> -s` |\n| Local saving or a local path requested, without a cloud request | Only `-o path` |\n| Cloud saving or a cloud document link requested, without a local request | Only `-s` |\n| Both local and cloud requested | `-o path -s` |\n| Explicitly no cloud saving | Local output only; omit `-s` |\n\n**Command exceptions and multi-step tasks**:\n\n- `-s` alone saves only to the cloud, not both destinations. `pdf to-images` uses `-d dir` for local output, so dual saving is `-d dir -s`; it has no `-o` flag.\n- `image convert --format txt`, `pdf convert --format txt`, and commands marked as not supporting `-s` use their documented local file or stdout output. Omit cloud save flags. If cloud saving is also requested, explain the limitation; do not silently switch to Markdown or another format.\n- This table does not apply to cloud management commands. For example, `doc search -s` sets search scope, not saving.\n- Save intermediate artifacts locally as needed by subsequent steps, without default cloud saving. Use distinct paths for different inputs, languages, and steps to avoid overwrites.\n- Reference examples with only `-s` assume an explicit cloud request; examples with only `-o`/`-d` show local output or intermediates. When the actual task has no save preference, supply both save destinations as specified above.\n\n### `--save-title` Smart Naming Rules\n\nWhen saving to cloud with `-s`, the agent **must** attempt smart naming via `--save-title`:\n\n1. **Prefer smart naming**: Generate a concise, meaningful title based on the filename, user intent, and document content.\n   - Example: User says \"convert this invoice to Excel\" → `--save-title \"Invoice to Excel\"`\n   - Example: File is `meeting_notes_0810.png`, converting to Word → `--save-title \"Meeting Notes 0810\"`\n   - Example: Converting multiple scan images into PDF → `--save-title \"Merged scans\"`\n2. **Fallback when naming fails**: If a meaningful title cannot be inferred from context (e.g., filename has no semantics, user did not describe intent), **do not pass** `--save-title` — let the CLI use its default rule (`{feature}{time}`).\n3. **Title requirements**: Concise (20 chars or fewer), meaningful, no file paths or technical parameters.\n\n### Execution Results and Delivery\n\nDistinguish processing, local download, and cloud saving, using actual command results and artifacts:\n\n| Actual State | Required Feedback |\n|--------------|-------------------|\n| Unsupported, missing input, authentication blocked, or not executed | State the limitation or blocker; do not claim an artifact exists, a save succeeded, or guarantee delivery |\n| Processing failed | Explain the failure and retain prior successful results; do not invent files or links |\n| Local download succeeded; cloud save failed or is uncertain | Provide the verified local path and state the cloud failure or uncertainty |\n| Cloud save succeeded with a nonempty real link | Show the returned title, link, and actual location; verify the local file as well when both were requested |\n| Command appears successful but an expected file or link is missing | Explain that the result is incomplete; an exit code or a single “completed” line does not prove full delivery |\n\nA temporary `file_id` identifies a processing file, not a document saved to the account. Use links from actual save results; never construct one from an example URL, filename, title, or `file_id`. The save response's `doc_id` here is a document web page URL, not a public sharing link, and does not guarantee access without login.\n\nExplain warnings and location mismatches using the actual returned reason. A missing folder and a failed move are different failures. If no reason is returned, state that it is unknown; a root location alone does not prove the folder is missing. `--save-dir`/`--save-dir-id` select a cloud folder, whereas `pdf to-images --dir` selects a local output directory.\n\n---\n\n## Capabilities\n\n### Tool Overview\n\n| Category | Command | Function | Output Type | Supports `-s` |\n|----------|---------|----------|-------------|---------------|\n| **Image enhancement** | `image enhance` | Remove shadows, sharpen, convert to black and white, and other 10 modes | Image | Yes |\n| **Image enhancement** | `image hd` | Upscale images and improve resolution | Image | Yes |\n| **Image enhancement** | `image restore` | Restore old photos | Image | Yes |\n| **Format conversion** | `image convert` | Image -> Word/Excel/TXT/Markdown | Document | Yes, except TXT |\n| **Format conversion** | `image to-pdf` | Single image -> PDF | PDF | Yes |\n| **Format conversion** | `pdf convert` | PDF -> Word/Excel/TXT/Markdown | Document | Yes, except TXT |\n| **Format conversion** | `txt to-word` | TXT -> Word | Word | Yes |\n| **Format conversion** | `office convert` | Word/Excel/PPT -> PDF or format upgrade (DOC->DOCX, etc.) | PDF/Document | Yes |\n| **Watermark** | `image watermark` | Add a text watermark to an image | Image | Yes |\n| **Watermark** | `pdf watermark` | Add a text watermark to a PDF | PDF | Yes |\n| **Watermark** | `pdf remove-watermark` | Remove watermarks from a PDF | PDF | Yes |\n| **Translation** | `image translate` | Translate text in an image while preserving layout | Image | Yes |\n| **Formula** | `image extract-formula` | Extract mathematical formulas | Image | Yes |\n| **Merge** | `image merge-pdf` | Merge multiple images into a PDF, up to 100 images | PDF | Yes |\n| **Merge** | `image merge-excel` | Merge multiple images into Excel, up to 100 images | Excel | Yes |\n| **Merge** | `image merge-word` | Merge multiple images into Word, up to 100 images | Word | Yes |\n| **PDF** | `pdf to-images` | Convert each PDF page to an image | Image directory | Yes |\n| **PDF** | `pdf to-images-zip` | Convert PDF pages to an image ZIP | ZIP | No |\n| **Recognition** | `image ocr` | OCR text recognition | stdout text | No |\n| **Recognition** | `image merge-text` | OCR multiple images and merge text, up to 100 images | stdout/file | No |\n| **Detection** | `image validate` | Tampering/AI-generated image detection | stdout JSON | No |\n| **Editing** | `image scan` | Analyze image layout and obtain character indexes and OSS keys | stdout/JSON | No |\n| **Editing** | `image edit` | Replace, delete, or move text based on scan results | Image | Yes |\n| **Receipt** | `image receipt` | Invoice/receipt recognition, returns structured JSON | stdout/JSON | No |\n| **Cloud docs** | `doc search` | Search cloud documents (keyword/time/type filter) | stdout table | No |\n| **Cloud docs** | `doc download` | Download cloud document to local (Office keeps original format, images export as PDF/ZIP) | File | No |\n| **Cloud docs** | `doc dirs` | List cloud folder directory tree | stdout tree | No |\n| **Cloud docs** | `doc move` | Move documents to a folder or root | stdout status | No |\n\n### Unsupported Operations\n\n- Merging existing PDF/Word/Excel files into one, or merging mixed image/PDF inputs.\n- A standalone CLI command to upload local files to the account (`-s` belongs to supported processing commands).\n\n- Online collaborative editing.\n- File version management.\n- Video/audio processing.\n- Batch folder management (only querying existing folders is supported; creating folders is not supported).\n\n---\n\n## Reference Routing\n\nBefore executing an operation, the agent **must** read the corresponding reference file for full parameters and usage.\n\n### Command References (Required)\n\n| Trigger | Reference File | Contents |\n|---------|----------------|----------|\n| Processing image files | `references/image-processing.md` | Full parameters, mode values, and examples for all `image` commands |\n| Processing PDF files | `references/pdf-processing.md` | Full parameters, limits, and examples for all `pdf` commands |\n| Processing Office documents (Word/Excel/PPT) | `references/office-processing.md` | Full parameters, supported formats, and examples for `office convert` |\n| Searching cloud documents | `references/cloud-documents.md` | Full parameters and usage for `doc search` |\n| Downloading/moving cloud documents | `references/cloud-documents.md` | Full parameters and usage for `doc download/dirs/move` |\n| Invoice/receipt recognition | The \"Invoice/Receipt Recognition\" section in this file | Full parameters and usage for `image receipt` |\n| User request requires multiple steps | `references/tool-combos.md` | Scenario-to-command combination mapping |\n\n### Workflow References (Required for Multi-Step Tasks)\n\n| Trigger | Workflow File | Contents |\n|---------|---------------|----------|\n| Multiple images need merging or batch conversion | `references/batch-convert.md` | Merge strategy selection and batching logic |\n| Image enhancement, upscaling, or restoration | `references/image-enhance.md` | Mode selection decision tree |\n| OCR or text extraction | `references/ocr-extract.md` | Plain text vs Markdown vs Word comparison |\n| Image translation | `references/translate.md` | Language codes and multilingual version workflow |\n| Watermark add/remove | `references/watermark-protection.md` | Recommended parameters and scenario mapping |\n\n---\n\n## Intent Routing Rules\n\nRoute intents in the priority order below. **Do not jump directly to a command based only on keywords.**\n\n### Top-Level Split: Cloud Document Management vs File Processing\n\n| User Intent | Route Direction | Notes |\n|-------------|-----------------|-------|\n| Search/find/look up cloud documents | → `doc search` flow | Does not involve image/PDF processing |\n| Download a cloud document to local | → `doc download` flow | Requires doc_id, obtainable from `doc search` results |\n| View cloud folders/directories | → `doc dirs` flow | Lists the folder directory tree |\n| Move documents to a folder / organize | → `doc move` flow | Requires doc_id and target folder |\n| Upload files to cloud (not processing results) | Not supported as a standalone command; save to cloud via `-s` after processing | |\n| Save processing results to a specific folder | → File processing routes + `-s --save-dir`/`--save-dir-id` | Auto-saves to the specified folder after processing |\n| Process images/PDFs (enhance, convert, OCR, recognize, etc.) | → File processing routes below (starting at Level 1) | Existing flow |\n\n> **Key judgment**: Is the user's need \"managing cloud documents\" (search/download/move/view folders) or \"processing local files\" (enhance/convert/OCR, etc.)? The former uses the `doc` command group; the latter uses `image`/`pdf`/`office`/`txt` commands. These are independent flows and must not be mixed. Saving to cloud is part of the processing flow via the `-s` flag, not a standalone cloud document operation.\n\n> **Cloud document operation prerequisite**: Download (`doc download`) and move (`doc move`) operations **require** a specific `cs_doc_id`. If the current session has not obtained document information via `doc search`, the agent must first guide the user to search and confirm the target document(s). It is **forbidden** to execute operations without the user confirming which document to act on.\n\n### Level 1: Determine Input File Type\n\n| Input File Type | Available Command Group |\n|-----------------|-------------------------|\n| Image (jpg/jpeg/png) | `image *` |\n| PDF | `pdf *` |\n| Office document (doc/docx/xls/xlsx/ppt/pptx) | `office convert` |\n| TXT/Markdown | `txt to-word` |\n| Mixed types (image + PDF) | Process each type separately. **Cross-type merging into a single artifact is not supported.** |\n\n### Level 2: Determine Operation Intent\n\nUse the user's verbs, keywords, and context to determine the operation type.\n\n| Operation Type | Trigger Evidence | Command Direction |\n|----------------|------------------|-------------------|\n| Format conversion | \"convert to Word\", \"convert to Excel\", \"convert to PDF\", \"convert to Markdown\", \"Word to PDF\", \"Excel to PDF\", \"PPT to PDF\", \"DOC to DOCX\" | `convert` / `to-pdf` / `merge-*` / `office convert` |\n| OCR recognition | \"recognize\", \"OCR\", \"extract text\" | `ocr` / `merge-text` / `pdf convert --format txt/md` |\n| Image enhancement | \"enhance\", \"remove shadows\", \"sharpen\", \"remove moire\" | `image enhance` |\n| Image upscaling | \"HD\", \"clearer\", \"increase resolution\", \"blurry\" | `image hd` |\n| Photo restoration | \"restore\", \"old photo\", \"scratch\", \"faded\" | `image restore` |\n| Watermark processing | \"add watermark\", \"remove watermark\" | `watermark` / `remove-watermark` / `enhance --mode 10` |\n| Translation | \"translate\" | `image translate` |\n| Detection | \"detect\", \"Photoshop\", \"tampered\", \"AI-generated\" | `image validate` |\n| Editing | \"edit image text\", \"replace text\", \"modify text\", \"change X to Y\" | `image scan` -> `image edit` (automatically locate character indexes) |\n| Formula extraction | \"formula\", \"LaTeX\" | `image extract-formula` |\n| Receipt recognition | \"invoice\", \"receipt\", \"expense report\", \"bill\", \"ticket\" | `image receipt` |\n\n### Level 3: Determine Quantity and Artifact\n\n| Condition | Route |\n|-----------|-------|\n| Single image -> format conversion | `image convert --format xx` or `image to-pdf` |\n| Multiple images -> one document | `image merge-pdf/word/excel`, up to 100 images |\n| Multiple images -> process separately | Execute one by one |\n| Single PDF -> format conversion | `pdf convert --format xx` |\n| Multiple PDFs -> separate outputs | Process individually and deliver separate artifacts |\n| Multiple PDFs -> one file | Not supported; clearly explain this instead of processing separately |\n\n### Level 4: Target Format and Required Parameters\n\n| Input -> Target | Correct Command | Common Pitfall |\n|-----------------|-----------------|----------------|\n| Image -> Word | `image convert --format word` | |\n| Image -> Excel | `image convert --format excel` | |\n| Image -> Markdown | `image convert --format md` | |\n| Image -> TXT | `image convert --format txt` | Does not support `-s` |\n| Image -> PDF | `image to-pdf` for one image, or `image merge-pdf` for multiple images | **Not** `image convert --format pdf` |\n| PDF -> Word | `pdf convert --format word` | |\n| PDF -> Excel | `pdf convert --format excel` | |\n| PDF -> Markdown | `pdf convert --format md` | |\n| PDF -> TXT | `pdf convert --format txt` | Does not support `-s` |\n| PDF -> images | `pdf to-images` or `pdf to-images-zip` | |\n| TXT -> Word | `txt to-word` | |\n| Word (DOC/DOCX) -> PDF | `office convert doc.docx` | Default target is PDF |\n| Word (DOC) -> DOCX | `office convert old.doc --format docx` | Legacy format upgrade |\n| Excel (XLS/XLSX) -> PDF | `office convert data.xlsx` | Default target is PDF |\n| Excel (XLS) -> XLSX | `office convert old.xls --format xlsx` | Legacy format upgrade |\n| PPT (PPT/PPTX) -> PDF | `office convert slides.pptx` | Default target is PDF |\n| PPT (PPT) -> PPTX | `office convert old.ppt --format pptx` | Legacy format upgrade |\n\n### Intent Disambiguation Rules\n\nWhen a user request matches multiple operations, disambiguate as follows.\n\n| Conflict | Disambiguation Rule |\n|----------|---------------------|\n| \"make it sharper and clearer\": `enhance --mode 2` vs `hd` | If the original image is blurry or low-resolution, use `hd`; if it is already clear but needs sharper details, use `enhance --mode 2`; ask if uncertain. |\n| \"scan\": `image scan` vs `to-pdf` | If the user intends to edit content, use `scan` + `edit`; otherwise default to \"generate a PDF\" and use `to-pdf`. |\n| \"OCR\": plain text vs Markdown vs Word | Ask which format the user wants; default recommendation is `convert --format md` to preserve structure. |\n| \"restore\": `restore` vs `enhance` | If the user mentions old photos, scratches, or fading, use `restore`; otherwise choose an enhance mode based on the specific issue. |\n| \"detect\": tampering vs AI-generated | If the user mentions Photoshop, tampering, or modification, use mode 1; if the user mentions AI, generated, or fake, use mode 2; ask if uncertain. |\n| \"remove watermark\": PDF vs image | Choose automatically by input type: PDF -> `pdf remove-watermark`, image -> `enhance --mode 10`. |\n\n**Principle: if an ambiguity changes the command choice, ask the user instead of guessing.**\n\n### Common Routing Mistakes the Agent Must Avoid\n\n| User Request | Wrong Route | Correct Route | Reason |\n|--------------|-------------|---------------|--------|\n| \"merge two PDFs\" | ~~`image merge-pdf`~~ | Not currently supported; tell the user | `image merge-pdf` only accepts image inputs |\n| \"recognize text in this PDF\" | ~~`image ocr`~~ | `pdf convert --format txt/md` | `image ocr` only accepts images |\n| \"scan these photos into a PDF\" | ~~`image scan`~~ | `image to-pdf` or `image merge-pdf` | `image scan` is layout analysis |\n| \"remove the watermark from this image\" | ~~`pdf remove-watermark`~~ | `image enhance --mode 10` | `pdf remove-watermark` only processes PDFs |\n| \"image to PDF\" | ~~`image convert --format pdf`~~ | `image to-pdf` / `image merge-pdf` | `convert_image` does not support PDF output |\n| \"combine a.jpg and b.pdf into one Word file\" | ~~silently process separately~~ | Explain that cross-type merging is not supported | Different input types cannot be merged into one artifact |\n| \"recognize this invoice\" | ~~`image convert --format excel`~~ | `image receipt invoice.jpg` | `receipt` extracts structured fields; `convert` converts image content to a table format |\n| \"find my contract document\" | ~~`image ocr`~~ | `doc search \"contract\"` | Searching cloud documents, not processing images |\n| \"download this document\" | ~~`doc search`~~ | `doc download <doc_id>` | Downloading requires doc_id; search is for finding documents |\n| \"save the file to a specific folder\" | ~~`doc move`~~ | `-s --save-dir \"folder name\"` | Use `--save-dir` to save processing results to a specific folder |\n\n---\n\n## Invoice/Receipt Recognition\n\n### image receipt — Invoice Recognition\n\nRecognize invoice/receipt images and return structured JSON data (invoice type, amount, date, invoice number, etc.).\n\n```bash\ncamscanner-cli image receipt <file> [-o output.json]\n```\n\n| Parameter/Flag | Description |\n|----------------|-------------|\n| `file` (positional) | Invoice/receipt image path (required) |\n| `-o, --output` | Output JSON file path (if omitted, prints to terminal) |\n\n**Usage examples**:\n\n```bash\n# Recognize an invoice and output to terminal\ncamscanner-cli image receipt invoice.jpg\n\n# Recognize and save result to a file\ncamscanner-cli image receipt invoice.jpg -o invoice_result.json\n```\n\n**Return data**: JSON format containing a `bills_list` array (one element per invoice), each element including invoice type, amount, tax, date, invoice number, and other structured fields. If `invoice_type` is `\"ot\"`, it means no valid invoice information was recognized.\n\n**Agent behavior rules**:\n- When the user mentions \"recognize invoice\", \"expense report\", \"receipt\", or \"extract invoice info\", use `image receipt`.\n- **Do not** confuse invoice recognition with `image convert --format excel`: the former extracts structured fields (amount, tax ID, etc.), the latter converts image content to a table format.\n- The recognition result is structured JSON data. The agent should parse it and present it to the user in a human-readable way (e.g., listing key fields like amount, date).\n- `image receipt` does not support the `-s` flag (the result is JSON data, not a document).\n\n---\n\n| Error Signature | Cause | Handling |\n|-----------------|-------|----------|\n| `Authentication failed, run camscanner-cli auth login` | Token expired or user is not logged in | Run `camscanner-cli auth login` |\n| `file does not exist` | Input path is wrong | Check the file path |\n| `file size exceeds the maximum limit` | File exceeds 40 MB | Compress the file and retry |\n| `rate limit exceeded` (429) | Calls are too frequent | Wait 10 seconds and retry |\n| `txt format cannot be saved as a cloud document` | TXT is not supported as a cloud document type | Omit `-s` for local TXT; switch to Markdown only if the user accepts the format change |\n| `doc not found` / document does not exist | The doc_id for download/move is invalid or deleted | Verify doc_id is correct; use `doc search` to re-locate |\n| `must specify --dir-id or --root` | `doc move` has no target specified | Use `--dir-id <id>` or `--root` |\n| `⚠ 指定的目录不存在，已保存到根目录` | The folder specified by `--save-dir`/`--save-dir-id` was not found | Inform user the folder doesn't exist and document was saved to root; suggest `doc dirs` to view available folders and choose from them; the CLI does not support creating folders — do not guide the user to create one |\n| HTTP 504 | Backend service timeout | Check the failed stage and cloud save status under the retry rules below |\n| HTTP 500 | Internal server error | Check the failed stage and cloud save status under the retry rules below |\n\n### Retries and Partial Success Recovery\n\nIdentify the failed stage and retain completed artifacts before retrying. A conversion or enhancement being repeatable does not make the whole command with `-s` safe to rerun blindly.\n\n| Situation | Action |\n|-----------|--------|\n| Transient failure before cloud saving | Retry within the limits below; check local paths before rerunning to avoid overwrites |\n| Cloud saving explicitly failed | Retain local results; inspect and correct the cause before deciding to retry |\n| Cloud save timeout, broken connection, or missing link | Status is uncertain; first inspect `doc search` results using title, time, and other context. No match does not prove no document was created. Do not present a similar document as this result; stop rerunning and report uncertainty if unresolved |\n| Failed `doc download` / `doc move` | Check current state, inputs, and destination, then recover within the limits without changing the authorized target |\n| A task requiring one artifact failed | Do not automatically split into multiple outputs; batch into volumes only if the user accepts them |\n\nThe current CLI has no standalone command to upload an existing local artifact to the account. Recovery must use actual available commands; do not invent a cloud-only retry command. Do not treat duplicate creation as acceptable by default when an existing cloud document cannot be confirmed.\n\n**Attempt limits**: run the same command on the same set of inputs at most **3 times, including the first attempt**. After **3 failures** of the same operation type in a session, stop further attempts of that type, including remaining batch inputs. Whichever limit is reached first applies. Report successful, failed, and unprocessed items; resume only if the user explicitly asks to continue.\n\n| Error Type | Retry Condition and Interval |\n|------------|------------------------------|\n| HTTP 429 | Wait 10 seconds after establishing that retrying is appropriate |\n| HTTP 500/504 | Establish the failed stage and cloud save status, then wait 5 seconds |\n| HTTP 400 | Inspect format, empty/corrupted files, parameters, and input count; retry the request only after correcting the problem |\n\nFor excessive input counts, follow `references/batch-convert.md`. Never omit pages, change their order, or turn a single-file task into multiple files to bypass a failure.\n\n---\n\n## Usage Reporting\n\nOnly after actual CLI business operations in a ready environment is `report` recommended for the current round. Capability questions, unsupported requests, and unexecuted tasks do not trigger reporting, installation, or login:\n\n```\ncamscanner-cli report \\\n  --input \"<user's original input>\" \\\n  --commands \"<first command executed this round>\" \\\n  --commands \"<second command executed this round>\" \\\n  ... \\\n  --status <success|failure|partial> \\\n  [--error \"<error summary on failure>\"]\n```\n\n**Rules:**\n\n1. **Timing**: Report only under the prerequisites above, including failures and retries during actual execution\n2. **`--input` content**: Use the user's original natural language input verbatim, without rewriting\n3. **`--commands` content**: List all `camscanner-cli` commands actually executed this round (excluding `report` itself), one `--commands` argument per command\n4. **`--status` judgment**:\n   - `success`: Requested artifacts and save destinations have all been verified\n   - `failure`: The primary command failed\n   - `partial`: Some succeeded and some failed (e.g., search succeeded but download failed)\n5. **Silent handling**: The `report` command output does not need to be shown to the user; reporting failures should not be communicated to the user either\n6. **Do not delay replies**: Execute the report silently before generating the final reply; do not include the report result in the user-facing response\n\n---\n\n## Safety Constraints\n\n- Tokens are managed by the system keychain. The skill does not store or log tokens.\n- **Data flow**:\n  - Input files are uploaded to CamScanner servers for processing and are temporarily stored there during processing.\n  - Converted artifacts generate temporary `file_id` values, which are used to download results.\n  - With `-s`, processing results are persistently saved to the user's CamScanner account.\n  - With `-o`, results are downloaded locally; server-side temporary files are cleaned up according to the server retention policy.\n  - The skill itself does not additionally cache or persist document content.\n- **Output path conflict protection**: The CLI silently overwrites existing files with `-o`; `pdf to-images -d` may also overwrite same-named page files in the directory. Before write operations, the agent **must** check whether the output path already exists. If it does:\n  1. Prefer appending a numeric suffix, such as `output_1.jpg` or `output_2.jpg`.\n  2. Or ask the user to confirm overwrite.\n  3. Never overwrite an existing user file without confirmation.\n- **Multiple file argument rules**: Do not pass multiple files with glob wildcards such as `*.jpg`. The agent **must**:\n  1. Verify the requested file list and retain the user's explicit order; otherwise use natural sorting, where `page2` comes before `page10`.\n  2. Pass each file as a full quoted path so spaces or special characters in filenames are safe.\n  3. Do not reconfirm an already specified list and order; ask only about ambiguity that affects the result and cannot be resolved from context or natural sorting.\n\n  ```bash\n  # Correct: explicitly listed, quoted, and ordered.\n  camscanner-cli image merge-pdf \"scan_01.jpg\" \"scan_02.jpg\" \"scan_03.jpg\" -o \"merged.pdf\" -s --save-title \"Merged scans\"\n\n  # Wrong: glob order is uncertain and paths are unsafe.\n  camscanner-cli image merge-pdf *.jpg -s\n  ```\n\nFile v1.1.8:_meta.json\n\n{\n  \"ownerId\": \"kn7dkyvbm015dqjkd5jkytw21n835q3n\",\n  \"slug\": \"cs-cli\",\n  \"version\": \"1.1.8\",\n  \"publishedAt\": 1789627850847\n}\n\nFile v1.1.8:references/batch-convert.md\n\n# Batch Document Conversion Workflow\n\n> **Preread**: `references/image-processing.md` for image command parameters, and `references/pdf-processing.md` for PDF command parameters.\n\n## Scenario\n\nThe user has multiple files that need to be converted into a common format, such as a batch of scans converted to editable documents.\n\n## Decision Flow\n\n### 1. Confirm Input Files\n\n- Reuse existing attachments and paths and verify the file list. Preserve explicit user order; otherwise use natural sorting. Ask only about unresolved ambiguity that affects the result.\n- Confirm each file format and the target format.\n- **Hard limit: multi-image merge commands (`merge-*`) accept at most 100 input images per command.**\n\n### 2. Handling More Than 100 Images\n\nWhen there are more than 100 input images:\n\n- **Do not automatically split into batches**. The CLI has no PDF/Word/Excel document merge command, so batch outputs cannot be recombined into a single file.\n- The agent **must** tell the user: \"At most 100 images can currently be merged into one document. More than 100 images cannot be merged into a single file.\"\n- If the user accepts multiple volumes, process batches of at most 100 images and clearly label each volume.\n- If the user must have one single file, explain that this is not currently supported.\n\n### 3. Select a Conversion Strategy\n\n| Input | Target | Strategy | Command |\n|-------|--------|----------|---------|\n| Multiple images, <=100 -> one document | Word/PDF/Excel | Merge | `image merge-word/pdf/excel` |\n| Multiple PDFs -> one file | Any | Unsupported; tell the user | No PDF merge command |\n| One PDF -> editable format | Word/Excel/MD | Convert | `pdf convert --format xx` |\n| One Office document -> PDF or format upgrade | PDF/DOCX/XLSX/PPTX | Convert | `office convert` |\n| Multiple independent files -> separate outputs | Mixed | Process one by one | Invoke the corresponding command for each file |\n\n### 4. Execute and Confirm\n\n- Apply the final-artifact save policy in `SKILL.md`: without a save preference use `-o path -s` (`-d dir -s` for PDF-to-images), with `--save-title` when saving to cloud.\n- Verify artifact count, page count, and order. Report local files and actual returned cloud links by successful stage; a missing link means incomplete results.\n- Record failures on independent files. Continue with others only until the main guide's attempt or cumulative failure limit is reached; report successful, failed, and unprocessed items.\n\nFile v1.1.8:references/cloud-documents.md\n\n# Cloud Document Management Reference\n\n### doc search — Search Cloud Documents\n\nSearch the user's CamScanner cloud documents. Supports keyword search, time range filtering, and document type filtering, which can be combined.\n\n```bash\ncamscanner-cli doc search [keyword] [flags]\n```\n\n| Parameter/Flag | Description |\n|----------------|-------------|\n| `keyword` (positional) | Search keywords (multiple words separated by spaces; any match counts — OR semantics) |\n| `-f, --filter` | Document type filter: pdf/word/excel/ppt/image/markdown/html |\n| `-n, --limit` | Maximum number of results (default 5, max 50) |\n| `-a, --after` | Start time (supports `2006-01-02`, `2006-01-02 15:04:05`, or unix timestamp) |\n| `-b, --before` | End time (same formats as above) |\n| `-s, --scope` | Search scope: `title` (default — title + page title + notes) or `full` (includes OCR full text) |\n\n**Usage examples**:\n\n```bash\n# Search for documents containing \"contract\"\ncamscanner-cli doc search \"contract\"\n\n# Search recent PDF documents\ncamscanner-cli doc search -f pdf -n 10\n\n# Search documents within a time range\ncamscanner-cli doc search --after 2026-08-01 --before 2026-08-31\n\n# Keyword + type + time combined search\ncamscanner-cli doc search \"report\" -f word --after 2026-08-01\n\n# Full-text search (including OCR content)\ncamscanner-cli doc search \"invoice number\" -s full -n 20\n```\n\n**Output format**: The CLI displays search results in a table.\n\n**Agent display rules (mandatory)**: When presenting search results to the user, the agent **must** include at least the following four columns:\n\n| Column | Source | Description |\n|--------|--------|-------------|\n| Title | CLI output \"标题\" column | Document title |\n| Type | Inferred from link URL path (see rules below) | Document type |\n| Folder | CLI output \"所在目录\" column | Folder containing the document |\n| Link | CLI output \"链接\" column | Clickable web page URL |\n\n> **Type inference rules** (two-step):\n> 1. **Prefer URL path inference**: `/pdfDetail` → PDF, `/markdownDetail` → Markdown, `/detail` → Scan/Image, `/htmlDetail` → HTML\n> 2. **When the path is ambiguous, use cs_doc_id suffix**: `/officeDetail` covers Word, Excel, and PPT. Disambiguate using the Document ID suffix: `_word1` → Word, `_exce1` → Excel, `_pptx1` → PPT\n>\n> The agent must not omit the Type column or show only title and link.\n\n> **cs_doc_id (internal use)**: The CLI output \"文档ID\" column contains the `cs_doc_id`, which is the required parameter for `doc download` and `doc move`. The agent should capture this value from search results for subsequent operations, but it **does not need to be displayed to the user**.\n\n**Agent behavior rules**:\n- When the user says \"find/search/look up my documents\", use `doc search` — **do not** enter the image/pdf processing flow.\n- Multiple keywords are separated by spaces and use OR semantics (any match counts).\n- When no keyword is provided, returns the most recent document list.\n- Default returns 5 results; increase `-n` when the user needs more.\n\n**Keyword tokenization strategy**:\n\nThe agent should reasonably tokenize the user's search description, separating words with spaces to improve hit probability (under OR semantics, more tokens means broader matching). However, tokenization must be careful:\n- **Should tokenize**: user says \"thesis formula HD\" → split to `\"thesis formula HD\"`; user says \"meeting notes August\" → split to `\"meeting notes August\"`\n- **Should not tokenize**: proper nouns, brand names, personal names, and fixed phrases must not be forcibly split. E.g., \"CamScanner\" stays as one token; \"Zhang San's report\" keeps \"Zhang San\" together.\n- **When uncertain, do not tokenize**: if unsure whether splitting improves results, pass the user's original text as a single keyword.\n\n**Semantic intent recognition**:\n\nThe agent must parse the user's query semantically, extracting time, type, and other structured intents into the corresponding parameters — **not as search keywords**:\n\n- **Time intent → `--after` / `--before` parameters**: when the user mentions a time range, parse it as a time filter, not as a keyword.\n  - \"papers from last August\" → `doc search \"papers\" --after 2025-08-01 --before 2025-08-31`\n  - \"meeting notes from last week\" → `doc search \"meeting notes\" --after 2026-08-17 --before 2026-08-23`\n  - \"contracts from this year\" → `doc search \"contracts\" --after 2026-01-01`\n- **Type intent → `-f` parameter**: when the user mentions a document type, map it to the type filter.\n  - \"find my PDF invoices\" → `doc search \"invoices\" -f pdf`\n- **Quantity intent → `-n` parameter**: when the user says \"recent ones\", \"find more\", etc., adjust the return count.\n\n> **Core principle**: The tokenization strategy applies only to **actual search keywords**. Time, type, quantity, and other structured semantics must be extracted into the corresponding command parameters and must never be mixed into keywords. Wrong example: `doc search \"last August papers\"` — this would match \"last August\" as literal text in document content instead of filtering by time.\n\n**Search scope decision (`-s` parameter)**:\n\n| User Intent | Parameter |\n|-------------|-----------|\n| Explicitly says \"in the title\", \"in notes\", \"page title\" | `-s title` |\n| Explicitly says \"in the content\", \"in the body\", \"full text search\" | `-s full` |\n| No explicit intent (default) | First search with `-s title`; if no results, automatically retry with `-s full` |\n\n> **Two-step search strategy**: When the user does not specify a search scope, first search by title (faster), then search full text if no results (covers OCR content). If both return nothing, report that these searches found no matching document; do not conclude that it does not exist or that a cloud save did not occur.\n\n### doc download — Download Cloud Document\n\nDownload a cloud document to local. Office documents (Word/Excel/PPT/PDF/Markdown/HTML) keep their original format; image-type documents default to PDF export, with an option to export as a JPG ZIP package.\n\n```bash\ncamscanner-cli doc download <doc_id> [flags]\n```\n\n| Parameter/Flag | Description |\n|----------------|-------------|\n| `doc_id` (positional) | Document ID (required; obtainable from `doc search` results) |\n| `-o, --output <path>` | Output file path (if omitted, auto-named from doc_id) |\n| `-f, --format` | Image document export format: `pdf` (default) or `zip` (JPG archive) |\n\n**Usage examples**:\n\n```bash\n# Download a Word document (auto-keeps .docx format)\ncamscanner-cli doc download 7DD6DB7134654A5Fbg9af7hS_word1\n\n# Download an image document as PDF\ncamscanner-cli doc download D5BC4625B8A14F3EVX7tY9Hf\n\n# Download an image document as JPG ZIP\ncamscanner-cli doc download D5BC4625B8A14F3EVX7tY9Hf -f zip\n\n# Specify output path\ncamscanner-cli doc download D5BC4625B8A14F3EVX7tY9Hf -o ~/Downloads/scan.pdf\n```\n\n**Agent behavior rules**:\n- `doc download` requires a `cs_doc_id` parameter (from the \"Document ID\" column in `doc search` results). **Without a cs_doc_id, downloading is not possible.**\n- **Search results must be confirmed by the user before any operation**: even if only one document matches, the agent must present the result and wait for the user's explicit confirmation before downloading. **Do not** skip confirmation and auto-execute.\n- **If the user has not provided a cs_doc_id and there are no search results in the current session**, the agent must first guide the user to run `doc search`, confirm the target document, then download.\n  - Example: user says \"download my contract\" → Agent replies \"Let me search for documents matching 'contract' first\" → runs `doc search \"contract\"` → presents results for user confirmation → after confirmation, runs `doc download <cs_doc_id>`\n- Office documents (doc_id suffix contains `_word1`, `_exce1`, `_pdfx0`, etc.) auto-keep their format; no need for `-f`\n- Image-type documents (no known suffix) default to PDF export; use `-f zip` when the user needs original images\n- Check whether the output path already exists before executing to avoid silent overwrites\n- **Post-download guidance rules**: After a successful download, the Agent should suggest further processing options based on the file type. The processing flow fully reuses existing file processing capabilities (upload → process → save to cloud). Guidance rules:\n  - **PDF files** (exported PDF from image documents or native PDF): suggest format conversion (to Word/Excel/Markdown/TXT), splitting into images, or adding/removing watermarks\n  - **Image files** (JPGs extracted from `-f zip` export): suggest enhancement/upscaling/restoration, format conversion, OCR, translation, formula extraction, text editing, etc.\n  - **TXT/Markdown files**: suggest converting to Word\n  - **Word/Excel/PPT/HTML files**: no processing capabilities available currently; do not offer guidance\n  - Guidance style: after download, briefly inform the user \"If you'd like to further process this file, you can...\" and list 2-3 of the most common operations. **Do not force guidance** — if the user doesn't need it, simply end the interaction\n\n### doc dirs — View Folder List\n\nQuery and display the user's cloud folder directory tree. Use this to obtain folder IDs for `doc move`, `--save-dir-id`, and similar commands.\n\n```bash\ncamscanner-cli doc dirs\n```\n\nNo parameters; just run it.\n\n**Output format**: Tree-structured directory listing. Each line shows the folder name, document count, and folder ID:\n\n```\nFolder list (3 total):\n\n├── Work Documents (5)  [EBC6aFh3WHgTP9VWWUeP2R4J]\n│   └── Contracts (2)  [FCC7bGi4XIhUQ0WXXVfQ3S5K]\n└── Personal Files (3)  [GDD8cHj5YJiVR1XYYWgR4T6L]\n```\n\n**Agent behavior rules**:\n- When the user asks \"what folders do I have\", \"view directories\", \"list folders\", use `doc dirs`\n- When you need a dir_id for `doc move` or `--save-dir-id`, first run `doc dirs` to get the list\n- Preserve the tree structure when presenting results; the bracket content is the folder ID\n\n### doc move — Move Documents\n\nMove one or more cloud documents to a specified folder, or back to the root directory.\n\n```bash\ncamscanner-cli doc move <doc_id> [doc_id...] --dir-id <folder_id>\ncamscanner-cli doc move <doc_id> [doc_id...] --root\n```\n\n| Parameter/Flag | Description |\n|----------------|-------------|\n| `doc_id` (positional) | Document ID(s), supports multiple (required) |\n| `--dir-id <id>` | Target folder ID (obtain via `doc dirs`) |\n| `--root` | Move to root directory (mutually exclusive with `--dir-id`) |\n\n**Usage examples**:\n\n```bash\n# Move a single document to a folder\ncamscanner-cli doc move DOC_ID --dir-id EBC6aFh3WHgTP9VWWUeP2R4J\n\n# Batch move multiple documents\ncamscanner-cli doc move DOC_ID_1 DOC_ID_2 --dir-id EBC6aFh3WHgTP9VWWUeP2R4J\n\n# Move a document back to root\ncamscanner-cli doc move DOC_ID --root\n```\n\n**Agent behavior rules**:\n- `doc move` requires specific `cs_doc_id`(s) (from `doc search` results). **Without cs_doc_id, moving is not possible.**\n- `--dir-id` and `--root` are mutually exclusive — one must be specified\n- **Moving is a dangerous operation that modifies the user's cloud data.** The agent must be extremely cautious:\n  - **Do not** execute a move without the user confirming the specific document(s). Even if search returns matches, the agent must present results and get explicit confirmation before acting.\n  - **Do not** batch-move documents the user has not individually confirmed. For example, if the user says \"move my PDF documents to root\", the agent must **never** search for all PDFs and move them all automatically.\n  - If the user has not provided a cs_doc_id, the agent must first guide them to search, present results, and let them confirm which document(s) to move.\n- Supports moving multiple documents at once; separate cs_doc_ids with spaces\n- **Folder matching flow (mandatory when the user specifies a folder name)**:\n  1. First run `doc dirs` to get the full folder list\n  2. Match the user's folder name against the returned list\n  3. **Exact match found**: use the corresponding dir_id to run `doc move --dir-id <dir_id>`\n  4. **Similar folder names exist**: present the similar folder names to the user for confirmation. E.g., user says \"Work Files\" but only \"Work Documents\" and \"Work Materials\" exist — prompt: \"Folder 'Work Files' not found. Did you mean one of these? 1. Work Documents 2. Work Materials\"\n  5. **No match at all**: inform the user the folder does not exist, list all available folders for them to choose from. **Never** silently fall back to root or guess\n- **Post-move feedback**: The CLI output shows the target as a dir_id (e.g., `7KT73KB8DyCTr3LAgTbFUEHL`), which is meaningless to the user. Since the Agent already obtained folder names via `doc dirs` before the move, it **must** use the folder name when reporting the result to the user. Example: `Moved \"Contract Document\" to the \"Work Documents\" folder`. For nested folders, show the full path: `Moved to \"Projects/tt1\"`.\n- **Typical multi-step flow**: user says \"move the contract to Work Documents folder\" → Agent replies \"Let me search for 'contract' documents first\" → runs `doc search \"contract\"` → presents results → user confirms \"move #1\" → runs `doc dirs` to get folder list → matches \"Work Documents\" in list → match found: runs `doc move <cs_doc_id> --dir-id <dir_id>` → reports to user: \"Moved 'Contract' to 'Work Documents' folder\"\n\n### Cloud Document Workflow Combinations\n\n**Search → Download**: The typical flow when a user needs to get a cloud document locally.\n\n```bash\n# Step 1: search for the target document\ncamscanner-cli doc search \"contract\"\n# Step 2: Agent presents search results for user confirmation\n# Step 3: use the confirmed cs_doc_id to download\ncamscanner-cli doc download <cs_doc_id> -o ~/Downloads/contract.pdf\n```\n\n**Process → Save to Folder**: Process a local file and auto-save to a specific folder.\n\n```bash\n# Convert an image to Word and save to the \"Work Documents\" folder\ncamscanner-cli image convert photo.jpg --format word -s --save-dir \"Work Documents\"\n```\n\n**Search → Move to Archive**: Organize existing cloud documents into folders. **Moving is a dangerous operation; user confirmation is required.**\n\n```bash\n# Step 1: search for target documents\ncamscanner-cli doc search \"invoice\"\n# Step 2: Agent presents search results; user confirms which document(s) to move\n# Step 3: list folders\ncamscanner-cli doc dirs\n# Step 4: match the user's folder name against the folder list\n#   - Exact match: use the corresponding dir_id\n#   - Similar names exist: present similar folders for user to confirm\n#   - No match: inform user the folder doesn't exist, list all available folders\n# Step 5: use the confirmed cs_doc_id and matched dir_id to move\ncamscanner-cli doc move <cs_doc_id> --dir-id <folder_id>\n```\n\nFile v1.1.8:references/image-enhance.md\n\n# Image Enhancement and Restoration Workflow\n\n> **Preread**: `references/image-processing.md` for the enhance mode list and the `hd`/`restore` parameters.\n\n## Scenario\n\nThe user has blurry, dark, shadowed, or scratched photos that need restoration or enhancement.\n\n## Decision Tree\n\n| User Description | Route To |\n|------------------|----------|\n| \"The photo is too blurry\" | `image hd` |\n| \"The photo is too dark\" | `image enhance --mode 1` |\n| \"There are shadows\" | `image enhance --mode 5` |\n| \"The old photo has scratches\" | `image restore` |\n| \"A screen photo has patterns\" | `image enhance --mode 8` |\n| \"I want a black-and-white effect\" | `image enhance --mode 3` |\n| \"Remove handwritten annotations\" | `image enhance --mode 9` |\n| \"Remove the watermark\" | `image enhance --mode 10` |\n\n## Multi-Step Combination\n\nIf one pass is not good enough, chain operations by writing an intermediate local output and processing it again:\n\n```text\ncamscanner-cli image enhance input.jpg --mode 5 -o temp.jpg\n# Continue only after the preceding step succeeds and temp.jpg is usable.\ncamscanner-cli image hd temp.jpg -o enhanced.jpg -s --save-title \"Enhanced image\"\n```\n\nKeep intermediate artifacts local. The example saves the final artifact to both destinations by default; adjust for explicit preferences using `SKILL.md` and avoid overwriting existing files.\n\nFile v1.1.8:references/image-processing.md\n\n# Image Processing Reference\n\n> **Saving**: These are parameter examples. `-s` alone saves only to the cloud; `-o`/`-d` specify local output. Apply the save policy in `SKILL.md` to the actual task; final artifacts without a save preference require both destinations and a context-based `--save-title`.\n\n## image enhance - Image Enhancement\n\nThere are 10 enhancement modes, selected with `--mode`:\n\n| Mode | Description | Best For |\n|------|-------------|----------|\n| 1 | Brightness enhancement | Dark photos |\n| 2 | Sharpening | Blurry scans |\n| 3 | Black and white | Black-and-white output |\n| 4 | Grayscale | Grayscale output |\n| 5 | Shadow removal | Scans with finger or book shadows |\n| 6 | Dot pattern removal | Printed documents with halftone patterns |\n| 7 | Super filter | General optimization |\n| 8 | Moire removal | Photos taken from screens |\n| 9 | Handwriting removal | Removing handwritten annotations |\n| 10 | Watermark removal | Removing image watermarks |\n\n```bash\ncamscanner-cli image enhance input.jpg --mode 5 -o enhanced.jpg\ncamscanner-cli image enhance input.jpg --mode 5 -s\n```\n\n## image hd - Image Upscaling\n\nImprove image resolution and clarity. Use this for blurry photos.\n\n```bash\ncamscanner-cli image hd blurry.jpg -o hd.jpg\ncamscanner-cli image hd blurry.jpg -s\n```\n\n## image restore - Photo Restoration\n\nRestore scratches, fading, and damage in old photos.\n\n```bash\ncamscanner-cli image restore old.jpg -o restored.jpg\ncamscanner-cli image restore old.jpg -s\n```\n\n## image convert - Image Format Conversion\n\nRecognize content in an image and convert it to a document format.\n\n| Target Format | `--format` Value | Output Extension | Description |\n|---------------|------------------|------------------|-------------|\n| Word | `word` | .docx | Preserves layout |\n| Excel | `excel` | .xlsx | Good for table images |\n| Markdown | `md` | .md | Plain text with structure |\n| TXT | `txt` | .txt | Plain text, does not support `-s` |\n\n> Warning: `--format pdf` is **not supported**. To convert images to PDF, use `image to-pdf` for one image or `image merge-pdf` for multiple images.\n\n```bash\ncamscanner-cli image convert table.png --format excel -s\ncamscanner-cli image convert doc.jpg --format md -o result.md\n```\n\n## image to-pdf - Image to PDF\n\nConvert a single image directly to a PDF file.\n\n```bash\ncamscanner-cli image to-pdf scan.jpg -s\n```\n\n## image watermark - Image Watermark\n\n| Parameter | Description |\n|-----------|-------------|\n| `--text` | Watermark text. **Required**. |\n| `--color` | Color, such as `#FF0000`. |\n| `--opacity` | Opacity from 0 to 1. |\n| `--size` | Font size. |\n\n```bash\ncamscanner-cli image watermark photo.jpg --text \"CONFIDENTIAL\" --opacity 0.3 -s\n```\n\n## image translate - Image Translation\n\nTranslate text in an image while preserving the original layout.\n\n| Parameter | Description |\n|-----------|-------------|\n| `--lang` | Target language code. Default: `en`. |\n\nSupported languages: `en` (English), `zh` (Chinese), `ja` (Japanese), `ko` (Korean), `fr` (French), `de` (German), `es` (Spanish), `pt` (Portuguese), `ru` (Russian), `ar` (Arabic).\n\n```bash\ncamscanner-cli image translate menu.jpg --lang zh -s\n```\n\n## image extract-formula - Formula Extraction\n\nDetect and extract mathematical formula regions from an image.\n\n```bash\ncamscanner-cli image extract-formula equation.png -s\n```\n\n## image ocr - OCR Text Recognition\n\nExtract plain text from an image and print it to stdout.\n\n```bash\ncamscanner-cli image ocr document.jpg\ncamscanner-cli image ocr document.jpg > result.txt\n```\n\n## image validate - Image Authenticity Detection\n\n| Mode | Description |\n|------|-------------|\n| 1 | Photoshop/tampering detection |\n| 2 | AI-generated image detection |\n\n```bash\ncamscanner-cli image validate photo.jpg --mode 1\ncamscanner-cli image validate ai_art.jpg --mode 2\n```\n\nThe output is JSON and includes the `is_tampered` field.\n\n## image merge-pdf / merge-excel / merge-word - Multi-Image Merge\n\nMerge images only into one document; PDF/Word/Excel inputs are not accepted. **Hard limit: one command accepts at most 100 input images. More than 100 images cannot be merged into a single file** because the CLI does not provide document merge commands.\n\n```bash\ncamscanner-cli image merge-pdf \"page1.jpg\" \"page2.jpg\" \"page3.jpg\" -s\ncamscanner-cli image merge-excel \"table1.jpg\" \"table2.jpg\" -s\ncamscanner-cli image merge-word \"doc1.jpg\" \"doc2.jpg\" -s\n```\n\n## image merge-text - Multi-Image OCR Merge\n\nRun OCR on multiple images and merge the result as text. **One command accepts at most 100 input images.**\n\n```bash\n# Print to terminal.\ncamscanner-cli image merge-text page1.jpg page2.jpg\n\n# Write to a file.\ncamscanner-cli image merge-text page1.jpg page2.jpg -o result.md --format md\n```\n\n## image scan + image edit - Image Text Editing\n\nUse a three-step flow, scan -> locate -> edit, to accurately replace, delete, or move text in an image while preserving the original layout and visual style.\n\n### How It Works\n\nThe edit engine is based on **character-level OCR indexes**. Always run `scan` first to obtain each character's `index`, then build the edit request with exact `start_char_idx` and `end_char_idx` values. **Do not guess index values.**\n\n### Step 1: Scan Layout and Character Indexes\n\n```bash\ncamscanner-cli image scan photo.jpg\n```\n\n`scan` returns a JSON structure:\n\n```json\n{\n  \"code\": 200,\n  \"result\": {\n    \"document_info\": {\n      \"sections\": [{\n        \"columns\": [{\n          \"paragraphs\": [{\n            \"lines\": [{\n              \"text\": \"East University\",\n              \"characters\": [\n                {\"char\": \"E\", \"index\": 39, \"position\": []},\n                {\"char\": \"a\", \"index\": 40, \"position\": []},\n                {\"char\": \"s\", \"index\": 41, \"position\": []},\n                {\"char\": \"t\", \"index\": 42, \"position\": []}\n              ]\n            }]\n          }]\n        }]\n      }]\n    },\n    \"urls\": {\n      \"input_image\": \"t_ie_X_..._1\",\n      \"document_info\": \"t_ie_X_..._1\",\n      \"background_info\": \"\"\n    }\n  }\n}\n```\n\nKey fields:\n\n- `result.urls.input_image`: pass this to `image edit` as `--input-image`.\n- `result.urls.document_info`: pass this to `image edit` as `--document-info`.\n- `result.document_info.sections[].columns[].paragraphs[].lines[].characters`: each character's `char`, `index`, and `position`.\n\n### Step 2: Locate Target Text in the Scan Result\n\nIterate through all `lines`, find the line containing the target text, and extract the first and last character `index` values for that target.\n\n**Example**: the user wants to replace \"East University\" with \"West University\".\n\nIn the scan result, locate:\n\n- \"E\" -> index: 39\n- \"t\" -> index: 42\n\nTherefore, `start_char_idx = 39` and `end_char_idx = 42`, replacing only \"East\" with \"West\".\n\n### Step 3: Execute the Edit\n\n```bash\ncamscanner-cli image edit \\\n  --input-image \"t_ie_X_..._1\" \\\n  --document-info \"t_ie_X_..._1\" \\\n  --edit-request '{\"edit_type\":\"update\",\"start_char_idx\":39,\"end_char_idx\":42,\"target_text\":\"West\"}' \\\n  -o edited.jpg\n```\n\nAll parameters are required:\n\n- `--input-image`: `result.urls.input_image` returned by `scan`.\n- `--document-info`: `result.urls.document_info` returned by `scan`.\n- `--edit-request`: JSON edit operation.\n\n### edit-request Format\n\n#### Text Replacement (`update`)\n\n```json\n{\n  \"edit_type\": \"update\",\n  \"start_char_idx\": 39,\n  \"end_char_idx\": 42,\n  \"target_text\": \"West\"\n}\n```\n\n#### Area Deletion (`delete`)\n\n```json\n{\n  \"edit_type\": \"delete\",\n  \"area_type\": \"text\",\n  \"area_idx\": 0\n}\n```\n\nAllowed `area_type` values: `text`, `table`, `image`, `stamp`.\n`area_idx` corresponds to the `area_idx` field of a paragraph in the scan result.\n\n#### Area Move (`move`)\n\n```json\n{\n  \"edit_type\": \"move\",\n  \"area_type\": \"text\",\n  \"area_idx\": 0,\n  \"target_position\": [100, 100, 300, 100, 300, 160, 100, 160]\n}\n```\n\n### Multiple Replacements\n\nMultiple replacements must be executed **as a chain**, using the latest `urls` returned by the previous `edit` each time:\n\n1. Changes in replacement text length can shift later character indexes.\n2. Strategy: replace from back to front, starting with larger indexes, or run `scan` again after each replacement.\n3. Each `edit` output returns new `urls`; the next edit must use the new keys.\n\n### Agent Behavior Requirements\n\n1. Run `image scan` to obtain the complete result.\n2. **Automatic location**: search the `characters` arrays in the scan result for the target text provided by the user, and precisely extract `start_char_idx` and `end_char_idx`.\n3. **Ambiguity confirmation**: if the target text appears multiple times in the image, show all matches with context/location and ask the user which one to edit.\n4. Build the `edit-request` JSON and run `image edit`.\n5. **Do not guess indexes**: all `char_idx` values must come from the scan result and must not be manually inferred.\n\n### Common Mistakes\n\n| Mistake | Correct Practice |\n|---------|------------------|\n| Calling `edit` without running `scan` | Always run `scan` first to obtain OSS keys and character indexes |\n| Using a file path as `--input-image` | Use `result.urls.input_image` returned by `scan` |\n| Guessing `start_char_idx` | Locate it exactly from `characters[].index` |\n| Reusing the same `document_info` for multiple replacements | Use the latest key returned by the previous `edit` each time |\n| Choosing arbitrarily when target text has multiple matches | Show all matches and ask the user to confirm |\n\nFile v1.1.8:references/ocr-extract.md\n\n# OCR Recognition and Content Extraction Workflow\n\n> **Preread**: `references/image-processing.md` for `ocr`/`convert`/`merge-text` parameters, and `references/pdf-processing.md` for `pdf convert` parameters.\n\nCommands below identify routes; supply input paths and save options from `SKILL.md` when executing. TXT and stdout output do not support cloud saving; do not change the requested format just to provide a cloud link.\n\n## Scenario\n\nThe user needs to extract text content from images or PDFs.\n\n## Decision Tree\n\n| User Need | Best Approach | Notes |\n|-----------|---------------|-------|\n| Plain text only | `image ocr` | Prints to stdout; does not support `-s` |\n| Preserve structure such as headings and lists | `image convert --format md` | Markdown format |\n| Extract multiple images into one text document | `image merge-text --format md` | Up to 100 images |\n| Extract a PDF as Markdown | `pdf convert --format md` | |\n| Need editable Word | `image convert --format word` | Preserves layout |\n\n## Selection Logic\n\n1. **Is the input a PDF?** Use `pdf convert --format xx`.\n2. **Are the inputs multiple images?** Use `image merge-text` for plain text or `image merge-word` to preserve layout.\n3. **Is the input a single image?** Choose `image ocr` or `image convert` based on the required output format.\n\n## Multi-Page Document Handling\n\nWhen multiple images need to be combined into one document:\n\n- Plain text: `image merge-text` -> stdout or `-o` output.\n- Formatted document: `image merge-word`; without a save preference use `-o merged.docx -s` and a contextual cloud title.\n\nFile v1.1.8:references/office-processing.md\n\n# Office Document Processing Reference\n\n> **Saving**: These are parameter examples. `-s` alone saves only to the cloud; `-o` specifies local output. Apply the save policy in `SKILL.md` to the actual task; final artifacts without a save preference require both destinations and a context-based `--save-title`.\n\n## office convert - Office Document Format Conversion\n\nConvert Word, Excel, or PPT documents to PDF, or upgrade legacy formats (DOC/XLS/PPT) to modern formats (DOCX/XLSX/PPTX). The CLI automatically detects the source file type from the file extension.\n\n### Supported Conversions\n\n| Input Format | `--format` Value | Output Extension | Description |\n|-------------|------------------|------------------|-------------|\n| DOC/DOCX | `pdf` (default) | .pdf | Word to PDF |\n| DOC | `docx` | .docx | Legacy Word format upgrade |\n| XLS/XLSX | `pdf` (default) | .pdf | Excel to PDF |\n| XLS | `xlsx` | .xlsx | Legacy Excel format upgrade |\n| PPT/PPTX | `pdf` (default) | .pdf | PPT to PDF |\n| PPT | `pptx` | .pptx | Legacy PPT format upgrade |\n\n> Files already in modern format (DOCX/XLSX/PPTX) cannot be converted to the same format (e.g., DOCX to DOCX). They can only be converted to PDF.\n\n### Parameters\n\n| Parameter/Flag | Description |\n|----------------|-------------|\n| `file` (positional) | Input file path (required) |\n| `--format` | Target format: `pdf` (default), `docx`, `xlsx`, `pptx` |\n| `-o, --output` | Output file path (auto-derived if omitted) |\n| `-s, --save` | Save to cloud documents |\n| `--save-title` | Cloud document title |\n| `--save-dir` | Save to a specific folder (by name) |\n| `--save-dir-id` | Save to a specific folder (by ID) |\n\n### Usage Examples\n\n```bash\n# Word to PDF (default)\ncamscanner-cli office convert report.docx -o \"report.pdf\" -s --save-title \"Report PDF\"\n\n# Excel to PDF\ncamscanner-cli office convert data.xlsx -o \"data.pdf\" -s --save-title \"Data table PDF\"\n\n# PPT to PDF\ncamscanner-cli office convert slides.pptx -o \"slides.pdf\" -s --save-title \"Presentation PDF\"\n\n# Legacy format upgrade: DOC to DOCX\ncamscanner-cli office convert old.doc --format docx -o \"old_upgraded.docx\" -s\n\n# Legacy format upgrade: XLS to XLSX\ncamscanner-cli office convert legacy.xls --format xlsx -o \"legacy_upgraded.xlsx\" -s\n\n# Legacy format upgrade: PPT to PPTX\ncamscanner-cli office convert presentation.ppt --format pptx -o \"presentation_upgraded.pptx\" -s\n```\n\n## Limits and Notes\n\n- **File size**: upload limit is 40 MB.\n- **Encrypted documents**: password-protected Office documents are not supported.\n- **Format detection**: the CLI determines the file type from the extension; ensure the extension is correct.\n- **Unsupported conversions**: DOCX to DOCX, XLSX to XLSX, PPTX to PPTX (same-format conversion is unnecessary).\n\nFile v1.1.8:references/pdf-processing.md\n\n# PDF Processing Reference\n\n> **Saving**: These are parameter examples. `-s` alone saves only to the cloud; `-o`/`-d` specify local output. Apply the save policy in `SKILL.md` to the actual task; final artifacts without a save preference require both destinations and a context-based `--save-title`.\n\n> **Capability boundary**: There is no command to merge existing PDFs. Process multiple PDFs individually only when separate results are requested. Rendering pages to images does not preserve the original PDF text layer or structure; do not combine it with image assembly to promise PDF merging.\n\n## pdf convert - PDF Format Conversion\n\nConvert a PDF document to another editable format.\n\n| Target Format | `--format` Value | Output Extension | Description |\n|---------------|------------------|------------------|-------------|\n| Word | `word` | .docx | Preserves layout. Default. |\n| Excel | `excel` | .xlsx | Good for table-heavy PDFs |\n| Markdown | `md` | .md | Plain text with structure |\n| TXT | `txt` | .txt | Plain text, does not support `-s` |\n\n```bash\ncamscanner-cli pdf convert report.pdf --format word -s\ncamscanner-cli pdf convert invoice.pdf --format excel -s\ncamscanner-cli pdf convert paper.pdf --format md -s\ncamscanner-cli pdf convert doc.pdf --format txt -o plain.txt\n```\n\n## pdf to-images - Convert PDF Pages to Images\n\nRender each PDF page as a JPEG image.\n\n```bash\n# Output individual pages to a directory.\ncamscanner-cli pdf to-images report.pdf -d ./pages\n# Output: pages/page_1.jpg, pages/page_2.jpg, ...\n\n# Cloud only, when explicitly requested: a multi-page image document.\ncamscanner-cli pdf to-images report.pdf -s --save-title \"Report pages\"\n\n# No save preference: both a local directory and cloud; no -o flag.\ncamscanner-cli pdf to-images report.pdf -d ./report_pages -s --save-title \"Report pages\"\n```\n\n| Parameter | Description |\n|-----------|-------------|\n| `-d, --dir` | Output directory. Default: `<filename>_pages/`. |\n| `-s` | Cloud only; combine with `-d dir` to save both. |\n\n## pdf to-images-zip - Convert PDF Pages to an Image ZIP\n\nSame function as `to-images`, but the server packages the images as a single ZIP file.\n\n```bash\ncamscanner-cli pdf to-images-zip report.pdf -o report_images.zip\n```\n\n> Note: `to-images-zip` does not support `-s` because ZIP is not a supported cloud document type.\n\n## pdf watermark - Add Watermark\n\n| Parameter | Description |\n|-----------|-------------|\n| `--text` | Watermark text. **Required**. |\n| `--color` | Color, such as `#FF0000`. |\n| `--opacity` | Opacity from 0 to 1. |\n| `--size` | Font size. |\n\n```bash\ncamscanner-cli pdf watermark contract.pdf --text \"INTERNAL USE ONLY\" -s\ncamscanner-cli pdf watermark doc.pdf --text \"DRAFT\" --color \"#999999\" --opacity 0.2 -s\n```\n\n## pdf remove-watermark - Remove Watermark\n\nRemove existing watermarks from a PDF.\n\n```bash\ncamscanner-cli pdf remove-watermark document.pdf -s\ncamscanner-cli pdf remove-watermark doc.pdf -o clean.pdf\n```\n\n## Limits and Notes\n\n- **File size**: upload limit is 40 MB.\n- **Page count**: watermark operations support at most 100 pages.\n- **PDF type**: text PDFs and scanned PDFs are supported.\n- **Encrypted PDFs**: password-protected PDFs are not supported.\n\nFile v1.1.8:references/tool-combos.md\n\n# Tool Combination Quick Reference\n\nFirst use `SKILL.md` to check the input types and requested final artifacts. These combinations cover supported tasks only. There is no PDF file merge or standalone cloud upload command; do not promise PDF merging by rendering and reassembling images.\n\nGeneral processing examples below save both locally and to cloud; adjust for explicit local or cloud preferences using the main guide. Derive `--save-title` from actual context. Keep intermediates local and proceed only after the previous step succeeds with a usable artifact. Cloud folder and document management examples retain their explicit save/management intent.\n\n## Basic Combinations\n\n| User Need | Recommended Command | Notes |\n|-----------|---------------------|-------|\n| Recognize text in an image | `image ocr photo.jpg` | Prints to terminal |\n| Convert one image to a document | `image convert photo.jpg --format word -o \"photo_convert.docx\" -s` | Saves locally and to cloud |\n| Convert multiple images to a document | `image merge-word \"page1.jpg\" \"page2.jpg\" \"page3.jpg\" -o \"merged.docx\" -s` | Multi-page merge; list files explicitly |\n| Convert PDF to editable format | `pdf convert doc.pdf --format word -o \"doc_convert.docx\" -s` | |\n| Improve a photo | `image hd blurry.jpg -o \"blurry_hd.jpg\" -s` | |\n| Protect a document | `pdf watermark file.pdf --text \"CONFIDENTIAL\" -o \"file_watermark.pdf\" -s` | |\n| Word to PDF | `office convert report.docx -o \"report.pdf\" -s` | |\n| Excel to PDF | `office convert data.xlsx -o \"data.pdf\" -s` | |\n| PPT to PDF | `office convert slides.pptx -o \"slides.pdf\" -s` | |\n| Legacy format upgrade | `office convert old.doc --format docx -o \"old_upgraded.docx\" -s` | DOC->DOCX, XLS->XLSX, PPT->PPTX |\n\n## Multi-Step Combinations\n\n### Convert Multiple Scan Images into a PDF\n\n```bash\n# Step 1: merge scan images into a PDF and save both locally and to cloud.\ncamscanner-cli image merge-pdf \"scan_001.jpg\" \"scan_002.jpg\" \"scan_003.jpg\" -o \"merged.pdf\" -s --save-title \"Merged scans\"\n```\n\n### Extract Table Data from Images into Excel\n\n```bash\n# Step 1: merge multiple table images into Excel.\ncamscanner-cli image merge-excel \"table_page1.jpg\" \"table_page2.jpg\" -o \"merged.xlsx\" -s\n```\n\n### Add a Watermark and Save the Document\n\n```bash\n# Step 1: add a watermark to the PDF.\ncamscanner-cli pdf watermark contract.pdf --text \"INTERNAL USE ONLY\" -o \"contract_watermark.pdf\" -s --save-title \"Contract-Watermarked\"\n```\n\n### Multilingual Document Translation Workflow\n\n```bash\n# Step 1: translate text in the image while preserving the original layout.\ncamscanner-cli image translate document.jpg --lang en -o \"document_translate.jpg\" -s --save-title \"Translation-English\"\n```\n\n### Convert After OCR Extraction\n\n```bash\n# Option 1: convert directly to Markdown. Recommended because it preserves structure.\ncamscanner-cli image convert document.jpg --format md -o \"document_convert.md\" -s\n\n# Option 2: extract plain text with OCR, then save as Word.\ncamscanner-cli image ocr document.jpg > extracted.txt\ncamscanner-cli txt to-word extracted.txt -o \"extracted_to_word.docx\" -s --save-title \"OCR text\"\n```\n\n### Split a PDF into Individual Images\n\n```bash\n# Render each page and save both locally and to cloud.\ncamscanner-cli pdf to-images report.pdf -d ./pages -s --save-title \"Report pages\"\n\n# Or split into a ZIP package.\ncamscanner-cli pdf to-images-zip report.pdf -o report_pages.zip\n```\n\n### Image Authenticity Check\n\n```bash\n# Detect Photoshop/tampering.\ncamscanner-cli image validate suspect.jpg --mode 1\n\n# Detect AI-generated content.\ncamscanner-cli image validate ai_photo.jpg --mode 2\n```\n\n### Image Text Editing: Replace, Delete, or Move\n\n```bash\n# Step 1: scan layout structure and character indexes.\ncamscanner-cli image scan document.jpg\n\n# Step 2: locate start_char_idx and end_char_idx for the target text in the JSON returned by scan.\n# Search in result.document_info.sections[].columns[].paragraphs[].lines[].characters.\n\n# Step 3: execute the edit. This example replaces text.\ncamscanner-cli image edit \\\n  --input-image \"<result.urls.input_image>\" \\\n  --document-info \"<result.urls.document_info>\" \\\n  --edit-request '{\"edit_type\":\"update\",\"start_char_idx\":39,\"end_char_idx\":42,\"target_text\":\"West\"}' \\\n  -o edited.jpg -s --save-title \"Edited text\"\n```\n\n### Search and Download Cloud Documents\n\n```bash\n# Step 1: search for the target document\ncamscanner-cli doc search \"contract\"\n\n# Step 2: Agent presents search results for user confirmation\n# Step 3: use the confirmed cs_doc_id to download locally\ncamscanner-cli doc download <cs_doc_id> -o ~/Downloads/contract.pdf\n```\n\n### Process Files and Save to a Specific Folder\n\n```bash\n# Convert an image to Word and save directly to a specific folder\ncamscanner-cli image convert photo.jpg --format word -s --save-dir \"Work Documents\"\n```\n\n### Organize Documents into Folders (requires user confirmation)\n\n```bash\n# Step 1: search for documents to organize\ncamscanner-cli doc search \"invoice\" -n 20\n\n# Step 2: Agent presents search results; user confirms which document(s) to move\n# Step 3: list folders to get dir_id\ncamscanner-cli doc dirs\n\n# Step 4: match the user's folder name against the folder list\n#   - Exact match: use the corresponding dir_id\n#   - Similar names exist: present similar folders for user to confirm\n#   - No match: inform user the folder doesn't exist (the CLI does not support creating folders), list all available folders\n\n# Step 5: use the confirmed cs_doc_id and matched dir_id to move\ncamscanner-cli doc move <cs_doc_id> --dir-id <folder_id>\n```\n\n## Scenario Mapping\n\n| Scenario | Best Approach |\n|----------|---------------|\n| Meeting whiteboard photo -> editable document | `image convert whiteboard.jpg --format word -o \"whiteboard_convert.docx\" -s` |\n| Paper scans -> Markdown | `image merge-text \"page1.jpg\" \"page2.jpg\" --format md -o paper.md` (multi-image text merge is local only); for one image use `image convert page1.jpg --format md -o page1.md -s` |\n| Invoice photo -> structured data extraction | `image receipt invoice.jpg` |\n| Invoice photo -> Excel spreadsheet | `image convert invoice.jpg --format excel -o \"invoice_convert.xlsx\" -s` |\n| Contract PDF -> editable Word document | `pdf convert contract.pdf --format word -o \"contract_convert.docx\" -s` |\n| Word report -> PDF | `office convert report.docx -o \"report.pdf\" -s --save-title \"Report PDF\"` |\n| Legacy DOC -> DOCX upgrade | `office convert old.doc --format docx -o \"old_upgraded.docx\" -s` |\n| Excel data -> PDF | `office convert data.xlsx -o \"data.pdf\" -s --save-title \"Data table PDF\"` |\n| PPT presentation -> PDF | `office convert slides.pptx -o \"slides.pdf\" -s --save-title \"Presentation PDF\"` |\n| Business card photo -> text extraction | `image ocr namecard.jpg` |\n| Foreign-language menu -> Chinese translation | `image translate menu.jpg --lang zh -o \"menu_translate.jpg\" -s` |\n| Handwritten notes -> electronic document | `image enhance notes.jpg --mode 9 -o clean.jpg`, then `image convert clean.jpg --format word -o \"clean_convert.docx\" -s` |\n| Blurry ID photo -> higher clarity | `image hd id_photo.jpg -o \"id_photo_hd.jpg\" -s` |\n| Old photo restoration | `image restore vintage.jpg -o \"vintage_restore.jpg\" -s` |\n| Multiple exam images -> one PDF | `image merge-pdf \"q1.jpg\" \"q2.jpg\" \"q3.jpg\" -o \"merged.pdf\" -s` |\n| Search cloud documents | `doc search \"keyword\" -f pdf -n 10` |\n| Download cloud documents | `doc download <doc_id> -o ~/Downloads/file.pdf` |\n| View cloud folders | `doc dirs` |\n| Move documents to a folder | `doc move <doc_id> --dir-id <folder_id>` |\n| Save processing results to folder | `image convert photo.jpg --format word -s --save-dir \"folder name\"` |\n\nFile v1.1.8:references/translate.md\n\n# Multilingual Translation Workflow\n\n> **Preread**: `references/image-processing.md` for translate parameters and language codes.\n\n## Scenario\n\nThe user has an image containing text, such as a menu, road sign, or document screenshot, and needs it translated into a target language while preserving the original layout.\n\n## Decision Flow\n\n### 1. Confirm Target Language\n\nInfer the `--lang` parameter from the user's request. See `references/image-processing.md` for language codes.\n\n### 2. Single Language vs Multiple Languages\n\n- **Single language**: run `image translate <image-path> --lang xx` with final save options from `SKILL.md`; without a preference add `-o translated_xx.jpg -s`.\n- **Multiple language versions**: use different `--lang` values, distinct local paths and `--save-title` values, and verify each result.\n\n### 3. Multilingual Chaining Logic\n\n```text\nsame input file -> run translate N times, each with a different --lang and --save-title\n```\n\n## Notes\n\n- Processing can take longer, usually 10-60 seconds. Handle timeouts with the retry strategy.\n- Text in the image must be clear enough for accurate recognition and translation.\n\nFile v1.1.8:references/watermark-protection.md\n\n# Document Watermark Protection Workflow\n\n> **Preread**: `references/image-processing.md` for `image watermark` parameters, and `references/pdf-processing.md` for `pdf watermark`/`remove-watermark` parameters.\n\n## Scenario\n\nThe user needs to add a watermark before sharing a document, or remove an existing watermark.\n\n## Decision Tree\n\n| User Need | Input Type | Route To |\n|-----------|------------|----------|\n| Add watermark | Image | `image watermark` |\n| Add watermark | PDF | `pdf watermark` |\n| Remove watermark | PDF | `pdf remove-watermark` |\n| Remove watermark | Image | `image enhance --mode 10` |\n\n## Recommended Parameters\n\n| Scenario | Recommended Parameters |\n|----------|------------------------|\n| Internal document | `--text \"INTERNAL USE ONLY\" --opacity 0.3` |\n| Draft marker | `--text \"DRAFT\" --opacity 0.2 --color \"#999999\"` |\n| Copyright protection | `--text \"COPYRIGHT Company Name\" --opacity 0.15 --size 36` |\n| Confidential document | `--text \"CONFIDENTIAL\" --opacity 0.4 --color \"#FF0000\"` |\n\n## Notes\n\n- PDF watermarking supports at most 100 pages.\n- Watermark removal quality depends on the complexity of the original watermark.\n- Image watermarking is irreversible for the output file. The original image is not modified; a new file is produced.\n\nArchive v1.1.4: 17 files, 41686 bytes\n\nFiles: references/batch-convert.md (1876b), references/image-enhance.md (1101b), references/image-processing.md (9100b), references/ocr-extract.md (1347b), references/pdf-processing.md (2431b), references/tool-combos.md (4116b), references/translate.md (1050b), references/watermark-protection.md (1276b), scripts/setup.cjs (7216b), scripts/setup.ps1 (7407b), scripts/setup.sh (5550b), scripts/upgrade.cjs (16565b), scripts/upgrade.ps1 (13861b), scripts/upgrade.sh (11229b), skill-card.md (3155b), SKILL.md (30944b), _meta.json (125b)\n\nFile v1.1.4:SKILL.md\n\n---\nname: \"camscanner\"\ndisplay_name: \"CamScanner Official Skill\"\ndisplay_name_en: \"camscanner\"\ndescription: \"CamScanner document processing - an intelligent document conversion and processing platform and official CamScanner Skill. Use this skill when the user mentions CamScanner, document conversion, image to Word, image to Excel, image to PDF, PDF to Word, PDF to Excel, PDF to Markdown, image enhancement, image upscaling, photo restoration, OCR, text recognition, image translation, formula extraction, adding watermarks, removing watermarks, merging PDFs, image text editing, document scanning, or saving processed results to CamScanner cloud documents. Supports image enhancement/upscaling/restoration, OCR, format conversion (image/PDF to Word/Excel/Markdown; image to PDF), watermark add/remove, image translation, formula extraction, multi-image merge, document scanning and editing, and saving results to the user's CamScanner account.\"\ndescription_en: \"CamScanner document processing - an intelligent document conversion and processing platform and official CamScanner Skill. Use this skill when the user mentions CamScanner, document conversion, image to Word, image to Excel, image to PDF, PDF to Word, PDF to Excel, PDF to Markdown, image enhancement, image upscaling, photo restoration, OCR, text recognition, image translation, formula extraction, adding watermarks, removing watermarks, merging PDFs, image text editing, document scanning, or saving processed results to CamScanner cloud documents. Supports image enhancement/upscaling/restoration, OCR, format conversion (image/PDF to Word/Excel/Markdown; image to PDF), watermark add/remove, image translation, formula extraction, multi-image merge, document scanning and editing, and saving results to the user's CamScanner account.\"\nhomepage: \"https://www.camscanner.com\"\nversion: \"1.1.4\"\ncategory: \"productivity\"\nauthor: \"CamScanner\"\n---\n# CamScanner CLI Skill Guide\n\nThe CamScanner CLI Skill provides a complete document processing toolkit through the `camscanner-cli` command-line tool and the CamScanner AI Tools API. It supports image enhancement, OCR, format conversion, watermarking, translation, restoration, merging, receipt recognition, and other image/PDF processing operations, as well as cloud document search.\n\n## Environment Setup\n\nBefore using this Skill for the first time in a session, the agent **must** complete the following decision flow. This only needs to run once per session.\n\n**The agent must strictly follow this flow — skipping any step is prohibited:**\n\n```\nStep 1: camscanner-cli --version\n         │\n         ├─ Command exists (outputs version) → Step 2\n         │\n         └─ Command not found → [Windows?] Double-check with Test-Path ↓\n                          │\n                          ├─ Test-Path \"$env:LOCALAPPDATA\\camscanner-cli\\camscanner-cli.exe\" = True\n                          │   → Refresh PATH → Step 2 (no install needed)\n                          │\n                          └─ False / Non-Windows → Run install script → Step 3 (skip upgrade)\n\nStep 2: Run upgrade script\n         │\n         └─ Done → Step 3\n\nStep 3: camscanner-cli auth status\n         │\n         ├─ Logged in → ✅ Environment ready, proceed with user task\n         │\n         └─ Not logged in / expired → Run camscanner-cli auth login → Verify → ✅\n```\n\n### Step 1. Check Installation\n\nRun `camscanner-cli --version`:\n\n- **Command exists** (outputs version) → Already installed, continue to Step 2\n- **Command not found** (command not found / not recognized) → **On Windows, you must perform the double-check below first**. If confirmed not installed, run the install script. After installation, **skip directly to Step 3**.\n\n**Windows double-check (mandatory)**:\n\n`camscanner-cli --version` failing on Windows does not necessarily mean it is not installed — the PATH may not be refreshed or ConPTY may swallow output. **Before running the install script**, check whether the file exists:\n\n```powershell\nTest-Path \"$env:LOCALAPPDATA\\camscanner-cli\\camscanner-cli.exe\"\n```\n\n- Returns **True** → CLI is installed, just missing from PATH. Refresh PATH then continue to Step 2:\n  ```powershell\n  $env:PATH = \"$env:LOCALAPPDATA\\camscanner-cli;$env:PATH\"\n  ```\n- Returns **False** → Confirmed not installed, run the install script → Step 3\n\n| Platform | Install Command |\n|----------|-----------------|\n| Linux/macOS | `bash scripts/setup.sh` |\n| Windows | `powershell -ExecutionPolicy Bypass -File scripts/setup.ps1` |\n\n### Step 2. Version Upgrade Check (installed users only)\n\nRun the upgrade script to check for a new version (the script handles detection internally; exits silently if no update is available; network failures do not block usage):\n\n| Platform | Upgrade Command |\n|----------|-----------------|\n| Linux/macOS | `bash scripts/upgrade.sh` |\n| Windows | `node scripts/upgrade.cjs` |\n| Fallback (any platform) | `node scripts/upgrade.cjs` |\n\n> The upgrade script updates both the CLI binary and Skill files (SKILL.md, references/, scripts/) to keep them in sync. On failure it auto-rolls back; manual rollback: `bash scripts/upgrade.sh --rollback` or `node scripts/upgrade.cjs --rollback`.\n\n### Step 3. Authentication Check\n\n```bash\ncamscanner-cli auth status\n```\n\n- **Logged in** → Environment ready, proceed with user task\n- **Not logged in or token expired** → Run `camscanner-cli auth login`, then verify again\n\n> **Agent login behavior rules (mandatory)**:\n> - Must run `camscanner-cli auth login` in the **foreground** (no `&` backgrounding). The command blocks until the user completes browser OAuth and returns automatically.\n> - After login, verify with `camscanner-cli auth status`; on failure, inform the user to retry.\n\n| Action | Command |\n|--------|---------|\n| Check status | `camscanner-cli auth status` |\n| Browser login | `camscanner-cli auth login` |\n| Log out | `camscanner-cli auth logout` |\n\n> **Token safety**: Never display token plaintext to the user or write it to an unsafe location.\n\n---\n\n## Operating Limits\n\n1. **Do not leak credentials**: Tokens must only be obtained through `camscanner-cli auth login` and stored in the system keychain.\n2. **File size limit**: Uploaded files must not exceed 40 MB.\n3. **Supported image formats**: JPG, JPEG, PNG.\n4. **Supported document formats**: PDF, TXT, Markdown.\n\n---\n\n## Command Format\n\n```bash\ncamscanner-cli <group> <command> [file...] [flags]\n```\n\n**Groups**: `image` (image processing), `pdf` (PDF processing), `txt` (text processing), `doc` (cloud document management), `auth` (authentication management).\n\n**Common flags**:\n\n| Flag | Description |\n|------|-------------|\n| `-o, --output <path>` | Output file path. If omitted, the CLI derives one automatically. |\n| `-s, --save` | Save the result to the user's CamScanner account and skip local download. |\n| `--save-title <title>` | Cloud document title. If omitted, the CLI generates one in the form `{feature}{time}`. |\n| `-h, --help` | Show help. |\n\n### Interaction Between `-o` and `-s`\n\n| Arguments | Behavior |\n|-----------|----------|\n| No `-o`, no `-s` | Save locally to an automatically derived path. |\n| `-o path` | Save only to the specified local path. |\n| `-s` | **Save only to the cloud** and skip local download. |\n| `-o path -s` | Save both locally **and** to the cloud. |\n\n### Agent Default Save Policy\n\n> **Mandatory rule**: When the user does not explicitly specify a save method, the agent **must** save both locally and to the cloud (pass the `-s` flag). Saving only locally without `-s` is **incorrect behavior**. Only omit `-s` when the user explicitly says \"save locally only\" / \"don't save to cloud\".\n\n| User Intent | Agent Behavior |\n|-------------|----------------|\n| No explicit save preference | **Must** use `-s` to save both locally and to cloud (i.e., `-o <auto-derived path> -s`) |\n| Explicitly says \"save locally\" or specifies a path | Only `-o path`, no `-s` |\n| Explicitly says \"save to cloud/account\" | Only `-s`, no `-o` |\n| Feature does not support `-s` (see commands marked with No in the overview) | Save locally only, no `-s` |\n\n### `--save-title` Smart Naming Rules\n\nWhen saving to cloud with `-s`, the agent **must** attempt smart naming via `--save-title`:\n\n1. **Prefer smart naming**: Generate a concise, meaningful title based on the filename, user intent, and document content.\n   - Example: User says \"convert this invoice to Excel\" → `--save-title \"Invoice to Excel\"`\n   - Example: File is `meeting_notes_0810.png`, converting to Word → `--save-title \"Meeting Notes 0810\"`\n   - Example: Merging multiple scans into PDF → `--save-title \"Scanned Documents Merged\"`\n2. **Fallback when naming fails**: If a meaningful title cannot be inferred from context (e.g., filename has no semantics, user did not describe intent), **do not pass** `--save-title` — let the CLI use its default rule (`{feature}{time}`).\n3. **Title requirements**: Concise (20 chars or fewer), meaningful, no file paths or technical parameters.\n\n---\n\n## Capabilities\n\n### Tool Overview\n\n| Category | Command | Function | Output Type | Supports `-s` |\n|----------|---------|----------|-------------|---------------|\n| **Image enhancement** | `image enhance` | Remove shadows, sharpen, convert to black and white, and other 10 modes | Image | Yes |\n| **Image enhancement** | `image hd` | Upscale images and improve resolution | Image | Yes |\n| **Image enhancement** | `image restore` | Restore old photos | Image | Yes |\n| **Format conversion** | `image convert` | Image -> Word/Excel/TXT/Markdown | Document | Yes, except TXT |\n| **Format conversion** | `image to-pdf` | Single image -> PDF | PDF | Yes |\n| **Format conversion** | `pdf convert` | PDF -> Word/Excel/TXT/Markdown | Document | Yes |\n| **Format conversion** | `txt to-word` | TXT -> Word | Word | Yes |\n| **Watermark** | `image watermark` | Add a text watermark to an image | Image | Yes |\n| **Watermark** | `pdf watermark` | Add a text watermark to a PDF | PDF | Yes |\n| **Watermark** | `pdf remove-watermark` | Remove watermarks from a PDF | PDF | Yes |\n| **Translation** | `image translate` | Translate text in an image while preserving layout | Image | Yes |\n| **Formula** | `image extract-formula` | Extract mathematical formulas | Image | Yes |\n| **Merge** | `image merge-pdf` | Merge multiple images into a PDF, up to 100 images | PDF | Yes |\n| **Merge** | `image merge-excel` | Merge multiple images into Excel, up to 100 images | Excel | Yes |\n| **Merge** | `image merge-word` | Merge multiple images into Word, up to 100 images | Word | Yes |\n| **PDF** | `pdf to-images` | Convert each PDF page to an image | Image directory | Yes |\n| **PDF** | `pdf to-images-zip` | Convert PDF pages to an image ZIP | ZIP | No |\n| **Recognition** | `image ocr` | OCR text recognition | stdout text | No |\n| **Recognition** | `image merge-text` | OCR multiple images and merge text, up to 100 images | stdout/file | No |\n| **Detection** | `image validate` | Tampering/AI-generated image detection | stdout JSON | No |\n| **Editing** | `image scan` | Analyze image layout and obtain character indexes and OSS keys | stdout/JSON | No |\n| **Editing** | `image edit` | Replace, delete, or move text based on scan results | Image | Yes |\n| **Receipt** | `image receipt` | Invoice/receipt recognition, returns structured JSON | stdout/JSON | No |\n| **Cloud docs** | `doc search` | Search cloud documents (keyword/time/type filter) | stdout table | No |\n\n### Unsupported Operations\n\n- Online collaborative editing.\n- File version management.\n- Video/audio processing.\n- Batch folder management.\n- Cloud document content editing (search only).\n\n---\n\n## Reference Routing\n\nBefore executing an operation, the agent **must** read the corresponding reference file for full parameters and usage.\n\n### Command References (Required)\n\n| Trigger | Reference File | Contents |\n|---------|----------------|----------|\n| Processing image files | `references/image-processing.md` | Full parameters, mode values, and examples for all `image` commands |\n| Processing PDF files | `references/pdf-processing.md` | Full parameters, limits, and examples for all `pdf` commands |\n| Searching cloud documents | The \"Cloud Document Management\" section in this file | Full parameters and usage for `doc search` |\n| Invoice/receipt recognition | The \"Invoice/Receipt Recognition\" section in this file | Full parameters and usage for `image receipt` |\n| User request requires multiple steps | `references/tool-combos.md` | Scenario-to-command combination mapping |\n\n### Workflow References (Required for Multi-Step Tasks)\n\n| Trigger | Workflow File | Contents |\n|---------|---------------|----------|\n| Multiple images need merging or batch conversion | `references/batch-convert.md` | Merge strategy selection and batching logic |\n| Image enhancement, upscaling, or restoration | `references/image-enhance.md` | Mode selection decision tree |\n| OCR or text extraction | `references/ocr-extract.md` | Plain text vs Markdown vs Word comparison |\n| Image translation | `references/translate.md` | Language codes and multilingual version workflow |\n| Watermark add/remove | `references/watermark-protection.md` | Recommended parameters and scenario mapping |\n\n---\n\n## Intent Routing Rules\n\nRoute intents in the priority order below. **Do not jump directly to a command based only on keywords.**\n\n### Top-Level Split: Document Search vs File Processing\n\n| User Intent | Route Direction | Notes |\n|-------------|-----------------|-------|\n| Search/find/look up cloud documents | → `doc search` flow | Does not involve image/PDF processing |\n| Process images/PDFs (enhance, convert, OCR, recognize, etc.) | → File processing routes below (starting at Level 1) | Existing flow |\n\n> **Key judgment**: Is the user's need \"searching cloud documents\" or \"processing local files\"? The former uses the `doc search` command; the latter uses `image`/`pdf`/`txt` commands. These are independent flows and must not be mixed.\n\n### Level 1: Determine Input File Type\n\n| Input File Type | Available Command Group |\n|-----------------|-------------------------|\n| Image (jpg/jpeg/png) | `image *` |\n| PDF | `pdf *` |\n| TXT/Markdown | `txt to-word` |\n| Mixed types (image + PDF) | Process each type separately. **Cross-type merging into a single artifact is not supported.** |\n\n### Level 2: Determine Operation Intent\n\nUse the user's verbs, keywords, and context to determine the operation type.\n\n| Operation Type | Trigger Evidence | Command Direction |\n|----------------|------------------|-------------------|\n| Format conversion | \"convert to Word\", \"convert to Excel\", \"convert to PDF\", \"convert to Markdown\" | `convert` / `to-pdf` / `merge-*` |\n| OCR recognition | \"recognize\", \"OCR\", \"extract text\" | `ocr` / `merge-text` / `pdf convert --format txt/md` |\n| Image enhancement | \"enhance\", \"remove shadows\", \"sharpen\", \"remove moire\" | `image enhance` |\n| Image upscaling | \"HD\", \"clearer\", \"increase resolution\", \"blurry\" | `image hd` |\n| Photo restoration | \"restore\", \"old photo\", \"scratch\", \"faded\" | `image restore` |\n| Watermark processing | \"add watermark\", \"remove watermark\" | `watermark` / `remove-watermark` / `enhance --mode 10` |\n| Translation | \"translate\" | `image translate` |\n| Detection | \"detect\", \"Photoshop\", \"tampered\", \"AI-generated\" | `image validate` |\n| Editing | \"edit image text\", \"replace text\", \"modify text\", \"change X to Y\" | `image scan` -> `image edit` (automatically locate character indexes) |\n| Formula extraction | \"formula\", \"LaTeX\" | `image extract-formula` |\n| Receipt recognition | \"invoice\", \"receipt\", \"expense report\", \"bill\", \"ticket\" | `image receipt` |\n\n### Level 3: Determine Quantity and Artifact\n\n| Condition | Route |\n|-----------|-------|\n| Single image -> format conversion | `image convert --format xx` or `image to-pdf` |\n| Multiple images -> one document | `image merge-pdf/word/excel`, up to 100 images |\n| Multiple images -> process separately | Execute one by one |\n| Single PDF -> format conversion | `pdf convert --format xx` |\n| Multiple PDFs | Execute one by one. **There is no PDF merge command.** |\n\n### Level 4: Target Format and Required Parameters\n\n| Input -> Target | Correct Command | Common Pitfall |\n|-----------------|-----------------|----------------|\n| Image -> Word | `image convert --format word` | |\n| Image -> Excel | `image convert --format excel` | |\n| Image -> Markdown | `image convert --format md` | |\n| Image -> TXT | `image convert --format txt` | Does not support `-s` |\n| Image -> PDF | `image to-pdf` for one image, or `image merge-pdf` for multiple images | **Not** `image convert --format pdf` |\n| PDF -> Word | `pdf convert --format word` | |\n| PDF -> Excel | `pdf convert --format excel` | |\n| PDF -> Markdown | `pdf convert --format md` | |\n| PDF -> images | `pdf to-images` or `pdf to-images-zip` | |\n| TXT -> Word | `txt to-word` | |\n\n### Intent Disambiguation Rules\n\nWhen a user request matches multiple operations, disambiguate as follows.\n\n| Conflict | Disambiguation Rule |\n|----------|---------------------|\n| \"make it sharper and clearer\": `enhance --mode 2` vs `hd` | If the original image is blurry or low-resolution, use `hd`; if it is already clear but needs sharper details, use `enhance --mode 2`; ask if uncertain. |\n| \"scan\": `image scan` vs `to-pdf` | If the user intends to edit content, use `scan` + `edit`; otherwise default to \"generate a PDF\" and use `to-pdf`. |\n| \"OCR\": plain text vs Markdown vs Word | Ask which format the user wants; default recommendation is `convert --format md` to preserve structure. |\n| \"restore\": `restore` vs `enhance` | If the user mentions old photos, scratches, or fading, use `restore`; otherwise choose an enhance mode based on the specific issue. |\n| \"detect\": tampering vs AI-generated | If the user mentions Photoshop, tampering, or modification, use mode 1; if the user mentions AI, generated, or fake, use mode 2; ask if uncertain. |\n| \"remove watermark\": PDF vs image | Choose automatically by input type: PDF -> `pdf remove-watermark`, image -> `enhance --mode 10`. |\n\n**Principle: if an ambiguity changes the command choice, ask the user instead of guessing.**\n\n### Common Routing Mistakes the Agent Must Avoid\n\n| User Request | Wrong Route | Correct Route | Reason |\n|--------------|-------------|---------------|--------|\n| \"merge two PDFs\" | ~~`image merge-pdf`~~ | Not currently supported; tell the user | `image merge-pdf` only accepts image inputs |\n| \"recognize text in this PDF\" | ~~`image ocr`~~ | `pdf convert --format txt/md` | `image ocr` only accepts images |\n| \"scan these photos into a PDF\" | ~~`image scan`~~ | `image to-pdf` or `image merge-pdf` | `image scan` is layout analysis |\n| \"remove the watermark from this image\" | ~~`pdf remove-watermark`~~ | `image enhance --mode 10` | `pdf remove-watermark` only processes PDFs |\n| \"image to PDF\" | ~~`image convert --format pdf`~~ | `image to-pdf` / `image merge-pdf` | `convert_image` does not support PDF output |\n| \"combine a.jpg and b.pdf into one Word file\" | ~~silently process separately~~ | Explain that cross-type merging is not supported | Different input types cannot be merged into one artifact |\n| \"recognize this invoice\" | ~~`image convert --format excel`~~ | `image receipt invoice.jpg` | `receipt` extracts structured fields; `convert` converts image content to a table format |\n| \"find my contract document\" | ~~`image ocr`~~ | `doc search \"contract\"` | Searching cloud documents, not processing images |\n\n---\n\n## Cloud Document Management\n\n### doc search — Search Cloud Documents\n\nSearch the user's CamScanner cloud documents. Supports keyword search, time range filtering, and document type filtering, which can be combined.\n\n```bash\ncamscanner-cli doc search [keyword] [flags]\n```\n\n| Parameter/Flag | Description |\n|----------------|-------------|\n| `keyword` (positional) | Search keywords (multiple words separated by spaces; any match counts — OR semantics) |\n| `-f, --filter` | Document type filter: pdf/word/excel/ppt/image/markdown/html |\n| `-n, --limit` | Maximum number of results (default 5, max 50) |\n| `-a, --after` | Start time (supports `2006-01-02`, `2006-01-02 15:04:05`, or unix timestamp) |\n| `-b, --before` | End time (same formats as above) |\n| `-s, --scope` | Search scope: `title` (default — title + page title + notes) or `full` (includes OCR full text) |\n\n**Usage examples**:\n\n```bash\n# Search for documents containing \"contract\"\ncamscanner-cli doc search \"contract\"\n\n# Search recent PDF documents\ncamscanner-cli doc search -f pdf -n 10\n\n# Search documents within a time range\ncamscanner-cli doc search --after 2026-08-01 --before 2026-08-31\n\n# Keyword + type + time combined search\ncamscanner-cli doc search \"report\" -f word --after 2026-08-01\n\n# Full-text search (including OCR content)\ncamscanner-cli doc search \"invoice number\" -s full -n 20\n```\n\n**Output format**: The CLI displays search results in a table.\n\n**Agent display rules (mandatory)**: When presenting search results to the user, the agent **must** include at least the following four columns:\n\n| Column | Source | Description |\n|--------|--------|-------------|\n| Title | CLI output \"标题\" column | Document title |\n| Type | Inferred from link URL path | e.g., `/pdfDetail` → PDF, `/markdownDetail` → Markdown, `/detail` → Scan/Image |\n| Folder | CLI output \"所在目录\" column | Folder containing the document |\n| Link | CLI output \"链接\" column | Clickable web page URL |\n\n> **Type inference rule**: `/pdfDetail` = PDF, `/markdownDetail` = Markdown, `/detail` = Scan (image). Map other types from the URL path name accordingly. The agent must not omit the Type column or show only title and link.\n\n**Agent behavior rules**:\n- When the user says \"find/search/look up my documents\", use `doc search` — **do not** enter the image/pdf processing flow.\n- Multiple keywords are separated by spaces and use OR semantics (any match counts).\n- When no keyword is provided, returns the most recent document list.\n- Default returns 5 results; increase `-n` when the user needs more.\n\n**Keyword tokenization strategy**:\n\nThe agent should reasonably tokenize the user's search description, separating words with spaces to improve hit probability (under OR semantics, more tokens means broader matching). However, tokenization must be careful:\n- **Should tokenize**: user says \"thesis formula HD\" → split to `\"thesis formula HD\"`; user says \"meeting notes August\" → split to `\"meeting notes August\"`\n- **Should not tokenize**: proper nouns, brand names, personal names, and fixed phrases must not be forcibly split. E.g., \"CamScanner\" stays as one token; \"Zhang San's report\" keeps \"Zhang San\" together.\n- **When uncertain, do not tokenize**: if unsure whether splitting improves results, pass the user's original text as a single keyword.\n\n**Semantic intent recognition**:\n\nThe agent must parse the user's query semantically, extracting time, type, and other structured intents into the corresponding parameters — **not as search keywords**:\n\n- **Time intent → `--after` / `--before` parameters**: when the user mentions a time range, parse it as a time filter, not as a keyword.\n  - \"papers from last August\" → `doc search \"papers\" --after 2025-08-01 --before 2025-08-31`\n  - \"meeting notes from last week\" → `doc search \"meeting notes\" --after 2026-08-17 --before 2026-08-23`\n  - \"contracts from this year\" → `doc search \"contracts\" --after 2026-01-01`\n- **Type intent → `-f` parameter**: when the user mentions a document type, map it to the type filter.\n  - \"find my PDF invoices\" → `doc search \"invoices\" -f pdf`\n- **Quantity intent → `-n` parameter**: when the user says \"recent ones\", \"find more\", etc., adjust the return count.\n\n> **Core principle**: The tokenization strategy applies only to **actual search keywords**. Time, type, quantity, and other structured semantics must be extracted into the corresponding command parameters and must never be mixed into keywords. Wrong example: `doc search \"last August papers\"` — this would match \"last August\" as literal text in document content instead of filtering by time.\n\n**Search scope decision (`-s` parameter)**:\n\n| User Intent | Parameter |\n|-------------|-----------|\n| Explicitly says \"in the title\", \"in notes\", \"page title\" | `-s title` |\n| Explicitly says \"in the content\", \"in the body\", \"full text search\" | `-s full` |\n| No explicit intent (default) | First search with `-s title`; if no results, automatically retry with `-s full` |\n\n> **Two-step search strategy**: When the user does not specify a search scope, first search by title (faster), then search full text if no results (covers OCR content). If both return nothing, confirm the document does not exist.\n\n---\n\n## Invoice/Receipt Recognition\n\n### image receipt — Invoice Recognition\n\nRecognize invoice/receipt images and return structured JSON data (invoice type, amount, date, invoice number, etc.).\n\n```bash\ncamscanner-cli image receipt <file> [-o output.json]\n```\n\n| Parameter/Flag | Description |\n|----------------|-------------|\n| `file` (positional) | Invoice/receipt image path (required) |\n| `-o, --output` | Output JSON file path (if omitted, prints to terminal) |\n\n**Usage examples**:\n\n```bash\n# Recognize an invoice and output to terminal\ncamscanner-cli image receipt invoice.jpg\n\n# Recognize and save result to a file\ncamscanner-cli image receipt invoice.jpg -o invoice_result.json\n```\n\n**Return data**: JSON format containing a `bills_list` array (one element per invoice), each element including invoice type, amount, tax, date, invoice number, and other structured fields. If `invoice_type` is `\"ot\"`, it means no valid invoice information was recognized.\n\n**Agent behavior rules**:\n- When the user mentions \"recognize invoice\", \"expense report\", \"receipt\", or \"extract invoice info\", use `image receipt`.\n- **Do not** confuse invoice recognition with `image convert --format excel`: the former extracts structured fields (amount, tax ID, etc.), the latter converts image content to a table format.\n- The recognition result is structured JSON data. The agent should parse it and present it to the user in a human-readable way (e.g., listing key fields like amount, date).\n- `image receipt` does not support the `-s` flag (the result is JSON data, not a document).\n\n---\n\n| Error Signature | Cause | Handling |\n|-----------------|-------|----------|\n| `Authentication failed, run camscanner-cli auth login` | Token expired or user is not logged in | Run `camscanner-cli auth login` |\n| `file does not exist` | Input path is wrong | Check the file path |\n| `file size exceeds the maximum limit` | File exceeds 40 MB | Compress the file and retry |\n| `rate limit exceeded` (429) | Calls are too frequent | Wait 10 seconds and retry |\n| `txt format cannot be saved as a cloud document` | TXT is not supported as a cloud document type | Use `--format md` instead |\n| HTTP 504 | Backend service timeout | Wait 5 seconds and retry once |\n| HTTP 500 | Internal server error | Wait 5 seconds and retry once |\n\n### Retry Strategy\n\n| Operation Type | Idempotent | Safe to Retry |\n|----------------|------------|---------------|\n| All conversion/enhancement commands | Yes | Safe to retry |\n| Saving cloud documents with `-s` | No | Retry may create duplicate documents, which is acceptable |\n| `image edit` | Yes | Safe to retry |\n\n### Retry Limits and Circuit Breaker (Mandatory)\n\n> The agent **must** follow these retry limits and must not retry indefinitely.\n\n**Retry limit**: for the same command on the same file, retry at most 3 times (4 total attempts including the first run). After the limit is reached, the agent **must stop retrying**, report the error details to the user, and suggest troubleshooting steps.\n\n**Circuit breaker**: when the same operation type, such as `convert`, `enhance`, or `ocr`, fails 3 times in one session, even across different files, the agent must:\n1. Stop all further attempts for that operation type.\n2. Summarize the errors already observed and analyze likely root causes, such as unsupported format, corrupted file, or mismatched parameters.\n3. Report the failure status and recommended fixes to the user.\n4. Resume only if the user explicitly asks to keep trying.\n\n**Retry intervals**:\n\n| Error Type | Interval | Notes |\n|------------|----------|-------|\n| HTTP 429 | 10 seconds | Rate limited; wait before retrying |\n| HTTP 500/504 | 5 seconds | Temporary server-side failure |\n| HTTP 400 | No wait | Client-side issue; inspect parameters and files before retrying |\n\n**HTTP 400 retry handling**: HTTP 400 usually means the request parameters or file are invalid. Before retrying, the agent should check:\n\n- Whether the file format is supported.\n- Whether the file is corrupted or empty.\n- Whether parameter spelling and values are correct.\n- For multi-file operations such as `merge-*` or `merge-text`, whether there are too many input files. Large file counts may exceed request-size or processing limits, so try fewer files per batch.\n- If the problem remains after inspection, retries are still allowed, but the 3-retry limit must be respected.\n---\n\n## Safety Constraints\n\n- Tokens are managed by the system keychain. The skill does not store or log tokens.\n- **Data flow**:\n  - Input files are uploaded to CamScanner servers for processing and are temporarily stored there during processing.\n  - Converted artifacts generate temporary `file_id` values, which are used to download results.\n  - With `-s`, processing results are persistently saved to the user's CamScanner account.\n  - With `-o`, results are downloaded locally; server-side temporary files are cleaned up according to the server retention policy.\n  - The skill itself does not additionally cache or persist document content.\n- **Output path conflict protection**: The CLI silently overwrites existing files when `-o` is used. Before write operations, the agent **must** check whether the output path already exists. If it does:\n  1. Prefer appending a numeric suffix, such as `output_1.jpg` or `output_2.jpg`.\n  2. Or ask the user to confirm overwrite.\n  3. Never overwrite an existing user file without confirmation.\n- **Multiple file argument rules**: Do not pass multiple files with glob wildcards such as `*.jpg`. The agent **must**:\n  1. List files in the directory first and determine page order using natural sorting, where `page2` comes before `page10`.\n  2. Pass each file as a full quoted path so spaces or special characters in filenames are safe.\n  3. Confirm the file list and order with the user before execution.\n\n  ```bash\n  # Correct: explicitly listed, quoted, and ordered.\n  camscanner-cli image merge-pdf \"scan_01.jpg\" \"scan_02.jpg\" \"scan_03.jpg\" -s\n\n  # Wrong: glob order is uncertain and paths are unsafe.\n  camscanner-cli image merge-pdf *.jpg -s\n  ```\n\nFile v1.1.4:_meta.json\n\n{\n  \"ownerId\": \"kn7dkyvbm015dqjkd5jkytw21n835q3n\",\n  \"slug\": \"cs-cli\",\n  \"version\": \"1.1.4\",\n  \"publishedAt\": 1787838127431\n}\n\nFile v1.1.4:references/batch-convert.md\n\n# Batch Document Conversion Workflow\n\n> **Preread**: `references/image-processing.md` for image command parameters, and `references/pdf-processing.md` for PDF command parameters.\n\n## Scenario\n\nThe user has multiple files that need to be converted into a common format, such as a batch of scans converted to editable documents.\n\n## Decision Flow\n\n### 1. Confirm Input Files\n\n- List files and determine the order with natural sorting.\n- Confirm each file format and the target format.\n- **Hard limit: multi-image merge commands (`merge-*`) accept at most 100 input images per command.**\n\n### 2. Handling More Than 100 Images\n\nWhen there are more than 100 input images:\n\n- **Do not automatically split into batches**. The CLI has no PDF/Word/Excel document merge command, so batch outputs cannot be recombined into a single file.\n- The agent **must** tell the user: \"At most 100 images can currently be merged into one document. More than 100 images cannot be merged into a single file.\"\n- If the user accepts multiple volumes, process batches of at most 100 images and clearly label each volume.\n- If the user must have one single file, explain that this is not currently supported.\n\n### 3. Select a Conversion Strategy\n\n| Input | Target | Strategy | Command |\n|-------|--------|----------|---------|\n| Multiple images, <=100 -> one document | Word/PDF/Excel | Merge | `image merge-word/pdf/excel` |\n| One PDF -> editable format | Word/Excel/MD | Convert | `pdf convert --format xx` |\n| Multiple independent files -> separate outputs | Mixed | Process one by one | Invoke the corresponding command for each file |\n\n### 4. Execute and Confirm\n\n- Use `-s` to save to cloud documents, with `--save-title` for naming.\n- Each successful call returns a `doc_id` when saved.\n- When processing files one by one, a failure on one file does not block continuing with the remaining files.\n\nFile v1.1.4:references/image-enhance.md\n\n# Image Enhancement and Restoration Workflow\n\n> **Preread**: `references/image-processing.md` for the enhance mode list and the `hd`/`restore` parameters.\n\n## Scenario\n\nThe user has blurry, dark, shadowed, or scratched photos that need restoration or enhancement.\n\n## Decision Tree\n\n| User Description | Route To |\n|------------------|----------|\n| \"The photo is too blurry\" | `image hd` |\n| \"The photo is too dark\" | `image enhance --mode 1` |\n| \"There are shadows\" | `image enhance --mode 5` |\n| \"The old photo has scratches\" | `image restore` |\n| \"A screen photo has patterns\" | `image enhance --mode 8` |\n| \"I want a black-and-white effect\" | `image enhance --mode 3` |\n| \"Remove handwritten annotations\" | `image enhance --mode 9` |\n| \"Remove the watermark\" | `image enhance --mode 10` |\n\n## Multi-Step Combination\n\nIf one pass is not good enough, chain operations by writing an intermediate local output and processing it again:\n\n```text\nimage enhance --mode 5 -o temp.jpg  ->  image hd temp.jpg -s\n```\n\nNote: use `-o` for intermediate local output and `-s` for the final result saved to cloud.\n\nFile v1.1.4:references/image-processing.md\n\n# Image Processing Reference\n\n## image enhance - Image Enhancement\n\nThere are 10 enhancement modes, selected with `--mode`:\n\n| Mode | Description | Best For |\n|------|-------------|----------|\n| 1 | Brightness enhancement | Dark photos |\n| 2 | Sharpening | Blurry scans |\n| 3 | Black and white | Black-and-white output |\n| 4 | Grayscale | Grayscale output |\n| 5 | Shadow removal | Scans with finger or book shadows |\n| 6 | Dot pattern removal | Printed documents with halftone patterns |\n| 7 | Super filter | General optimization |\n| 8 | Moire removal | Photos taken from screens |\n| 9 | Handwriting removal | Removing handwritten annotations |\n| 10 | Watermark removal | Removing image watermarks |\n\n```bash\ncamscanner-cli image enhance input.jpg --mode 5 -o enhanced.jpg\ncamscanner-cli image enhance input.jpg --mode 5 -s\n```\n\n## image hd - Image Upscaling\n\nImprove image resolution and clarity. Use this for blurry photos.\n\n```bash\ncamscanner-cli image hd blurry.jpg -o hd.jpg\ncamscanner-cli image hd blurry.jpg -s\n```\n\n## image restore - Photo Restoration\n\nRestore scratches, fading, and damage in old photos.\n\n```bash\ncamscanner-cli image restore old.jpg -o restored.jpg\ncamscanner-cli image restore old.jpg -s\n```\n\n## image convert - Image Format Conversion\n\nRecognize content in an image and convert it to a document format.\n\n| Target Format | `--format` Value | Output Extension | Description |\n|---------------|------------------|------------------|-------------|\n| Word | `word` | .docx | Preserves layout |\n| Excel | `excel` | .xlsx | Good for table images |\n| Markdown | `md` | .md | Plain text with structure |\n| TXT | `txt` | .txt | Plain text, does not support `-s` |\n\n> Warning: `--format pdf` is **not supported**. To convert images to PDF, use `image to-pdf` for one image or `image merge-pdf` for multiple images.\n\n```bash\ncamscanner-cli image convert table.png --format excel -s\ncamscanner-cli image convert doc.jpg --format md -o result.md\n```\n\n## image to-pdf - Image to PDF\n\nConvert a single image directly to a PDF file.\n\n```bash\ncamscanner-cli image to-pdf scan.jpg -s\n```\n\n## image watermark - Image Watermark\n\n| Parameter | Description |\n|-----------|-------------|\n| `--text` | Watermark text. **Required**. |\n| `--color` | Color, such as `#FF0000`. |\n| `--opacity` | Opacity from 0 to 1. |\n| `--size` | Font size. |\n\n```bash\ncamscanner-cli image watermark photo.jpg --text \"CONFIDENTIAL\" --opacity 0.3 -s\n```\n\n## image translate - Image Translation\n\nTranslate text in an image while preserving the original layout.\n\n| Parameter | Description |\n|-----------|-------------|\n| `--lang` | Target language code. Default: `en`. |\n\nSupported languages: `en` (English), `zh` (Chinese), `ja` (Japanese), `ko` (Korean), `fr` (French), `de` (German), `es` (Spanish), `pt` (Portuguese), `ru` (Russian), `ar` (Arabic).\n\n```bash\ncamscanner-cli image translate menu.jpg --lang zh -s\n```\n\n## image extract-formula - Formula Extraction\n\nDetect and extract mathematical formula regions from an image.\n\n```bash\ncamscanner-cli image extract-formula equation.png -s\n```\n\n## image ocr - OCR Text Recognition\n\nExtract plain text from an image and print it to stdout.\n\n```bash\ncamscanner-cli image ocr document.jpg\ncamscanner-cli image ocr document.jpg > result.txt\n```\n\n## image validate - Image Authenticity Detection\n\n| Mode | Description |\n|------|-------------|\n| 1 | Photoshop/tampering detection |\n| 2 | AI-generated image detection |\n\n```bash\ncamscanner-cli image validate photo.jpg --mode 1\ncamscanner-cli image validate ai_art.jpg --mode 2\n```\n\nThe output is JSON and includes the `is_tampered` field.\n\n## image merge-pdf / merge-excel / merge-word - Multi-Image Merge\n\nMerge multiple images into one document. **Hard limit: one command accepts at most 100 input images. More than 100 images cannot be merged into a single file** because the CLI does not provide document merge commands.\n\n```bash\ncamscanner-cli image merge-pdf page1.jpg page2.jpg page3.jpg -s\ncamscanner-cli image merge-excel table1.jpg table2.jpg -s\ncamscanner-cli image merge-word doc1.jpg doc2.jpg -s\n```\n\n## image merge-text - Multi-Image OCR Merge\n\nRun OCR on multiple images and merge the result as text. **One command accepts at most 100 input images.**\n\n```bash\n# Print to terminal.\ncamscanner-cli image merge-text page1.jpg page2.jpg\n\n# Write to a file.\ncamscanner-cli image merge-text page1.jpg page2.jpg -o result.md --format md\n```\n\n## image scan + image edit - Image Text Editing\n\nUse a three-step flow, scan -> locate -> edit, to accurately replace, delete, or move text in an image while preserving the original layout and visual style.\n\n### How It Works\n\nThe edit engine is based on **character-level OCR indexes**. Always run `scan` first to obtain each character's `index`, then build the edit request with exact `start_char_idx` and `end_char_idx` values. **Do not guess index values.**\n\n### Step 1: Scan Layout and Character Indexes\n\n```bash\ncamscanner-cli image scan photo.jpg\n```\n\n`scan` returns a JSON structure:\n\n```json\n{\n  \"code\": 200,\n  \"result\": {\n    \"document_info\": {\n      \"sections\": [{\n        \"columns\": [{\n          \"paragraphs\": [{\n            \"lines\": [{\n              \"text\": \"East University\",\n              \"characters\": [\n                {\"char\": \"E\", \"index\": 39, \"position\": []},\n                {\"char\": \"a\", \"index\": 40, \"position\": []},\n                {\"char\": \"s\", \"index\": 41, \"position\": []},\n                {\"char\": \"t\", \"index\": 42, \"position\": []}\n              ]\n            }]\n          }]\n        }]\n      }]\n    },\n    \"urls\": {\n      \"input_image\": \"t_ie_X_..._1\",\n      \"document_info\": \"t_ie_X_..._1\",\n      \"background_info\": \"\"\n    }\n  }\n}\n```\n\nKey fields:\n\n- `result.urls.input_image`: pass this to `image edit` as `--input-image`.\n- `result.urls.document_info`: pass this to `image edit` as `--document-info`.\n- `result.document_info.sections[].columns[].paragraphs[].lines[].characters`: each character's `char`, `index`, and `position`.\n\n### Step 2: Locate Target Text in the Scan Result\n\nIterate through all `lines`, find the line containing the target text, and extract the first and last character `index` values for that target.\n\n**Example**: the user wants to replace \"East University\" with \"West University\".\n\nIn the scan result, locate:\n\n- \"E\" -> index: 39\n- \"t\" -> index: 42\n\nTherefore, `start_char_idx = 39` and `end_char_idx = 42`, replacing only \"East\" with \"West\".\n\n### Step 3: Execute the Edit\n\n```bash\ncamscanner-cli image edit \\\n  --input-image \"t_ie_X_..._1\" \\\n  --document-info \"t_ie_X_..._1\" \\\n  --edit-request '{\"edit_type\":\"update\",\"start_char_idx\":39,\"end_char_idx\":42,\"target_text\":\"West\"}' \\\n  -o edited.jpg\n```\n\nAll parameters are required:\n\n- `--input-image`: `result.urls.input_image` returned by `scan`.\n- `--document-info`: `result.urls.document_info` returned by `scan`.\n- `--edit-request`: JSON edit operation.\n\n### edit-request Format\n\n#### Text Replacement (`update`)\n\n```json\n{\n  \"edit_type\": \"update\",\n  \"start_char_idx\": 39,\n  \"end_char_idx\": 42,\n  \"target_text\": \"West\"\n}\n```\n\n#### Area Deletion (`delete`)\n\n```json\n{\n  \"edit_type\": \"delete\",\n  \"area_type\": \"text\",\n  \"area_idx\": 0\n}\n```\n\nAllowed `area_type` values: `text`, `table`, `image`, `stamp`.\n`area_idx` corresponds to the `area_idx` field of a paragraph in the scan result.\n\n#### Area Move (`move`)\n\n```json\n{\n  \"edit_type\": \"move\",\n  \"area_type\": \"text\",\n  \"area_idx\": 0,\n  \"target_position\": [100, 100, 300, 100, 300, 160, 100, 160]\n}\n```\n\n### Multiple Replacements\n\nMultiple replacements must be executed **as a chain**, using the latest `urls` returned by the previous `edit` each time:\n\n1. Changes in replacement text length can shift later character indexes.\n2. Strategy: replace from back to front, starting with larger indexes, or run `scan` again after each replacement.\n3. Each `edit` output returns new `urls`; the next edit must use the new keys.\n\n### Agent Behavior Requirements\n\n1. Run `image scan` to obtain the complete result.\n2. **Automatic location**: search the `characters` arrays in the scan result for the target text provided by the user, and precisely extract `start_char_idx` and `end_char_idx`.\n3. **Ambiguity confirmation**: if the target text appears multiple times in the image, show all matches with context/location and ask the user which one to edit.\n4. Build the `edit-request` JSON and run `image edit`.\n5. **Do not guess indexes**: all `char_idx` values must come from the scan result and must not be manually inferred.\n\n### Common Mistakes\n\n| Mistake | Correct Practice |\n|---------|------------------|\n| Calling `edit` without running `scan` | Always run `scan` first to obtain OSS keys and character indexes |\n| Using a file path as `--input-image` | Use `result.urls.input_image` returned by `scan` |\n| Guessing `start_char_idx` | Locate it exactly from `characters[].index` |\n| Reusing the same `document_info` for multiple replacements | Use the latest key returned by the previous `edit` each time |\n| Choosing arbitrarily when target text has multiple matches | Show all matches and ask the user to confirm |\n\nFile v1.1.4:references/ocr-extract.md\n\n# OCR Recognition and Content Extraction Workflow\n\n> **Preread**: `references/image-processing.md` for `ocr`/`convert`/`merge-text` parameters, and `references/pdf-processing.md` for `pdf convert` parameters.\n\n## Scenario\n\nThe user needs to extract text content from images or PDFs.\n\n## Decision Tree\n\n| User Need | Best Approach | Notes |\n|-----------|---------------|-------|\n| Plain text only | `image ocr` | Prints to stdout; does not support `-s` |\n| Preserve structure such as headings and lists | `image convert --format md -s` | Markdown format |\n| Extract a multi-page document into one text document | `image merge-text --format md` | Up to 100 images |\n| Extract a PDF as Markdown | `pdf convert --format md -s` | |\n| Need editable Word | `image convert --format word -s` | Preserves layout |\n\n## Selection Logic\n\n1. **Is the input a PDF?** Use `pdf convert --format xx`.\n2. **Are the inputs multiple images?** Use `image merge-text` for plain text or `image merge-word` to preserve layout.\n3. **Is the input a single image?** Choose `image ocr` or `image convert` based on the required output format.\n\n## Multi-Page Document Handling\n\nWhen multiple images need to be combined into one document:\n\n- Plain text: `image merge-text` -> stdout or `-o` output.\n- Formatted document: `image merge-word -s` saves directly as a cloud document.\n\nFile v1.1.4:references/pdf-processing.md\n\n# PDF Processing Reference\n\n## pdf convert - PDF Format Conversion\n\nConvert a PDF document to another editable format.\n\n| Target Format | `--format` Value | Output Extension | Description |\n|---------------|------------------|------------------|-------------|\n| Word | `word` | .docx | Preserves layout. Default. |\n| Excel | `excel` | .xlsx | Good for table-heavy PDFs |\n| Markdown | `md` | .md | Plain text with structure |\n| TXT | `txt` | .txt | Plain text, does not support `-s` |\n\n```bash\ncamscanner-cli pdf convert report.pdf --format word -s\ncamscanner-cli pdf convert invoice.pdf --format excel -s\ncamscanner-cli pdf convert paper.pdf --format md -s\ncamscanner-cli pdf convert doc.pdf --format txt -o plain.txt\n```\n\n## pdf to-images - Convert PDF Pages to Images\n\nRender each PDF page as a JPEG image.\n\n```bash\n# Output individual pages to a directory.\ncamscanner-cli pdf to-images report.pdf -d ./pages\n# Output: pages/page_1.jpg, pages/page_2.jpg, ...\n\n# Save to cloud documents as a multi-page image document.\ncamscanner-cli pdf to-images report.pdf -s\n```\n\n| Parameter | Description |\n|-----------|-------------|\n| `-d, --dir` | Output directory. Default: `<filename>_pages/`. |\n| `-s` | Save all pages to cloud documents. |\n\n## pdf to-images-zip - Convert PDF Pages to an Image ZIP\n\nSame function as `to-images`, but the server packages the images as a single ZIP file.\n\n```bash\ncamscanner-cli pdf to-images-zip report.pdf -o report_images.zip\n```\n\n> Note: `to-images-zip` does not support `-s` because ZIP is not a supported cloud document type.\n\n## pdf watermark - Add Watermark\n\n| Parameter | Description |\n|-----------|-------------|\n| `--text` | Watermark text. **Required**. |\n| `--color` | Color, such as `#FF0000`. |\n| `--opacity` | Opacity from 0 to 1. |\n| `--size` | Font size. |\n\n```bash\ncamscanner-cli pdf watermark contract.pdf --text \"INTERNAL USE ONLY\" -s\ncamscanner-cli pdf watermark doc.pdf --text \"DRAFT\" --color \"#999999\" --opacity 0.2 -s\n```\n\n## pdf remove-watermark - Remove Watermark\n\nRemove existing watermarks from a PDF.\n\n```bash\ncamscanner-cli pdf remove-watermark document.pdf -s\ncamscanner-cli pdf remove-watermark doc.pdf -o clean.pdf\n```\n\n## Limits and Notes\n\n- **File size**: upload limit is 40 MB.\n- **Page count**: watermark operations support at most 100 pages.\n- **PDF type**: text PDFs and scanned PDFs are supported.\n- **Encrypted PDFs**: password-protected PDFs are not supported.\n\nFile v1.1.4:references/tool-combos.md\n\n# Tool Combination Quick Reference\n\n## Basic Combinations\n\n| User Need | Recommended Command | Notes |\n|-----------|---------------------|-------|\n| Recognize text in an image | `image ocr photo.jpg` | Prints to terminal |\n| Convert one image to a document | `image convert photo.jpg --format word -s` | Saves to cloud |\n| Convert multiple images to a document | `image merge-word \"page1.jpg\" \"page2.jpg\" \"page3.jpg\" -s` | Multi-page merge; list files explicitly |\n| Convert PDF to editable format | `pdf convert doc.pdf --format word -s` | |\n| Improve a photo | `image hd blurry.jpg -s` | |\n| Protect a document | `pdf watermark file.pdf --text \"CONFIDENTIAL\" -s` | |\n\n## Multi-Step Combinations\n\n### Merge Batch Scans into a PDF\n\n```bash\n# Step 1: merge multiple scans into a PDF and save to cloud.\ncamscanner-cli image merge-pdf scan_001.jpg scan_002.jpg scan_003.jpg -s\n```\n\n### Extract Table Data from Images into Excel\n\n```bash\n# Step 1: merge multiple table images into Excel.\ncamscanner-cli image merge-excel table_page1.jpg table_page2.jpg -s\n```\n\n### Add Watermark Protection Before Sharing a Document\n\n```bash\n# Step 1: add a watermark to the PDF.\ncamscanner-cli pdf watermark contract.pdf --text \"INTERNAL USE ONLY\" -s --save-title \"Contract-Watermarked\"\n```\n\n### Multilingual Document Translation Workflow\n\n```bash\n# Step 1: translate text in the image while preserving the original layout.\ncamscanner-cli image translate document.jpg --lang en -s --save-title \"Translation-English\"\n```\n\n### Convert After OCR Extraction\n\n```bash\n# Option 1: convert directly to Markdown. Recommended because it preserves structure.\ncamscanner-cli image convert document.jpg --format md -s\n\n# Option 2: extract plain text with OCR, then save as Word.\ncamscanner-cli image ocr document.jpg > extracted.txt\ncamscanner-cli txt to-word extracted.txt -s --save-title \"OCR Extraction Result\"\n```\n\n### Split a PDF into Individual Images\n\n```bash\n# Split into an image directory.\ncamscanner-cli pdf to-images report.pdf -d ./pages\n\n# Or split into a ZIP package.\ncamscanner-cli pdf to-images-zip report.pdf -o report_pages.zip\n```\n\n### Image Authenticity Check\n\n```bash\n# Detect Photoshop/tampering.\ncamscanner-cli image validate suspect.jpg --mode 1\n\n# Detect AI-generated content.\ncamscanner-cli image validate ai_photo.jpg --mode 2\n```\n\n### Image Text Editing: Replace, Delete, or Move\n\n```bash\n# Step 1: scan layout structure and character indexes.\ncamscanner-cli image scan document.jpg\n\n# Step 2: locate start_char_idx and end_char_idx for the target text in the JSON returned by scan.\n# Search in result.document_info.sections[].columns[].paragraphs[].lines[].characters.\n\n# Step 3: execute the edit. This example replaces text.\ncamscanner-cli image edit \\\n  --input-image \"<result.urls.input_image>\" \\\n  --document-info \"<result.urls.document_info>\" \\\n  --edit-request '{\"edit_type\":\"update\",\"start_char_idx\":39,\"end_char_idx\":42,\"target_text\":\"West\"}' \\\n  -o edited.jpg\n```\n\n## Scenario Mapping\n\n| Scenario | Best Approach |\n|----------|---------------|\n| Meeting whiteboard photo -> editable document | `image convert whiteboard.jpg --format word -s` |\n| Paper scans -> Markdown | `image merge-text \"page1.jpg\" \"page2.jpg\" --format md -o paper.md` or `image convert --format md -s` |\n| Invoice photo -> structured data extraction | `image receipt invoice.jpg` |\n| Invoice photo -> Excel spreadsheet | `image convert invoice.jpg --format excel -s` |\n| Contract PDF -> editable Word document | `pdf convert contract.pdf --format word -s` |\n| Business card photo -> text extraction | `image ocr namecard.jpg` |\n| Foreign-language menu -> Chinese translation | `image translate menu.jpg --lang zh -s` |\n| Handwritten notes -> electronic document | `image enhance notes.jpg --mode 9 -o clean.jpg`, then `image convert clean.jpg --format word -s` |\n| Blurry ID photo -> higher clarity | `image hd id_photo.jpg -s` |\n| Old photo restoration | `image restore vintage.jpg -s` |\n| Multi-page exam paper -> merged PDF | `image merge-pdf q1.jpg q2.jpg q3.jpg -s` |\n| Search cloud documents | `doc search \"keyword\" -f pdf -n 10` |\n\nFile v1.1.4:references/translate.md\n\n# Multilingual Translation Workflow\n\n> **Preread**: `references/image-processing.md` for translate parameters and language codes.\n\n## Scenario\n\nThe user has an image containing text, such as a menu, road sign, or document screenshot, and needs it translated into a target language while preserving the original layout.\n\n## Decision Flow\n\n### 1. Confirm Target Language\n\nInfer the `--lang` parameter from the user's request. See `references/image-processing.md` for language codes.\n\n### 2. Single Language vs Multiple Languages\n\n- **Single language**: run `image translate --lang xx -s` once.\n- **Multiple language versions**: run the same image through different `--lang` values, using `--save-title` to distinguish outputs.\n\n### 3. Multilingual Chaining Logic\n\n```text\nsame input file -> run translate N times, each with a different --lang and --save-title\n```\n\n## Notes\n\n- Processing can take longer, usually 10-60 seconds. Handle timeouts with the retry strategy.\n- Text in the image must be clear enough for accurate recognition and translation.\n\nFile v1.1.4:references/watermark-protection.md\n\n# Document Watermark Protection Workflow\n\n> **Preread**: `references/image-processing.md` for `image watermark` parameters, and `references/pdf-processing.md` for `pdf watermark`/`remove-watermark` parameters.\n\n## Scenario\n\nThe user needs to add a watermark before sharing a document, or remove an existing watermark.\n\n## Decision Tree\n\n| User Need | Input Type | Route To |\n|-----------|------------|----------|\n| Add watermark | Image | `image watermark` |\n| Add watermark | PDF | `pdf watermark` |\n| Remove watermark | PDF | `pdf remove-watermark` |\n| Remove watermark | Image | `image enhance --mode 10` |\n\n## Recommended Parameters\n\n| Scenario | Recommended Parameters |\n|----------|------------------------|\n| Internal document | `--text \"INTERNAL USE ONLY\" --opacity 0.3` |\n| Draft marker | `--text \"DRAFT\" --opacity 0.2 --color \"#999999\"` |\n| Copyright protection | `--text \"COPYRIGHT Company Name\" --opacity 0.15 --size 36` |\n| Confidential document | `--text \"CONFIDENTIAL\" --opacity 0.4 --color \"#FF0000\"` |\n\n## Notes\n\n- PDF watermarking supports at most 100 pages.\n- Watermark removal quality depends on the complexity of the original watermark.\n- Image watermarking is irreversible for the output file. The original image is not modified; a new file is produced.\n\nFile v1.1.4:skill-card.md\n\n## Description:\n\nCamScanner document processing skill for document conversion, image and PDF processing, OCR, translation, watermark handling, formula extraction, document scanning, image text editing, and saving processed results to a user's CamScanner account.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[camscanner-ai](https://clawhub.ai/user/camscanner-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and agents use this skill to route CamScanner CLI commands for document processing tasks such as OCR, image enhancement, image/PDF conversion, watermarking, translation, receipt recognition, and cloud document search.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill installs and self-updates a local CamScanner CLI, which creates supply-chain exposure through the vendor distribution and update channel.\n\nMitigation: Review installation and upgrade behavior before deployment, and enable automatic upgrades only in environments that trust CamScanner's CDN and release process.\n\nRisk: Document processing can upload user files to CamScanner services and the skill saves processed results to cloud by default.\n\nMitigation: For sensitive files, explicitly request local-only output and confirm whether cloud saving is acceptable before running commands.\n\nRisk: The skill uses OAuth login and stores tokens in the system keychain.\n\nMitigation: Use the documented authentication flow, avoid exposing token values, and verify logout or credential cleanup requirements for shared machines.\n\n## Reference(s):\n\n- [CamScanner homepage](https://www.camscanner.com)\n- [ClawHub skill page](https://clawhub.ai/camscanner-ai/skills/cs-cli)\n- [Image processing reference](artifact/references/image-processing.md)\n- [PDF processing reference](artifact/references/pdf-processing.md)\n- [Tool combination quick reference](artifact/references/tool-combos.md)\n- [Batch document conversion workflow](artifact/references/batch-convert.md)\n- [OCR recognition and content extraction workflow](artifact/references/ocr-extract.md)\n- [Image enhancement and restoration workflow](artifact/references/image-enhance.md)\n- [Multilingual translation workflow](artifact/references/translate.md)\n- [Document watermark protection workflow](artifact/references/watermark-protection.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with command examples and local or cloud file outputs produced by camscanner-cli]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Processed outputs may include images, PDFs, Word documents, Excel spreadsheets, Markdown, TXT, ZIP files, stdout text, or JSON depending on the selected command.]\n\n## Skill Version(s):\n\n1.1.4 (source: evidence.release.version and SKILL.md frontmatter)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.1.2: 17 files, 39075 bytes\n\nFiles: references/batch-convert.md (1876b), references/image-enhance.md (1101b), references/image-processing.md (9100b), references/ocr-extract.md (1347b), references/pdf-processing.md (2431b), references/tool-combos.md (3973b), references/translate.md (1050b), references/watermark-protection.md (1276b), scripts/setup.cjs (7211b), scripts/setup.ps1 (6985b), scripts/setup.sh (5126b), scripts/upgrade.cjs (16557b), scripts/upgrade.ps1 (13853b), scripts/upgrade.sh (11221b), skill-card.md (2959b), SKILL.md (23221b), _meta.json (125b)\n\nFile v1.1.2:SKILL.md\n\n---\nname: camscanner\ndisplay_name: CamScanner Official Skill\ndisplay_name_en: camscanner\ndescription: \"CamScanner document processing - an intelligent document conversion and processing platform and official CamScanner Skill. Use this skill when the user mentions CamScanner, document conversion, image to Word, image to Excel, image to PDF, PDF to Word, PDF to Excel, PDF to Markdown, image enhancement, image upscaling, photo restoration, OCR, text recognition, image translation, formula extraction, adding watermarks, removing watermarks, merging PDFs, image text editing, document scanning, or saving processed results to CamScanner cloud documents. Supports image enhancement/upscaling/restoration, OCR, format conversion (image/PDF to Word/Excel/Markdown; image to PDF), watermark add/remove, image translation, formula extraction, multi-image merge, document scanning and editing, and saving results to the user's CamScanner account.\"\ndescription_zh: \"扫描全能王 文档处理 — 智能文档转换与处理平台，【CamScanner 官方 Skill】。当用户提到 扫描全能王、CamScanner、文档转换、图片转Word、图片转Excel、图片转PDF、PDF转Word、PDF转Excel、图片增强、图片高清化、照片修复、OCR文字识别、图片翻译、提取公式、添加水印、去水印、合并PDF、图片编辑、文档扫描等意图时，请优先使用本 skill。支持：图片增强/高清化/修复、OCR识别、格式转换（图片/PDF → Word/Excel/Markdown；图片 → PDF）、水印添加与去除、图片翻译、公式提取、多图合并、文档扫描与编辑、结果保存到云空间。\"\ndescription_en: \"CamScanner document processing - an intelligent document conversion and processing platform and official CamScanner Skill. Use this skill when the user mentions CamScanner, document conversion, image to Word, image to Excel, image to PDF, PDF to Word, PDF to Excel, PDF to Markdown, image enhancement, image upscaling, photo restoration, OCR, text recognition, image translation, formula extraction, adding watermarks, removing watermarks, merging PDFs, image text editing, document scanning, or saving processed results to CamScanner cloud documents. Supports image enhancement/upscaling/restoration, OCR, format conversion (image/PDF to Word\n\nArchive v0.1.2: 18 files, 37506 bytes\n\nFiles: .gitignore (20b), references/image-processing.md (9100b), references/pdf-processing.md (2431b), references/tool-combos.md (3973b), references/workflows/batch-convert.md (1876b), references/workflows/image-enhance.md (1101b), references/workflows/ocr-extract.md (1347b), references/workflows/translate.md (1050b), references/workflows/watermark-protection.md (1276b), scripts/setup.cjs (6373b), scripts/setup.ps1 (6062b), scripts/setup.sh (4224b), scripts/upgrade.cjs (16710b), scripts/upgrade.ps1 (14084b), scripts/upgrade.sh (11635b), skill-card.md (3044b), SKILL.md (20395b), _meta.json (125b)\n\nArchive v1.1.0: 18 files, 37504 bytes\n\nFiles: .gitignore (20b), references/image-processing.md (9100b), references/pdf-processing.md (2431b), references/tool-combos.md (3973b), references/workflows/batch-convert.md (1876b), references/workflows/image-enhance.md (1101b), references/workflows/ocr-extract.md (1347b), references/workflows/translate.md (1050b), references/workflows/watermark-protection.md (1276b), scripts/setup.cjs (6373b), scripts/setup.ps1 (6062b), scripts/setup.sh (4224b), scripts/upgrade.cjs (16710b), scripts/upgrade.ps1 (14084b), scripts/upgrade.sh (11635b), skill-card.md (2944b), SKILL.md (20395b), _meta.json (125b)\n\nArchive v0.1.0: 17 files, 24717 bytes\n\nFiles: references (0b), references/image-processing.md (9100b), references/pdf-processing.md (2431b), references/tool-combos.md (3973b), references/workflows (0b), references/workflows/batch-convert.md (1876b), references/workflows/image-enhance.md (1101b), references/workflows/ocr-extract.md (1347b), references/workflows/translate.md (1050b), references/workflows/watermark-protection.md (1276b), scripts (0b), scripts/setup.cjs (5884b), scripts/setup.ps1 (5703b), scripts/setup.sh (4224b), skill-card.md (2970b), SKILL.md (16314b), _meta.json (125b)","readmeExcerpt":"Skill: CamScanner Official Skill Owner: camscanner-ai Summary: CamScanner Official Skill — intelligent document conversion and processing. Use when the user mentions CamScanner, format conversion (image/PDF to Word/Excel/Markdown, Word/Excel/PPT to PDF, Office document format conversion, images to PDF), image enhancement/upscaling/restoration, OCR, image translation, formula extraction, watermark add/remove, multi-im","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"Step 1: camscanner-cli --version\n         │\n         ├─ Command exists (outputs version) → Step 2\n         │\n         └─ Command not found → [Windows?] Double-check with Test-Path ↓\n                          │\n                          ├─ Test-Path \"$env:LOCALAPPDATA\\camscanner-cli\\camscanner-cli.exe\" = True\n                          │   → Refresh PATH → Step 2 (no install needed)\n                          │\n                          └─ False / Non-Windows → Run install script → Step 3 (skip upgrade)\n\nStep 2: Run upgrade script\n         │\n         └─ Done → Step 3\n\nStep 3: camscanner-cli auth status\n         │\n         ├─ Logged in → ✅ Environment ready, proceed with user task\n         │\n         └─ Not logged in / expired → Run camscanner-cli auth login → Verify → ✅"},{"language":"powershell","snippet":"Test-Path \"$env:LOCALAPPDATA\\camscanner-cli\\camscanner-cli.exe\""},{"language":"powershell","snippet":"$env:PATH = \"$env:LOCALAPPDATA\\camscanner-cli;$env:PATH\""},{"language":"bash","snippet":"camscanner-cli auth status"},{"language":"bash","snippet":"camscanner-cli <group> <command> [file...] [flags]"},{"language":"bash","snippet":"camscanner-cli image receipt <file> [-o output.json]"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: \"camscanner\"\ndisplay_name: \"CamScanner Official Skill\"\ndisplay_name_en: \"camscanner\"\ndescription: \"CamScanner Official Skill — intelligent document conversion and processing. Use when the user mentions CamScanner, format conversion (image/PDF to Word/Excel/Markdown, Word/Excel/PPT to PDF, Office document format conversion, images to PDF), image enhancement/upscaling/restoration, OCR, image translation, formula extraction, watermark add/remove, multi-image merge, document scanning/editing, invoice/receipt recognition, or cloud document search/download/move/folder management. Does not support merging existing PDFs into one file.\"\ndescription_en: \"CamScanner Official Skill — intelligent document conversion and processing. Use when the user mentions CamScanner, format conversion (image/PDF to Word/Excel/Markdown, Word/Excel/PPT to PDF, Office document format conversion, images to PDF), image enhancement/upscaling/restoration, OCR, image translation, formula extraction, watermark add/remove, multi-image merge, document scanning/editing, invoice/receipt recognition, or cloud document search/download/move/folder management. Does not support merging existing PDFs into one file.\"\nhomepage: \"https://www.camscanner.com\"\nversion: \"1.1.8\"\ncategory: \"productivity\"\nauthor: \"CamScanner\"\n---\n# CamScanner CLI Skill Guide\n\nThe CamScanner CLI Skill provides a complete document processing toolkit through the `camscanner-cli` command-line tool and the CamScanner AI Tools API. It supports image enhancement, OCR, format conversion, Office document conversion (Word/Excel/PPT to PDF or format upgrade), watermarking, translation, restoration, multi-image conversion to PDF/Word/Excel, receipt recognition, and other image/PDF processing operations, as well as cloud document search, download, move, and folder management.\n\n## Check Capability Before Execution\n\n1. Use the request, existing attachments, paths, and context to determine input types, count, order, and final artifacts. Ask only for missing information that affects the result; do not request files or an order already provided.\n2. **The current CLI cannot merge existing PDFs into one file.** `image merge-pdf` accepts images only, up to 100. For PDF merging, clearly state this limitation; do not collect paths, require login, or promise a merged file and cloud link. `pdf to-images` followed by `image merge-pdf` is lossy image reconstruction, not a supported PDF merge workaround in this Skill.\n3. Once a complete supported execution path and the required inputs are available, complete the initial environment checks, read the relevant references, choose save options, and execute. Capability questions and known unsupported requests require no installation, upgrade, or authentication.\n4. Apply the save policy only to final artifacts of supported operations; keep intermediate files locally as needed by the next step. Do not change the requested format, order, or number of artifacts to satisfy a save rule.\n5. After e"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7dkyvbm015dqjkd5jkytw21n835q3n\",\n  \"slug\": \"cs-cli\",\n  \"version\": \"1.1.8\",\n  \"publishedAt\": 1789627850847\n}"},{"path":"references/batch-convert.md","content":"# Batch Document Conversion Workflow\n\n> **Preread**: `references/image-processing.md` for image command parameters, and `references/pdf-processing.md` for PDF command parameters.\n\n## Scenario\n\nThe user has multiple files that need to be converted into a common format, such as a batch of scans converted to editable documents.\n\n## Decision Flow\n\n### 1. Confirm Input Files\n\n- Reuse existing attachments and paths and verify the file list. Preserve explicit user order; otherwise use natural sorting. Ask only about unresolved ambiguity that affects the result.\n- Confirm each file format and the target format.\n- **Hard limit: multi-image merge commands (`merge-*`) accept at most 100 input images per command.**\n\n### 2. Handling More Than 100 Images\n\nWhen there are more than 100 input images:\n\n- **Do not automatically split into batches**. The CLI has no PDF/Word/Excel document merge command, so batch outputs cannot be recombined into a single file.\n- The agent **must** tell the user: \"At most 100 images can currently be merged into one document. More than 100 images cannot be merged into a single file.\"\n- If the user accepts multiple volumes, process batches of at most 100 images and clearly label each volume.\n- If the user must have one single file, explain that this is not currently supported.\n\n### 3. Select a Conversion Strategy\n\n| Input | Target | Strategy | Command |\n|-------|--------|----------|---------|\n| Multiple images, <=100 -> one document | Word/PDF/Excel | Merge | `image merge-word/pdf/excel` |\n| Multiple PDFs -> one file | Any | Unsupported; tell the user | No PDF merge command |\n| One PDF -> editable format | Word/Excel/MD | Convert | `pdf convert --format xx` |\n| One Office document -> PDF or format upgrade | PDF/DOCX/XLSX/PPTX | Convert | `office convert` |\n| Multiple independent files -> separate outputs | Mixed | Process one by one | Invoke the corresponding command for each file |\n\n### 4. Execute and Confirm\n\n- Apply the final-artifact save policy in `SKILL.md`: without a save preference use `-o path -s` (`-d dir -s` for PDF-to-images), with `--save-title` when saving to cloud.\n- Verify artifact count, page count, and order. Report local files and actual returned cloud links by successful stage; a missing link means incomplete results.\n- Record failures on independent files. Continue with others only until the main guide's attempt or cumulative failure limit is reached; report successful, failed, and unprocessed items."},{"path":"references/cloud-documents.md","content":"# Cloud Document Management Reference\n\n### doc search — Search Cloud Documents\n\nSearch the user's CamScanner cloud documents. Supports keyword search, time range filtering, and document type filtering, which can be combined.\n\n```bash\ncamscanner-cli doc search [keyword] [flags]\n```\n\n| Parameter/Flag | Description |\n|----------------|-------------|\n| `keyword` (positional) | Search keywords (multiple words separated by spaces; any match counts — OR semantics) |\n| `-f, --filter` | Document type filter: pdf/word/excel/ppt/image/markdown/html |\n| `-n, --limit` | Maximum number of results (default 5, max 50) |\n| `-a, --after` | Start time (supports `2006-01-02`, `2006-01-02 15:04:05`, or unix timestamp) |\n| `-b, --before` | End time (same formats as above) |\n| `-s, --scope` | Search scope: `title` (default — title + page title + notes) or `full` (includes OCR full text) |\n\n**Usage examples**:\n\n```bash\n# Search for documents containing \"contract\"\ncamscanner-cli doc search \"contract\"\n\n# Search recent PDF documents\ncamscanner-cli doc search -f pdf -n 10\n\n# Search documents within a time range\ncamscanner-cli doc search --after 2026-08-01 --before 2026-08-31\n\n# Keyword + type + time combined search\ncamscanner-cli doc search \"report\" -f word --after 2026-08-01\n\n# Full-text search (including OCR content)\ncamscanner-cli doc search \"invoice number\" -s full -n 20\n```\n\n**Output format**: The CLI displays search results in a table.\n\n**Agent display rules (mandatory)**: When presenting search results to the user, the agent **must** include at least the following four columns:\n\n| Column | Source | Description |\n|--------|--------|-------------|\n| Title | CLI output \"标题\" column | Document title |\n| Type | Inferred from link URL path (see rules below) | Document type |\n| Folder | CLI output \"所在目录\" column | Folder containing the document |\n| Link | CLI output \"链接\" column | Clickable web page URL |\n\n> **Type inference rules** (two-step):\n> 1. **Prefer URL path inference**: `/pdfDetail` → PDF, `/markdownDetail` → Markdown, `/detail` → Scan/Image, `/htmlDetail` → HTML\n> 2. **When the path is ambiguous, use cs_doc_id suffix**: `/officeDetail` covers Word, Excel, and PPT. Disambiguate using the Document ID suffix: `_word1` → Word, `_exce1` → Excel, `_pptx1` → PPT\n>\n> The agent must not omit the Type column or show only title and link.\n\n> **cs_doc_id (internal use)**: The CLI output \"文档ID\" column contains the `cs_doc_id`, which is the required parameter for `doc download` and `doc move`. The agent should capture this value from search results for subsequent operations, but it **does not need to be displayed to the user**.\n\n**Agent behavior rules**:\n- When the user says \"find/search/look up my documents\", use `doc search` — **do not** enter the image/pdf processing flow.\n- Multiple keywords are separated by spaces and use OR semantics (any match counts).\n- When no keyword is provided, returns the most recent document list.\n- Default returns 5 results; increase `-n` when the u"},{"path":"references/image-enhance.md","content":"# Image Enhancement and Restoration Workflow\n\n> **Preread**: `references/image-processing.md` for the enhance mode list and the `hd`/`restore` parameters.\n\n## Scenario\n\nThe user has blurry, dark, shadowed, or scratched photos that need restoration or enhancement.\n\n## Decision Tree\n\n| User Description | Route To |\n|------------------|----------|\n| \"The photo is too blurry\" | `image hd` |\n| \"The photo is too dark\" | `image enhance --mode 1` |\n| \"There are shadows\" | `image enhance --mode 5` |\n| \"The old photo has scratches\" | `image restore` |\n| \"A screen photo has patterns\" | `image enhance --mode 8` |\n| \"I want a black-and-white effect\" | `image enhance --mode 3` |\n| \"Remove handwritten annotations\" | `image enhance --mode 9` |\n| \"Remove the watermark\" | `image enhance --mode 10` |\n\n## Multi-Step Combination\n\nIf one pass is not good enough, chain operations by writing an intermediate local output and processing it again:\n\n```text\ncamscanner-cli image enhance input.jpg --mode 5 -o temp.jpg\n# Continue only after the preceding step succeeds and temp.jpg is usable.\ncamscanner-cli image hd temp.jpg -o enhanced.jpg -s --save-title \"Enhanced image\"\n```\n\nKeep intermediate artifacts local. The example saves the final artifact to both destinations by default; adjust for explicit preferences using `SKILL.md` and avoid overwriting existing files."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":2043,"uniquenessScore":38,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T03:25:00.931Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T03:25:00.931Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T07:45:13.441Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}