A product architecture explainer

OpenUI renders the interface. Snappy OS makes it real.

The OpenUI docs describe a powerful generative UI loop. We keep that loop intact—then add a connector data plane, SQLite mirrors, an HTML-first creative canvas, governed capability execution, durability, and an AI-native operating surface. This is the open-kimono account of both the system and the failure-driven method that produced it.

The short version: Printing Press grounds the model in real source data; HTML/CSS authors the visual composition; OpenUI Lang becomes React components, state, queries, mutations, and actions; Snappy governs the entire object from permission through persistence and proof.

See the architecture See how it was made

Three-layer infographic showing real sources grounding an HTML and OpenLang binding layer, then a governed object shared by a human and an AI with proof above it. — One causal thread: ground the claim, bind the behavior, prove the outcome.

Library

Components, schemas, renderers, and action contracts define the vocabulary.

Prompt

The library becomes model-readable instructions and tool definitions.

LLM

The model chooses and composes an interface for the user’s intent.

Lang stream

A compact, declarative OpenUI Lang program arrives progressively.

Parser

The program becomes a validated, typed element tree.

Renderer

Registered React components become the live interface.

Where Snappy stays deliberately native

OpenUI Lang createLibrary Renderer toolProvider Query / Mutation AgentInterface AssistantMessage + toolCalls Artifact preview + panel defineArtifactRenderer Progressive parsing

OpenUI also explicitly documents forward references for progressive rendering[3], and component/state/data as distinct Lang statement types.[4] That separation is the foundation Snappy extends rather than replaces.

02 / The connector data road

RunConnectorCommand grounds the UI before the UI exists.

RunConnectorCommand is Snappy’s one resident road for reading a connected external source. The model passes a connector slug and the user’s natural-language request once. Printing Press resolves and completes the read internally, then returns bounded rows plus the exact contracts the generative UI must bind. A blended ask uses one call per source—often concurrently—then one model judgment and one composed surface.

Infographic showing a natural-language request crossing RunConnectorCommand, a Printing Press connector choosing a live API or SQLite mirror, and emitting bounded rows plus Query and Mutation contracts into a generated surface. — **One parent call, two grounding moments.**Rows inform model judgment; the registered Query handle keeps the rendered surface live.

01 / INTENT

User asks naturally

“Show my important unread email before tomorrow’s meetings.”

02 / RESIDENT TOOL

RunConnectorCommand

The exact request enters one selected connected source. This tool is read-only.

03 / PRINTING PRESS

Focused read loop

Direct exact reads skip the inner model. Complex asks can fan out list → detail in one bounded internal loop.

04 / SOURCE

Live API or SQLite mirror

Printing Press chooses the honest serving road. SELECT-only SQL can answer compound local questions in one call.

05 / CONTRACT

Rows + exact handles

The result includes operation-scoped rows, columns, query bindings, mutation contracts, source state, and a ledger.

06 / GENERATIVE UI

ComposeUI

The model synthesizes the answer and authors HTML/OpenUI Lang against those exact fields and handles.

07 / RUNTIME

Reactive surface

The Renderer’s toolProvider resolves Query and Mutation calls through the governed provider registry.

Moment A · composition-time grounding

The model sees real rows and real shape.

RunConnectorCommand gives the outer model enough bounded source truth to judge what matters, reconcile sources, choose fields, and design the answer. Internal list/detail operations stay inside the connector road instead of bloating the parent chat with tool-call choreography.

Moment B · render-time binding

The surface rebinds the source, not a pasted snapshot.

Query("exact_handle", exact_args) inside the emitted Lang points the Renderer back to the registered provider and mirror. That is what lets a saved surface reopen, refresh, and remain queryable rather than becoming decorative JSON frozen into cards.

The local data plane

SQLite mirrors make connected data feel native.

Printing Press connectors can maintain a user-local SQLite mirror. The mirror gives Snappy a low-latency, structured source for reads, search, counts, filters, joins, and offline-aware state—without forcing every repaint to wait on a remote API.

The important distinction is honesty: local rows carry sync age and source state. If a live request fails authentication, cached rows are stale evidence, not a fake fresh success.

query_contracts[] query_binding served_reads[] registered_mutation_contracts[] operation_ledger[] mirror_snapshot

Mirror-first when the user schedules sync Reads return from local SQLite immediately; a debounced background sync can refresh the source without blocking the answer.

Auto/live when freshness requires it Without mirror-first opt-in, Printing Press retains ownership of the live-versus-local decision and records the actual execution source.

sql for compound local questions When the generated connector exposes it, a SELECT-only SQL verb can answer counts, filters, aggregations, and joins over the mirror in one read.

Generated contracts, never hand-written recipes The connector’s manifest and registered provider identity mint the query/mutation road. Table names and CLI stdout remain implementation material, not product vocabulary.

The deeper Printing Press idea is not “generate an API wrapper.” Before Snappy ever calls the connector, the press researches the API and competing tools, requires a one-sentence Non-Obvious Insight about the source’s hidden value, absorbs the useful ecosystem features, then generates a shared Go client, CLI, MCP server, domain-specific SQLite schema, compound commands, compact agent output, typed exits, and verification proofs. The full endpoint surface supplies breadth; the local data model and compound commands supply depth. Snappy consumes the resulting semantic capabilities instead of rebuilding connector intelligence in the app.[PP1]

Discover the source’s secret identity

“Discord is institutional memory,” “Stripe is business health,” “Linear is a team-behavior observatory.” The connector’s product thesis is a required compilation input, not launch copy.

Absorb, then transcend

Catalog what existing CLIs, skills, and MCP servers already do; match the useful parts; then use local relational history to create compound questions a stateless wrapper cannot answer.

Emit for agents, not API tourists

Auto-JSON when piped, --compact, dry-run, typed exit codes, search, SQL, and bounded output make the generated capability cheap and recoverable under repeated model use.

03 / HTML + OpenLang

HTML paints. OpenUI behaves. React makes it real.

