artifacts

The cockpit-is-renderer principle says every cockpit affordance must map to a snappy-os skill. The Live artifacts sidebar destination (cd-22 / cd-23 in dogfood-loop/refs/) is no exception - this skill is the producer.

An artifact is a named, refreshable piece of structured output a user has opted to keep around: a daily revenue chart, a top-pipeline-deals table, a weekly catchup brief. Each is one JSON file in state/log/artifacts/, keyed by uuid. The cockpit lists them via GET /artifacts and creates new ones via POST /artifacts.

The lib at state/lib/artifacts.ts is the action scope. Refresh + delete are deliberately deferred until the cockpit's interaction surface lands - list + create is the minimum viable producer that lets the empty-state vignette ("Create your first artifact") become non-empty.

Pure read for listArtifacts. createArtifact writes one new file atomically (temp + rename) so partial writes are never visible to the listing.

Steps

1. listArtifacts(): Promise<Artifact[]> - read every *.json under

state/log/artifacts/, parse, validate shape, drop bad rows, return sorted by created_at desc. Creates the directory if missing so the first call on a fresh checkout returns [] cleanly.

1. createArtifact({ name, description?, pinned_chat_id?, source_connectors? })

- mint a randomUUID(), build the Artifact row, write state/log/artifacts/<id>.json atomically (temp + rename), return the materialized object. name is required; everything else is optional.

1. The HTTP endpoints are wired in state/bin/head-screen/server.ts:

• GET /artifacts → returns the array directly.
• POST /artifacts (body { name, description? }) → returns the new

