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": "<assetId>", "mediaType": "application/pdf", "filename": "<original>" }

Do NOT paste raw bytes or data: URIs into the reply body — they bypass the content-addressed store, defeat caching, and make follow-up retrieval impossible. The chat renderer reads ContentBlock attachments and surfaces them as previews. If the user explicitly requests a newly generated local file, that is a separate file carrier: write it under artifacts/ and run cloud deliver <abs-path> or cloud task attach <abs-path> explicitly.

Backing capabilities (D22 mapping)

Replaces these v1.x built-in skills: asset-search, asset-describe, asset-read.

Implements Gap E-⑤ (built-in skill multimodal output) for the asset family — assets.describe / assets.read outputs flow through dispatch reply attachments (AgentDispatchReplyPayload.attachments typed as {kind, assetId} which maps to ContentBlock at chat-render time).