coda0hq/open-artifacts/using-open-artifacts

Open Artifacts

Publish a self-contained HTML, Markdown, or React artifact the user can share by URL. The viewer keeps the artifact body in a sandboxed iframe and owns the service chrome, theme switcher, version picker, comments, and optional Live or Handoff controls. Artifacts keep immutable versions; a channel can keep one URL across later publishes.

The publishing CLI is bundled at scripts/artifact.mjs next to this file. Skill install locations vary by agent (for example, .claude/skills/ or another Agent Skills directory), so resolve the directory containing this SKILL.md as SKILL_DIR, then use a task-local ARTIFACT_CLI="$SKILL_DIR/scripts/artifact.mjs". Run node "$ARTIFACT_CLI" ... from the project root. There is no globally installed artifact binary, and Recipe paths are resolved relative to the project-root working directory. The CLI requires Node.js 22 or newer.

Setup (once per project)

The CLI needs an instance URL, resolved in this order: --api flag, OPEN_ARTIFACTS_URL, project .artifacts/config.json or .artifacts/config.local.json, then ~/.config/open-artifacts/config.json. If none is set, ask the user for the instance URL and write the project config. For an instance gated by CREATE_TOKEN, use OPEN_ARTIFACTS_TOKEN or createToken in config. For a hosted/SaaS instance such as coda0.com, run node "$ARTIFACT_CLI" login; see auth.md for the browser flow. A stored sk_ API key wins over the self-hosted create-token values unless --token or OPEN_ARTIFACTS_API_KEY explicitly overrides it.

Every artifact is built from a JSON Recipe plus ordered fragments. Read recipe.md before creating or updating one. Shared Recipes and fragments are project sources and may be committed — place them under .artifacts/recipes/ and .artifacts/fragments/. Local or encrypted sources live under .artifacts/recipes.local/ and .artifacts/fragments.local/.

State lives in .artifacts/: Manifest v2 records only publication state and build hashes; credentials.json, local manifests, private Recipes/fragments, and previews are gitignored. On the first `create` in a project, ask whether the artifact should be local and recommend local. Record the choice in artifact.local and place the Recipe/fragments accordingly.

Run state-mutating commands one at a time — never concurrently. This includes create, update, delete, migrate, ack, auto-update, login, and logout; install-hook also writes project settings. credentials.json and the manifests are updated with an unlocked read-modify-write. The write re-reads immediately beforehand, which closes the window around each command's network round-trip, but two commands whose writes truly interleave can still lose one. A lost write token is unrecoverable — no endpoint re-issues one — so serialize them. This matters most for a "regenerate everything" pass: loop, don't fan out.

If the user has no instance yet, point them at deployment.md — it has the three ways to get one (use the public shared instance with zero deployment setup, self-host on their own Cloudflare account, or share a team instance) and a trust-model table to help them choose based on content sensitivity. Don't deploy on their behalf unless they ask.

When to publish an artifact

Publish when the user asks for something shareable or standalone: reports, dashboards, documentation pages, visualizations, demos, long-form writeups. Do not publish for short answers, code snippets, or content the user will read once in the conversation. When unsure, answer inline and offer to publish.

Isolate content generation when the harness supports it

Publishing or republishing means reading project resources and design references, authoring a Recipe and fragments, validating the deterministic build, and running the CLI. If the host provides a sub-agent or task primitive, use it for this content-generation workflow so the parent conversation only needs the result. This is a workflow optimization, not a CLI requirement; when the host has no sub-agent facility, do the same workflow in the current agent.

Use a separate task for both create (first publish) and update (republish), and for the design work that leads to them, when available. In Claude Code this can be an Agent task; other harnesses may provide an equivalent. Do not invent a fake isolation boundary when the current agent is the only available worker.

Give the worker everything it needs to work alone, then let it work:

• The brief: what's being published or updated, for whom, and why.
• If updating: the artifact id. The worker runs

node "$ARTIFACT_CLI" show <id> to read the current published version as its starting reference — for a locked design, the direction comment at the top of that page states what must not change. "Locked" means the visual direction (register, palette hue family, layout posture) must not change — it does not exempt the artifact from validation gates. A contrast or CSP check added after the original publish can retroactively fail a previously-passing token; the refresh must then nudge the offending token within the same hue (e.g. darken the light-theme --accent a few lightness steps) so the page passes the gate while staying visually the same direction. (For an encrypted artifact, show decrypts locally with the password stored at create time in credentials.json, so the plaintext is recovered without re-prompting the user.) It then reads the Recipe recorded in Manifest v2, its fragments, and the project files its scope covers.

