Guide

1. Connect the tab

First time here? The QuickStart for Cursor, Codex, Claude Code, and OpenCode walks through connection, a calculator change, generated Why feedback, and saving a local runnable copy.

Open the example as a normal browser page. In a host that supports native WebMCP site tools, enable this page’s tools using that host’s controls. Keep the tab open. Ask the agent to call yichus_examples_list; it should name the examples on this page. Native host setup.

git clone https://github.com/snoble/yichus
cd yichus
pnpm install
pnpm run yichus-mcp:build

{
  "mcpServers": {
    "yichus-browser": {
      "command": "node",
      "args": ["/absolute/path/to/yichus/packages/yichus-mcp/dist/cli.js"]
    }
  }
}

2. Give the agent a concrete change

Start with yichus_development_guide on a development page. Its tool description introduces the engine boundary and the inspect → edit → compare → check workflow; the result supplies the full guidance and reference links. The example guide and the browser workbench’s api_guide also include this guidance.

Engines use existing libraries for execution and integrations; Bosatsu supplies typed calculations, handlers, policies, and effects. Before adding code, have the agent inspect similar implementations and shared definitions. After editing, compare the same structure and check the relevant properties. This can expose a refactor worth making or an interface that makes the feature easier. The argument for this division of work explains both its opportunity and its limits.

Open Work with your agent inside an example’s source drawer for a prompt containing its id. For the event-budget tutorial, you can use:

Call yichus_example_guide, then read exampleId "event_budget".
Add a $50 booking fee to the cost calculation.
Use the source revision you read when updating and running it.
Check the preview: the starting balance should be $150.
Open Why beside the balance and check that it includes the fee.
Tell me what you changed and tested.

Your agent must use the example tools on the tab containing the tutorial. They share its current source buffers. Edits stay in that page; copy or save the files before leaving.

3. Check the feedback together

Preview feedback contains rendered text, control values, page width, chart count, and runtime errors. It is not a screenshot and does not judge whether a diagram looks good. A compilation error hides the previous preview. After a source edit, the agent must compile again before presenting results.

For dependency diagrams, diagramView gives the current view, focused definition, and rendered text. It is absent when the source drawer is closed. Use yichus_page_feedback to find visible buttons and disclosures, then yichus_page_action to expand a package, reveal other checked types, follow a definition, or return to the full map. Shared-type groups show their names directly. Numerical details are under All measurements; the tool result retains the complete artifact. Read feedback again after navigating. These groups describe checked types and dependencies; they do not prove behavior or a permission policy.

Ask the agent to test a normal case and a relevant boundary case, report the actual inputs and outputs, and explain remaining assumptions. A successful compile establishes that the source is accepted. A run shows what happened for those inputs. Neither establishes that a calculator’s model fits the real world.

On the API workbench, open a verified app with yichus_app_open, read yichus_app_views, then use yichus_app_act to select a view, fill its controls and submit visibly. Start with the view’s example arguments and replace the values. Read yichus_app_feedback for the selected view, displayed identity, current inputs, pending state and rendered result or error. Standalone generated apps expose the same tools with their app name as a prefix. A later edit or action supersedes pending display feedback; it does not undo an already dispatched server mutation.

yichus_app_call makes a headless request. It leaves the visible form, selected user and rendered result unchanged. Use it for independent API requests; use yichus_app_act when the user should see the interaction. Feedback excludes bearer tokens.

yichus_page_feedback reads the surrounding page’s visible text, source editors, status messages, and accessible embedded views. Embedded feedback includes rendered text and controls, with explicit limits on nesting, frame count, text and controls; inaccessible or truncated contents are labeled. On the standalone editor, Explorer, API workbench, and spec demo, use it to check the page after a tool call or an accepted suggestion. It also returns a short development orientation, the guide tool’s name, and a link to these instructions.

On those standalone pages, yichus_page_edit replaces an editable text area only if its full current text matches expectedSource. Use the editor id and source from feedback. yichus_page_action activates a visible button or disclosure by its listed id. The button may start asynchronous work: read feedback again for its status and diagnostics. Use the dedicated example tools for source drawers and their sandboxed previews.

Other editing surfaces

• Calculator editor: the yichus_playground_* tools read and replace its two files, compile, and inspect output. Its Agent reference tab documents the workflow.
• API workbench: start with api_guide. The api_* tools accept sources and return analysis; map, stack, and evaluation calls also update the page. yichus_app_* tools let you share a generated app. Workbench instructions.
• Explorer playground and the state-machine spec demo: their yichus_autocomplete_* tools provide revision-checked suggestions. The user accepts a suggestion with Tab, then runs the page’s analysis. For a complete agent edit/run loop, use the page edit/action/feedback tools. The completion tools themselves do not run a checker. Explorer clears its results when the source changes or is reset. The chosen binding is restored after reanalysis if it still exists. Reset restores the last successfully loaded sample; a pending replacement cannot erase that reset buffer. After a failed first load, Analyze retries the sample from an empty editor or checks the replacement source you entered. Its worker runs compilation and navigation asynchronously: after Analyze, read feedback until “Analysis complete” or an error appears. Failed or cancelled analysis cannot supply the previous program’s results.
• The game, counter, particle, and drag demos expose their shipped sources and runnable programs. Their source drawers are read-only; changes currently require a local build.

Source and results pass to the connected agent through your browser host or local relay. Compilation happens in your browser; Yichus does not send source to a hosted compiler.

Make a calculator → · Repair a program →