The agent loop

The product is a tight loop an agent can run on its own: write, check, render, look, repair. Every agent gets the same loop over the same files. A developer's agent uses the CLI, the hosted assistant in the dashboard uses its own tools, and any other agent uses MCP.

Where the loop startsCopy Anchor Link

A new email starts from the gallery design that fits the brief. The CLI uses samva templates suggest and samva templates from-brief, and an agent over MCP calls templates_suggest and templates_create_from_brief. A named company's email starts from Samva's recreation of it; with none, the project starts from the closest design. Agents over hosted MCP read the design guidance with templates_design_guide.

What each step returnsCopy Anchor Link

• Check compiles every template and validates every fixture, then returns diagnostics: a code, a location, and a fix for each finding. --json adds the range and severity in a form a tool can apply. A save whose source cannot build fails with TemplateSourceError and its diagnostics; fix the source and save again.
• Render returns the subject, preheader, HTML, and plain text for one named fixture. On the CLI, --locale and --time-zone render for a specific reader. A build that failed returns no render beside the findings that explain it. The render also reports sentBytes, the size of the HTML as delivered, and previewBytes, the larger size of the returned HTML with imported assets embedded for preview. Gmail clips a message whose sentBytes exceed 102 KB.
• Look returns screenshots of one fixture. The CLI writes desktop and mobile PNG files, in light and dark, to .samva/snapshots; the MCP tool and the hosted assistant return desktop and mobile images and a dark-mode image.
• Save appends one Git commit after validating every template and fixture. Publish needs a clean, pushed commit. The hosted assistant saves each request that changed files as a version when it finishes; restoring an earlier version stays your action.

A typical repairCopy Anchor Link

1. The agent runs samva templates check --json and reads the findings.
2. It fixes the location a finding names, such as guarding input.trackingUrl with input.trackingUrl && ....
3. It renders the fixture that exercises the change, for example samva templates render order-shipped --fixture no-tracking.
4. It takes a snapshot and looks at the mobile and dark variants.
5. It commits when the check is clean.

What agents can readCopy Anchor Link

• The hosted MCP server publishes the template guide, the full reference, and a machine-readable contract as resources: samva://guide/template-editor, samva://reference/sml, and samva://reference/contract. The contract lists the components with their props, the forms of the static profile, the formatters, and the diagnostic codes, generated from the compiler so it does not drift. See Connect an agent over MCP.
• The @samva/markup package ships the same contract as @samva/markup/contract.json, a readable generated/reference.md, and the sml skill, so an agent working in a clone has everything without a connection.
• The samva Agent Skill routes an agent to the template authoring reference.
• This documentation is available as Markdown, and llms.txt lists every page.

Two edits, one meaningCopy Anchor Link

The canvas, the assistant, and a developer's push all land as revisions of the same file. When two revisions touch the same lines, the conflict surfaces for explicit resolution instead of one edit silently winning.