Agent blueprint

Human usage: copy this page URL and tell the agent:

Ejecuta https://auradesignsystem.com/docs/mcp-agent-blueprint

(Local docs: http://localhost:4000/docs/mcp-agent-blueprint.)

This page is an agent runbook, not the CLI command aura blueprint. The runbook may invoke that command when the project is missing its wiki, image-generation command, preflight, or Sonar scaffolding.

Agent: follow this runbook

If the user pasted this URL with Ejecuta, Run, Execute, or Aplica, you are the agent. Do not only explain. Audit the workspace, install what is missing, and report.

Default target: consumer project (an app using Aura). Only use the Aura monorepo registry path if the repo clearly is aura-design-system (has packages/registry/registry/default/components/).

0. Preconditions

• Work in the project root that has (or will have) package.json / the Next app.
• Prefer non-interactive installs: pnpm dlx ….
• Do not invent secrets. Do not force-push.
• If components.json is missing and the app is not Next-like, say what blocked you and stop after the audit.

1. Audit (read before write)

Check and record present / missing for each:

Also note: Tailwind/Aura CSS already applied? (globals.css with accent/gray scales, or prior aura setup / init).

2. Install / fix gaps

Apply only what is missing. Prefer the smallest fix.

A. Full Aura apply (no Aura yet, or heavily incomplete)

pnpm dlx @aura-design/cli@latest setup

(setup updates components.json, globals.css, adds registry packages, rules, skills, and runs CLI blueprint scaffolding. Use from the app root.)

If the user only wants AI context (not full theme rewrite), skip setup and use the targeted adds below.

B. Targeted AI context (typical “old project already on Aura”)

pnpm dlx shadcn@latest add @aura/rules @aura/skills @aura/rule-design-md

• @aura/rules → .cursor/rules/
• @aura/skills → .cursor/skills/ (includes port-component-to-aura and generate-brand-images)
• @aura/rule-design-md → rule + root DESIGN.md

If the blueprint wiki, Image-Identity.md, or pnpm ai:image is missing, scaffold those project capabilities without rewriting the Aura theme:

pnpm dlx @aura-design/cli@latest blueprint .

Ensure components.json has:

"registries": {
  "@aura": "https://auradesignsystem.com/r/{name}.json"
}

(Optional local registry while developing Aura itself: "@aura-dev": "http://localhost:4000/r/{name}.json".)

C. MCP config (create if missing)

Write project .cursor/mcp.json if absent:

{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

Then tell the user (you cannot finish this in the terminal):

1. Restart Cursor or reload MCP.
2. Settings → MCP → enable shadcn (green dot).

3. Verify

Confirm after installs:

• .cursor/rules/ has Aura foundation rules
• .cursor/skills/port-component-to-aura/SKILL.md exists
• .cursor/skills/generate-brand-images/SKILL.md and its generator script exist
• wiki/obsidian-*/01-Identity/Image-Identity.md exists
• package.json has ai:image; .env.example names GOOGLE_API_KEY
• Root DESIGN.md exists (or user declined design-md)
• components.json includes @aura
• .cursor/mcp.json has shadcn MCP (user must enable in UI)

Optional smoke: pnpm dlx shadcn@latest add @aura/button only if the user asked to install a component; do not add random UI.

4. How to work after setup

• Consumer app: follow the skill port-component-to-aura in project mode — write into @/components aliases; do not create Ladle/registry metadata.
• Aura monorepo: skill registry mode — component + Ladle Default story + metadata/{kebab}.yml + registry:generate / registry:build.
• Landing with images: follow generate-brand-images. Read the blueprint 01-Identity notes first. If image identity is undefined, ask focused identity questions and update Image-Identity.md before generating.
• Gemini access: the bundled command reads GOOGLE_API_KEY or GEMINI_API_KEY directly from root .env. If absent, ask whether the user wants to add a key, use agent-native image generation when available, or continue with placeholders; never fabricate a key.
• Batch landing flow: inspect the landing, create one manifest for the necessary image set, run pnpm ai:image -- --manifest <path>, integrate accepted local assets, then record their paths in the wiki.
• Mobile form UX (critical): input / textarea / select font-size MUST be ≥ 17px. Never put text-sm or text-xs on editable fields—iOS Safari zooms on focus below that size. Keep html { font-size: 17px; } and the global floor in styles/main.css (font-size: max(1rem, 17px)). See Typography rules and DESIGN.md.
• Concepts: MCP overview · Rules · Installation

5. Final reply to the user (required format)

## Agent blueprint — result

**Project:** <path or package name>
**Scenario:** consumer | aura-monorepo

| Check | Before | Action | After |
| --- | --- | --- | --- |
| components.json @aura | … | … | … |
| DESIGN.md | … | … | … |
| .cursor/rules | … | … | … |
| .cursor/skills | … | … | … |
| Blueprint image identity | … | … | … |
| Gemini image command | … | … | … |
| .cursor/mcp.json | … | … | … |

**Manual step for you:** enable shadcn MCP in Cursor Settings (if not already green).

**Next:** paste a component URL to port it, or describe a landing page; the agent can plan and generate its identity-aligned image set.

Stop when the table is accurate. Do not claim MCP is connected if the user still needs to flip the Settings toggle.

Related

• MCP — what MCP/skills/rules are
• Rules — install @aura/rules
• Installation — aura CLI init
• CLI aura blueprint — separate; wiki/preflight/Sonar only