Your instinct is right: this is one of the clearest departures from the docs. The OpenUI documentation we reviewed centers registered component libraries as the visual vocabulary.[5] Snappy reverses the emphasis for ambitious surfaces: one authored HTML/CSS canvas owns art direction, while OpenUI Lang supplies live data, state, registered React components, and governed actions.

Infographic showing an expressive HTML and CSS canvas interlocking with an OpenLang capability spine for Query, State, Mutation, and Action, with React components portaled between them. — **The role inversion.**HTML/CSS carries art direction; OpenLang carries data, state, capability, and registered React behavior.

OpenUI docs emphasize

Compose the interface from registered components.

The library defines the visual and behavioral vocabulary. The model emits component calls, and defineComponent maps Lang nodes to React components with validated props.[6] The official material does not present Snappy’s one-HTML-canvas + React-portal mount pattern.

Snappy OS adds

Use HTML/CSS as the creative shell; mount capability inside it.

Html and HtmlMount are Snappy-defined OpenUI components. HTML gets full layout and visual freedom. The component kit becomes interactive atoms, specialized capabilities, and the quick-answer path.

The surface is a layered runtime, not “just HTML.”

5 · HTML + CSS creative canvas Responsive layout, typography, imagery, spatial rhythm, transitions, and art direction.

4 · HtmlMount → React portals Real OpenUI controls are mounted into named data-openui-mount slots inside the HTML.

3 · OpenUI Lang typed tree The parser resolves component calls, forward references, expressions, state, Query, Mutation, and Action nodes.

2 · OpenUI Renderer + React state Registered components become React elements; $state and actions become reactive runtime behavior.

1 · toolProvider + Snappy governance Query reads, Mutation staging, grants, approvals, source contracts, mirrors, and receipts execute below the visual layer.

SIMPLIFIED COMPOSITION SHAPEHTML + OPENUI LANG

// Local reactive state
$search = ""

