Put a project on a live screen

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.
• 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.

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. 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.

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.

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:

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 — what each panel kind discloses, and the budgets and refresh rates that a screen runs under.
• Live viewing links and access — what stops a link, and what revoking one cannot undo.
• Manage saved insights — trend panels publish an exact saved revision, so save the insight first.
• Permission scope reference — 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.

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.