Skip to content

Open-source design agent: on-brand stills, decks, diagrams, charts and motion graphics from a chat thread, built on Deep Agents.

Agent-native setup for coding agents, and a landing-page README (#12)

Amal Irgashev0a16a3416d03
diff --git a/.agents/skills/design-agent-customize/SKILL.md b/.agents/skills/design-agent-customize/SKILL.md
new file mode 100644
index 0000000..b2ccd0c
--- /dev/null
+++ b/.agents/skills/design-agent-customize/SKILL.md
@@ -0,0 +1,62 @@
+---
+name: design-agent-customize
+description: Change what Design Agent knows and does. Teach it a new deliverable with a runtime skill, change its instructions, design doctrine or checks, connect MCP servers and tools, or change models and cost caps. Use when someone wants it to make something new, follow a new rule, or use another tool.
+---
+
+# Customize Design Agent
+
+Every kind of knowledge has one home. Find the owner before editing, so a fix lands once and every
+asset after it follows:
+
+| The change | Its home |
+| --- | --- |
+| Brand facts: colours, fonts, logos, voice, graphic language | `workspace/brand/` ([brand-onboarding](../brand-onboarding/SKILL.md)) |
+| A deliverable or workflow the team asks for often | a runtime skill, `skills/<name>/SKILL.md` |
+| Doctrine for every visual: hierarchy, type, colour, charts | `skills/design-wiki/references/` |
+| Identity, delivery and approval rules, how it talks | `instructions.md` (a budget test fails past about 8k tokens) |
+| A rule a machine can count | a check in `workspace/tools/` |
+| A tool or data source | an MCP server in `config/mcp.toml` |
+| Which model plays which role, effort, budgets | `.env` settings; [Models](../../../docs/models.md) |
+
+## Add a runtime skill
+
+Start with the graphic the team asks for every week.
+
+1. Read two skills close to it (`skills/stills/`, `skills/thumbnails/`) and `skills/design-wiki/SKILL.md`.
+2. Create `skills/<name>/SKILL.md` as a real folder one level deep (MDA does not follow symlinks
+ there). Frontmatter: `name` is the folder; `description` says when to use it, in the words
+ people use when they ask. Body: what good looks like, sizes, steps, the checks to run. Put depth
+ in `references/` and keep the body small.
+3. No brand facts, colours or libraries from a CDN in the skill: the brand pack supplies them.
+4. `uv run pytest -q tests/unit/test_taste_skills.py tests/unit/test_media_skills.py` checks
+ frontmatter, size, links, and that every tool, script and check it names exists.
+5. Try it with the request people actually send: `uv run design-agent ask "…"`. Look at the files.
+6. Add an eval task if it matters ([design-agent-evals](../design-agent-evals/SKILL.md)), then
+ redeploy ([design-agent-deploy](../design-agent-deploy/SKILL.md)).
+
+Vendored HyperFrames skills (listed in `skills-lock.json`) are never edited: override them in a
+sibling skill of ours, or send the change upstream.
+
+## Instructions, doctrine and checks
+
+- Phrase rules as defaults with a reason, or as checks with evidence. A rule about the model is
+ temporary; retest it when the model changes and delete what the new model outgrows.
+- A rule a machine can count belongs in code, as a check, not in prose.
+- After editing, run `uv run pytest -q`, then compare before and after with the evals.
+
+## Tools
+
+- **MCP servers:** copy `config/mcp.example.toml` to `config/mcp.toml` and declare servers. Locally,
+ header values come from the environment (`headers_env`); on MDA a server that needs credentials
+ names a workspace connection (`connection`). MDA serves HTTP and SSE only. Paper is configured
+ with `PAPER_*`, not here ([Paper](../../../docs/partners/paper.md)).
+- **Media keys:** `OPENAI_API_KEY` (images), `ELEVENLABS_API_KEY` (voice, music, sound effects),
+ `GROQ_API_KEY` (transcription).
+- **A new host tool** is code in `src/design_agent/tools/`: keys stay on the host and results drop
+ into the sandbox as files. Follow the change discipline in `AGENTS.md`.
+
+## Models and cost
+
+`uv run design-agent config set DESIGN_AGENT_MODEL=provider:model`, then
+`uv run design-agent test model`. `DESIGN_AGENT_JOB_BUDGET_USD` makes the agent ask before passing
+a budget; `DESIGN_AGENT_HELPER_EFFORT_CAP` caps helpers' effort. More: [Customization](../../../docs/customization.md).
diff --git a/.agents/skills/design-agent-deploy/SKILL.md b/.agents/skills/design-agent-deploy/SKILL.md
new file mode 100644
index 0000000..fc6ba88
--- /dev/null
+++ b/.agents/skills/design-agent-deploy/SKILL.md
@@ -0,0 +1,51 @@
+---
+name: design-agent-deploy
+description: Put Design Agent in a team's Slack. Deploy it to Managed Deep Agents (one command, managed Slack app) or self-host it with Docker Compose, verify it with a real request, ship updates, and keep a separate test copy. Use when someone wants the agent running for their team.
+---
+
+# Deploy Design Agent
+
+A deployment is what the team uses. Ask before `deploy`, before connecting Slack, and before
+anything that bills (publishing a snapshot, hosting). Never print a key; name missing settings.
+Setup comes first: `uv run design-agent doctor` should pass and the brand pack should validate
+(`design-agent-onboarding`, `brand-onboarding`).
+
+| | Managed Deep Agents (recommended) | Self-hosted |
+| --- | --- | --- |
+| Who runs it | LangSmith: runtime, sandboxes, Slack app, schedules | the person: API, Postgres, Docker host |
+| Needs | a LangSmith organization with MDA access and a deployment-capable `LANGSMITH_API_KEY` | Docker with Compose v2.24+ |
+| Cost | hosting is paid, plus model and media spend | their machine, plus model and media spend |
+
+## Managed Deep Agents
+
+1. **Publish the computer once.** `uv run design-agent sandbox build && uv run design-agent sandbox test`
+ proves the recipe locally; `uv run design-agent sandbox publish --fs-gib 16` builds the snapshot
+ in their workspace (sandbox time is billed). Publish again whenever `sandbox/setup.sh` changes.
+2. **Show what ships.** `uv run design-agent deploy --build-only` stages `.mda/deploy-src/` and
+ prints which secrets ship and which stay home. Walk the person through it.
+3. **Try a copy first.** `uv run design-agent deploy --name design-agent-test` is a separate
+ deployment; the team's agent is untouched.
+4. **Deploy** with `uv run design-agent deploy` after a yes. The first deploy provisions the Slack
+ app; the person authorizes it in their Slack workspace.
+5. **Verify with real requests:** a quick still, then a short storyboarded teaser. In Slack you
+ should see live progress, a check-in while it renders, and files attached at the end. Without
+ Slack, call the deployment's API ([docs/deploy-mda.md](../../../docs/deploy-mda.md) has the
+ snippet); files attach to the run's LangSmith trace. `uv run mda logs` tails the deployment.
+6. **Updates:** change, `deploy --build-only`, then `deploy`. A redeploy stops running helpers; each
+ affected thread offers to resume from its saved transcript.
+
+## Self-hosted
+
+1. `uv run design-agent config set DESIGN_AGENT_MODEL=…` (the person types the key or sets it in
+ `.env`), then `uv run design-agent config generate DESIGN_AGENT_API_TOKENS POSTGRES_PASSWORD`.
+2. `docker compose -f deploy/self-host/compose.yaml up -d --build`, then
+ `curl -s http://127.0.0.1:8080/health`.
+3. **Slack (optional):** create an app from `config/slack-manifest.example.yaml`, set
+ `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN`, then add `--profile slack` to the compose command.
+4. **Verify:** `POST /threads/{id}/messages` with `Authorization: Bearer <token>`, then poll
+ `GET /threads/{id}/updates` for background work.
+5. **Security:** the API starts sandboxes through the Docker socket, which is root-equivalent. Use a
+ dedicated host, or LangSmith sandboxes (`DESIGN_AGENT_SANDBOX=langsmith`) without the socket.
+
+A local preflight does not prove a deployment: only a real request does. Details:
+[Deploy with MDA](../../../docs/deploy-mda.md), [Self-hosting](../../../docs/self-hosting.md).
diff --git a/.agents/skills/design-agent-evals/SKILL.md b/.agents/skills/design-agent-evals/SKILL.md
new file mode 100644
index 0000000..b6ab334
--- /dev/null
+++ b/.agents/skills/design-agent-evals/SKILL.md
@@ -0,0 +1,25 @@
+---
+name: design-agent-evals
+description: Find out whether a change made Design Agent better or worse. Run the eval set or a few tasks before and after against the same model, read the reports, look at the files, and turn a real request that went wrong into a task. Use after changing instructions, skills, checks or models, or when someone asks how good it is.
+---
+
+# Evaluate a change
+
+Eval runs spend model and media money. `eval run` prints the budget: show it to the person and get
+a yes. The whole set costs about $120 per model; a few tasks cost a few dollars.
+
+1. `uv run design-agent eval list` shows every task with its dollar and minute caps.
+2. **Pick the tasks the change touches**, plus one behavior task: still tasks for a stills skill,
+ the teaser and film for motion, `exact-copy` for copy rules.
+3. **Run before and after, same model, same tasks:**
+ `uv run design-agent eval run --task <id> --task <id> --out workspace/out/evals/<label>`.
+4. **Read the reports.** Each folder has `report.json`, `README.md` (failed checks per task, spend,
+ time) and `files/<task>/`. Open the files and look at them. The graders check outputs, sizes,
+ copy and behavior, never taste: a person judges taste.
+5. **Report numbers from the reports:** checks passed, spend and time, before against after. Do not
+ summarize a run you did not read.
+6. **Turn a real failure into a task.** When a thread shows something going wrong, add an entry to
+ `tests/eval/tasks.json` modelled on a similar task (the request, expected outputs and sizes, exact
+ copy lines, budgets), then `uv run pytest -q tests/unit/test_evals.py`.
+
+Graders and reports: [Evals](../../../docs/evals.md).
diff --git a/.agents/skills/design-agent-onboarding/SKILL.md b/.agents/skills/design-agent-onboarding/SKILL.md
index 2909b49..06f36d7 100644
--- a/.agents/skills/design-agent-onboarding/SKILL.md
+++ b/.agents/skills/design-agent-onboarding/SKILL.md
@@ -27,11 +27,10 @@ by name. Do not deploy, connect accounts or publish anything until the person as
6. **Try it.** `uv run design-agent ask "Make a LinkedIn card announcing …"`. Finals land in
`workspace/out/<thread>/`, the last line estimates what the run cost, and `--thread <id>`
continues a conversation.
-7. **Choose where it runs.** Explain `docs/deploy-mda.md` (managed: runtime, sandbox, Slack,
- schedules; one command) and `docs/self-hosting.md` (Docker Compose with Postgres, your Slack app,
- your machine). For MDA: `uv run design-agent sandbox publish` once, then
- `uv run design-agent deploy --build-only` to inspect exactly what ships, then `deploy` when the
- person says so. For self-hosting: `config generate DESIGN_AGENT_API_TOKENS POSTGRES_PASSWORD`,
- then `docker compose -f deploy/self-host/compose.yaml up --build`.
-8. **Verify the deployment** with a real message in Slack (or `POST /threads/{id}/messages`): a
- quick still, then a short storyboarded teaser. A local preflight does not prove a deployment.
+7. **Choose where it runs.** Managed Deep Agents (managed runtime, sandboxes, Slack app and
+ schedules; one command) or self-hosted (Docker Compose with Postgres and their own Slack app).
+ The [design-agent-deploy](../design-agent-deploy/SKILL.md) skill takes it from there, including
+ verifying with a real request.
+8. **What next.** Teach it the deliverable the team asks for every week
+ ([design-agent-customize](../design-agent-customize/SKILL.md)), and measure changes with
+ [design-agent-evals](../design-agent-evals/SKILL.md).
diff --git a/.agents/skills/design-agent-troubleshoot/SKILL.md b/.agents/skills/design-agent-troubleshoot/SKILL.md
new file mode 100644
index 0000000..c724c84
--- /dev/null
+++ b/.agents/skills/design-agent-troubleshoot/SKILL.md
@@ -0,0 +1,35 @@
+---
+name: design-agent-troubleshoot
+description: Diagnose Design Agent when something fails. Setup, a render, a deploy, Slack or a model call. Run doctor and the connection tests, read logs and traces, match the symptom to its fix, and never print credentials. Use when a command errors, a reply never comes, or a file looks wrong.
+---
+
+# Troubleshoot Design Agent
+
+Report missing settings by name and never paste a key, token or `.env` line.
+
+1. `uv run design-agent doctor` (add `--json` to parse it) checks every model role, keys, the brand,
+ the sandbox, MDA declarations, MCP and Paper. Fix what it names first.
+2. Real calls, a few cents each: `uv run design-agent test model`, `test sandbox`, `test paper`,
+ `test slack`, `test db`.
+3. Match the symptom:
+
+| Symptom | Fix |
+| --- | --- |
+| `demo` needs a sandbox | start Docker, then `uv run design-agent sandbox build` |
+| A render is missing a font | `uv run design-agent fonts verify`; `family` in `fonts.toml` must be the name inside the file |
+| Off-brand colours or a failed brand check | `uv run design-agent brand validate`, then `brand css` |
+| "The connection to the model stalled" or "stayed unavailable" | check the provider's status, then reply `continue` in the thread |
+| Background news arrives a minute or two late on MDA | expected: MDA schedules land on the next minute |
+| "A restart may have stopped…" | a deploy or restart stopped helpers; ask the agent to resume them |
+| Paper "not connected" | Paper Desktop is closed or the bridge is down; boards still render in the sandbox |
+| `deploy` refuses the sandbox | `uv run design-agent sandbox publish` first |
+| An MCP server is missing | the startup log names the one that failed; the rest keep working |
+
+4. **Logs:** `uv run mda logs` on MDA; `docker compose -f deploy/self-host/compose.yaml logs api`
+ when self-hosted. Logs carry exception classes, never provider messages or keys.
+5. **Traces:** every run is traced in LangSmith (an MDA deployment's project is
+ `<deployment>-production`). Follow a bad file back to the skills read, tools called and checks
+ run. API runs attach delivered files to the trace.
+6. **A real bug:** reproduce it with a failing test before changing code, then follow `AGENTS.md`.
+
+More: [Operations](../../../OPERATIONS.md).
diff --git a/.agents/skills/design-agent-update/SKILL.md b/.agents/skills/design-agent-update/SKILL.md
new file mode 100644
index 0000000..fe3ed88
--- /dev/null
+++ b/.agents/skills/design-agent-update/SKILL.md
@@ -0,0 +1,21 @@
+---
+name: design-agent-update
+description: Bring a fork or clone of Design Agent up to date with the upstream repository while keeping the team's brand, skills and edits, rebuild what changed, and redeploy safely. Use when someone asks to update, upgrade or pull the latest Design Agent.
+---
+
+# Update from upstream
+
+The brand pack (`workspace/brand/`), licensed fonts (`private-fonts/`) and `.env` are Git-ignored,
+so an update never touches them. The team's own skills and instruction edits can conflict.
+
+1. `git status`. Commit the person's local work first, or ask; never use a bare `git stash`.
+2. Add the remote once: `git remote add upstream https://github.com/langchain-ai/design-agent.git`.
+ Then `git fetch upstream` and read the new entries in `CHANGELOG.md` for breaking changes.
+3. Merge `upstream/main` into the person's branch. In conflicts, keep their skills and instruction
+ edits and take upstream's code; ask when a conflict touches both.
+4. `uv sync`, `uv run design-agent doctor`, `uv run pytest -q`, `uv run design-agent skills verify`.
+5. If `sandbox/setup.sh` changed: `uv run design-agent sandbox build && uv run design-agent sandbox test`;
+ for Managed Deep Agents, also `uv run design-agent sandbox publish` (the snapshot name follows the
+ recipe's hash).
+6. Try the update on a test copy (`uv run design-agent deploy --name design-agent-test`), then
+ deploy the team's agent after a yes ([design-agent-deploy](../design-agent-deploy/SKILL.md)).
diff --git a/AGENTS.md b/AGENTS.md
index 49ae618..395a4ab 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,15 +1,32 @@
# Working in this repository
-Build a portable, open-source design agent with one shared core and two deployment paths: Managed
+Design Agent is an open-source design agent with one shared core and two deployment paths: Managed
Deep Agents (MDA, recommended, one command) and self-hosting (Docker). It makes on-brand stills,
decks, diagrams, charts and motion graphics from a chat thread, on its own computer, with HyperFrames
as the video engine and Paper as the shared canvas. Keep company-specific brands, credentials, fonts,
reference films and operational history out of the public repository.
-**Setting up or using Design Agent?** Follow
-[.agents/skills/design-agent-onboarding/SKILL.md](.agents/skills/design-agent-onboarding/SKILL.md)
-(and [brand-onboarding](.agents/skills/brand-onboarding/SKILL.md) for a brand). The rest of this
-file is for changing the agent.
+## What people ask you to do here
+
+Most people open this repository to set up, brand, deploy or extend their own design agent. Each
+job has a skill in `.agents/skills/` (Claude Code also finds them through `.claude/skills`). Open the
+matching `SKILL.md` and follow it:
+
+| The person wants to… | Skill |
+| --- | --- |
+| set it up, see the demo, connect a model or Paper | [design-agent-onboarding](.agents/skills/design-agent-onboarding/SKILL.md) |
+| add their brand from a guide, website, files or a Paper file | [brand-onboarding](.agents/skills/brand-onboarding/SKILL.md) |
+| put it in their team's Slack: deploy to MDA or self-host | [design-agent-deploy](.agents/skills/design-agent-deploy/SKILL.md) |
+| teach it a new deliverable, rule or tool, or change models | [design-agent-customize](.agents/skills/design-agent-customize/SKILL.md) |
+| check whether a change made it better or worse | [design-agent-evals](.agents/skills/design-agent-evals/SKILL.md) |
+| fix something that fails | [design-agent-troubleshoot](.agents/skills/design-agent-troubleshoot/SKILL.md) |
+| update their fork to the latest version | [design-agent-update](.agents/skills/design-agent-update/SKILL.md) |
+| move HyperFrames forward (maintainers) | [vendor-sync](.agents/skills/vendor-sync/SKILL.md) |
+| cut a release (maintainers) | [release-check](.agents/skills/release-check/SKILL.md) |
+
+For anything else, start from the map of every document, [docs/README.md](docs/README.md). Never
+print a key, and ask before deploying, connecting accounts or spending money. The rest of this file
+is the contract for changing the agent itself.
Code and tests are the source of truth; `SPEC.md` records the product intent behind them.
@@ -43,7 +60,7 @@ Code and tests are the source of truth; `SPEC.md` records the product intent beh
third-party footage, frames or contact sheets.
- `private-fonts/`: operator-supplied licensed fonts. Git-ignored; reach the sandbox only as
MDA deployment files or self-host mounts.
-- `agent.py`, `identity.py`, `channels/`, `schedules/`, `sandbox/`, `memory.py`: MDA project
+- `agent.py`, `identity.py`, `channels/`, `schedules/`, `sandbox/`, `tools/mcp.py`: MDA project
declarations. Keep them thin.
- `src/design_agent/assembly.py`: the shared model, tools, middleware, subagents and policy.
- `src/design_agent/harness/`: orchestration (background helpers, wake-ups, check-ins, durable
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 868e0e4..20977e2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,9 @@
### Added
+- Skills for coding agents to deploy, customize, evaluate, troubleshoot and update Design Agent,
+ routed from `AGENTS.md`, with a test that every skill is routed and names only real commands; a
+ map of every document (`docs/README.md`) and `llms.txt`.
- One shared Deep Agents assembly for Managed Deep Agents, the CLI and the self-hosted path, with
an exact-id model capability registry (Claude Opus 5.5 by default, direct providers, optional
LangSmith Gateway).
diff --git a/README.md b/README.md
index afc7524..a7fb2bd 100644
--- a/README.md
+++ b/README.md
@@ -16,258 +16,158 @@
<a href="https://www.python.org"><picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/badge/python-3.11%2B-7FC8FF.svg?variant=outline&logo=python&mode=dark"><img src="https://shieldcn.dev/badge/python-3.11%2B-006DDD.svg?variant=outline&logo=python&mode=light" alt="Python 3.11+"></picture></a>
<a href="https://github.com/langchain-ai/deepagents"><picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/badge/built%20on-Deep%20Agents-7FC8FF.svg?variant=outline&logo=lu:Layers&mode=dark"><img src="https://shieldcn.dev/badge/built%20on-Deep%20Agents-006DDD.svg?variant=outline&logo=lu:Layers&mode=light" alt="Built on Deep Agents"></picture></a>
<a href="https://docs.langchain.com/langsmith/python/managed-deep-agents-overview"><picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/badge/deploy-Managed%20Deep%20Agents-7FC8FF.svg?variant=outline&logo=lu:Rocket&mode=dark"><img src="https://shieldcn.dev/badge/deploy-Managed%20Deep%20Agents-006DDD.svg?variant=outline&logo=lu:Rocket&mode=light" alt="Deploy with Managed Deep Agents"></picture></a>
- <a href="docs/self-hosting.md"><picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/badge/self--host-Docker-7FC8FF.svg?variant=outline&logo=docker&mode=dark"><img src="https://shieldcn.dev/badge/self--host-Docker-006DDD.svg?variant=outline&logo=docker&mode=light" alt="Self-host with Docker"></picture></a>
- <a href="https://hyperframes.heygen.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/badge/video-HyperFrames-7FC8FF.svg?variant=outline&logo=lu:Clapperboard&mode=dark"><img src="https://shieldcn.dev/badge/video-HyperFrames-006DDD.svg?variant=outline&logo=lu:Clapperboard&mode=light" alt="Video with HyperFrames"></picture></a>
- <a href="https://paper.design"><picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/badge/canvas-Paper-7FC8FF.svg?variant=outline&logo=lu:PenTool&mode=dark"><img src="https://shieldcn.dev/badge/canvas-Paper-006DDD.svg?variant=outline&logo=lu:PenTool&mode=light" alt="Canvas in Paper"></picture></a>
</p>
<p>
- <a href="#get-started">Get started</a> ·
- <a href="#how-it-works">How it works</a> ·
- <a href="#deploy-it">Deploy</a> ·
- <a href="OPERATIONS.md">Docs</a> ·
- <a href="CONTRIBUTING.md">Contributing</a>
+ <b><a href="#see-it-work">▶ Watch the 2-minute film</a></b> ·
+ <b><a href="#get-started">Get started in 5 minutes</a></b> ·
+ <a href="docs/README.md">Docs</a>
</p>
</div>
-<p align="center">
- <img src="https://github.com/langchain-ai/design-agent/raw/main/docs/assets/readme/hero.png" alt="Design Agent at work: a Slack request for a launch film, and the agent's computer with its project folders, a HyperFrames render in the terminal, the film preview, layers and references" width="100%">
-</p>
-
-We built Design Agent as our own design teammate at LangChain, and now it's open source.
+**Build your company's design agent, batteries included.** Fork it, add your brand, and put it in
+your team's Slack with Managed Deep Agents. People ask it like they'd ask a designer and get
+finished, on-brand graphics, decks, diagrams and films back.
-You ask for something the way you'd ask a designer: "a LinkedIn card for Thursday's launch", "turn
-this into a 2x2", "a 30-second teaser for the new release". It picks a concept, lays the piece out,
-builds it on its own computer, checks it against your brand, and posts the files back to you. For
-anything big, like a film, it shows you a storyboard first, and you approve it before it renders.
-
-> [!NOTE]
-> Everything you see here uses LangChain's brand, because that's the brand we run it with. Out of
-> the box Design Agent uses a neutral sample brand, and it switches to yours as soon as you add
-> your brand pack (see [Make it yours](#make-it-yours)).
+It's the agent we run at LangChain. Since August it has shipped over 3,000 assets, posts with its
+work drew about 4.5M views on X, and three in four requests come from outside marketing.
## See it work
<p align="center">
- <a href="https://github.com/langchain-ai/design-agent/blob/main/docs/assets/readme/design-agent-explainer.mp4"><img src="https://github.com/langchain-ai/design-agent/raw/main/docs/assets/readme/film-thumbnail.png" alt="Play the 2-minute film: How Design Agent works, one Slack request from the sandbox to the final film" width="100%"></a>
- <br><sub><b><a href="https://github.com/langchain-ai/design-agent/blob/main/docs/assets/readme/design-agent-explainer.mp4">▶ Click to watch the 2-minute film</a></b>: one Slack request, from the sandbox to skills, Paper, the helpers, HyperFrames, the checks and the sound.</sub>
+ <a href="https://github.com/langchain-ai/design-agent/raw/main/docs/assets/readme/design-agent-explainer.mp4"><img src="docs/assets/readme/film-thumbnail.png" alt="Play the 2-minute film: how Design Agent goes from one Slack request to a finished film" width="100%"></a>
</p>
-## What you can ask for
+<p align="center"><sub>One Slack request for a launch film: the plan, the storyboard, helpers rendering in parallel, the checks and the final cut.</sub></p>
-- **Social cards and ad sets:** one layout, recomposed for every size you need. It doesn't just
- scale it down.
-- **Slides, one-pagers and decks**, as PNG or PDF.
-- **Diagrams and charts**, drawn from your data. The numbers are computed in code, never
- eyeballed.
-- **Thumbnails, banners and GIFs.**
-- **Short films and motion graphics:** storyboard first, then a
- [HyperFrames](https://hyperframes.heygen.com) render, with voice, music and sound if you add
- the keys.
-- **Work on a shared canvas:** layouts and storyboards land in [Paper](https://paper.design) as
- editable layers, if you connect it.
+| Building it yourself | Starting here |
+| --- | --- |
+| Months on a harness, a sandbox, skills and a Slack UX | Fork it, add your brand, deploy with one command |
+| A coding agent that makes the look every AI makes | Work that follows your brand, checked on every render |
+| Design requests wait in a queue | Anyone asks in Slack: a graphic in minutes, a film overnight |
+| Every team fixes the same mistakes | Fix a skill once, and every asset after gets better |
+
+## Batteries included
+
+- **A lead agent that works for hours.** It plans, takes your notes mid-job, and hands long work to
+ helpers running in parallel.
+- **A designer's computer for every thread,** with Chrome, FFmpeg,
+ [HyperFrames](https://hyperframes.heygen.com), D2 and your fonts. Keys stay outside it.
+- **35 skills and a design wiki** for stills, decks, charts, diagrams, storyboards, motion, sound
+ and thumbnails.
+- **Your brand as code:** colours, fonts, logos and voice in one pack, checked on every render.
+- **The Slack experience:** a plan and ETA, live progress, steering mid-job, and approval before
+ anything goes public.
+- **A shared canvas** in [Paper](https://paper.design) for storyboards and layouts.
+- **Evals built from real requests,** and every run traced in LangSmith.
+- **One-command deploy** to Managed Deep Agents, or self-host it with Docker.
+- **Skills for your coding agent** to set it up, brand it, deploy it, extend it and fix it.
## Get started
-You need **Python 3.11+**, [uv](https://docs.astral.sh/uv/) and **Docker**. Setup takes about five
-minutes, plus a few more the first time Docker builds the agent's computer.
+**Hand it to your coding agent.** Open Claude Code, Codex or Cursor in the repo and say what you
+want. [AGENTS.md](AGENTS.md) sends it to the right [skill](.agents/skills/):
+
+| Say | It will |
+| --- | --- |
+| "Set up Design Agent and run the demo." | install it, build its computer, and render a demo with no API keys |
+| "Build our brand pack from our website and brand guide." | draft the pack, validate it, and ask you to review it |
+| "Deploy it to our Slack." | publish the sandbox, show you what ships, and deploy after your yes |
+| "Teach it to make our weekly newsletter header." | add a skill for it and try it on a real request |
+| "Did that change make it better?" | run the evals before and after, and show you the numbers |
-**1. Install it and watch the demo.** The demo needs no API keys. It runs the real agent,
-sandbox and checks with a scripted model, and renders a launch card in three sizes plus a
-4-second teaser into `workspace/out/demo/`.
+**Or by hand.** You need **Python 3.11+**, [uv](https://docs.astral.sh/uv/) and **Docker**. The demo
+runs the real agent, sandbox and checks with a scripted model, and leaves a launch card in three
+sizes and a 4-second teaser in `workspace/out/demo/`:
```bash
-git clone https://github.com/langchain-ai/design-agent.git
-cd design-agent
+git clone https://github.com/langchain-ai/design-agent.git && cd design-agent
uv sync
uv run design-agent sandbox build
uv run design-agent demo
```
-**2. Connect a model.** Put `ANTHROPIC_API_KEY=…` in `.env` yourself, so the key stays out of your
-shell history. Then:
-
-```bash
-uv run design-agent config set DESIGN_AGENT_MODEL=anthropic:claude-opus-5-5
-uv run design-agent test model
-```
-
-**3. Ask for something.**
+Then put `ANTHROPIC_API_KEY=…` in `.env` and ask for something real. Files land in
+`workspace/out/<thread>/`, and the last line tells you what the run cost:
```bash
uv run design-agent ask "A LinkedIn card announcing our design review service, 1200x627."
```
-Your files land in `workspace/out/<thread>/`, and the last line tells you roughly what the run
-cost. Add `--thread <id>` to keep a conversation going.
+## Why it doesn't look like AI
-**Rather have your coding agent set it up?** Open Claude Code, Codex or Cursor in the repo and
-paste this:
+- **It looks at its work.** It renders, then looks at the image before it posts anything.
+- **Your brand is code.** Layouts only take your tokens: your colours, fonts and spacing.
+- **It checks what a machine can count.** Colours, fonts, contrast, sizes and chart math are checked
+ in code on every render. Taste stays with your designers.
+- **Big pieces start cheap.** A film starts as a plan and a storyboard, and nothing renders until you
+ say yes.
-> Read AGENTS.md and .agents/skills/design-agent-onboarding/SKILL.md. Help me connect a model, add
-> my brand, connect Paper, and choose a deployment path.
+<p align="center">
+ <img src="docs/assets/readme/hero.png" alt="The agent's computer: a Slack request for a launch film, project folders, a HyperFrames render in the terminal, the film preview, layers and references" width="100%">
+</p>
## Make it yours
-Your brand lives in `workspace/brand/`. It holds your colours and the role each one plays, fonts,
-logos, voice and graphic language, and it's the only place the agent learns your brand from. The
-[brand-onboarding skill](.agents/skills/brand-onboarding/SKILL.md) builds it from your brand guide,
-your website, a folder of files or a Paper file. Then `brand validate` and `fonts verify` check it.
-
-| Want | Add | More |
+| Want | Add | Guide |
| --- | --- | --- |
-| Your brand | `workspace/brand/` (until then, the sample brand) | [brand-onboarding skill](.agents/skills/brand-onboarding/SKILL.md) |
+| Your brand | `workspace/brand/` (until then, a neutral sample brand) | [brand-onboarding skill](.agents/skills/brand-onboarding/SKILL.md) |
| Generated images | `OPENAI_API_KEY` | [Models](docs/models.md) |
| Voice, music, sound effects | `ELEVENLABS_API_KEY` | [sound skill](skills/sound/SKILL.md) |
-| The Paper canvas | `PAPER_MODE=local` with Paper Desktop, or `bridged` for a deployed agent | [Paper](docs/partners/paper.md) |
+| The Paper canvas | `PAPER_MODE=local` with Paper Desktop, or `bridged` when deployed | [Paper](docs/partners/paper.md) |
| Web search, your docs, other tools | MCP servers in `config/mcp.toml` | [Customization](docs/customization.md) |
-Licensed fonts go in `private-fonts/`. Git ignores that folder, so they never get committed.
+Everything on this page uses LangChain's brand, because that's the one we run. Licensed fonts go in
+`private-fonts/`, which Git ignores.
## Deploy it
-Same agent, two ways to run it.
-
| | Managed Deep Agents (recommended) | Self-hosted |
| --- | --- | --- |
-| Get going | `uv run design-agent sandbox publish`, then `uv run design-agent deploy` | `docker compose -f deploy/self-host/compose.yaml up -d --build` |
+| Start | `uv run design-agent sandbox publish`, then `uv run design-agent deploy` | `docker compose -f deploy/self-host/compose.yaml up -d --build` |
| Who runs it | LangSmith | you: the API, Postgres and a Docker host |
| Slack | a managed app you authorize | your own Slack app |
| Guide | [Deploy with MDA](docs/deploy-mda.md) | [Self-hosting](docs/self-hosting.md) |
-`deploy` shows you exactly which settings it will ship and asks before it deploys anything. Want
-to try a change without touching your team's agent? Run `deploy --name design-agent-test` and you
-get a separate copy. Managed Deep Agents needs a LangSmith organization with MDA access, and
-[hosting is paid](https://www.langchain.com/pricing). Model, image and audio usage is billed by your
-providers either way.
+`deploy` shows exactly what it will ship and asks first. `deploy --name design-agent-test` gives you
+a separate copy to try changes on.
-## How it works
+## Questions
-Under the hood there are three parts we built for design work, sitting on top of parts we didn't
-have to build:
-
-- **The lead and its helpers.** The lead reads your brief, picks the concept and writes a plan.
- It does small jobs itself. Big ones it hands to helpers that work in parallel: three directions
- to compare, or one act each of a film.
-- **The context.** Skills, a design wiki, your brand pack and memory. It loads only what the job
- in front of it needs.
-- **The designer's computer.** A sandbox with real tools: Chrome, FFmpeg, HyperFrames, D2 and
- your fonts. Everything is built and checked there.
-- **Off the shelf:** the [Deep Agents](https://github.com/langchain-ai/deepagents) harness,
- [Managed Deep Agents](https://docs.langchain.com/langsmith/python/managed-deep-agents-overview)
- (or your own infrastructure) and a frontier model.
-
-The split that matters: **the model makes the creative calls, and code does everything that has
-to be exactly right.** That means rendering, measuring, checking, delivering files and holding
-your keys.
-
-<details>
-<summary><b>The architecture, in more detail</b></summary>
-
-One assembly (`src/design_agent/assembly.py`) builds the model, tools, middleware and helpers.
-Runtime profiles plug it into Managed Deep Agents, the CLI, the self-hosted API, Slack and
-schedules.
-
-**The lead and its helpers**
-
-- Each thread gets one lead. It writes a plan in the thread's project folder and decides what to
- delegate.
-- Helpers run in the background on the same sandbox and files. Each one has a heartbeat, a
- durable transcript, and a lead that can steer it.
-- Nobody sits and waits. Render watchers and check-ins wake the lead when work lands, fails or
- stalls: one-time schedules on Managed Deep Agents, an in-process waker everywhere else.
-- Before anything ships, the lead and helpers look at their own renders with a vision `look`
- tool.
-
-**The context**
-
-- The always-on prompt is small, about 4k tokens. Workflows live in [skills](skills/)
- (`skills/<name>/SKILL.md`) and load on demand. On Managed Deep Agents they mount read-only from
- Context Hub.
-- Brand facts come only from the brand pack. It's staged into the sandbox with its fonts and logos.
-- Context stays bounded:
- - Long tool results go to files, with a short summary in the conversation.
- - Provider tool search loads MCP tools only when they're needed.
- - Helpers can clear old tool results server-side.
- - Prompt caching keeps the lead's prefix warm for an hour.
-
-**The designer's computer**
-
-- One recipe, [`sandbox/setup.sh`](sandbox/), pins Chrome Headless Shell, FFmpeg, HyperFrames,
- sharp, ECharts, D2 and open fonts by version and sha256. It ends with a probe that renders a
- page, a film and a diagram. The same recipe builds:
- - the local and self-hosted Docker image;
- - the LangSmith snapshot that Managed Deep Agents clones for each thread;
- - the CI image.
-- Every thread gets its own sandbox, and its files persist in `/workspace/projects/` between turns.
- - Locally, it's a container with no network, dropped capabilities, an unprivileged user, and
- limits capped to your machine.
- - On Managed Deep Agents, it's a LangSmith sandbox (16 GiB disk, 8 vCPU) with default-deny
- egress.
-- Before a run, a manifest with a sha256 checklist stages skills, the checks, your brand pack and
- its fonts into `/workspace`, read-only.
-
-**The checks** ([`workspace/tools/`](workspace/tools/README.md)) run before anything is delivered:
-
-| Check | What it catches |
-| --- | --- |
-| `brand-lint` | off-brand colours, fonts, radii and copy |
-| `video-gate`, `hyperframes check` | non-deterministic animation, layout, motion and contrast problems |
-| `artifact-contract` | a wrong size or duration, a missing file, a blank first frame |
-| font check | a brand font that silently fell back, web fonts included |
-| chart and graph contracts | truncated baselines, mixed units, shares that don't add up to 100%, a diagram that changed shape |
-
-**Keys stay outside.** The sandbox never holds a credential. Host tools run next to the agent,
-keep the keys, and drop their results in as files:
-
-- image generation;
-- voice, music and sound effects;
-- transcription;
-- an asset fetcher with SSRF protection;
-- Paper, scoped by a policy;
-- your MCP servers;
-- delivery: to Slack, to `workspace/out/` locally, or attached to the LangSmith trace for API
- runs.
-
-**Where each piece runs**
-
-| | Managed Deep Agents | Self-hosted |
-| --- | --- | --- |
-| Agent | `agent.py` (`define_deep_agent`), `identity.py`, `tools/mcp.py` | the same assembly in a FastAPI app |
-| Threads and memory | LangSmith | Postgres checkpointer and store |
-| Sandboxes | LangSmith sandboxes from your snapshot (`sandbox/__init__.py`) | containers on your Docker host |
-| Slack | managed app (`channels/slack.py`) | your Bolt app, Socket Mode or signed HTTP |
-| Wake-ups and housekeeping | runtime schedules; `schedules/housekeeping.py` every 15 minutes | in-process waker and maintenance loop |
-| Skills | synced to Context Hub; binary files ship as deployment files | read from the checkout |
+**What does it cost?** The code is free (Apache 2.0). You pay your model provider: at LangChain the
+median request costs about 50 cents in model spend, and long films and decks cost more. Managed Deep
+Agents [hosting is paid](https://www.langchain.com/pricing).
-**Models.** Claude Opus 5.5 is the default, and any tool-calling model with vision works. A
-registry keyed by exact model id sets effort, tool search and output limits per role: lead,
-helper, look, tool selector and learning. The optional [LangSmith Gateway](docs/models.md) uses
-each provider's native route, so caching and context editing keep working. Every call is metered
-per job, helper and role, and LangSmith traces every run.
+**Will it use my brand?** Yes. Add your brand pack and every file follows it. Your coding agent
+builds the pack with you from your brand guide, website, files or a Paper file.
-Go deeper: [Architecture](docs/architecture/README.md) ·
-[Orchestration](docs/architecture/orchestration.md) ·
-[Context and failures](docs/architecture/context-and-failures.md).
+**Where do I start?** With the graphic your team asks for every week. Let people brief the agent,
+review the work and ask for changes in Slack, then teach it the next thing.
-</details>
+**Do I need Slack?** No. Use the terminal (`design-agent ask`), the self-hosted HTTP API, or a
+deployment's API.
-## FAQ
+**Is it safe with my keys?** The sandbox never holds a credential and has no network by default.
+Host tools do the fetching, generating and delivering, and drop results in as files.
-**Can it use my brand instead of LangChain's?** Yes, that's the whole point of the brand pack. Add
-yours and every output follows it.
+**Which models?** Claude Opus 5.5 by default. OpenAI and Google models, any OpenAI-compatible
+endpoint and the LangSmith Gateway work too. See [Models](docs/models.md).
-**Which models does it work with?** Claude Opus 5.5 by default. OpenAI and Google models work
-through the same registry, and so do any OpenAI-compatible endpoint and the LangSmith Gateway.
-See [Models](docs/models.md).
+**Does it replace a designer?** No. It takes the repetitive requests, so designers spend their time on
+the work only they can do, and their judgment lives on in its skills and checks.
-**Do I need Slack?** No. You can use the terminal (`design-agent ask`), the self-hosted HTTP API,
-or a Managed Deep Agents deployment's API.
+## How it works
+
+The model makes the creative calls. Code does everything that has to be exactly right: rendering,
+measuring, checking, delivering files and holding your keys. It's built on the
+[Deep Agents](https://github.com/langchain-ai/deepagents) harness and runs on
+[Managed Deep Agents](https://docs.langchain.com/langsmith/python/managed-deep-agents-overview) or
+your own infrastructure.
-**Can the agent reach the internet or my keys?** No. The sandbox has no network by default and
-never holds a credential. Host tools do the fetching, generating and delivering for it.
+Read the [architecture](docs/architecture/README.md), or start changing it:
+[instructions.md](instructions.md) · [skills/](skills/) · [Customization](docs/customization.md) ·
+[Evals](docs/evals.md) · [Operations](OPERATIONS.md) · [Contributing](CONTRIBUTING.md).
-**How do I know the output is any good?** Every file goes through the checks before you get it,
-and the [eval set](docs/evals.md) grades outputs, copy and behaviour without a model judging taste.
+**Build yours.** Fork the repo and ask your coding agent to set it up. [Get started](#get-started).
## Built with
@@ -287,18 +187,6 @@ Also: [LangSmith](https://smith.langchain.com) ·
[sharp](https://sharp.pixelplumbing.com). Logos belong to their owners. HyperFrames and Paper are
partner projects we build on.
-## Build on it
-
-| Want to change or explore | Start here |
-| --- | --- |
-| Instructions, skills and taste | [instructions.md](instructions.md) · [skills/](skills/) · [Customization](docs/customization.md) |
-| Models and cost | [Models](docs/models.md) · [Context and failures](docs/architecture/context-and-failures.md) |
-| Background work, wake-ups, pipelines | [Orchestration](docs/architecture/orchestration.md) |
-| The sandbox and the checks | [sandbox/](sandbox/) · [workspace/tools/](workspace/tools/README.md) |
-| Evals | [Evals](docs/evals.md) |
-| Running it day to day | [Operations](OPERATIONS.md) |
-| Contributing | [Contributing](CONTRIBUTING.md) · [Agent instructions](AGENTS.md) · [Coding-agent skills](.agents/skills/) |
-
---
[Apache 2.0](LICENSE) · [Notices](NOTICE.md) · [Changelog](CHANGELOG.md) · [Security](SECURITY.md) · [Code of conduct](CODE_OF_CONDUCT.md)
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..27512d8
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,47 @@
+# Documentation
+
+Every guide, by what you're trying to do. Coding agents: the skills in
+[.agents/skills/](../.agents/skills/) walk through each job step by step; [AGENTS.md](../AGENTS.md)
+says which one fits.
+
+## Set it up and make it yours
+
+| Guide | Covers |
+| --- | --- |
+| [README](../README.md#get-started) | the five-minute demo and your first request |
+| [CLI](cli.md) | every `design-agent` command |
+| [Models](models.md) | providers, the LangSmith Gateway, roles, effort, cost |
+| [Customization](customization.md) | brand packs, instructions, runtime skills, learning, MCP servers |
+| [Paper](partners/paper.md) | the shared canvas: local, bridged and off |
+| [HyperFrames](partners/hyperframes.md) | the video engine and its vendored skills |
+
+## Run it for your team
+
+| Guide | Covers |
+| --- | --- |
+| [Deploy with MDA](deploy-mda.md) | publishing the sandbox, what ships, deploying, verifying |
+| [Self-hosting](self-hosting.md) | Docker Compose, the HTTP API, your own Slack app, security |
+| [Paper hosted worker](partners/paper-hosted-worker.md) | Paper Desktop on a server for a deployed agent |
+| [Operations](../OPERATIONS.md) | configuration, the sandbox, costs, troubleshooting, upgrades, backups |
+
+## Know it's working
+
+| Guide | Covers |
+| --- | --- |
+| [Evals](evals.md) | the design set, behaviors, graders, reports |
+
+## How it's built
+
+| Guide | Covers |
+| --- | --- |
+| [Architecture](architecture/README.md) | the assembly, the lead and helpers, context, the sandbox, checks, keys |
+| [Orchestration](architecture/orchestration.md) | background helpers, wake-ups, restarts, pipelines |
+| [Context and failures](architecture/context-and-failures.md) | what the model sees, caching, cost, failure boundaries |
+| [Surfaces](architecture/surfaces.md) | Slack progress and steering, the API, the CLI |
+| [Upstream](upstream.md) | seams we work around and what we've asked for |
+| [Official links](sources/official-links.md) | primary documentation for every external contract |
+
+## Contribute
+
+[Contributing](../CONTRIBUTING.md) · [Agent instructions](../AGENTS.md) · [Security](../SECURITY.md) ·
+[Changelog](../CHANGELOG.md)
diff --git a/docs/architecture/README.md b/docs/architecture/README.md
index c443d85..fdbb0a9 100644
--- a/docs/architecture/README.md
+++ b/docs/architecture/README.md
@@ -18,3 +18,87 @@ helpers in the same sandbox; their ends wake the lead.
Trust boundaries: model output, user files, Slack events, canvas content, MCP metadata and web pages
are data. Keys live in host tools; the sandbox has no credentials and no network by default.
+
+## The lead and its helpers
+
+- Each thread gets one lead. It writes a plan in the thread's project folder and decides what to
+ delegate.
+- Helpers run in the background on the same sandbox and files. Each one has a heartbeat, a
+ durable transcript, and a lead that can steer it.
+- Nobody sits and waits. Render watchers and check-ins wake the lead when work lands, fails or
+ stalls: one-time schedules on Managed Deep Agents, an in-process waker everywhere else.
+- Before anything ships, the lead and helpers look at their own renders with a vision `look`
+ tool.
+
+## The context
+
+- The always-on prompt is small, about 4k tokens. Workflows live in [skills](../../skills/)
+ (`skills/<name>/SKILL.md`) and load on demand. On Managed Deep Agents they mount read-only from
+ Context Hub.
+- Brand facts come only from the brand pack. It's staged into the sandbox with its fonts and logos.
+- Context stays bounded:
+ - Long tool results go to files, with a short summary in the conversation.
+ - Provider tool search loads MCP tools only when they're needed.
+ - Helpers can clear old tool results server-side.
+ - Prompt caching keeps the lead's prefix warm for an hour.
+
+## The designer's computer
+
+- One recipe, [`sandbox/setup.sh`](../../sandbox/), pins Chrome Headless Shell, FFmpeg, HyperFrames,
+ sharp, ECharts, D2 and open fonts by version and sha256. It ends with a probe that renders a
+ page, a film and a diagram. The same recipe builds:
+ - the local and self-hosted Docker image;
+ - the LangSmith snapshot that Managed Deep Agents clones for each thread;
+ - the CI image.
+- Every thread gets its own sandbox, and its files persist in `/workspace/projects/` between turns.
+ - Locally, it's a container with no network, dropped capabilities, an unprivileged user, and
+ limits capped to your machine.
+ - On Managed Deep Agents, it's a LangSmith sandbox (16 GiB disk, 8 vCPU) with default-deny
+ egress.
+- Before a run, a manifest with a sha256 checklist stages skills, the checks, your brand pack and
+ its fonts into `/workspace`, read-only.
+
+## The checks
+
+The checks ([`workspace/tools/`](../../workspace/tools/README.md)) run before anything is delivered:
+
+| Check | What it catches |
+| --- | --- |
+| `brand-lint` | off-brand colours, fonts, radii and copy |
+| `video-gate`, `hyperframes check` | non-deterministic animation, layout, motion and contrast problems |
+| `artifact-contract` | a wrong size or duration, a missing file, a blank first frame |
+| font check | a brand font that silently fell back, web fonts included |
+| chart and graph contracts | truncated baselines, mixed units, shares that don't add up to 100%, a diagram that changed shape |
+
+## Keys stay outside
+
+The sandbox never holds a credential. Host tools run next to the agent,
+keep the keys, and drop their results in as files:
+
+- image generation;
+- voice, music and sound effects;
+- transcription;
+- an asset fetcher with SSRF protection;
+- Paper, scoped by a policy;
+- your MCP servers;
+- delivery: to Slack, to `workspace/out/` locally, or attached to the LangSmith trace for API
+ runs.
+
+## Where each piece runs
+
+| | Managed Deep Agents | Self-hosted |
+| --- | --- | --- |
+| Agent | `agent.py` (`define_deep_agent`), `identity.py`, `tools/mcp.py` | the same assembly in a FastAPI app |
+| Threads and memory | LangSmith | Postgres checkpointer and store |
+| Sandboxes | LangSmith sandboxes from your snapshot (`sandbox/__init__.py`) | containers on your Docker host |
+| Slack | managed app (`channels/slack.py`) | your Bolt app, Socket Mode or signed HTTP |
+| Wake-ups and housekeeping | runtime schedules; `schedules/housekeeping.py` every 15 minutes | in-process waker and maintenance loop |
+| Skills | synced to Context Hub; binary files ship as deployment files | read from the checkout |
+
+## Models
+
+Claude Opus 5.5 is the default, and any tool-calling model with vision works. A
+registry keyed by exact model id sets effort, tool search and output limits per role: lead,
+helper, look, tool selector and learning. The optional [LangSmith Gateway](../models.md) uses
+each provider's native route, so caching and context editing keep working. Every call is metered
+per job, helper and role, and LangSmith traces every run.
diff --git a/llms.txt b/llms.txt
new file mode 100644
index 0000000..385cf4b
--- /dev/null
+++ b/llms.txt
@@ -0,0 +1,32 @@
+# Design Agent
+
+> An open-source design agent for a whole company. People ask it in Slack, like they'd ask a designer, and get finished, on-brand graphics, decks, diagrams, charts and short films back. It plans the piece, builds it on its own sandbox computer (Chrome, FFmpeg, HyperFrames), checks it against the company's brand in code, and delivers the files. Built on Deep Agents; deploys to Managed Deep Agents in one command, or self-hosts with Docker. Apache 2.0.
+
+Working in a clone? Read AGENTS.md first: it maps each job (setup, brand, deploy, customize, evals, troubleshooting, updates) to a step-by-step skill in .agents/skills/.
+
+## Start
+
+- [README](https://github.com/langchain-ai/design-agent/blob/main/README.md): what it is, the five-minute demo, first request
+- [AGENTS.md](https://github.com/langchain-ai/design-agent/blob/main/AGENTS.md): instructions for coding agents, and which skill fits each job
+- [Documentation map](https://github.com/langchain-ai/design-agent/blob/main/docs/README.md): every guide by task
+
+## Skills for coding agents
+
+- [Set up](https://github.com/langchain-ai/design-agent/blob/main/.agents/skills/design-agent-onboarding/SKILL.md): install, demo, model, Paper, first request
+- [Add a brand](https://github.com/langchain-ai/design-agent/blob/main/.agents/skills/brand-onboarding/SKILL.md): build the brand pack from a guide, website, files or Paper
+- [Deploy](https://github.com/langchain-ai/design-agent/blob/main/.agents/skills/design-agent-deploy/SKILL.md): Managed Deep Agents or self-hosted, with Slack
+- [Customize](https://github.com/langchain-ai/design-agent/blob/main/.agents/skills/design-agent-customize/SKILL.md): new deliverables, rules, tools and models
+- [Evals](https://github.com/langchain-ai/design-agent/blob/main/.agents/skills/design-agent-evals/SKILL.md): measure a change before and after
+- [Troubleshoot](https://github.com/langchain-ai/design-agent/blob/main/.agents/skills/design-agent-troubleshoot/SKILL.md): doctor, connection tests, logs, traces
+- [Update](https://github.com/langchain-ai/design-agent/blob/main/.agents/skills/design-agent-update/SKILL.md): bring a fork up to date
+
+## Reference
+
+- [CLI](https://github.com/langchain-ai/design-agent/blob/main/docs/cli.md)
+- [Architecture](https://github.com/langchain-ai/design-agent/blob/main/docs/architecture/README.md)
+- [Deploy with Managed Deep Agents](https://github.com/langchain-ai/design-agent/blob/main/docs/deploy-mda.md)
+- [Self-hosting](https://github.com/langchain-ai/design-agent/blob/main/docs/self-hosting.md)
+- [Customization](https://github.com/langchain-ai/design-agent/blob/main/docs/customization.md)
+- [Models](https://github.com/langchain-ai/design-agent/blob/main/docs/models.md)
+- [Evals](https://github.com/langchain-ai/design-agent/blob/main/docs/evals.md)
+- [Operations](https://github.com/langchain-ai/design-agent/blob/main/OPERATIONS.md)
diff --git a/tests/unit/test_coding_agent_skills.py b/tests/unit/test_coding_agent_skills.py
new file mode 100644
index 0000000..7e5c856
--- /dev/null
+++ b/tests/unit/test_coding_agent_skills.py
@@ -0,0 +1,53 @@
+"""Coding agents find every job through AGENTS.md, and every skill names only commands that exist."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+
+from design_agent.cli import main
+
+ROOT = Path(__file__).resolve().parents[2]
+SKILLS = ROOT / ".agents" / "skills"
+FRONTMATTER = re.compile(
+ r"\A---\nname: (?P<name>[^\n]+)\ndescription: (?P<description>[^\n]+)\n---\n"
+)
+COMMAND = re.compile(r"design-agent ([a-z][a-z-]*)(?: ([a-z][a-z-]*))?")
+
+
+def skill_dirs() -> list[Path]:
+ return sorted(p for p in SKILLS.iterdir() if p.is_dir())
+
+
[email protected]("skill", skill_dirs(), ids=lambda p: p.name)
+def test_frontmatter_names_the_folder_and_says_when_to_use_it(skill: Path) -> None:
+ match = FRONTMATTER.match((skill / "SKILL.md").read_text(encoding="utf-8"))
+ assert match, f"{skill.name}/SKILL.md needs name and description frontmatter"
+ assert match["name"] == skill.name
+ assert len(match["description"]) >= 60, f"{skill.name}: say what it does and when to use it"
+
+
+def test_agents_md_routes_to_every_skill() -> None:
+ agents = (ROOT / "AGENTS.md").read_text(encoding="utf-8")
+ missing = [p.name for p in skill_dirs() if f".agents/skills/{p.name}/SKILL.md" not in agents]
+ assert not missing, f"AGENTS.md has no route to: {missing}"
+
+
+def test_claude_code_sees_the_same_skills() -> None:
+ link = ROOT / ".claude" / "skills"
+ assert link.is_symlink() and link.resolve() == SKILLS.resolve()
+
+
[email protected]("skill", skill_dirs(), ids=lambda p: p.name)
+def test_every_command_named_exists(skill: Path) -> None:
+ text = (skill / "SKILL.md").read_text(encoding="utf-8")
+ unknown: list[str] = []
+ for name, sub in COMMAND.findall(text):
+ command = main.commands.get(name)
+ if command is None:
+ unknown.append(name)
+ elif sub and hasattr(command, "commands") and sub not in command.commands:
+ unknown.append(f"{name} {sub}")
+ assert not unknown, f"{skill.name} names commands the CLI does not have: {unknown}"