Mercury CLI
Documentation

Code

Samples

A sample is a page the model draws and keeps: a design at true size, a report to read, a comparison, or a small interactive page. The model makes one only when asked to see something, never on its own and never to decorate an answer. Each sample is kept per session, versioned, and opens again on request. Samples are off by default.

Sample controls

  • Boot Menu Samples row: Turns samples on for new sessions.
  • MERCURY_SAMPLES=1: Turns samples on when set in the environment before the session starts.
  • /samples: Lists the session's samples, newest first, with the name, v<N>, the state and when it last changed. Enter opens the selected one and Esc returns.
  • mercury.sample({ name, title?, html }): Keeps a page from a Workshop cell. The same name appends a version to the same sample and never makes a second sample.
  • Samples row of mercury doctor and /health: States which way the switch stands.

Enable samples

To enable samples, follow these steps:

  1. Turn on the Boot Menu's Samples row.
  2. Start a new session.

The session has mercury.sample in the Workshop bridge, the loopback listener and the /samples command.

Request a sample

To request a sample, follow these steps:

  1. Ask the model to show the page, mockup or report.

The model draws the page in a Workshop cell and keeps it as a named, versioned sample. The cell's result names each sample it kept, with its title, its version and its address, and the words it answered. The page's data stays in the cell, so a redraw is a small edit and every redraw is the next version of the same sample.

Open a sample

To open a sample, follow these steps:

  1. Enter /samples.
  2. Select a sample.
  3. Press Enter.

The page opens in the browser with the sample's name, its state, a version switcher, the page in a frame that keeps it exactly as the model wrote it, and a foot for a note.

In the full layout, a sample takes a berth in the SESSIONS bar beside its session, showing its mark, its name and its version, and a click opens it. In the compact layout, the line under the composer counts the session's samples, the detail view that line opens lists them, and Enter on one opens it. A new sample or a new version shows up on its own. While the tab is open, the page refreshes as the model redraws: the new version joins the switcher and, when the newest version was on screen, the frame moves to it.

Browser controls

  • Version switcher: Selects a version. ← and → move between versions.
  • Code: Shows the version's HTML read-only.
  • Copy: Puts the HTML on the clipboard.
  • Download: Saves the version as <name>-v<N>.html.
  • ?: Shows the keys.

Send review marks

To send review marks, follow these steps:

  1. Choose Edit with Mercury, or press m.
  2. Click a spot on the page.
  3. Enter the comment in the box that opens.
  4. Press Enter to keep the pin.
  5. Add a note for the whole page in the foot, if wanted.
  6. Choose Approve or Changes needed, if wanted.
  7. Choose Send marks to Mercury, or press s.

Mercury receives the pins, the note and the verdict as one message in the session, as if typed. The model answers it in its next turn, and a message sent while a turn is running waits as any typed message does.

Esc removes a new pin. Pins can be dragged, reopened and removed, and each remembers the element under it: its tag, id, class and first words. The verdict moves the sample's state to approved or changes needed, and a new version opens it again.

Storage and local access

Samples live under the session in the config home, never in the project, at <config-home>/sessions/<session>/samples/<id>/:

  • sample.json: The record: name, title, state and versions.
  • v1.html, v2.html: Each version, the model's HTML as written.
  • marks-v2.json: The marks left on that version.

Nothing is hosted and nothing leaves the machine. A listener on 127.0.0.1 serves the page while the session's process runs, on a port chosen fresh each time. Every address carries a token made once per session process and never written to disk, and a request without it answers 404. The page loads no remote script or font.

A session that cannot open a loopback port writes the page beside the version as a self-contained file, v<N>.page.html, with every version inlined, and opens that instead. Its send button reads Copy for Mercury and puts the same message text on the clipboard for pasting into the composer.

Workshop, Sessions, Using Mercury