artifacts · diff

v0.1.0 to v0.2.0

59 added, 55 removed. Audit C to A.

What this update changes in the checks

This update trips no new check.

It clears 2 checks: No link to a raw IP address; No script tag.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: artifacts
- description: Generate standalone, downloadable artifacts — single-file HTML pages, SVG diagrams, PDFs, slide decks, JSON exports. Write to ./artifacts/<timestamp>-<slug>/ so the user can grab the file. Load whenever the user asks for "a file", "an export", "a downloadable", a one-off mockup, or a chart.
- version: 0.1.0
+ description: Produce a standalone, versioned deliverable (web page, React/Vue component, SVG, diagram, doc) the user will keep and iterate on. Use the built-in artifact_* tools — NOT write_file — so the artifact is versioned, undoable, and previewable in a real browser. Load whenever the user asks for "an artifact", "a file", "a mockup", "a component", a one-off page, a chart, or anything they'll take away and refine.
+ version: 0.2.0
author: QodeX
triggers:
- artifact
- - export
- - download
- - one-file
+ - mockup
+ - component
- standalone html
- svg
- - mockup
- - pdf
+ - chart
+ - one-pager
+ - preview
slash-aliases:
- artifact
- artifacts
allowed-tools:
+ - artifact_create
+ - artifact_update
+ - artifact_list
+ - artifact_get
+ - artifact_rollback
+ - artifact_preview
+ - browser_navigate
+ - browser_screenshot
+ - vision_analyze
- read_file
- - write_file
- - edit_text
- - multi_edit
- - ls
- - glob
- - grep
- - bash
---
- # Artifacts — Deliver a File the User Can Take
-
- The user wants a standalone deliverable, not just code changes inside the
- project. Build it as a self-contained file in a predictable spot.
+ # Artifacts — Versioned, Previewable Deliverables
- ## Output location
- ```
- ./artifacts/<YYYY-MM-DD>-<slug>/<name>.<ext>
- ```
- - Use the project's `cwd` (don't write to `$HOME` or `/tmp`).
- - Create the directory if it doesn't exist.
- - Slug = kebab-case summary of the artifact (max 6 words).
- - If you generate multiple files, put them all under the same dated dir.
+ When the user wants a standalone deliverable (a web page, a React/Vue component,
+ an SVG, a chart, a doc) — something they'll keep and refine, not project source
+ code — use the built-in **artifact tools**. Do NOT hand-write the file with
+ `write_file` and tell the user to open it. The artifact tools give you
+ versioning, rollback, undo, and one-step browser preview for free.
- ## Required formats — defaults & rules
+ ## The tools (use these — not write_file)
- ### Standalone HTML
- - **One file.** Inline CSS in `<style>`. Inline JS in `<script>`. No external dependencies unless the user said "use library X".
- - If you NEED a library (charts, three.js), prefer ESM CDN with SRI hash; document why.
- - `<!doctype html>`, `<meta charset>`, `<meta viewport>`. Always.
- - Add a small footer line `<!-- generated by QodeX :: skill=artifacts :: <ISO> -->`.
+ - **`artifact_create`** `{ title, type, content, note? }` → creates v1, returns an `id`.
+ `type` is one of: `html`, `react`, `svg`, `markdown`, `vue`, `text`.
+ For a React component, pass the component source as `type: "react"` — you do
+ NOT need to write an HTML wrapper, CDN script tags, or a Babel harness. The
+ preview builds that for you.
+ - **`artifact_update`** `{ id, content, note? }` → saves a NEW version (old ones kept).
+ - **`artifact_preview`** `{ id }` → builds a self-contained preview page, starts a
+ local static server, returns a URL. React/Vue render with NO build step.
+ - **`artifact_list` / `artifact_get` / `artifact_rollback`** → browse / read / revert.
- ### SVG
- - Width/height in `viewBox` only. No fixed pixel dims.
- - Self-contained: no external fonts; use system fonts or inline a base64 woff2 if absolutely required.
- - Tag `<title>` and `<desc>` for accessibility.
+ ## The standard flow
- ### PDF
- - Generate via the user's local tools (Chrome headless, Pandoc, wkhtmltopdf). Don't hit external services.
- - If no PDF toolchain is available, produce HTML first and write a one-liner the user can run.
+ 1. **Create**: call `artifact_create` with the right `type`. For React, the
+ `content` is just the component (e.g. a `function Counter() { ... }` plus a
+ render call, or a default export) — no boilerplate HTML.
+ 2. **Preview**: call `artifact_preview` with the returned `id`. It returns a URL.
+ 3. **See it**: call `browser_navigate` with that URL, then `browser_screenshot`.
+ Optionally `vision_analyze` the screenshot to check it actually looks right.
+ 4. **Iterate**: if something's off, call `artifact_update` with the fixed content
+ (a new version), then preview again.
- ### Slide deck
- - Reveal.js single-file, OR a Markdown file that any deck tool can consume (Marp / Slidev). Ask if the choice isn't obvious.
+ ## Type-specific notes
- ### Data export
- - JSON: pretty-print (2-space). Stable key order. Trailing newline.
- - CSV: RFC 4180. UTF-8 with BOM only if the user is sending it to Excel.
+ - **react** — write the component source directly. The harness pulls React +
+ Babel in-browser, so JSX renders immediately. If you define a top-level
+ component, the preview auto-mounts it; or include your own `ReactDOM` render.
+ - **vue** — single-file component or a root component; rendered via an in-browser
+ loader, no bundler.
+ - **html** — full document or a fragment; rendered as-is.
+ - **svg** — use `viewBox`, no fixed pixel dims.
+ - **markdown** — rendered with a markdown renderer in the preview.
## Quality checklist before declaring done
- 1. The file opens correctly with a double-click (HTML/SVG).
- 2. No `localhost:` / `http://0.0.0.0/` references baked in.
- 3. No accidental secrets, no leaked tokens, no internal-only URLs.
- 4. Print the **full absolute path** of every artifact in your summary so the user can `open <path>` directly.
- ## Examples of what artifacts SHOULD be
- - "Show me a chart of the auth latency" → `artifacts/2026-05-29-auth-latency/chart.html`
- - "Make me a one-pager about the project" → `artifacts/2026-05-29-project-onepager/index.html`
- - "Export the schema as a diagram" → `artifacts/2026-05-29-schema/schema.svg`
+ 1. You called `artifact_create` (and `artifact_preview` if the user wants to see it) —
+ not `write_file`.
+ 2. For visual artifacts, you actually previewed and (ideally) screenshotted it,
+ rather than assuming it renders.
+ 3. No baked-in `localhost:` URLs in the artifact source, no secrets/tokens.
+ 4. Reported the artifact `id` so the user can ask for revisions by id.
## What artifacts is NOT for
- - Project source files (just edit those in place).
- - README updates (they live with the code, not under `./artifacts/`).
- - Anything the user will check into git as part of the codebase.
+
+ - Project source files — edit those in place with the normal file tools.
+ - README / docs that live with the code and get checked into git.