Parse, read, search, navigate, summarize, and extract tables or structured evidence from PDFs, images, Office files, HTML, OFD, and other supported local documents or document URLs through xparse-cli. Use this Skill for single-document conversion, server-generated DOCX/PDF/XLSX files, targeted secti

xparse parse Use the installed xparse cli as the only parsing, authentication, quota, and document navigation execution kernel. Do not reproduce its HTTP, OAuth, quota, PDF splitting, or result merging logic in the Skill. Task context For every new user request, create one private 0600 JSON file before the first xParse command: Preserve the user's wording and keep the operational reason brief. Never include hidden reasoning, credentials, document content, or the final answer. Pass task context <FILE only on the first xParse invocation for that request. Delete the temporary file after that invocation. Later commands inherit the task. Do not pass inline JSON through shell arguments, echo , or a heredoc. Command integrity and structured error gate Run every operational xparse cli invocation as a standalone shell command. Do not pipe it through head , tail , grep , or another command, and do not append cleanup, printing, file reads, or other shell commands that can replace its exit status. Perform task context cleanup in a separate shell call. For every failed command, parse the final stderr object whose schema version is xparse error.v1 . Treat that object as failure even if a shell wrapper reports exit code 0. Apply this gate before issuing another xParse command: retryable=false means do not retry or reinterpret the same logical action. Follow only the declared next action . For CONTACT SUPPORT , report the error and preserved identifiers, then issue no more xParse commands for the current request. retryable=true permits at most one Agent layer retry of the same logical action. Keep the same Task, Run, Resource, and operation id where present. Changing flags, authentication options, selector form, Resource identifier, timing, or switching between task read and task export does not create a new logical action or reset its retry budget. Do not run diagnostic xParse commands unless the Task state or next action explicitly calls for them. Goal completion pressure is not a recovery signal; a correct failure report completes the Agent action. After a non retryable failure, another attempt is allowed only after the user confirms an external remediation or explicitly requests a new action. Reuse the preserved Task and Run identifiers; never recreate completed server work. Free, free package, and paid routing Use api auto by default. The CLI queries the service quota before parsing and uses the current server response as the authority instead of relying on a Skill snapshot. Mode CLI behavior Use it when api auto Uses the daily free API allowance first. When quota reports an AppKey authenticated free package with sufficient free remain count , it can use that package through the existing authenticated route. Default for supported PDF and image work. api free Forces the free endpoint and does not use the authenticated free package route. The user explicitly requires the free endpoint only. api paid Forces the paid endpoint and follows the service's existing package/balance billing behavior. The user explicitly approves paid use, or approves it after learning that the format requires the paid API. Authentication is identity, not permission to spend. Never choose api paid only because OAuth or AppKey credentials exist. Run xparse cli quota output json when the user asks about quota, when a routing failure needs explanation, or before proposing a paid retry. Read all returned facts: daily free pages remaining and reset time; whether the request is authenticated; authenticated free package total, historical used count, and current free remain count when present (routing uses only free remain count ); maximum pages and file size per request. Do not cache or calculate an allowance in the Skill. parse api auto performs its own quota preflight, and the parse response remains authoritative if quota changes between inspection and execution. The Skill must not promise stronger billing guarantees than the existing server provides. Device OAuth and AppKey are different identities. If quota returns authenticated=false or omits free package , do not infer package access from an OAuth login indicator. Treat only fields in the current quota response as available. The free endpoint supports PDF and images. Office, HTML, OFD, and other formats may require api paid ; explain this and obtain the user's approval before switching modes. If all reported free sources are insufficient, stop and explain the current quota rather than silently retrying as paid. Choose the workflow Choose by input shape and durability, not by whether authentication already exists: Workflow selection and billing selection are independent decisions. Task versus parse is chosen from the request's input shape and durability needs; auto , free , and paid choose only the billing route. A quota, eligibility, authorization, funding, or format outcome must never change an accepted multi document Task into individual parse calls. Only an explicit user request that narrows the original scope to a genuinely new one document action may be treated as a new parse operation. Use parse for one document or URL when the user needs an immediate result, conversion, or local outline/search navigation. Use the durable Task Runtime for two or more local documents, or when the user explicitly needs a persistent Task ID, later status checks, selective result reads, exports, debugging, or continuation. A one file request can therefore still be a Task when durability is explicit. Task Runtime control plane routes and OAuth authentication are available in both domestic and overseas environments. Free first Task billing is a separate capability: if the selected environment returns TASK FREE MODE UNAVAILABLE , stop and explain it. Never replace the Task with serial parse calls or silently switch to paid execution. Durable multi document Task Runtime For local files, start one server persisted Task instead of launching multiple parse commands: api auto is free first and fails closed: it does not silently create a paid Task. Use api paid only after the user explicitly approves paid service behavior. Do not parallelize individual parse commands for inputs that belong to one Task. task run returns after the server accepts the Run. When structured progress is enabled, stderr is an xparse event.v1 JSONL stream: run accepted exposes the accepted Task/Run identity immediately, and run status is emitted only when the state changes. Stdout contains exactly one final submission JSON. Preserve operation id , task id , and run id . If submission fails or the process loses its response, reuse the observed operation id with operation id ; never invent a new ID for the same logical submission. Keep Agent workflows on the default submit and return path. Do not add wait or a short fixed timeout automatically. When a user explicitly requests foreground waiting or wait and export, wait polls the same Run; its local timeout returns the current accepted identity with wait timed out: true and next action: POLL STATUS . It does not cancel or recreate the Run. Continue with task status for that exact Task and Run. waiting paid authorization and waiting funds are accepted Task states, not CLI transport failures. The submission/status JSON and its next action are the single authority. They mean the user request is incomplete: stop immediately and issue no more xParse commands—not quota, status, read, export, debug, another task run , or parse —until the user confirms the required external action. Then call task resume once for the exact Task and Run. Use task status <TASK ID run id <RUN ID for bounded progress checks. Start at 2 seconds, then back off to 5, 10, 20, and 30 seconds; do not spend more than about two minutes polling in one Agent turn. Return control with the IDs and current state when work is still running. Never start a duplicate Task merely because the Run is still scheduled or running . Prefer task read when only one result is needed; use task export when the user needs the complete result set. On partial failure, run task debug before choosing a recovery action. Use task continue only when that accepted Run's debug result identifies the existing Resource's raw Parse error code 40423 . Supply per file passwords by repeating password ; when more than one Resource is involved, bind each value as <SELECTOR =<PASSWORD . This reruns only the selected failed Resources without reprocessing successful files. Task identity and state move forward only: PASSWORD INPUT REQUIRED permits only one documented correction replay of the originating command with the same operation id . For initial submission that command is task run ; for new files under an existing Task it is task rerun mode new files , and the error may legitimately include that existing task id . The CLI transparently reuses ready uploads; the Agent must not track File Asset IDs or decide which files to upload. An operation id without a Task/Run ID after another ambiguous submission permits one unchanged replay. Once a new task id or run id has been accepted for a logical submission, never return to task run for it. A task read or task export failure must not fall back to a new Task, serial parse , cached results, an alternate selector, or a different Run. Use task debug only for partial failed / failed , not to investigate a completed Run whose result access returned a non retryable error. Read [task runtime.md](references/task runtime.md) before starting, inspecting, or recovering a durable Task. Full document or conversion Use one parse command: For PDFs, pass an output directory so long Markdown is not truncated in terminal output. The CLI creates the directory when it does not exist: Read the saved result before requesting more detail. Add view json only when the task needs structured elements, coordinates, tables, pages, or title hierarchy. Server generated document exports When the user explicitly asks to export one document as DOCX, PDF, or XLSX, explain that this requires the paid parse endpoint and obtain paid approval before running the command. Request only the formats the user needs: export accepts docx , pdf , and xlsx ; pass a comma separated list or repeat the flag. The CLI removes duplicates, and XLSX automatically uses the table export scope. api paid and output <DIR are required when export is present. Immediately before downloading, the CLI resolves the selected AppKey or OAuth identity again so a long parse can refresh an expired OAuth token. It then downloads each successful export and verifies the saved file size. The output directory contains the ordinary parse result plus <basename .docx , <basename .pdf , and/or <basename .xlsx . Read or return those local files as the task result. If a name would overwrite the input, the CLI uses <basename .export.<format . Do not expose backend download URLs, file id values, or authorization details to the user. This single document feature is separate from task export , which exports the Markdown results of a durable multi document Task. Targeted reading, search, or extraction For a local document, use: 1. Run get doc info <FILE and retain its exact doc id . 2. Run parse <FILE api auto without page range . A successful complete local parse writes the navigation cache automatically. 3. Use get outline , search text , or read pages to locate relevant content. 4. Batch the required read content calls after navigation is complete. There is no separate cache preparation command. A successful complete local parse is the only preparation step. Page range parses inten

xparse-parse