artifact. Both endpoints emit CORS * so the WKWebView (file:// origin) can hit them.

Library API

state/lib/artifacts.ts exports two functions and the Artifact type. Importable from any TS agent code; also runnable as a CLI smoke.

export type ArtifactStatus = "fresh" | "stale" | "error";

export interface Artifact {
  id: string;
  name: string;
  description?: string;
  created_at: string;
  last_refreshed_at?: string;
  status: ArtifactStatus;
  pinned_chat_id?: string;
  source_connectors?: string[];
  last_output_preview?: string;
}

export async function listArtifacts(): Promise<Artifact[]>;
export async function createArtifact(opts: {
  name: string;
  description?: string;
  pinned_chat_id?: string;
  source_connectors?: string[];
}): Promise<Artifact>;

CLI:

npx tsx state/lib/artifacts.ts                       # list (JSON to stdout)
npx tsx state/lib/artifacts.ts create "Revenue brief" "Daily auto-refresh"

Storage shape

state/log/artifacts/
  <uuid>.json   # one per artifact

state/log/ is gitignored (per-machine ephemeral) - artifacts are local state, not synced across machines. If a future axis needs cross-machine artifacts, add a sync hook here, don't move the storage.

Per-row JSON schema example:

{
  "id": "8e1c4a08-…",
  "name": "Daily revenue brief",
  "description": "Pulled from FreshBooks each morning",
  "created_at": "2026-04-29T05:30:00.000Z",
  "status": "fresh",
  "source_connectors": ["freshbooks"]
}

Eval

Actor: listArtifacts() / createArtifact() in state/lib/artifacts.ts. Auditor: state/lint/library-shape.ts (the lib must export the two functions with the documented signatures) plus the cockpit dogfood loop that proves the sidebar list renders (not error fallback).

Eval kind: shape. Mechanical: import the lib, assert listArtifacts and createArtifact exist as functions, type-check passes, atomic write contract holds (no .tmp files visible to a concurrent list during create).

Pitfalls

• state/log/ is gitignored. Don't expect artifacts to follow the

agent across machines - they're local cache. If Robert needs portable artifacts, that's a separate axis (sync hook, not storage move).

• Atomic write is non-negotiable. A partial JSON file in the directory

means listArtifacts parse-fails the row and silently drops it - the cockpit will never see it. Always temp+rename.

• name is required, everything else is optional. The cockpit's

"New artifact" sheet should enforce this client-side; the lib also throws if name is empty.

• Refresh / delete are NOT in this version. When they land, they're

separate endpoints (POST /artifacts/<id>/refresh, DELETE /artifacts/<id>) and separate skills. Don't bolt them on here.

Files

• state/lib/artifacts.ts - the API (importable + CLI).
• state/bin/head-screen/server.ts - owns GET /artifacts and

POST /artifacts.

• state/log/artifacts/ - per-row JSON storage (gitignored).

Rubric

criteria:
  - name: lib_exports_shape
    kind: deterministic
    check: "state/lib/artifacts.ts exports listArtifacts and createArtifact as async functions with the documented Artifact return shape (id, name, created_at, status all required)."
  - name: atomic_write_holds
    kind: deterministic
    check: "createArtifact writes via temp+rename — no `.tmp` file ever appears in state/log/artifacts/ visible to a concurrent listArtifacts call."
  - name: http_endpoints_wired
    kind: deterministic
    check: "GET /artifacts returns a JSON array; POST /artifacts with {name} returns the new artifact and persists it. CORS `*` set so the WKWebView (file://) can hit them."
  - name: corrupt_row_does_not_crash
    kind: deterministic
    check: "A bad JSON file in state/log/artifacts/ is silently skipped by listArtifacts — the listing returns the valid rows, never throws."

artifacts - loader

Per-turn rules for the artifacts skill. Full reference: state/skills/artifacts/SKILL.md. Storage: state/log/artifacts/<uuid>.json (gitignored, per-machine).

Critical Rules

• Atomic write or it never happened. createArtifact must temp+rename.

A partial JSON file in state/log/artifacts/ makes listArtifacts silently drop the row and the cockpit never sees it. Always atomic.

• state/log/ is gitignored. Artifacts are LOCAL cache. Do not assume

they sync across machines. If Robert needs portable artifacts, that's a separate axis.

• list returns desc by created_at. Don't change the sort without

updating the cockpit's expectations.

• Pure read for listArtifacts. Never write inside it. Even if a

corrupt row is found, skip silently - don't try to repair on read.

• Refresh / delete are NOT in this version. When they land, separate

endpoints + separate skills. Don't bolt them on here.

• name is required. createArtifact throws on empty name. Cockpit

should enforce client-side too.

Commands

| ui dashboard | state/skills/artifacts/resources/ui.openui | |invoke: import { listArtifacts, createArtifact } from "./state/lib/artifacts.ts" |cli list: npx tsx state/lib/artifacts.ts |cli create: npx tsx state/lib/artifacts.ts create "<name>" "<optional desc>" |http list: curl -s http://127.0.0.1:3147/artifacts |http create: curl -s -XPOST http://127.0.0.1:3147/artifacts -H 'content-type: application/json' -d '{"name":"Daily brief"}' |storage: state/log/artifacts/<uuid>.json |eval log: state/log/evals.ndjson (skill: "artifacts")

Endpoints (head-screen owns these)

• GET /artifacts - returns Artifact[], sorted desc by created_at.

CORS *.

• POST /artifacts - body { name, description? } → returns the new

Artifact. CORS *. 400 on missing/empty name.

Working primitives

• listArtifacts() - read every *.json under state/log/artifacts/,

parse, validate, drop bad rows, sort desc by created_at. Creates the directory if missing so the first call on a fresh checkout returns [].

• createArtifact({ name, description?, pinned_chat_id?, source_connectors? })

- mint uuid, atomic write, return the materialized row.

Self-Test

An agent reading this should correctly:

1. [ ] Use atomic write (temp + rename) in any new write path
2. [ ] Treat state/log/ as per-machine ephemeral storage
3. [ ] Reject empty name at the lib level (don't push validation to

the HTTP layer)

1. [ ] Skip corrupt rows silently in listArtifacts - never throw

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] artifacts: <what was missing>" >> state/log/loader-feedback.log

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] artifacts: <what was missing or fixed> [FIXED|LOGGED] action_kind=<kind>" >> state/log/loader-feedback.log

• <slug> MUST be the literal folder name of this loader

(state/skills/<slug>/AGENTS.md). The class token between [ts] and : is the producer slug, the writeback class, AND the grade class - they must be equal so state/lib/controller-tune.ts can pair the brief.

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

• action_kind is the SECOND pairing predicate (added 2026-04-27, task #327).

Pick the value that describes what you actually did - same slug, different action_kind means the writeback satisfies a different brief layer:

• shape-ok - only frontmatter-shape verification passed (rare from

a human; usually emitted by the lint, not a loader echo)

• skill-ran - the skill ran end-to-end and an eval row landed

in state/log/evals.ndjson

• loader-rewritten - you EDITED this AGENTS.md inline (the FIXED case),

OR the regen drain rewrote it

• pattern-elevated - you promoted a recurring failure to a Critical Rule

(rule fix or new-skill scaffold) If you LOGGED (couldn't fix inline), omit action_kind - the inferrer will pick it up from your body keywords.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/artifacts/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.