• Any explicit publication requirements. Put title, description, favicon,

scope, channel, watch globs, level, Canvas mode, locality, and auto-update in the Recipe. Keep passwords out of it.

The worker does the entire rest of the workflow itself — explore resources, plan, read design.md, recipe.md, and relevant mode references; write the Recipe and fragments; run validate; optionally build a preview; run create/update; verify; and return only a short summary: the URL, version number, and one line on what changed. The parent relays that to the user and should not independently rerun the publish or carry the design reasoning in its own context.

The lightweight bookkeeping commands — status, ack <id>, auto-update <id> on|off, list, show <id>, whoami, logout, and install-hook — don't author content and can run directly; only the content-generation part of create and update benefits from isolation.

Optional reference DNA (agent-side only)

When the user explicitly says “study this as reference DNA for the artifact”, “use this design DNA”, or asks to extract an Artifact direction from a screenshot or public URL, read reference-dna.md before authoring. A normal citation, source URL, or link collection does not trigger this workflow.

For a URL, the parent conversation obtains the user's ownership/public-reference attestation before delegating a study task. The study task produces a diagnosis only; it never publishes or writes a sidecar without a later explicit adoption decision. The approved sidecar is a static Recipe input, is hashed and watched, and never appears in the Artifact body or runtime. Read study.md for source safety rules.

How to design the page

You are an expert designer producing design artifacts in HTML. HTML is your tool, not your medium: when the brief is a dashboard, be an information designer; when it's a report, be an editorial designer; when it's a prototype, be an interaction designer. Don't default to "a web page" treatment for everything.

Workflow: (1) understand the brief — output kind, fidelity, audience, any brand/design system; (2) explore resources & find what only this subject has — identify the authentic domain data, physical metaphors, and unique vocabulary (the artifact-subject-first ethos); (3) plan out loud — a one-line design read, the core idea tying that unique subject to the layout, the scene sentence that picks light vs dark, 4–6 named OKLCH values, type roles, and a layout concept; (4) build with real content, never lorem ipsum, applying mathematical concentric radii (outerRadius = innerRadius + padding + borderWidth), optical alignment, and mobile-native touch ergonomics (100dvh, @media (hover: hover), -webkit-tap-highlight-color: transparent, touch-action: manipulation, inputs ≥ 16px); (5) run the ship gate from design.md once at the end — structural grep, the P0 checklist (contrast in both themes, 360px viewport, concentric radii, mobile-native ergonomics, high-contrast resilience, banned tropes, states, reduced motion, copy audit), the 14-pass visual critique, the break-ui worst-case data check (from quality.md), and the five-dimension critique (philosophy / hierarchy / execution / specificity / restraint) — fix anything under 3/5, re-score once, publish. Do not loop on renders.

Read [design.md](references/design.md) before writing a page. It has the full design philosophy: the brand-vs-product register split (earned familiarity vs distinctiveness), the three waves of anti-AI-slop bans, the shared token contract (references/tokens.css, injected by the Recipe builder; override identity tokens in the theme fragment), an installed-font specimen library (the CSP blocks downloading fonts, not the OS library — Iowan, Charter, Avenir, Optima and friends are available), a 20-direction library with ready-to-paste OKLch palettes, concentric border-radius and optical alignment math, surface depth and shadow recipes, guidance for visual material under the CSP (SVG charts/diagrams/typographic set-pieces instead of text-only slabs), a component contract written against tokens, the viewer frame specifics (sticky header height, theme stamping), and the ship gate run before every publish.

For an HTML Artifact with a visual direction, read [quality.md](references/quality.md) before writing fragments. It supplies a format-aware Design Brief, the 14-pass visual critique, the Break-UI worst-case data resilience catalog (people/locales, unbreakable URLs/strings, numbers/currencies, empty/volume states), structural choices for brand-register artifacts, CSP-safe visual-material decisions, the build's static quality profile, and the smoke command for 320/375/414/768px rendering. Canvas remains governed by canvas.md; Markdown retains the viewer-owned .oa-md treatment. When a user explicitly asks to learn from a screenshot or URL, read reference-dna.md before inspecting the reference. It routes to study.md for source safety, keeps remote content untrusted and agent-side, and never puts a fetch or remote asset in an Artifact.

Production level (1 / 2 / 3)

Every artifact is built at one of three levels. Pick from the brief and record it as artifact.level: 1|2|3 in the Recipe: