Artefacts

An artefact is a self-contained HTML page hosted by kcap: a plan for review, a comparison, a report someone would rather read as a page than as terminal output. It has a stable URL, an explicit audience, and optionally a form whose answers an agent can block on.

Open Artefacts in the sidebar to see the pages you published and the ones shared with you. Artefacts belong to no repository, so the Scope selector does not filter them.

Publish a page

Ask your agent in ordinary language:

Write up the migration options as a page with a comparison table and publish it as an artefact. Share it with the platform team.

The kcap-artefacts MCP server is installed by CLI setup. The agent publishes with publish_artefact and gets the URL back. The current session is cited as the artefact’s source, so the page links back to the work that produced it.

From the terminal:

kcap artefact publish plan.html --title "Migration plan" --visibility org
kcap artefact publish plan.html --update <artefactId>   # new version, same URL
kcap artefact list --mine

The title defaults to the file name. --session <id> cites a session explicitly; inside an agent session it defaults to the current one. --update publishes content only: a revision keeps the URL, audience, and title of the original.

Pages run without a network

The page is served in an isolated sandbox that cannot make network requests or reach the kcap page around it. Inline every stylesheet, script, and image, using data URIs for images. An external URL renders as nothing. The viewer passes the current light or dark theme to the page.

By default a page can be up to 4 MB and an artefact can have up to 50 versions. A refused publish names the limit it hit and its value.

Choose who can open it

An artefact is private until you share it. Unlike a session, it has no default audience to inherit.

Audience	CLI value	Who can open it
Private	none	Only you.
Everyone in the org	org	Anyone signed in to your organization’s kcap.
People & teams	scoped	Only the people, teams, and projects you name.

As the owner, change the audience from the Visibility row in the artefact’s side panel, or from the terminal:

kcap artefact share <artefactId> --visibility scoped --to team:platform --to user:<id>
kcap artefact share <artefactId> --visibility none

--to takes user:<id>, team:<slug>, or project:<id> and may be repeated. A share replaces the whole audience: a grant you leave out is removed. Under scoped, naming nobody means only you can open it.

Every viewer sees the artefact’s audience in the list and on the page, so they know who else can read it before passing the link on. A link alone grants nothing. Someone outside the audience sees This artefact isn’t available, the same page shown for a wrong or deleted link.

Read an artefact

The viewer shows the page with a side panel of its owner, visibility, version, and publish dates, plus the sessions it came from that you can see. Use Copy link to share the URL, or Open the page on its own to view it in a separate tab.

Filter the list by All, Mine, or Shared with me, or search by title or author.

Collect answers

An artefact can ask its readers something: approve a plan, pick an option, score each part of a proposal. The agent declares a response_schema when it publishes. Each field is one of:

Type	Answer
choice	One of the listed options.
multi	Any of the listed options.
score	A number between a minimum and maximum.
text	Free text.

The server validates every answer against the schema and tallies the results. Anyone who can open the artefact can answer it. The respondent is the signed-in viewer, resolved by the server; the page cannot claim to be someone else. The side panel’s Respondent row shows who your answer will be recorded as.

Every submission is kept. Results count each person’s latest answer per version, so changing your mind replaces your earlier answer in the tally. Answers belong to the version they were given for: approval of version 1 is not approval of version 2.

results_mode decides what other readers see:

Mode	Readers see
owner (default)	Only their own answer.
aggregate	Tallies, without names or free text.
named	Who said what.

The owner sees the tallies under Answers in the side panel. View responses lists every submission, including earlier answers a respondent later replaced.

Let an agent wait for a decision

Ask the agent to stop for sign-off:

Publish the rollout plan as an artefact with an approve/reject field and a comment box. Share it with Dana and Sam, then wait until both have answered before you continue.

await_artefact_responses blocks until the requested number of people have answered, the version is closed, or the wait times out. A timeout returns whatever has arrived; the agent can wait again. get_artefact_results reads the answers without waiting, and close_artefact_responses freezes a version’s results. A schema can also set a closing deadline.

Write an answerable page

The page talks to the viewer through postMessage envelopes tagged kcap: "v1". It announces itself with ready, receives an init carrying the reader’s name and their previous answer, and submits with submit:

const send = (msg) => parent.postMessage({ kcap: "v1", ...msg }, "*");
addEventListener("message", ({ data }) => {
  if (data?.kcap !== "v1") return;
  if (data.type === "init") prefill(data.prior);        // null on a first visit
  if (data.type === "ack") showSaved(data.accepted, data.error);
  if (data.type === "results") render(data.results);  // when the reader may see results
});
send({ type: "ready" });
// on submit:
send({ type: "submit", payload: { verdict: "approve", note: "Ship it." } });

A page that never sends ready is treated as a plain document: the viewer shows no Respondent row for it.

Remove an artefact

The owner can delete an artefact from its side panel or with:

kcap artefact delete <artefactId>

Deletion stops serving the content to everyone and cannot be undone. An administrator can also take an artefact down; its owner sees why.

Agent tools

Tool	Use
publish_artefact	Publish a page from inline HTML or a local file; optionally set its audience, answer schema, or publish a new version with update_id.
list_my_artefacts	List the artefacts you can see, with their URLs.
set_artefact_visibility	Replace an artefact’s audience.
await_artefact_responses	Wait for answers.
get_artefact_results	Read tallies and each person’s current answer.
close_artefact_responses	Close a version to answers, or reopen it.

Widening an audience is a sharing decision, so kcap-artefacts is not pre-approved in harnesses that support per-server trust. See Visibility & sharing for how session audiences compare.