# wirk show

> **Preview.** This page describes the interface WIRK launches with. The hosted service is in private staging and access is by invitation. What is live today: /docs/index.md#what-is-live-today

> **Not live yet.** `POST /v2/show`, `wirk show` and the `wirk_show` tool ship with the 0.3 clients; pages are served from `show.wirk.life`.

When a person needs to see something, don't hand-write HTML. Send a small view config, or the preset `status`, and get back a link. Every opening reads WIRK again, so the page is current; it never holds a copy of your records.

```
wirk show status
wirk show --file view.json
wirk show --revoke https://show.wirk.life/v/…
```

MCP: `wirk_show` with `{"preset": "status"}`, `{"title": …, "blocks": […]}` or `{"revoke": "<link>"}`.

## Who can open a link

Anyone who has the link can open it, read-only, for 24 hours. Share it directly with the person; never paste it into WIRK, Git or a pull request. The page shows what its creator can read at the moment it is opened, never more.

## The answer

```
https://show.wirk.life/v/kX3…Q
Where the launch stands · 4 blocks · 23 records · read as alice-agents in Acme (1a2b3c4d) · 38 ms
Anyone with this link can open it, read-only, until Fri 2 Oct 10:42 BST. Each opening reads WIRK again.
Share the link directly with the person; never paste it into WIRK, Git or pull requests.
Revoke: wirk show --revoke <link>
```

The link is alone on the first line. The CLI opens it in a browser unless you pass `--no-open`.

## Request

```
POST /v2/show
Authorization: Bearer <token>

{"preset": "status"}
```

Send exactly one of:

| Key | Makes |
|---|---|
| `preset` | `"status"`: the page below |
| `title` and `blocks` | A page from your config |
| `revoke` | Revokes a link you made |

Optional beside them: `timezone` (an IANA name such as `Europe/London` for times on the page; the clients send the machine's), `workspace_id`, `format`. There is no `request_id`: a retry makes a second link, which changes no record and expires on its own.

## Blocks

A config is a `title` (1–120 characters) and 1–20 `blocks`, shown in order. Each block has exactly one type key, plus that type's options. Every block takes an optional `title`.

| Block | Main key | Options | Shows |
|---|---|---|---|
| `note` | `"note": "text"` (1–4,000 characters) | `ask` (1–500): a highlighted recommendation | Your words |
| `facts` | `"facts": [{"label", "count": Fields, "of": Fields, "detail"}]` (1–8; `of` and `detail` optional) | | Count tiles; `of` shows "N of M" with a bar |
| `items` | `"items": Fields` or `"items": [Ref, …]` (1–32 refs) | `about`, `group` (a field key), `limit` (1–100, default 20), `notes`; with refs, `track: true` draws an ordered rail | Records, most urgent first: overdue, due within 7 days, in progress or blocked, other open work, then closed |
| `item` | `"item": Ref` | `notes` | One item: body, criteria, links, linked-from counts, fields |

**Fields** is the [query](/docs/query.md#filters) `fields` map, including `kind` and `proposal`. **Ref** is a full ID, a short ID or an exact title. `notes` maps a record ID to one line of your text (1–300 characters), shown beside that record.

## The status preset

`{"preset": "status"}` expands to:

```json
{"title": "Status",
 "blocks": [
  {"facts": [
    {"label": "Work items", "count": {"kind": "work"}},
    {"label": "Proposals waiting", "count": {"proposal": ["proposed", "deferred"]}},
    {"label": "Changed in 7 days", "count": {"changed_days": 7}}]},
  {"items": {"proposal": ["proposed", "deferred"]}, "limit": 10, "title": "Proposals waiting for review"},
  {"items": {"kind": "work"}, "group": "status", "limit": 60, "title": "Work by status"},
  {"items": {"changed_days": 7}, "title": "Changed in the last 7 days"}]}
```

## Example: a decision page

```json
{"title": "Two proposals need you before the release",
 "blocks": [
  {"note": "Both proposals mark merged work complete. Each cites its pull request and test evidence; nothing else changes."},
  {"items": {"proposal": ["proposed", "deferred"]}, "title": "Waiting for your decision"},
  {"item": "5c1e7a90", "title": "What the first proposal completes",
   "notes": {"5c1e7a90": "Merged in pull request 41; CI green."}}]}
```

## The page

One self-contained page: no scripts, no external requests, light and dark, readable on a phone. Every record shows its short ID, revision and age, so a person can point an agent at it. The footer says whose access it shows, when it was read, and who can open it until when. Pages are read-only; corrections go through an agent.

## Limits and errors

- At most 20 blocks, 12 counted selections, 500 records and 32 KiB of config per page.
- At most 200 links per principal per wirkspace in any 24 hours: `too_many_views` (429) says when the next can be made.
- A filter, ref or field refused while building the page comes back with its own code and the block's path, for example `blocks.2.items.status`. Nothing is stored.
- `invalid_view`: a bound exceeded, or an unknown time zone. `views_unavailable` (503): pages are not switched on for this service yet.
- Revoking: only the creator can revoke (`not_authorized` otherwise); revoking twice is fine.