/assets

name: assets
scope: common
description: Locate, inspect, and read content-addressed workspace assets — search by filename/metadata, describe before reading bytes, then read bounded ranges. Use whenever the user references an uploaded file, when you need to cite file evidence, or when a task input/output is an asset URI. Executes via the `cloud asset` CLI and tools.

Assets

Workspace assets are **content-addressed** (SHA-256). Each asset has a stable URI, MIME type, size, and metadata. Treat assets as **opaque bytes you must search → describe → read** in that order. Don't claim you read a file unless a CLI call actually returned its content.

When to use

• The user references a file by name, path, or `prismer://...` URI and you need its content.
• A task description includes asset attachments — find them, inspect them, decide if you need to read bytes.
• You're answering a question that requires citing file evidence (extract text, quote a paragraph, summarize a doc).
• You need to find a file by hash, filename, or content keyword.

CLI Reference

Search

cloud asset list                                          # everything in current workspace
cloud asset list --limit 20 --kind file
cloud asset list --filename "design-doc*"                 # filename glob
cloud asset list --mime "application/pdf"                 # by MIME
cloud asset list --updated-after "2026-05-01"             # recency
cloud asset by-hash <sha256>                              # exact content lookup

Describe (metadata only, no bytes)

cloud asset get <assetId>                                 # full metadata, no content
# OR for in-process MCP tools (when daemon exposes them):
#   prismer.asset.describe { uri | assetId | contentHash }

Read (bounded ranges only)

cloud asset download <assetId> --out ./local-copy         # whole file to disk
cloud asset download <assetId> --offset 0 --length 4096   # first 4 KB
# For LLM-friendly text extraction:
cloud asset read <assetId> --offset 0 --length 4096       # text range read
cloud asset read <assetId> --as-text                      # full text (for small text-like assets)

Upload / Sync

cloud asset upload ./report.pdf                           # → asset record + content hash
cloud asset upload ./report.pdf --conversation-id <id>    # pin to conversation
cloud asset sync                                          # refresh local cache index

Workflow

1. **Search first** — use `cloud asset list` with filename / MIME / hash filters unless the user gave you an exact ID or URI. 2. **Describe before reading bytes** — `cloud asset get <id>` to confirm MIME, size, and that this is the right file. 3. **Read bounded ranges** — `--offset` + `--length`. Start with a small range (4 KB) to identify encoding/structure, then expand only if needed. 4. **Preserve the locator** — record the asset ID, content hash, and URI in your reply so the user can follow up.

Operating Rules

Search

• Don't guess asset identifiers when `asset list` can locate them. Filename + size + workspace = usually unique.
• Prefer **exact** filters (hash, full filename, MIME) over broad terms.
• Content search is **best-effort for text-like assets only**. PDFs, images, binaries won't match content queries — search by metadata.
• Use a small `--limit` for targeted lookups; expand only when the first batch misses.

Describe

• **Always describe before reading.** Metadata tells you whether reading is safe (text vs binary, size, encoding).
• Don't treat metadata as proof of file contents — title and MIME can lie. The content hash is the only authoritative identity.
• If multiple locators disagree (e.g. filename matches two assets with different hashes), **stop and re-search** rather than reading the wrong file.
• Avoid reading binary or image-heavy assets as text. Use the `liteparse` local `lit` workflow for supported parsing/OCR, `office-artifacts` for document-specific operations, or an available vision tool for images. Do not invoke `cloud parse`: the cloud heavy-format parser is not available.

Read

• **Never load an entire large file** — `--length` caps reads. Start at 4 KB, expand only when the answer requires it.
• Byte offsets don't align to line or character boundaries in multibyte text — handle the partial-token edge at the read boundary.
• Watch the `truncated` flag in the response. If set, plan additional reads or tell the user the answer is based on a partial read.
• Report partial reads explicitly when drawing conclusions from excerpts ("based on the first 8 KB of `<filename>`...").

Cite

• When citing file evidence, **include the asset ID/URI and the locator** (offset + length, page number, or hash). The user needs to be able to follow up.
• Never claim you read an asset unless a CLI/tool call **succeeded** with content in the response. Hallucinated reads are the #1 trust failure.

Output reporting

After search: list matches with `<assetId> <filename> <mime> <sizeBytes>`. If 0 matches, say so and suggest broader filters.

After describe: surface MIME, size, and any structured metadata fields relevant to the user's question (page count for PDFs, dimensions for images, etc.).

After read: include the asset locator + range + content. If `truncated: true`, say "(partial — read X of Y bytes)".

ContentBlock output (v2.0 §4.6 / Gap E-⑤)

When this skill resolves an **image** asset for downstream rendering, emit a ContentBlock pointing at the asset id rather than inlining bytes or a pre-signed URL into prose:

{ "kind": "image", "assetId": "<assetId>", "mediaType": "image/png", "alt": "<one-line desc>" }

When it resolves an existing **file** asset (PDF, CSV, archive), do not copy it into `$PRISMER_ARTIFACTS_DIR` or create a duplicate upload. Return the existing asset through the structured ContentBlock attachment using its authoritative `assetId`:

{ "kind": "file", "assetId": "<a