Skip to content
AssureSwarm Docs

Agent Operating Guide

/coach-item-document-attach

Attach a file or external URL to an item by resolving the workflow step that will hold it: files upload immediately, URLs go through human review.

Attach a document, an uploaded file or an external URL, to an item such as a control, policy, or authority source. Canvas stores documents on workflow steps, not on items directly, so this skill resolves the item’s attached workflow and the step that should hold the document, then attaches there. A file uploads immediately via upload_document , the human gate is your choice to attach it, while an external URL goes through suggest_change human review before it links. If the item has no workflow step yet, the skill offers to attach a workflow first rather than failing.

When to use

Section titled “When to use”

When you think in terms of an item, “file this SOC 2 report against the control”, rather than a specific workflow step. If you already know the step you want, the step-scoped document skills attach to it directly.

Inputs

Section titled “Inputs”
Flag Required Notes
--item <id-or-slug-or-title> Yes The item to attach against.
--file <path> or --url <url> Yes (exactly one) The document source: a local file, or an external http(s) URL.
--step <stepId> No The specific step to own the document; resolved from the item’s workflow if absent.
--file-name <text> No Display name; derived from the file or URL if absent.
--mime-type <type> No File mode; inferred from the extension.
--file-type <text> No URL mode; a short type label.
--reason <text> No The suggestion’s reason (URL mode).

Example

Section titled “Example”

/coach-item-document-attach --item "Access provisioning" --file vendor-soc2.pdf resolves the control, finds its evidence step (asking you to pick if the workflow has more than one), base64-encodes the file, and calls upload_document: the file lands on the step right away. Passing --url https://… instead submits a stepdocumentlink suggestion you approve in Canvas.

Good to know

Section titled “Good to know”
  • File writes are immediate; URL links go through review. That’s why the handoff link differs: a URL gives you a review-and-approve link, a file gives you the step viewer.
  • Uploads are base64 and capped at 10 MB. For very large corpora, prefer a URL link over uploading binaries.
  • An item with no attached workflow can’t hold a document. Attaching a workflow first , even a one-step “Source documents” workflow, is the supported fix, and the skill offers it.
  • To remove a linked URL, submit a delete suggestion against the stepdocumentlink; its id comes from the step’s documents in a get_step_context response.
Section titled “Related”