Revamp for Agent Grid and fix the drifted tool surface

[macabeus]

Why now

The skill has not changed since 2026-03-27, but the repo is live: 132 clones from 60 unique cloners in the last 14 days, driven mostly from animaapp.com. Meanwhile the MCP tool surface was renamed underneath it.

Three of the four documented tools no longer exist. Every customer agent following this guide is calling dead names.

SKILL.md said	Reality
playground-create	artifact-create
playground-publish	artifact-publish
project-download_from_playground	removed — no replacement
codegen-figma_to_code	✅ unchanged

Seven shipped tools were undocumented: artifact-status, artifact-duplicate, artifact-unpublish, artifact-update_metadata, artifact-get_zip_upload_url, artifact-get_git_token, workspace-list_artifacts.

What changed

Everything is checked against @animaapp/mcp-tools definitions.ts / schemas.ts and the @animaapp/cli command definitions.

Behavioural corrections

• Generation is asynchronous. artifact-create returns status: 'generating'; the supported pattern is artifact-status(wait: true) until it resolves. The old skill told agents to hold a single 10-minute call open.
• framework defaults to html over MCP, not react.
• Adds the empty / import create types and the zip-upload flow — bringing your own code was entirely undocumented.
• Editing goes through git, never a browser. New references/git-workflow.md covers clone/push and non-renewable tokens.
• Publishing makes an app public and is not required for sharing.
• designSystem publish mode always fails over MCP.
• l2c accepts vanilla_css; p2c takes no uiLibrary.
• Headless auth is ANIMA_API_TOKEN, not the advertised ANIMA_API_KEY.
• Drops anima download, which is not a CLI command.

Rebrand
Agent Grid throughout; endpoint moves to https://api.agentgrid.io/v1/mcp in .mcp.json, server.json, openai.yaml, and the README.

Deliberately unchanged — so nothing already installed breaks:
plugin: anima · marketplace: anima@mcp-server-guide · registry: io.github.AnimaApp/anima · the skills/anima/ path (codex skill install documents it).

Structure

• anima-skill-references/ → skills/anima/references/, so the plugin reads them from disk instead of fetching github.com mid-task.
• anima/SKILL.md stays (it's the most-read file in the repo — 39 unique readers vs 1 for the skills/ copy) but is now generated by scripts/build-mirror.sh and enforced by CI instead of hand-synced.
• Adds assets/anima-icon.svg, which openai.yaml referenced without the file existing.

Verification

• Every tool name in the docs exists in definitions.ts, and all 10 real tools are documented — both set differences are empty.
• Every anima <cmd> in the docs is a registered CLI command.
• All JSON parses; both SKILL.md frontmatters parse; no relative link is dead; no public-api.animaapp.com or ANIMA_API_KEY remains.

Needs a human before merge

• assets/anima-icon.svg is a placeholder I generated — a plain geometric mark in the existing #FF6250. Design should replace it.
• Confirm api.agentgrid.io is the endpoint to publish to customers (both it and public-api.animaapp.com currently answer).
• The MCP tools return dev.animaapp.com/chat/<sessionId> URLs while the docs lead with app.agentgrid.io/artifacts/<sessionId>. Docs teach both and explain the id is the last path segment either way — but the split is worth closing product-side.
• server.json is bumped to 2.0.0; the MCP Registry entry needs a separate publish to pick it up.
• Naming: MCP tool descriptions say "Agent Grid", the CLI README says "AgentGrid". This PR uses Agent Grid.

[macabeus]

Adversarial review pass — 25 defects found, all fixed

Two independent reviewers audited this branch against tools/*/handlers.ts, the api package, the Redis job scripts, and the CLI. They ran separately and converged on the same three CRITICALs, which is the part I'd trust most.

I re-verified every material finding against source myself before changing anything.

CRITICAL

1. The CLI does not wait for generation — the worst one, and mine. artifact-create is non-blocking (handlers.ts:400); the CLI calls it once and prints "Artifact created!" (create.ts:123-140). artifact-status appears nowhere in the CLI and there is no status command. The skill told agents the CLI "handles the status wait for you" — they would have reported still-building apps as finished. Now documented as fire-and-forget, with MCP preferred for generation.
2. Two CLI examples always failed. -t l2c/-t f2c with --ui-library but no --framework react: the CLI defaults generation to html (create.ts:253) and the server rejects uiLibrary unless the framework is react (schemas.ts:239-246).
3. /plugin install anima@mcp-server-guide could not resolve. Claude Code keys marketplaces by marketplace.json's name (was "anima"), not the repo name — verified against a real known_marketplaces.json, where anthropics/claude-code is keyed claude-code-plugins. Renamed the marketplace to mcp-server-guide so the already-published command works; plugin id stays anima. This bug predates this PR.

MAJOR

4. codegen-figma_to_code defaults to react, not html — the html default belongs to artifact-create. The skill contradicted its own reference doc.
5. Inline files caps are 1000 files / 10 MB enforced (api/src/utils/projectZip.ts:10-11), not the "~100 KB" in the tool description. Agents were being pushed into the 3-step zip flow ~100× under the real limit, and the file-count cap — the one that actually bites — was undocumented.
6. A user may have only 3 active jobs, shared across generation, codegen, and deploy (claimMcpGeneration.lua:93). Explore mode's "fire 3 in parallel" sits exactly on the cap, so any concurrent publish silently kills a variant. Documented with the Too many concurrent jobs recovery.
7. codegen files is filtered (filterBoilerplate, CodegenEventHandler.ts:40-66) — config, entry points, *.d.ts, and all of src/components/, which is exactly where extracted and shadcn components live. Documented so agents don't read the absence as a failed generation.
8. type: empty is not a bare repo — it lands a seed README.md commit (ownCodeArtifact.ts:129-139), so "add the remote and push" is a non-fast-forward. Now says clone first.

MINOR (9 more)

Git token in the create response isn't unconditional; language is a no-op for p2c; l2c is TypeScript only under react; workspace-list_artifacts returns sessionId only on app rows (plus truncated, plus a silent empty list without read); codegen also accepts clean_react; artifact-publish also takes packageName/packageVersion and rejects them with mode: webapp; artifact-status returns thumbnailUrl; the html default applies to generation types only; ANIMA_TEAM_ID is read only alongside ANIMA_API_TOKEN; --api-url is on every command except config.

Also fixed

The icon moved to skills/anima/assets/ so openai.yaml's ./assets/ path resolves from the skill root that codex skill install targets.

Executable verification

Rebuilt the CLI from source and ran all 13 documented example invocations: every one parses and fails only at AUTH_REQUIRED. anima mcp-config emits {"anima":{"type":"http","url":"https://api.agentgrid.io/v1/mcp"}} — matching .mcp.json exactly. Three documented validation rules fire verbatim. build-mirror.sh is idempotent and the CI staleness check was verified empirically.

Still open for a human

• The assets/anima-icon.svg placeholder still needs a real mark from design.
• Product bug, not a docs bug: the artifact-create schema description advertises "~100 KB" for inline files while the enforcing code allows 10 MB / 1000 files, and the CLI hardcodes 10 MB with a comment claiming it is "kept in sync with artifact-create". Two of those three should change.
• Product gap: the CLI has no way to await or query generation. Today anima create -t p2c is unusable for agents that need to know when the app is ready. A status command (or a --wait flag) would close it.