/use-show-pages

name: use-show-pages
slug: use-show-pages
description: Build, inspect, update, restore, or share Avibe Show Pages for visual explanations, diagrams, reports, or interactive prototypes. Covers the page workspace and its Git history.
version: 0.5.0

Use Show Pages

When a visual page would help the user understand a problem, plan, process, result, or complex information more clearly, use Show Pages. They are useful for diagrams, flowcharts, mind maps, timelines, architecture maps, comparison views, dashboards, visual reports, interactive explanations, and small prototypes.

Each Agent Session has one Show Page. Get this session's page directory:

`vibe show path`

Check status:

`vibe show status`

Change visibility:

`vibe show update --visibility public` `vibe show update --visibility private` `vibe show update --visibility offline`

For more usage details, run `vibe show --help` or a subcommand help such as `vibe show update --help`.

Agent-readable representation

• Every Show Page URL is agent-readable without page-specific code: request the same private or public URL with `Accept: text/markdown` to receive its rendered Markdown representation.
• Author semantic HTML so that representation stays dense and useful: use headings for sections, lists for sequences or groups, and `<table>` for genuinely tabular data.
• Add `data-agent-hidden` to visual-only or sensitive-to-representation elements that should be omitted from Markdown. Add `agent-note="..."` when an element needs short agent-only context; the note text is preserved in the representation.

Show Page annotations & reverse marks

• Users can annotate your Show Page; each annotation arrives as a chat message tagged [show-annotation] with its event id. Some messages end with a ready-to-run reply command — whether to reply on the page or respond by editing the page content is your call, per scenario.
• After reworking a page area you may leave a short callout: `vibe show mark <selector-or-anchor> --message '...'` (same target replaces), or an `agent-note="..."` attribute on elements you author. Marks retire once read — leave at most 1-2 per turn.
• Inspect/withdraw: `vibe show marks` / `vibe show unmark <id|target> ...`; toggle the user's annotation mode: `vibe show annotate --on|--off [--mode smart|screenshot]`.

For live runtime, visibility, and URL availability, treat `vibe show status` and the relevant command output as authoritative.

Vault fetch from server handlers

For credentialed HTTP requests in `api/*.ts`, use the Node-only [server Vault adapter](references/vault-fetch.md) instead of spawning `vibe vault fetch` for every request. It preserves Vault custody and checks; it is never a browser import or a way to publish credentials.

Public server-to-server handlers

For an explicitly published POST endpoint that authenticates a non-browser sender, read [Public server APIs](references/server-api.md) before authoring its `.show-api.json` declaration. Trusted handler code owns sender authentication; the declaration does not publish a page or install/start its Runtime.

Show Page workspace history

These rules apply only to this Session's Show Page workspace and its Avibe history. Avibe manages page checkpoints automatically; do not create versions manually for page edits.

Before operating on history, run `vibe show status`. Use its `path` as `<show-workspace>` and inspect `history.mode`, `history.checkpointing_active`, and `history.git_dir`. Status is read-only; it does not initialize a repository. If checkpointing is inactive, do not assume new edits have automatic checkpoints or start managing Avibe history yourself. Existing history can still be inspected and restored when requested.

When `history.mode` is `managed`:

• Before using `git -C`, check that `git -C <show-workspace> rev-parse --absolute-git-dir`

resolves to `history.git_dir`. If it does not, do not use an enclosing repository or initialize one in its place.

• Read freely with `git -C <show-workspace> status / log / diff / show`.
• Restore files with `git -C <show-workspace> restore --source=<ref> -- <path>`.

When checkpointing is active, Avibe records the restored files in a new forward checkpoint. Do not move HEAD, switch branches, rewrite history, run gc, or commit checkpoints yourself, regardless of checkpoint availability.

• Adding remotes, pushing, or publishing the page requires the user's

corresponding authorization.

When `history.mode` is `self-managed`, the workspace has the user's own Git repository, separate from Avibe's shadow history:

• `git -C <show-workspace>` addresses the user's repository, not Avibe history.

Do not commit or modify that repository to manage Avibe page checkpoints.

• Separately entrusted repository work follows the user's mandate; page

checkpoint rules do not prohibit it.

• Only when the user asks to recover from Avibe history, use the returned

`history.git_dir` as `<shadow-git-dir>` with explicit paths: `git --git-dir=<shadow-git-dir> --work-tree=<show-workspace> log` to inspect, and `git --git-dir=<shadow-git-dir> --work-tree=<show-workspace> restore --source=<ref> -- <path>` to restore files. Do not commit to or otherwise mutate the shadow history.

Guidance:

• New Show Page workspaces are managed React/Vite apps that start as a clean "being generated" placeholder page (what the user sees while you build) plus a minimal file-based router (`src/router.tsx`) and one example page. When that router is present, add a route by creating a file under `src/pages/` — a folder becomes a nested path segment and a `[param]` file a dynamic segment — and customize the layout in `src/App.tsx`, styles in `src/styles.css`, and optional `api/*.ts` handlers. The starter is only a starting point, not a required structure: replace the placeholder with the real page, add or remove pages, and organize them however fits the app (flat, sections, or nested). Built-in UI is available to import, e.g.