# Put a project on a live screen

> Ask your agent to publish a read-only view of a project behind a private link, then open it on a phone, a tablet or a wall panel.

Canonical page: https://anectico.com/docs/investigate/live-screens/


A **live screen** is a read-only view of one project that anybody who holds its link can open. It
works on a phone between meetings, on a tablet at a desk, or on a panel on the wall that nobody signs
in to. It shows the panels you chose, refreshed on a timer, and it states on every panel how current
the number is.

Three things to know before you publish one:

- **The link is the credential.** Anyone who has it sees the screen, without signing in. That is the
  point of it, because a wall panel has nobody to sign in. It is also the risk. See [Live viewing
  links and access](/docs/manage/live-links-and-access).
- **It is not an editor.** A viewer can change fullscreen, text size and motion. A viewer cannot change
  the project, the window, the filter, the breakdown or the source set, and cannot reach people, raw
  records or exports from it.
- **It is not a dashboard.** A live screen is built from a small closed set of panel kinds. Each one
  was chosen because it can be shown to somebody who is not signed in. A funnel correlation, a web
  analytics, a revenue, a survey or a heatmap result is not one of them. Each is refused with
  `UNSUPPORTED_RESULT_SELECTOR`. See [Live screen templates and
  panels](/docs/investigate/live-screen-templates).

Your agent creates, previews, and publishes a screen. Editing a published screen changes a draft.
Nothing a viewer sees changes until the screen is published again.

## Ask your agent

> Create a live screen for the lobby panel from the `combined` template. Show me the labels you
> found. After I confirm them, preview it, and then publish it. Give me the link.

| Job | MCP tool or action | CLI command |
| --- | --- | --- |
| Create a screen from a template or from a list of panels | `create_live_screen` | `anectico live screen create` |
| List the screens, and read one screen with its links | `list_live_screens`, `get_live_screen_status` | `anectico live screen list`, `anectico live screen get`, `anectico live status` |
| Render the draft as a viewer would see it | `preview_live_screen` | `anectico live screen preview` |
| Replace both name and complete definition of a draft | `update_live_screen` | `anectico live screen update` |
| Publish the screen and mint its link | `publish_live_screen` | `anectico live screen publish` |
| List the project’s viewing links | `list_live_grants` | `anectico live grant list` |
| Pause or resume a link | `pause_live_grant`, `resume_live_grant` | `anectico live grant pause`, `anectico live grant resume` |
| Replace a link, or end it for good | `rotate_live_grant`, `revoke_live_grant` | `anectico live grant rotate`, `anectico live grant revoke` |
| Delete a screen and all its links | `delete_live_screen` | `anectico live screen delete` |