// HTML owns the complete visual composition
root = Html("<style>...responsive art direction...</style>
  <main class='inbox'>
    <header><h1>Priority inbox</h1></header>
    <section>{{#each items}}...{{subject}}...{{/each}}</section>
    <aside data-openui-mount='controls'></aside>
  </main>", {items: filtered}, [controls])

// Query supplies live data through toolProvider
mail = Query("gmail_messages", {limit: 20}, {rows: []})
filtered = @Filter(mail.rows, "subject", "contains", $search)
lead = @First(filtered)

// Mutation declares a governed capability; it is inert here
archive = Mutation("gmail_messages_modify", {id: lead.id,
  userId: "me", "remove-label-ids": ["INBOX"]})

// Real React/OpenUI controls mount inside the HTML slot
search = FormControl("Search", Input("search", "Filter inbox...",
  "text", null, $search))
stage = Button("Stage archive", Action([@Run(archive)]), "primary")
controls = HtmlMount("controls", [search, stage])

Query()

Calls a registered read handle and exposes reactive result fields to the program.

$state

Holds local, user-editable state for inputs, selections, filters, and view controls.

Mutation()

Declares a potential write against an exact registered capability; declaration alone does nothing.

Action()

Composes gesture-time operations such as @Run, @Set, @Reset, and query refresh.[7]

HtmlMount()

Places the real registered React component tree into a named slot in the authored HTML.

So is OpenUI Lang shorthand for JavaScript or React? Functionally, yes: it is a compact declarative program that the OpenUI parser and Renderer interpret into React components, state, and asynchronous tool behavior. Technically, it is not source-to-source compilation into a JavaScript file. In Snappy, arbitrary scripts are forbidden inside the HTML canvas; capability behavior must travel through OpenUI’s typed runtime and Snappy’s governed provider roads.

Concentric architecture infographic with the OpenUI core surrounded by source truth and mirrors, AI SDK harness and progressive tool disclosure, governance and approvals, durable artifacts, and activity receipts. — **Extension, not replacement.**The OpenUI core sits inside a larger source, authority, lifecycle, and proof architecture.

OpenUI reference stackSDK scope

App-defined toolsThe host supplies schemas and execution.

Generated promptLibrary + tools teach the model.

Model emits LangThe interface is composed for the request.

Parser + RendererThe shared OpenUI core.

Live UIThe host decides the surrounding lifecycle.

same renderer core

Snappy OS product stackOperating-system scope

One AI SDK harnessGreetings, analysis, connector work, and visual apps enter the same model-owned loop.

Lean resident core + ToolSearchThe model sees five essential tools, then pulls exact long-tail schemas only when needed.

Printing Press → source handlesGenerated connectors resolve user intent to real, registered Query() and Mutation() identities.

ComposeUI boundaryLang, placement, artifact identity, durability, and allowed actions enter as one typed tool call.

Product preflightSource match, served fields, component contracts, action wiring, grants, and approvals are checked before the UI is accepted.

OpenUI Parser + RendererOpenUI still owns parsing, progressive rendering, state, and correction feedback.

Artifact + state + receiptThe surface can remain inline or become a durable, reopenable, versioned Live App with provenance and paint truth.

The practical formula

OpenUI plus enforceable product laws.

OpenUI gives us a safe, model-native way to describe and render interfaces. Snappy adds the laws that make those interfaces trustworthy enough to become the product itself.

OpenUI = Library → Lang → Renderer
Snappy OS = Intent → Truth → Policy → OpenUI → Lifecycle → Proof

LAYER 01

One front door, no special-case lanes

Every request enters the same AI SDK harness. A greeting and a database dashboard differ by the handles disclosed—not by a hidden shortcut, regex lane, or canned renderer.

model-owned orchestration

LAYER 02

RunConnectorCommand grounds, then Query keeps it live

One resident read road resolves the natural-language ask, returns real rows for model judgment, and attaches the exact registered handle the generated surface must bind at render time.

source-attested UI

LAYER 03

Reads and writes are different roads

Queries can read only available, granted sources. Mutations remain inert until a real control fires them—and AI-requested external effects stage typed approval objects instead of silently executing.

governed capability execution

LAYER 04

HTML authors the canvas; OpenUI authors behavior

ComposeUI carries one HTML-first Lang program. CSS owns art direction; Query, state, Mutation, Action, and mounted React components supply the live functionality.

one render exit

LAYER 05

Validation checks meaning, not only syntax

Beyond parser validity, Snappy blocks phantom providers, unreachable handles, invented fields, dead mutations, fake data defaults, empty sections, static data dumps, and source-binding drift.

semantic preflight

LAYER 06

A generated surface can become software

A stable artifact identity makes the UI reopenable and versioned. Follow-up turns patch the same object instead of creating duplicates; query bindings remain live across refresh and re-entry.

durable Live Apps

LAYER 07

The product is usable by other AIs

A small semantic AI-for-AI surface exposes asks, grants, staged actions, approvals, artifacts, activity, and rendering. A generated whole-route MCP wrapper separately forces every side door to be classified and governed.

curated API + forcing function

LAYER 08

Success is a proven state

Prose cannot claim data loaded, an action ran, or a surface rendered unless the underlying state proves it. Live, cached, stale, empty, error, and auth-expired are explicit product states—not vibes.

truthful outcomes + receipts

Circular foundry infographic showing voice, conversations, screenshots, traces, and audits passing through preserve, mine, name the lie, find the owner, teach, enforce, prove, and delete stages to become a typed product boundary. — **The failure-to-law foundry.**Preserve raw signal; compile repeated failure into one owned boundary; prove the cold path; delete the superseded road.

This account is longitudinal, not repo-local. A home-wide inventory cataloged 202 Git worktrees before attribution filtering. The deep audit followed Robert-authored product lineages—Snappy OS, multiple generations of Snappy/Xano MCP, the builder kernel and Mini experiment, agent studios, content systems, eval harnesses, prompt optimization, and autonomous verification loops—while keeping obvious forks and third-party reference repos in a separate evidence class. The point is not the raw repo count; it is seeing which ideas survived years of rewrites.

2machines of Claude and Codex conversations, mined together so context could not disappear across environments

44voice dictations—high-information founder language preserved as requirements, not polished away into generic product prose

75dated audit, handoff, and demands documents folded into the canonical specification and defect index

32 MBof agent-to-agent mail mined alongside human conversations, with an explicit list of what remained unmined

01 / PRESERVE

Keep the raw signal.

Emotional language was treated as compressed acceptance criteria: “undeniable,” “5 seconds useful,” “deliver then approve,” “never make me explain it again.”

02 / MINE

Build a canonical memory.

Conversations, dictations, audits, and machine lanes became one source-ranked spec plus an explicit unmined ledger—so summaries could not quietly shrink the goal.[M1]

03 / NAME THE LIE

Turn each failure into a law.

“Cached data masqueraded as fresh,” “surface emitted but never painted,” and “mutation timed out after dispatch” became different typed states—not one generic error.

04 / FIND THE OWNER

Put the law at one boundary.

Credential truth belongs to the connector gate. Source identity belongs to the binding contract. Approval belongs to execution. Paint belongs to the client receipt.

05 / TEACH

Prompt at the decision moment.

Use prompt language for taste, strategy, and recovery. Put decisive guidance in the tool description the model sees when it must choose—not in a distant hint tail.

06 / ENFORCE

Compile dangerous prose into code.

If disobedience can create a lie, leak, or side effect, the instruction graduates into schemas, enums, state machines, provider gates, lints, or receipts.

07 / PROVE

Drive the cold path.

Test arbitrary human phrasing, the installed app, the actual runtime owner, live connector state, renderer paint, and a separate audit—not a curated prompt or same-session toast.

08 / DELETE

Remove the superseded road.

Once the SDK-native path works, delete sentinels, regex lanes, static connector tables, fallback surfaces, duplicate prompt catalogs, and legacy render exits.

Prompts as runtime architecture

The prompt is compiled, budgeted, cached, and audited.

There is no single magical system prompt. The runtime assembles a byte-stable head, a live variable tail, deferred skill loaders, typed result memory, and native tool schemas. The OpenUI grammar, component schema, and runtime catalog are generated from the same canonical library—without a hand-maintained second language.[M2]

Byte-stable headIdentity, harness law, OpenUI grammar, resident capability substrate; cacheable across turns.

Live truth tailTime, connector readiness, internal provider map, active object, workspace, approval state—rebuilt every turn.

Skill routingSmall AGENTS loader chooses the domain; the canonical SKILL body is fetched lazily, with a digest marker that survives truncation.

Five resident toolsAskUserQuestion, ToolSearch, ListComponents, RunConnectorCommand, and ComposeUI. The long tail stays deferred.

Typed tool memoryStatus, kind, error code, error path, and sanitized untrusted output give the model a recovery state instead of an opaque transcript.

Decision-local salienceHTML-first composition lives in ComposeUI’s description because that is where the model commits to a visual strategy.

Why the HTML instruction initially failed

The model still saw a 19.6k “phone book” of familiar component signatures. A late hint could not defeat that resident habit. The fix was not more adjectives; it was shrinking disclosure and moving the HTML-first law into ComposeUI’s highest-salience description.[M3]

Why prompts do not own policy

Prompt prose once contradicted the actual mutation gate, and the model repeated the prose instead of testing the tool. The runtime now treats the typed tool result as truth; prompt text explains how to recover.

Why prompt accounting is a feature

Prompt owners, token ceilings, cache placement, resident schemas, tool output caps, and reasoning effort were measured after real regressions—not tuned as abstract “context engineering.”

Why activation became infrastructure

Earlier Claude Code work found that good skills remained inert when the model had to remember to load them. Prompt-submit hooks, file context, rules, passive indexes, and later ToolSearch turned retrieval from a memory test into an environmental affordance.[M4]

Why “real” is a first-class label

The suggestion-engine harness explicitly separates live, sample, built-but-unrouted, migration-target, and honest-stub states. That same discipline now shapes Snappy’s connected, stale, empty, approval-pending, outcome-unknown, and painted verdicts.[M5]

Why raw volume stopped counting as evidence

Prompt-optimization work found 527 traces could collapse to roughly 12 unique inputs; optimizer choice and judge quality had to follow information diversity, not event count. The same law bounds connector rows and treats relevance × structure as the useful context budget.[M6]

Why attention became mutable state

The Charlotte/Cyborg line did not solve retrieval by stuffing in more memory. It modeled a current goal, suppression and boost signals, access history, salience, and nightly decay in local durable state. Context became an attention policy that changes with the task.[M9]

Why trusted context overwrites model IDs

In the companion-agent runtime, the model chooses the semantic action, but the boundary injects authoritative companion, user, post, comment, group, scene, and lineage IDs from session context—replacing hallucinated or mismatched arguments. Judgment belongs to the model; identity belongs to the runtime.[M10]

Why visual quality is a weakest-link gate

The Content Engine’s visual QC scores logic, composition, style, text, artifact cleanliness, and two-second concept relevance, then makes overall quality the minimum dimension—not the average. One fatal weakness cannot hide behind five pretty scores. Its preservation mode also learned when to judge the voice without rewriting it.[M11]

Deleted idea

Pins as quality exemplars

Rejected because curation hid a weak generator. Delight must be the default behavior of the generative road, not a hand-picked retrieval lane.

Reverted gate

Hard-blocking every unbound mockup

The strict rule over-constrained valid static creative work. It was demoted to advisory while factual data remains bind-or-omit.

Deleted detector

Labeling fabricated data after the fact

“Marking it fake” was recognized as hiding the failure. The source-binding and served-field boundary must prevent the fabricated claim.

Deleted path

Regex intent lanes and canned fast paths

They made demos look smart while arbitrary language failed. One model-owned harness and machine metadata replaced request-string routing.

Deleted duplicate

Sentinel plus surface-only message

It created two render/persist owners and lost prose on reload. One assistant message now owns both prose and its ComposeUI tool part.

Measured correction

High reasoning by default

It burned invisible tokens and time on compact OpenLang. “Auto” moved to low effort; explicit operator choice still wins.

Multi-year reversal

Every tool resident in every turn

The MCP lineage moved from more than 100 resident tools, through mode and slug filters, to 182 definitions extracted behind progressive discovery, and finally to five resident product concepts plus ToolSearch. Context became an operating budget, not a catalog shelf.[M7]

Autonomy correction

Agent activity as progress

Ralph-style loops kept branch tip equal to the best-known state: attempt, build, drive the real story, keep on proof, revert on failure, and preserve the evidence ledger. Motion without a retained, audited improvement stopped counting.[M8]

Golden chain infographic connecting source, handle, surface, authority, object, and receipt, with mirror, HTML, approval, versioning, human and AI, filesystem, and evaluation symbols around it. — **The causal chain is the invention.**The surrounding technologies matter because the links preserve one claim from source through visible effect.

N·01

Two-time grounding

Bounded rows ground model judgment at composition time; the exact registered Query() handle re-executes at render time. A causal contract proves those are the same operation, arguments, source, and fields.

N·02

Natural language → executable connector contract

RunConnectorCommand accepts the user’s request once. Printing Press may execute directly, fan out list-to-detail, or run declared SELECT-only SQL, then returns operation-scoped rows plus the exact read and write contracts ComposeUI can use.

N·03

HTML/OpenLang role inversion

Instead of asking the component kit to carry all visual expression, one authored HTML/CSS canvas owns art direction. OpenUI Lang becomes the capability spine: data, state, mutations, actions, and registered React behavior.

N·04

Governed portals

HtmlMount portals registered OpenLang children into named positions inside the canvas. The model gets arbitrary composition without gaining a second JavaScript or tool runtime.

N·05

Operation-scoped capability receipts

Multi-operation reads do not collapse into a union of rows and handles. Each executed operation retains its arguments, served fields, source identity, query handle, and eligible mutation contracts.

N·06

Mirrors as temporal source truth

SQLite is not treated as a generic cache. The mirror carries schema, product-row versus plumbing-row identity, sync state, credential state, freshness, and an explicit live/local serving decision.

N·07

Visible synthesis as a graph constraint

A multi-source surface must visibly connect the sources in its answer. Parallel raw tables do not satisfy synthesis; the binding contract checks that the rendered structure actually reconciles them.

N·08

Declaration separated from effect

A Lang Mutation() only declares capability. @Run stages at gesture time; policy resolves authority; a human-plane approval may execute; a fresh read verifies. Timeouts after dispatch become execution_outcome_unknown, never blind retries.

N·09

Generated UI as a durable object

The same surface can remain ephemeral or acquire artifact identity, version lineage, exact bindings, refresh behavior, and incremental in-place edits. It becomes software state, not a screenshot inside a transcript.

N·10

Loop stop ≠ product success

Validated, emitted, painted, hydrated, persisted, approved, executed, and verified are separate epistemic states. The model can stop when a surface reaches the wire without the product falsely calling it painted.

N·11

Curated AI surface + mechanical x-ray

External AIs receive a small semantic MCP product surface. Separately, a generated one-to-one route wrapper forces every local HTTP door to declare object, action, grant, mode, receipt, and result typing before it can hide.

N·12

The prompt stack as a governed compiler

The component library generates grammar, schemas, and catalogs; runtime disclosure is budgeted; live truth is separated from cacheable law; skills are lazy; result memory is typed. Prompt behavior and executable boundaries are designed together.

N·13

Compilers all the way down

Printing Press compiles APIs or observed traffic into capabilities. OpenUI compiles a component library into model grammar and Lang into React. Snappy compiles lived failures into typed laws, gates, state machines, and receipts. The product is a stack of truth-preserving compilation boundaries.

N·14

Capability maturity as filesystem state

In the builder kernel, a skill progresses from mentionable to callable, drillable, scriptable, cronable, and measurable by adding inspectable files—not editing a central router. The filesystem is both declaration and reflection.[K1]

N·15

Effect proof and quality proof are orthogonal

A certificate answers “did the effect happen?” An eval answers “is the result any good?” The historical Snappy Mini experiment made every verb declare an eval and caught quality defects that exit-code success and self-reporting had missed.[K2]

N·16

Human-owned program, agent-owned state

Another builder experiment split immutable human intent and sources from agent-rewritable verbs, libraries, logs, and learned state. The AI becomes the CPU for a portable program that can self-bootstrap across harnesses instead of depending on one vendor runtime.

Adapted honestly, not rebranded.

OpenUI still owns Lang, parsing, progressive rendering, actions/state, Query()/Mutation(), and the artifact preview/panel model. Vercel AI SDK owns the provider-neutral tool loop and stream parts. React owns the component runtime and portals. MCP supplies the protocol. SQLite supplies the local relational store. Snappy’s invention is the product contract that joins them—and the refusal to add a second implementation path when an upstream primitive already owns the job.

Infographic showing rough failures such as stale state, duplicate output, timeout, and context bloat entering typed mechanical dies and emerging as locks, state machines, bounded packets, and receipts. — **Failure becomes architecture only after it acquires an owner.**Prompts teach; schemas, gates, state machines, and receipts make the dangerous cases impossible or explicit.

Law 01 · Ground twice

The model needs rows now and handles later.

Rows at composition time let the model inspect fields, reconcile sources, and make judgment. Exact Query() bindings at render time let the surface refresh and reopen. Rows without handles create a frozen paste; handles without rows force blind composition.

General lesson: Separate model grounding from runtime binding, then causally attest that they describe the same read.[S1]

Law 02 · Prompts are not policy

Teach behavior in prompts; enforce truth at boundaries.

Models ignored “never read an unconnected source,” advertised dead mutations, and invented fallback data even when the prompt was explicit. Credential readiness, registered-provider reachability, served fields, and approval requirements now refuse mechanically.

General lesson: If violating an instruction creates a lie or side effect, convert the instruction into a typed boundary check.[S2]

Law 03 · One turn, one surface owner

Never invent a parallel render or persistence path.

A text sentinel plus a separate surface-only message rendered one tool result twice; reload then kept the surface and lost the prose. The correct OpenUI model is one assistant message: prose in content, surface in toolCalls, rendered once beneath that message.[8]

General lesson: Framework-native state should have one author and one durable identity.[S3]

Law 04 · Durability is identity

“Save this” is not enough; updates need an exact object.

A durable generated app needs a canonical artifact ID, stable app identity, version lineage, and patch semantics. Follow-ups must modify the active object, not mint a same-title sibling or regenerate the whole Lang program.

General lesson: Durable GenUI is object versioning, not transcript persistence.[S4]

Law 05 · Fast data must still declare time

A SQLite mirror is only useful if staleness is visible.

Local data makes generative surfaces feel immediate, but a cached row beside a dead credential can look “live” unless source state is explicit. Every surface needs one honest state: live, cached, stale, empty, error, or auth-expired.

General lesson: Latency optimization without freshness semantics is a truth regression.[S5]

Law 06 · Terminal truth needs one ledger

The stop condition and the success grader must read the same events.

Two detectors looking at different step-result paths graded composed, persisted surfaces as empty output. Snappy now derives terminal-surface truth from the same completed tool results the AI SDK stop condition sees.

General lesson: Never let orchestration completion and product success observe different realities.[S6]

Law 07 · Creative freedom, capability restraint

HTML gets visual freedom precisely because script is forbidden.

Arbitrary script inside a generated canvas would create a second, ungoverned tool and state runtime. Snappy permits HTML/CSS art direction, escapes bound data, paint-contains the surface, and mounts only registered React/OpenUI capabilities through HtmlMount.

General lesson: Give the model freedom in representation, not in authority.[S7]

Law 08 · Compare the real app turn

When probes pass and the UI fails, suspect a context split.

The live connector/provider map once disappeared only for profile-carrying turns—the exact shape the app sent—while curl probes saw the full context. The model looked “dumb,” but prompt assembly had split reality.

General lesson: Instrument prompt blocks and tool disclosure on the production request shape, not a convenient probe.[S8]

Law 09 · Never union causality

Multi-command results need operation-scoped contracts.

If list, detail, and aggregate reads are flattened into one row bag with one handle bag, the composer can bind a field to a broader or different query than the one that produced it. Each operation must retain its own args, rows, served fields, and handle.

General lesson: Preserve provenance at the granularity where execution happened.[S9]

Law 10 · Timeout is not rollback

A write can succeed after the caller loses the response.

Retrying an external mutation after a network timeout can duplicate the effect. Snappy distinguishes pre-dispatch failure from post-dispatch uncertainty, stamps execution_outcome_unknown, disables blind retry, and seeks an independent verification read.

General lesson: Model uncertainty about the effect itself; “exception” is a transport fact, not business-state truth.[S10]

Law 11 · Static is not unpainted

Not every successful surface owes a data paint receipt.

Decks, reports, and static visual artifacts were incorrectly sentenced to timeouts because the success grader demanded a query-settlement acknowledgement that could never exist. Artifact identity or a no-paint-required verdict is the right proof for that class.

General lesson: Define proof obligations by effect class, not one universal success boolean.[S11]

Law 12 · Keep context bounded

Complete data can still destroy the parent loop.

Four source results around 60k characters exhausted the provider input budget after the surface had already rendered. Connector output is now bounded and compacted after preserving full internal truth; the outer model receives enough rows to judge, not every byte the source can produce.

General lesson: Observation quality is relevance × structure, not raw volume.[S12]

Law 13 · Disclosure is a retrieval problem

A giant tool catalog makes a capable model less capable.

The MCP family first exposed more than 100 tools, then tried modes and slug filters, then extracted 182 definitions behind search. The surviving design is a tiny semantic resident core with exact schemas pulled on demand.

General lesson: Make the correct capability discoverable at decision time; do not make every capability resident all the time.[S13]

Law 14 · Count information, not events

Hundreds of traces can still be a tiny dataset.

A prompt optimizer saw 527 EmailResponder traces collapse to roughly 12 unique inputs after deduplication. Optimizer choice, judge quality, and confidence had to be based on diversity and rich context—not row count.

General lesson: Before optimizing an AI system, measure unique situations and comparable metrics; duplicated telemetry creates false confidence.[S14]

Law 15 · An effect receipt is not a quality verdict

“It ran” and “it was good” require different evidence.

The Mini experiment separated certificates from evals: one proves the action occurred, the other independently judges the result. Its content eval caught planted defects that exit codes and the actor’s self-report missed.

General lesson: Give every consequential verb both an effect proof and a quality proof, with a different actor and auditor.[S15]

Law 16 · Autonomy advances by retained proof

The best-known state matters more than an agent’s effort.

Autonomous browser loops attempted one story, built, drove the real path, retained the commit only on proof, and reverted failed attempts while preserving the audit ledger. Reversibility let the loop be aggressive without quietly degrading the branch.

General lesson: Design long-running agents as monotonic evidence systems: explore freely, but promote state only after an independent gate.[S16]

08 / Firsthand MCP proof

Another AI used the product—not a private implementation path.

On July 19, 2026, Codex entered through the public snappy-render MCP surface as caller claude-code. It discovered capabilities, read CoinGecko through the connector road, inspected the SQLite mirror, requested OpenUI composition, opened the Activity spine, and rendered a packaged-app screenshot. The result confirmed the architecture and exposed several contracts that still need tightening.

Discover

snappy_list_connectors returned four readable mirrors. CoinGecko was hydrated with 37,650 rows, 12 tables, and exact registered query handles—before any data request was attempted.

Ask

A plain-English request resolved to Printing Press command coins markets, returned five served rows in about five seconds, and stamped Query("coingecko_coins", …) plus the exact arguments and fields.

Mirror

The low-level proof read five rows in about one second from local table coins at ~/.local/share/coingecko-pp-cli/data.db, which contained 18,772 rows.

Compose

The one-call snappy_ask(render:true) timed out at the MCP client, yet Activity later recorded “allowed, 5 rows, with generated UI.” The server completed after the transport had given up.

Paint

snappy_render_proof produced a 121,427-byte screenshot from the installed app bundle. The app chrome and provenance rendered; the data canvas exposed a separate freshness problem.

Observed truth 01 · A handle is not a paint proof

The durable surface was bound—and still showed old fallback values.

The inspected CoinGecko artifact declared a live query, but after five seconds it still showed $62,500 Bitcoin and $1,200B market cap while the connector had just served roughly $64,664 and $1,297B. A loading spinner remained visible.

Transferable lesson: Validate composition, binding, provider resolution, first paint, freshness, and fallback provenance as separate stages. “Contains Query()” proves only one of them.

Observed truth 02 · The ledger can outlive the caller

Client timeout and server outcome are different facts.

The combined ask reported an aborted operation to the calling AI, but the Activity spine later showed that the governed read and generated UI completed. The standalone render, by contrast, landed an explicit failed receipt and no artifact.

Transferable lesson: Long-running AI tools need durable request IDs, resumable status reads, and idempotent retrieval. A transport exception must never be treated as authoritative execution state.

Observed truth 03 · Product state must agree with itself

The capability report contradicted its own mirror diagnosis.

The same response described CoinGecko as hydrated, fresh, and credential_missing:false, then marked it not AI-operable because “no credential” was present—even though the governed read succeeded immediately.

Transferable lesson: Health, readiness, credentials, grants, and operability must derive from one canonical state projection. An AI cannot safely plan from mutually incompatible booleans.

Observed truth 04 · Least privilege includes responses

A permitted read should return the decision grant, not the whole grant universe.

The mirror query was correctly allowed by a CoinGecko read grant, but its envelope also exposed unrelated grants for Gmail, Calendar, scripts, skills, and artifacts. Enforcement was scoped; disclosure was broader than the task required.

Transferable lesson: Apply least privilege to context and receipts as well as execution. Return the winning grant and relevant lineage; keep unrelated authority out of model-visible payloads.

Why include the rough edges? Because this is the difference between an architecture diagram and an operating system for agents. The product already makes failures inspectable through typed tools, envelopes, artifacts, and Activity. The next level is ensuring those truth surfaces converge—so the calling AI can recover without guessing and the rendered UI cannot silently look fresher than its data.

Nested comparison infographic showing the OpenUI grammar, parser, renderer, and action core installed inside the broader Snappy OS lifecycle of source grounding, connector execution, approval, durability, AI access, and proof. — **Not OpenUI versus Snappy OS.**OpenUI is the inherited generative rendering core; Snappy turns the host responsibilities around it into product law.

Dimension	OpenUI docs	Snappy OS
Primary unit	A generated interfaceA Lang program rendered by a registered library.	A governed UI objectA Lang program plus source identity, authority, lifecycle, state, and receipts.
Model path	The host calls a modelThe generated prompt teaches components and tools.	One provider-neutral AI SDK harnessThe SDK owns the tool loop, streaming parts, stop conditions, and terminal truth for every turn.
Tool disclosure	Tools are included in the generated promptThe app chooses the practical size and shape.	Five resident tools + ToolSearch cascadeA lean always-visible core; exact long-tail schemas are retrieved only when the model needs them.
Connector grounding	The host supplies tool resultsOpenUI starts once the application has defined the relevant tools and data road.	`RunConnectorCommand` owns the readThe user’s request enters a generated Printing Press skill unchanged; direct reads, list/detail fan-out, or SELECT-only SQL finish behind one parent tool call.
Data access	Function map or MCP client`toolProvider` resolves `Query()` and `Mutation()`.[2]	Printing Press → registered handlesGenerated connectors, local source mirrors, live readiness, exact arguments, and a dynamic provider registry feed that same `toolProvider`.
Local data plane	Application-specificOpenUI does not prescribe a connector cache or mirror architecture.	User-local SQLite mirrorsScheduled mirror-first reads, auto/live fallback, freshness state, and optional SELECT-only SQL make connected data fast without pretending cached means live.
Creative canvas	Registered component libraryModels compose the visual vocabulary assembled with `defineComponent` and `createLibrary`.[6]	One HTML/CSS canvas for ambitious surfacesSnappy’s custom `Html` component owns art direction; `HtmlMount` portals real React/OpenUI capabilities into named slots.
Composition	The model emits OpenUI LangThe renderer consumes the response stream.	The model calls `ComposeUI`The Lang program, object identity, placement, durability, and action allowance travel through one typed terminal tool part.
Validation	Parser + schemas + renderer errorsSyntax and component contracts are validated progressively.	Parser plus product-semantic gatesSnappy also checks provider reachability, query/mutation lane, source match, real served fields, action wiring, density, durability, and truthful defaults.
Writes	A Mutation calls the supplied toolPolicy belongs to the host.	Authority is part of the runtimeAI-side external effects stage; human approval owns execution. Credentials, grants, risk, exact payload, and receipts are enforced server-side.
Artifacts	Preview + actual viewOne artifact has an inline preview and a detailed panel/full view.	SDK-native artifact model, extendedSnappy adds saved HTML, files, images, documents, spreadsheets, presentations, Live Apps, storage, versioning, and rehydration to the same registry.
Messages	Content + tool calls in one assistant messageTool output renders inline beneath its parent message.	Exactly the same message truthProse stays prose; the ComposeUI tool part owns the surface. No sentinel, duplicate surface-only message, or parallel persistence road.
Lifecycle	The host decides what survivesRenderer state and artifact controls are available.	Ephemeral and durable share one roadA stable `app_slug` / artifact ID turns the same live-bound surface into a reopenable, in-place patchable, versioned object.
Truth model	Error and parse callbacksThe app receives the signals needed to present state.	A product-wide state-language contractEvery data surface declares live, cached, stale, empty, error, or auth-expired—and success prose is gated on the real result.
AI surface	OpenUI can execute tools through MCPMCP is one supported tool-provider form.	Snappy itself is an AI-for-AI capability busExternal AIs get a curated semantic surface; a separate generated MCP x-ray proves governance coverage across the whole local product.

Four-frame infographic showing one generated interface retaining identity as it evolves from answer to live surface to durable artifact to AI-and-human-operated application. — **Generated UI crosses the software boundary.**Identity, source handles, versions, staged effects, and receipts persist while the object evolves.

From generated UI to source-attested UI

The interface does not merely display plausible values. It carries the exact source handle, arguments, fields, freshness, and causal receipt needed to prove where those values came from.

From interactive UI to governed capability

A button is not simulated state. It is a real registered capability with a risk class, grant, approval policy, payload preview, execution road, and receipt.

From one response to durable software

The same composition can stay ephemeral or become a named, reopenable, versioned Live App. Follow-ups refine the active object rather than regenerating a disconnected screen.

From an AI feature to an AI-native OS

The model is not decorating an app. It is operating through the product’s own typed roads—and other AIs can use those same governed concepts without guessing hidden routes.

Equally important: what we are not doing

We are not inventing a competing UI syntax.

We are not bypassing the OpenUI Renderer.

We are not saving canned .openui answers per skill.

We are not hand-writing connector-specific UI tables.

We are not executing AI-requested writes silently.

We are not rendering one surface through two message paths.

We are not reducing multi-source judgment to parallel raw tables.

We are not calling a plausible visual result “success” without state proof.

Engineering x-ray infographic identifying trust, freshness, resumption, and taste as four repair zones inside an otherwise coherent generative interface system. — **Ambition enlarges the repair surface.**The open gaps are named so they can become the next sanitizer, freshness contract, resumable protocol, and visual eval.

Security hardening gap

The HTML canvas expands OpenUI’s trust boundary.

Standard OpenUI’s safety story is registered components rather than arbitrary generated code. Snappy deliberately admits model-authored HTML through dangerouslySetInnerHTML; bound values are escaped and <script>/<canvas> are rejected, but the current HtmlSurface path does not visibly sanitize the full authored DOM or explicitly reject every inline on* handler. That needs a dedicated sanitizer/allowlist and a tested CSP—not just a prompt instruction.[R1]

Known red fixture

Mirror freshness is not yet fully per-table.

The intended law is MAX(synced_at) from the actual content table. A gated red fixture documents that one current path can still derive freshness from the SQLite file mtime, so an unrelated bookkeeping write can make stale rows look newly synced.[R2]

Protocol recovery gap

Long MCP operations need resumable identity.

Dogfood proved that the server can complete after the MCP client aborts. Activity preserves the outcome, but the caller should receive a durable request ID it can poll or resume rather than infer state from a transport exception.

Specification boundary

The canonical spec contains both law and target state.

The mined specification is intentionally uncompromising and includes unshipped demands. It also declares unmined images, attachments, and encrypted calls. Readers must not cite every line as implemented behavior; the runtime contracts and passing gates are the evidence for what exists now.

Complexity cost

One product road still has a large enforcement surface.

The inspected tree contains thousands of TypeScript files, hundreds of tests, many state machines, and a wide lint suite. “One path” prevents semantic duplication; it does not make the implementation small. Owner maps, file-size ratchets, derived registries, and deletion discipline are necessary just to keep the contract navigable.

Prompt drift risk

Some product quality laws remain linguistic.

Source truth and authority can be checked mechanically. Taste, information hierarchy, and “do not look like a demo” still rely partly on directive prose and regression prompts. Phrase-pinned tests catch deletion, not semantic weakening; visual evals and independent human acceptance remain essential.

The deeper lesson: radical transparency improves the system. Naming a red fixture, a transport ambiguity, or an enlarged trust boundary converts “it seems fine” into the next precise contract. The open kimono is not separate from the engineering method—it is how the method keeps working.

The positioning

OpenUI is the rendering constitution. Snappy OS is the governed society built around it.

Our differentiation is not that we can make prettier generated screens. It is that a generated screen can be trusted as a live, permissioned, source-bound, durable piece of software—and can be operated by humans and AIs through the same product laws.

Editorial infographic showing an OpenUI constitution supporting a Snappy OS society with source infrastructure, approval courthouse, artifact archive, activity ledger, and human and AI citizens. — The rendering constitution stays legible because the society around it shares one source, authority, identity, and evidence system.

Provenance observatory infographic showing documentation, code, traces, commits, and conversations converging through separate lenses on a verified claim, with an open unmined ledger and third-party reference code kept separate. — **Claims are joins across evidence classes.**Official docs define upstream behavior; code and traces prove runtime behavior; commits and conversations explain why the boundaries exist.

12 / Source notes

Grounded in docs and running contracts.

This explainer distinguishes OpenUI’s documented SDK responsibilities from the product responsibilities Snappy OS adds. The official documentation was retrieved through Context7 and checked against the implementation links below; Snappy claims point to the repo boundaries that enforce them.

OpenUI documentation

Official overview — Library → Prompt Generator → Parser → Renderer Official defining-components guide — defineComponent and createLibrary Official Renderer guide — streaming, actions, state, toolProvider, errors Official Queries & Mutations guide — model-authored wiring, runtime execution Official system-prompt guide — generated grammar, tools, bindings, rules, examples Official incremental-editing guide — named-statement patches and merge semantics OpenUI Lang overview — library, prompt generator, parser, renderer Renderer API — streaming, actions, state, toolProvider, errors How it works — prompt, model, Lang, tool execution Lang v0.1 specification — streaming and forward references Lang v0.5 specification — component, state, and data statements Interactive app example — Query, Mutation, Action, Run, Set, Reset Custom component libraries — defineComponent maps Lang nodes to React Artifact renderers — inline preview and full actual view Assistant message model — content plus tool calls

How the system was made

Canonical mined specification — north star, non-negotiable laws, source coverage, explicit unmined ledger Defect index — observed failures, demanded corrections, and implementation status HTML-first decision record — original language, first failed acceptance, salience fix, deleted exemplar idea Cold dogfood prompts — ordinary human asks without tool hints Prompt assembly — byte-stable cached head and variable live tail Unconditional live-context assembly — the split-brain prompt lesson Skill loading — semantic routing, deferred canonical body, digest proof Prompt frame — active-object identity, typed tool memory, untrusted-output handling Prompt-owner accounting — token ownership, placement, and audit No-regex harness gate — generic runtime behavior over intent shortcuts Infographic prompt set — the shared art direction and all 14 section briefs

Longitudinal AI-development lineage

Snappy MCP SDK generation — the resident-tool, education, credential, and slug-enforcement era Snappy MCP Slug — 182 definitions extracted behind progressive disclosure after mode filtering failed Snappy MCP v3 — compact results, poka-yoke, aliases, agent fuzzing, and learning-oriented errors Cyborg / Charlotte MCP — goal-directed retrieval, inhibition, salience, decay, and a buffered outbound queue Companion Agent MCP — context-first prompt assembly, decision-local salience, authoritative identity injection, and bounded tool use Claude Code infrastructure — auto-activating skills, progressive disclosure, and context-reset-resistant dev docs Snappy Kernel — filesystem capability rungs, actor/auditor separation, and self-correcting skill contracts Snappy Mini — human-owned program, agent-owned state, portable verbs, certificates, and evals Suggestion Engine — live/sample/target honesty, recipe contracts, A/B levers, judge labels, and comparable eval corpora DSPy Worker — unique-example counting, metric comparability, rich-context judging, and optimizer selection Content Engine visual QC — weakest-link scoring and two-second concept relevance Content Engine voice stage — prompt versioning, thresholds, bounded retries, and score-without-rewrite preservation Backend Dashboard Ralph loop — best-known-state branches, proof artifacts, keep/revert, and bounded retries Printing Press — Non-Obvious Insight, absorb-and-transcend research, local relational depth, CLI + MCP generation

Snappy OS product contracts

Product contract — one front door, AI-for-AI surface, connector handles, synthesis State-language contract — truthful state and approval objects Lean resident core + ToolSearch disclosure One Vercel AI SDK harness and provider-neutral tool loop ComposeUI boundary — identity, provenance, persistence, source contracts Product-semantic Lang validation Registered Query / Mutation provider registry and governance

Connector road and HTML-first architecture

RunConnectorCommand — resident read boundary and Printing Press focused skill Direct execution, list/detail fan-out, mirror-first mode, and SELECT-only SQL Rows, query bindings, query contracts, mutation contracts, and mirror truth The HTML-first architecture decision Html + HtmlMount — escaped data, paint containment, and React portals Registration of Snappy’s Html components in the OpenUI library

Snappy OS OpenUI integration

SDK-native AgentInterface, one assistant message path, artifact registry Dynamic OpenUI toolProvider over the registered provider manifest Saved file, image, HTML, document, spreadsheet, and presentation artifact renderers Durable Lang bodies, artifact identity, versions, query handles Runtime composition and Live App contract

Truth, effects, and candid gaps

Causal source-binding and multi-source synthesis contract Loose stop signal versus strict paint-success verdict One typed mirror-state owner and precedence ladder Per-table content freshness helper Gated red fixture documenting the remaining file-mtime freshness defect Exactly-once execution, outcome-unknown state, and verification tiers Whole-surface MCP classification forcing function Html/HtmlMount implementation and current trust boundary