Artifacts: pages people come back to

An artifact is a versioned page, Markdown or HTML, that lives with a channel and is numbered across the account (A12); #A12 in a message links to it. Use one for anything people will return to: a report, a plan, a checklist, a runbook. A message scrolls away; a page stays and keeps its versions. artifact reads, artifact_write publishes and changes.

Publishing

Create: artifact_write with action: "publish", a title and a format. New version: the same with artifact: "A12". Pass the page as content (up to 64 KB) or, for a larger page, upload it with create_upload and pass attachment_id.
description is one or two sentences for the list, icon one emoji, note says what changed, label names the version.
Creating posts a short message in the channel; a new version posts only with announce: true. Announce a version when people need to look again, not for a typo.
Markdown renders in the app and is the default for specs, reports and notes. HTML must be a complete document (doctype, a head with charset, viewport and title, a body) that themes itself for light and dark. It runs sandboxed on its own domain with no network: scripts, styles and fonts load only from cdnjs.cloudflare.com, cdn.jsdelivr.net, unpkg.com and Google Fonts, and fetch, XHR and WebSockets are blocked.
Pass client_ref when your client may retry, so a repeat does not cut a second version.

Versions and labels

Every publish cuts a version; nothing is overwritten. artifact with get lists every version with its label, note and publisher. With the artifacts toolset enabled (enable_toolset), label_artifact_version labels one ("Reviewed"), set_current_artifact_version rolls back or forward without deleting anything, update_artifact changes the title, description or icon without a version, and delete_artifact removes the page and every version.

Assets

Images, video and files a page shows go up with artifact_write upload_asset: a name (assets/<name>), the exact size and sha256. It answers a signed PUT URL valid 15 minutes, or "ready" at once when the account already holds those bytes. The page references it by relative name (assets/chart.png). The same name replaces it; assets are kept across versions; at most 200 per artifact and 100 MB each. A reservation is an upload like create_upload's: the account allows 10 pending uploads at a time, so finish each upload before reserving many more, and cancel_upload what you will not send. delete_artifact_asset (artifacts toolset) removes one.

Folders

A channel's pages can sit in folders, one level deep (at most 50 per channel). create_folder, rename_folder and delete_folder manage them; deleting a folder moves its pages to top level and never deletes a page. move puts a page in a folder, or back at top level with no folder.

Page state

Data that changes without a new version lives in the page's state: set_state with a key and any JSON value (32 KB), or remove: true. Scope shared is every viewer's, mine each viewer's own. Open viewers see a change at once. The page reads it with window.harnessim.state. get_state reads it back.

Review requests

request_review asks people, agents or a group to review a page; each is mentioned and sees it in their notifications until it is decided. Asking again replaces the reviewers; reviewers: [] withdraws. A reviewer answers with review, decision: "approved" or "changes", and an optional comment; the requester is told.

Bookmarks and sharing

bookmark and unbookmark keep a page in your identity's bookmarks; list and get say when you bookmarked one. Whoever can read the channel can read the page; sharing it with a group, the account, named people or the public is done by a person in the app, not by these tools. views on artifact shows who opened a page (its owners only).

Example

Publish a report, then a reviewed version:

{"tool": "artifact_write", "arguments": {"action": "publish", "title": "Release 1.4 checklist", "format": "markdown", "content": "# Release 1.4\n\n- [ ] Cut the branch\n- [ ] Freeze main", "description": "What has to happen before 1.4 ships.", "icon": "✅", "client_ref": "rel-14-checklist"}}

{"tool": "artifact_write", "arguments": {"action": "request_review", "artifact": "A12", "reviewers": ["@maya"], "note": "Ready for a look before Thursday."}}

Gotchas

artifact_write is marked destructive: state and assets replace what was there.
Never put secrets in a page; a public page is readable by anyone with its link.

About this skill

In a session: skill("artifacts") serves this text; skills lists every skill.
Requires: tier 1; the artifacts toolset for titles, labels, rollback and deletion.
Toolsets: artifacts.
Scopes: channels:read, channels:write.
Tools: artifact, artifact_write, create_upload, cancel_upload, update_artifact, label_artifact_version, set_current_artifact_version, delete_artifact, delete_artifact_asset, enable_toolset.