The agent needs `mcp:read`, `mcp:write` and the Live scopes: `live:read`, `live:write` and
`live:publish`. The full recipe is in [Scope recipes for agent
jobs](/docs/agents/scope-recipes#publish-a-live-screen). `create_live_screen` is a first-class tool.
The agent calls it directly and does not use the write gateway. `list_live_screens` and
`get_live_screen_status` are read actions, run through `execute_read_action`. The other writes run
through `execute_internal_action`. Every Live write through either MCP or CLI first returns
a server confirmation preview containing the complete `before` and `proposed` configuration,
all required scopes, apply-time fields and consequences. Preparation changes nothing and runs
no measurement. After approval, repeat identical arguments with `confirm_token` or
`--confirm-token`. Creates, publication and rotation also require the same stable retry key.
There is no local `--yes` shortcut.

Creation chooses exactly one template or explicit definition. Replacement requires both name
and full definition, preserving every field you want to keep. Service-health panels require
an explicit nonempty `service_names` allowlist in MCP and CLI definitions. Publication previews
name all source scopes: trend needs `analytics:read`, `analytics:query`, `insights:read`,
`persons:read`; people affected needs `errors:read`; service health needs `services:read`;
alert state needs `alerts:read`; log volume needs `logs:read`; notes need no source scope.
A signed-in session can publish with `api_key:write` and the required Live/source scopes:
it creates a dedicated publisher key. Delegated OAuth cannot publish.

Screen and grant inventories accept `limit` and `cursor` / `--limit` and `--cursor` (default
50, maximum 1000). Each result is a page; follow `next_cursor` until `has_more` is false before
giving a complete inventory count. Status returns the full draft as `definition_json`, marked
as untrusted, alongside panel summaries and one grant page. Continue its grant cursor for the
rest. An active publication revision of zero does not establish that it was never published;
`last_published_revision` records the highest frozen revision, including disabled publications.

## What your agent gets back

- **Create.** Ask for one of the three starting templates (`product`, `engineering` or `combined`).
  The server composes a draft from what the project actually contains. Or the agent sends an explicit
  panel list. Create needs an `idempotency_key`, so a retried create returns the first screen and
  leaves no second one behind. This includes a retry that arrives while the original is still in
  flight. Creating a screen publishes nothing and shows nobody anything. A template returns the labels
  that it took out of your project (insight titles, service names, event names) and a note for
  everything that it looked for and did not find.
- **Status.** The full draft, its version, the published revision, and one page of link lifecycle states. Status and list never return a link or any part of one.
- **Preview.** The draft run through the same projection that a viewer receives, so you can read what
  a link would show before anybody is given one. Preview is a write action
  (`execute_internal_action`), not a read, for one reason: every trend panel submits a real
  measurement, so a preview costs what a refresh costs. Panels that the calling credential may not
  read come back **denied**, exactly as they would on the display.
- **Publish.** The first call names every panel that will be disclosed and returns a `confirm_token`.
  Only an identical second call that carries the token applies. The result carries the viewing link.

**The link is returned once, in the response text.** No read on the surface can hand it back
afterwards, because no read carries a field it could travel in. Give it to whoever needs it, and keep
a copy somewhere you trust. If you lose it, rotate the link. You cannot recover it.

## Open the proof

A live screen is not a proof page. The link opens the Live viewer at `/live/:screenId`. This path is
separate from the proof pages. It carries a secret, and it needs no sign-in. A proof page is a
read-only page for a signed-in person, and it opens from a link in a tool result. See [Proof
pages](/docs/agents/proof-pages).

In the Console, open **Published links** (`/published-links`) to see every Live display link in the
project and to revoke one. A Live link shows data to anyone who holds it, without sign-in, so revoke
a link that should no longer work. The Console does not create or edit screens. See [The
Console](/docs/manage/console#published-links).

## Create one with an agent

This is the path the feature was built for: one instruction to an agent that holds a project API key,
and one link back.

**1. Create the screen.** Use `create_live_screen`, as described above. The composed draft is returned
unreviewed. Read every discovered label yourself. Titles, event names, service names and cohort labels
are disclosures: an internal project code name or a customer’s name in an insight title reaches the
display word for word. When the labels are fit to show on a screen that needs no sign-in, tell the
agent to set `labels_reviewed` in the screen definition (`update_live_screen`).

**2. Read the draft back.** `list_live_screens` and `get_live_screen_status`, as above.

**3. Preview it.** `preview_live_screen`, as above.

**4. Publish.** `publish_live_screen` freezes the screen at the version you read, mints the viewing
link, and starts the refresh. It previews first. It needs an `idempotency_key`, so an interrupted
publish resumes and does not mint a second link. A key belongs to the call it was first used for.
Publishing a *different* screen with a key that was already spent on one is refused and not treated as
a retry, so a link is never reported against a screen that nobody published.

**5. Manage it.** `list_live_grants` lists a project’s viewing links with their names, state, expiry,
and the revision each one publishes. `pause_live_grant` and `resume_live_grant` apply immediately.
`rotate_live_grant` issues a replacement and kills the old one. `revoke_live_grant` ends a link
permanently. Rotate, revoke and `delete_live_screen` all preview and confirm first.

Publishing is refused, with a reason that says what to do, in these cases:

- the screen’s labels have not been reviewed (`LIVE_LABELS_UNREVIEWED`);
- the publishing key lacks a scope that one of the panels needs;
- the screen is over a budget; or
- the caller is a credential that can never hold a link: a connected app that acts on somebody’s
  behalf, or a key from another project.

A display outlives any browser session, so its authority has to be something that can still be
checked tomorrow. The link records the API key that published it. Each public snapshot checks that key’s
current permissions. Revoking, expiring, or freezing the key stops the display. To revoke the key,
open **Agents and keys** (`/agents`) in the Console, or ask the agent (`revoke_api_key`).

Delete a screen with a project API key of that project. Deletion needs `live:read` and `live:write`.
A previously published screen also needs `live:publish`, even after all its links have been revoked.
You do not need to create another key or recover the display’s publishing key. A never-published
screen does not need `live:publish`. Missing permissions are refused before anything is removed. A
successful deletion ends the screen’s remaining links and stops its displays.

## Create one with the CLI

The CLI mirrors every operation. It prints the link once on standard output, in the same way that it
prints a new API key:

```bash
anectico live screen create --project PROJECT_UUID --template combined --name 'Lobby panel' \
  --idempotency-key lobby-create
# Repeat the same command with --confirm-token TOKEN after reviewing the server proposal.
anectico live screen preview SCREEN_UUID --project PROJECT_UUID
# Repeat this measurement with its --confirm-token TOKEN before it runs.
anectico live screen publish SCREEN_UUID --project PROJECT_UUID --expected-version 1 \
  --grant-name 'Lobby panel' --idempotency-key lobby-publish
anectico live grant list --project PROJECT_UUID --limit 50
anectico live grant pause GRANT_UUID --project PROJECT_UUID
anectico live grant rotate GRANT_UUID --project PROJECT_UUID --idempotency-key lobby-rotate
anectico live grant revoke GRANT_UUID --project PROJECT_UUID
```

Each write first prints the server's full current and proposed state and the scopes it will check.
After approval, repeat the command with identical arguments and its `--confirm-token TOKEN`.
Keep each displayed idempotency key unchanged. `--expected-version` is the version you last read.
If somebody changes the screen or the reviewed state before confirmation, the server refuses the
write. Every command resolves to one project, and a project-bound key supplies its own.

## What a viewer sees

A panel carries its value, its title, and a freshness strip. The strip says when this platform last
looked, when the answer was computed, what window it measures, and whether the coverage is complete,
partial or unknown. Every panel shows its freshness strip and status word at all times. There is no
collapsed state that could hide a stale value.

Panels fail independently. One source that cannot answer is one tile that says so, next to panels that
are current. It is never a blank screen.

Each panel carries one status word:

| Status | What it means for the reader |
| --- | --- |
| Ready | The value is current. |
| Pending | Submitted, not yet answered. Normal in the first moments of a fresh publication. |
| Delayed | The project is at its limit of concurrent measurements. Nothing is broken; the same request is retried on the next cycle. |
| Unavailable | The source could not answer, or this panel kind is not served yet. |
| Denied | The publishing key's current permissions no longer admit this panel's source. The remedy is a credential change, not a retry. |
| Stale | A value exists but its freshness window has passed. Read the freshness strip before believing it. |
| Expired | The measurement behind the panel reached its expiry and has not been replaced yet. |
| Invalidated | The measurement was withdrawn because the underlying records were deleted or re-attributed. It is not old — it was taken back. |

Denied and Unavailable are deliberately separate words, because the fix is different. Denied is about
permissions. Unavailable is about the source.

A display that cannot reach the server clears itself instead of showing values whose authorization it
can no longer confirm. If the link is paused, rotated, revoked or expired, or the publishing key stops
working, the next read ends the session and the screen shows a neutral access-ended state.

## Browse and Ambient

**Browse** is the default, and the one to use on a phone or a laptop. It has ordinary scrolling, touch
targets big enough to hit, and headline panels first. On a phone the panels stack in a single column.
The display widens to more columns as the screen does.

**Ambient** is for a screen that nobody is holding, such as a tablet on a stand or a panel on a wall. It
offers fullscreen, larger type for viewing distance, and a screen wake lock where the browser supports
one. Both are optional and available on any device. Fullscreen and wake lock always need a deliberate
tap, because browsers require one.

If not every panel fits an ambient layout, choose the subset when you publish. Nothing is dropped
automatically, and nothing is shrunk to illegibility to force a single screen.

## Next

- [Live screen templates and panels](/docs/investigate/live-screen-templates) — what each panel kind
  discloses, and the budgets and refresh rates that a screen runs under.
- [Live viewing links and access](/docs/manage/live-links-and-access) — what stops a link, and what
  revoking one cannot undo.
- [Manage saved insights](/docs/investigate/saved-insights) — trend panels publish an exact saved
  revision, so save the insight first.
- [Permission scope reference](/docs/reference/permissions) — `live:read`, `live:write` and
  `live:publish`.

## Refresh budgets

A display viewer only renews a viewing lease. Opening and polling the page are free. While that
lease is active, each non-note panel's scheduled refresh counts one query operation. Retries of
the same publication, panel and cadence are free.

`get_live_screen_status` and `anectico live screen get` show `budget_origin` and `last_budget`. Changing panel work
moves the origin to the updater. Names, layout and notes keep it. A frozen publication retains its own
origin. A revoked accounting key or removed connection moves new refreshes to **scheduled work**.
The publishing key still controls who may view the public link.

An exhausted slot shows Stale with `budget_exceeded` and tries again at the next cadence. When
limits are unavailable, refreshes continue with `checked: false`. Public display grants show kind
and state only. They never reveal credential ids or names. See
[Scheduled work](/docs/manage/agent-budgets#scheduled-work).

An identical create retry returns the recorded first result even if the draft was later edited or retired. It never creates or restores another screen. Its preparation shows the current state separately from `recorded_result`; a reused key with different arguments is refused.

Publication and deletion preparation include the current frozen composition and every existing
link they will retire, across all link pages. The proposed state names each revoked link and
whether its dedicated publisher key will also be revoked. Publication IDs, clocks and the new
viewing secret are allocated on apply; the secret appears once in response text. The full status
read includes the complete frozen publication as untrusted evidence when one exists.