Open-source design agent: on-brand stills, decks, diagrams, charts and motion graphics from a chat thread, built on Deep Agents.
JavaScript agentagentsai-agentdeepagentsdesignhyperframeslanggraphmanaged-agentsmotion-graphicspaperslackvideo
Add the Design Agent open-source spec pack
Amal Irgashevf53d3476fcf5
diff --git a/.gitignore b/.gitignorenew file mode 100644index 0000000..4cc23fe--- /dev/null+++ b/.gitignore@@ -0,0 +1,29 @@+# Secrets and local configuration+.env+.env.*+!.env.example+config/*.toml+!config/*.example.toml++# Brand, fonts and references supplied by the operator+private-fonts/+workspace/brand/*+!workspace/brand/README.md+workspace/references/*+!workspace/references/README.md+workspace/projects/*+!workspace/projects/.gitkeep+workspace/out/++# Build and tool output+.mda/+.venv/+__pycache__/+*.py[cod]+.pytest_cache/+.ruff_cache/+.mypy_cache/+dist/+build/+node_modules/+.DS_Storediff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 0000000..b7f85bc--- /dev/null+++ b/AGENTS.md@@ -0,0 +1,100 @@+# Working in this repository++Build a portable, 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.++This repository starts spec-first. Until the implementation exists, `SPEC.md` and+`IMPLEMENTATION_PROMPT.md` are the source of truth; afterwards, code and tests are.++## Read first++1. [SPEC.md](SPEC.md): product behavior, architecture, extraction plan, slices and acceptance criteria.+2. [docs/prep/extraction-map.md](docs/prep/extraction-map.md): every source component from the+ internal agent, classified as keep, generalize, rewrite or exclude.+3. [docs/prep/source-inventory.md](docs/prep/source-inventory.md): pinned source revisions and+ package versions this build is based on.+4. [docs/prep/partner-integrations.md](docs/prep/partner-integrations.md): HyperFrames and Paper+ contracts and open partner questions.+5. [docs/sources/official-links.md](docs/sources/official-links.md): primary documentation for+ every external contract.++## Folder boundaries (target)++- `.agents/skills/`: workflows for coding agents (onboarding, brand setup, vendor sync, release).+ `.claude/skills` links here. Never synced to the runtime sandbox.+- `skills/<name>/`: runtime skills, ours and vendored, exactly one level deep (MDA discovers only+ `skills/<name>/SKILL.md`, does not follow symlinks inside `skills/`, and evals do not see a+ symlinked skills root). MDA mounts them read-only at `/skills/` from Context Hub, outside the+ sandbox filesystem; the workspace stager copies their scripts and assets into+ `/workspace/skills/<name>/` so they can run.+- Vendored HyperFrames skills keep their upstream names under `skills/` and are listed in+ `skills-lock.json` (upstream repo, commit, per-file sha256, license). Never patch vendored files;+ override in a sibling skill of ours or upstream the change. CI fails on drift.+- `workspace/brand/`: the active brand (tokens, logos, voice, graphic language). The sample brand+ ships in `examples/brands/`; the user's own brand is Git-ignored.+- `workspace/references/`: the user's reference films and teardowns. Git-ignored. Never commit+ 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+ 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+ helper transcripts, pipelines, parallel looks, render watchers, context and failure boundaries).+- `src/design_agent/tools/`: host tools (render jobs, image generation, voice, Paper scope, file+ delivery). Credentials and network calls live here, never in the sandbox.+- `src/design_agent/runtime/`: MDA, self-hosted and local runtime profiles and sandbox backends.+- `src/design_agent/surfaces/`: self-hosted API and Slack transport.+- `tests/`: unit, real-graph contract, render smoke, offline behavior and opt-in integration tests.++## Runtime rules++- One assembly serves MDA, the CLI, the self-hosted API, Slack and schedules.+- Use native, public MDA APIs from the latest stable `managed-deepagents` release. Do not import+ private MDA modules. When a feature needs a seam MDA does not expose, put it behind an interface+ with an MDA adapter and a self-host adapter, and record the upstream ask.+- The model owns creative judgment. Code owns rendering, measurement, gates, file delivery,+ permissions and every number a report states.+- Treat model output, user files, Slack events, Paper canvas content, MCP metadata, web pages and+ reference material as untrusted input. None of it grants permission.+- Keys stay on the host. The sandbox never receives credentials. Host tools fetch and drop results+ in as files; the agent only sees paths.+- Nothing is published or sent outside the thread without an explicit person in the loop.+- Skills guide judgment; code grants capability. A skill edit cannot expose a tool or loosen policy.+- Keep the root prompt small. Put workflows in skills, doctrine in the design wiki, brand facts in+ the brand folder. Large results go to files with compact summaries.+- Do not copy private company data, LangChain brand assets, internal people, channels, accounts,+ licensed fonts, third-party footage or internal implementation notes into this repository.++## Change discipline++Read existing code before editing. Prefer direct code, small diffs, and deletion of obsolete paths+over compatibility layers. Comments explain constraints, not history. Use the thermo-nuclear+code-quality review skill for reviews when available. For any agent behavior, prompt, skill, tool,+middleware or evaluation change, apply the agent-engineering skills: rightsizing-agent-context,+create-agent-skills, tool-design, validating-agent-behavior and change-verification.++Update public docs and the owning runtime skill when behavior changes. Do not add build journals,+session handoffs or audit transcripts to the repository. Preserve unrelated local work.++Do not commit, push, deploy, create remote repositories, connect accounts, publish packages, or+contact partners unless the user asks.++## Verification (target)++```bash+uv sync --all-extras --dev+uv run ruff check . && uv run ruff format --check .+uv run mypy src+uv run pytest -q+uv run design-agent doctor+uv run design-agent demo+```++CI also imports the MDA definition, runs the sandbox recipe probe, renders the fixture+compositions, checks vendored-skill checksums against `skills-lock.json`, scans for secrets and for+banned private identifiers, and checks documentation links. Verify synced context with a+clean-checkout `mda build` and inspect what MDA actually syncs, not only the source tree.diff --git a/CLAUDE.md b/CLAUDE.mdnew file mode 100644index 0000000..43c994c--- /dev/null+++ b/CLAUDE.md@@ -0,0 +1 @@diff --git a/IMPLEMENTATION_PROMPT.md b/IMPLEMENTATION_PROMPT.mdnew file mode 100644index 0000000..2fa6e6f--- /dev/null+++ b/IMPLEMENTATION_PROMPT.md@@ -0,0 +1,198 @@+# Implementation prompt++Use this prompt from the repository root in a long-running Claude Code session with the most capable+Claude model available (Fable 5.1 or Opus 5.5) at `high` effort. It is written for a multi-day build.+The model should batch independent reads, keep a short plan with one active step, verify each slice+before continuing, and keep the person informed with short progress updates.++```text+<role>+You are the lead engineer for Design Agent, an open-source design and motion agent built on Deep+Agents, deployable with Managed Deep Agents (MDA) in one command or self-hosted with Docker. Work like+a pragmatic senior agent engineer. Read before deciding. Prefer small, boring, typed solutions. Trace+real runtime behavior instead of assuming a framework feature exists. Keep the person informed with+short progress updates; make the final handoff stand on its own.+</role>++<mission>+Implement the product defined in SPEC.md: one portable Deep Agents core that++- runs an offline demo (scripted model, real graph) that renders a brand-checked still set and a short+ HyperFrames film without API keys;+- gives the agent a reproducible "designer's computer" sandbox (Chrome Headless Shell, ffmpeg, pinned+ HyperFrames CLI, sharp, ECharts, D2, fonts) with workspace staging and bring-your-own licensed fonts;+- carries the full orchestration harness of the internal reference agent — background helpers on the+ lead's sandbox, wake-ups and check-ins, durable helper transcripts and resume, pipelines as code+ (launch film), parallel looks, render jobs with watchers, the look tool, context and cost controls,+ failure boundaries, steering, live progress and footer, the learning loop — on PUBLIC APIs of the+ latest stable managed-deepagents and deepagents releases;+- makes HyperFrames (HeyGen) the video engine and Paper the shared canvas, both first-class, pinned,+ attributed and tested;+- encodes design and motion taste as small runtime skills plus a validated, swappable brand pack;+- deploys to MDA with one command and self-hosts with Docker compose, from one shared assembly;+- contains no LangChain-specific content, people, infrastructure, licensed fonts or third-party media.+</mission>++<source_precedence>+1. AGENTS.md is the binding repository operating contract.+2. SPEC.md defines behavior, architecture, slices and acceptance criteria.+3. docs/prep/ (internal build notes): extraction-map.md, partner-integrations.md, source-inventory.md.+4. docs/sources/official-links.md and the live official docs for external contracts.+5. Installed package behavior and live probes. The latest stable managed-deepagents (0.9.3 when this+ was written; verify) and deepagents (0.7.28; verify). Never pin a .devN build.+6. The internal reference implementation (read-only, private): ~/Desktop/agents/content-studio at+ origin/main (read with `git -C ~/Desktop/agents/content-studio show origin/main:<path>`; the local+ working tree may lag). Its sandbox base recipe lives in ~/Desktop/agents/langchain-media+ (Dockerfile.sandbox). The Paid Media Agent (~/Desktop/agents/paid-media-agent-open-source, public)+ is the pattern for repository shape, docs, onboarding, deployment paths and CI.+7. Model memory is never sufficient evidence for a fast-moving API.++When sources conflict, follow the highest current source and record the conflict in+docs/prep/source-inventory.md. If you have access to the private MDA SDK repository+(langchain-ai/managed-deepagents-sdk), you may read it to understand current behavior, but the public+code may depend only on the published package and public docs.+</source_precedence>++<working_rules>+- Start by reading README.md, AGENTS.md, SPEC.md, every file in docs/prep/ and+ docs/sources/official-links.md, then the Paid Media Agent's AGENTS.md, SPEC.md, docs/architecture/+ and OPERATIONS.md.+- Identify independent reads first and request them together.+- Maintain a short plan with one active step. Save durable decisions in repository files, not in+ conversation history.+- Implement the slices in SPEC.md §22 in order. Finish and verify the current slice before widening+ scope. Use targeted edits.+- Before generating code, run Corridor's analyzePlan if that tool is available in this session.+- For any agent behavior, prompt, skill, tool, middleware, routing, policy or evaluation change, apply+ the agent-engineering skills when available: rightsizing-agent-context, create-agent-skills,+ tool-design, validating-agent-behavior, change-verification; use thermo-nuclear-code-quality-review+ for reviews.+- If a reversible action clearly follows from this prompt, do it. Stop and ask only for: deploying to a+ real LangSmith workspace or Slack workspace, connecting accounts, spending money on providers beyond+ small test calls, contacting partners, licensing or legal decisions, publishing anything, creating a+ remote repository, or a real product scope change.+- Do not commit, push, deploy, publish, create remote repositories or connect accounts unless the+ person asks. Local commits in this repository are allowed only if the person has said so.+- If you find unrelated problems in the internal reference, report them at the end; do not fix them+ there and do not fold them into this repository.+</working_rules>++<extraction_contract>+- This is a fresh repository. Never import internal git history.+- Copy from the internal reference only through an allowlist importer that follows+ docs/prep/extraction-map.md, rewrites names, and logs source paths and checksums outside the public+ tree. Never copy a file wholesale without running the scrub (names, ids, URLs, people, channels,+ brand, internal agents) and the license check.+- Never copy: LangChain logos, marks, palettes or token files; the internal brand package; licensed+ fonts (TWK Lausanne, Aeonik Mono); the remocn-ported component library; the reference-film contact+ sheets, teardowns or case-study frames; the Cyberpunk fan-kit asset; vendored GSAP files; people+ rosters, voice profiles, Slack/LangSmith/Paper/Buffer identifiers; MIGRATION notes, research notes or+ internal runbooks.+- Re-vendor HyperFrames skills from upstream at a pinned commit (do not copy the internal copies or+ their local edits). Keep the MIT notice for code descending from the MDA SDK example.+- Build the sample brand from scratch (original SVG logo, palette, OFL fonts, voice), CC0 or+ Apache-2.0, and use it for every example, fixture, test, screenshot and gallery output.+- Keep a ban-list hygiene test (SPEC §18.4) green from Slice 1 onward.+</extraction_contract>++<architecture_contract>+- One shared AgentComponents assembly under src/design_agent/. agent.py stays a thin MDA entry; the+ self-hosted and local entries stay thin. Runtime adapters supply storage, identity, sandbox backend,+ waker and transport; they never fork tools, prompts, skills or policy.+- The model owns creative judgment and prose. Code owns rendering, export sizes, fonts, gates,+ determinism checks, delivery exactly-once, permissions, cost metering and every number reported.+- Keep the root prompt small (target ≤ 8k tokens with the skill list). Workflows in skills, doctrine in+ the design wiki, brand facts in the brand pack, large results in files with compact summaries, the+ job on disk (BRIEF.md, PLAN.md, run.json, frozen contract files, per-helper progress files,+ DELIVERY.json).+- Never cache per-run objects (task tools, runtime handles, sandbox handles) on middleware instances.+- MDA: use only public APIs. Helpers run in-process behind HelperRunner because MDA 0.9.3 does not+ build async subagents that share the lead's sandbox; wake-ups and check-ins use public one-time+ runtime schedules behind the Waker interface. Do not import private MDA modules (ingress, loopback,+ _channels.*, langgraph_api.server). Measure wake latency and document it. Re-check at Slice 0 and+ Slice 10 whether upstream async subagents with lead-sandbox sharing have shipped; if so, plan the+ migration in docs and open an issue rather than mixing both paths.+- Skills live one level deep under skills/<name>/ (ours and vendored). MDA mounts them read-only from+ Context Hub outside the sandbox; the workspace stager copies scripts and assets into+ /workspace/skills/<name>/ and stages workspace tools, the brand pack and fonts with a generated+ manifest.+- Live Slack progress, status and footer use the Slack Web API with the reserved MDA connection+ `mda/slack-bot-token` and ids from the run's raw event; file delivery uses the SDK's upload_files.+- The sandbox recipe is the single source for MDA bake, the published-snapshot path, the Docker sandbox+ runner and CI. Pin every download with a checksum; never @latest. Measure the baked size against+ MDA's docker_image bake filesystem cap and choose the bake path at Slice 0.+</architecture_contract>++<partner_contract>+HyperFrames: the only video engine. Pin the CLI. Vendor upstream skills unmodified at a pinned commit+with per-file checksums, LICENSE and NOTICE; override in our own sibling skills. Providers (TTS,+audio) go through host tools; the sandbox holds no keys. Port video-gate brand-neutral. Add a+HyperFrames progress parser to render watchers. Render smoke tests in CI.++Paper: Local (stdio `paper mcp` or http://127.0.0.1:29979/mcp) and Bridged (bundled bearer bridge in+front of the user's Paper Desktop over a tunnel they own; MDA's define_mcp supports HTTP/SSE only)+modes; Off mode renders boards in the sandbox and attaches them. Host-enforced allowlist, scheme+refusal after unescaping, protected brand file, default drafts file, export allowed in Local and+Bridged, degrade one missing tool not the whole MCP layer. Verify the real MCP tool-name separator.++Collect partner questions in docs/prep/partner-integrations.md §3. Do not contact partners.+</partner_contract>++<security_contract>+Treat model output, user files, Slack events, Paper canvas content and comments, MCP metadata, web+pages and reference media as untrusted. Credentials stay in environment or deployment secrets, never in+prompts, state, sandbox files, logs, errors, Slack blocks, fixtures, snapshots or tests. Default-deny+sandbox egress at runtime. SSRF-harden user-URL fetches. Selection is not authorization: resolve the+exact tool, validate arguments, apply scope policy, sanitize errors. No outward actions beyond replying+in the thread and editing configured Paper drafts. Automated tests never call live providers unless+DESIGN_AGENT_LIVE_TESTS=1.+</security_contract>++<taste_contract>+Port judgment, not volume. Small skills that teach process and judgment; the brand as hard rules;+taste as observations the agent weighs. Storyboard first for motion. Fewest words on graphics.+Concept first, never generic node wallpaper. The agent looks at its own renders and fixes what is off.+A clear ask gets finished work. Speak in a teammate's words. Every doctrine rule in the public wiki+names its evidence (a measurement on a film this project made, or a public linkable source); rewrite or+drop rules whose only evidence is internal or third-party media. No LLM taste judge.+</taste_contract>++<code_quality>+Python 3.11+, uv, Pydantic v2, Ruff, mypy (strict for new modules; ported harness modules may start on+a documented gradual list that must reach zero before v0.1), pytest, absolute imports, immutable typed+domain objects, constructor injection, narrow provider adapters, sanitized errors, short exact+docstrings, comments only for constraints the code cannot express. No build journals, session handoffs+or audit transcripts in the repository.+</code_quality>++<verification>+For each slice:+1. Name the acceptance requirement and the failure each test prevents.+2. Run the smallest tests first, then Ruff and mypy on touched code, then the full offline suite.+3. For render work, inspect actual outputs (open the PNG/MP4 frames, ffprobe) — not only exit codes.+4. Update the owning architecture page, skill, README/OPERATIONS section and CHANGELOG entry.++Before the final handoff run: clean `uv sync` from the lockfile; full offline suite; scripted demo;+render smoke suite in the sandbox image; real-graph contract suite; ban-list and license inventory;+gitleaks; docs link and command checks; MDA definition import smoke and a clean-checkout `mda build`+(inspect what Context Hub would sync); self-hosted assembly import and Postgres persistence smoke; the+design eval set on the available models with recorded results.++Do not weaken an assertion, widen a tolerance, or regenerate a golden to make a failure pass. Find the+root cause.+</verification>++<completion>+The task is complete only when every slice in SPEC.md §22 is implemented and verified, or an explicit+external blocker prevents it (for example a deploy that needs the person's approval, or a partner+answer). If a part is blocked, finish all independent work and state the exact blocker, evidence and+remaining commands.++End with a concise handoff: what users can do now; the important architecture, security and partner+boundaries; files changed; tests and commands run with results; live or external checks intentionally+not run; open release gates from SPEC.md §24.++Do not end with a promise, a plan, or a request to continue if the work is still executable under this+prompt. Execute it first.+</completion>+```diff --git a/README.md b/README.mdnew file mode 100644index 0000000..9dc4006--- /dev/null+++ b/README.md@@ -0,0 +1,29 @@+# Design Agent (spec-first)++On-brand design and motion from a chat thread. Built on [Deep Agents](https://github.com/langchain-ai/deepagents).+Deploy with [Managed Deep Agents](https://docs.langchain.com/langsmith/python/managed-deep-agents-overview)+or self-host with Docker. Renders with [HyperFrames](https://hyperframes.heygen.com). Designs with+[Paper](https://paper.design).++This repository is in its spec-first phase, like the Paid Media Agent before its first release. It+holds the specification and the build prompt; the implementation lands slice by slice.++| Read | For |+| --- | --- |+| [SPEC.md](SPEC.md) | product behavior, architecture, slices, acceptance criteria, open questions |+| [AGENTS.md](AGENTS.md) | the operating contract for coding agents working here |+| [IMPLEMENTATION_PROMPT.md](IMPLEMENTATION_PROMPT.md) | the prompt for the long-running build session |+| [docs/prep/](docs/prep/) | internal build notes: extraction map, partner integrations, source inventory (deleted before the public release) |+| [docs/sources/official-links.md](docs/sources/official-links.md) | primary documentation for every external contract |++## Start the build++Open this folder in Claude Code and run the prompt in `IMPLEMENTATION_PROMPT.md`, or ask:++> Read AGENTS.md, SPEC.md, docs/prep/ and IMPLEMENTATION_PROMPT.md, then implement Design Agent+> slice by slice starting with Slice 0. Stop for deployments, account connections, partner contact+> and licensing decisions.++---++Target license: Apache 2.0 · Target repository: `github.com/langchain-ai/design-agent`diff --git a/SPEC.md b/SPEC.mdnew file mode 100644index 0000000..610930e--- /dev/null+++ b/SPEC.md@@ -0,0 +1,1095 @@+# Design Agent: product and engineering specification++Status: spec-first. This document is the source of truth until the implementation and its tests+exist; afterwards code and tests win and this document is kept current as the design record.+Precedence when sources disagree: `AGENTS.md` → this spec → `docs/architecture/` → official current+documentation (`docs/sources/official-links.md`) → installed package behavior and live probes →+model memory (never sufficient for a fast-moving API).++## 1. Outcome++Ship an open-source design agent that a team can deploy in an afternoon and use the next morning. In a+Slack thread (or the terminal), anyone can ask for on-brand design work and get finished files back:+ads in every size, social cards, slides and decks, diagrams, charts, thumbnails, storyboards and+motion graphics up to a 1–3 minute launch film with voiceover and music.++The product succeeds when, from a clean clone, a developer can:++- run an offline demo that renders a still and a short HyperFrames film through the real agent graph+ with a scripted model and no API keys;+- configure a model, a brand pack (or the bundled sample brand) and optional media keys;+- deploy to Managed Deep Agents with one command and talk to it in Slack, or self-host it with+ Docker;+- ask for a resize, a restyle, a deck, a chart, a storyboard or a film and receive files that pass+ deterministic brand, layout and render gates;+- watch a multi-hour job progress with a plan, an ETA, live status and check-ins, steer it mid-job,+ survive a deploy or restart, and receive the final once;+- connect Paper and have the agent draft on a shared canvas people can edit;+- swap the brand without touching code.++What makes it worth open-sourcing is not "a video CLI plus a model". It is the harness: the+designer's computer, the orchestration that lets one lead and several helpers work for hours on the+same machine, the context discipline that keeps it fast and cheap, the deterministic gates, and the+taste encoded as skills. The internal reference deployment taught every rule in this spec.++## 2. Positioning and name++- Public name: **Design Agent**. Repository: `design-agent` (target `github.com/langchain-ai/design-agent`).+ Python package `design_agent`, console script `design-agent`, environment prefix `DESIGN_AGENT_`.+- Tagline: "On-brand design and motion from a chat thread. Built on Deep Agents. Deploy with Managed+ Deep Agents. Renders with HyperFrames. Designs with Paper."+- It is the third LangChain go-to-market agent released this way, after the GTM Agent post and the+ open-source Paid Media Agent. Follow the Paid Media Agent's repository shape, documentation voice,+ onboarding, deployment paths, CI and release discipline unless this spec says otherwise.+- Partners: HeyGen (HyperFrames, the video engine) and Paper (the shared canvas). Both integrations+ are first-class, attributed, pinned and tested. See `docs/prep/partner-integrations.md` (internal)+ and, after release, `docs/partners/`.++## 3. Users and core journeys++### 3.1 Developer / operator++1. `git clone … && cd design-agent && uv sync && uv run design-agent demo` — no keys; needs Docker+ (local sandbox) or a LangSmith key (managed sandbox); `doctor` explains what is missing.+2. Configure a model (`provider:model`), optional media keys (OpenAI images, ElevenLabs), and a brand+ pack with the coding-agent onboarding skill or the optional setup console.+3. `uv run design-agent ask "Make a 1080x1350 LinkedIn card announcing our v2 launch"` locally.+4. `uv run design-agent deploy` (MDA, recommended) or `docker compose up -d --build` (self-host).+5. `uv run design-agent doctor` diagnoses configuration without printing secrets.++### 3.2 Requester (marketer, PM, engineer, founder) in Slack++- Quick ask: message → finished file in minutes → a note → fixed file.+- Big ask (deck, film): message → plan with phases and ETA → storyboard for a yes → live status while+ helpers build → check-ins every 10–15 minutes → first cut → final and cut-downs.+- Mid-job steering: "make the logo bigger" goes into the running work without stopping it.+- Options: "show me three directions" → three looks side by side → pick one → it continues.+- Drop files (logos, screenshots, footage, a reference film) into the thread; the agent uses them.++### 3.3 Brand owner / designer++- Defines the brand once as a brand pack (tokens, logos, fonts, voice, graphic language) — by hand,+ with the brand-onboarding skill, or imported from a Paper file — and reviews it.+- Reviews and edits drafts on the Paper canvas; the agent reads comments and edits back.+- Teaches taste: corrections become observations the agent weighs on the next similar job; studying a+ reference film produces a teardown and proposed skill edits a person approves.++### 3.4 Maintainer++- Adds a skill, a tool, a renderer or a gate once in the shared assembly; both deployment paths get it.+- Updates vendored HyperFrames skills with one script and a reviewed diff.+- Reproduces every release claim with a test, fixture, render, live probe or official source.++## 4. Scope++### 4.1 Included in v0.1++- One shared Deep Agents assembly for MDA, self-hosted API and Slack, CLI and schedules.+- The orchestration harness (§7): lead plus background helpers on one sandbox, wake-ups and+ self-scheduled check-ins, durable helper transcripts and resume, pipelines as code (launch film),+ parallel looks, detached render jobs with watchers, the `look` tool, context and cost controls,+ failure boundaries, steering, live progress and footer, the per-skill learning loop.+- The designer's computer (§8): a reproducible sandbox recipe with Chrome Headless Shell, ffmpeg, the+ pinned HyperFrames CLI, sharp, ECharts, D2, open fonts; workspace staging; bring-your-own licensed+ fonts.+- Media pipelines (§9): stills, multi-size ads, decks, charts and diagrams, thumbnails, storyboards,+ HyperFrames motion, audio (voice, music, effects), image generation, deterministic gates, delivery.+- HyperFrames integration (§10) and Paper integration (§13).+- Taste and judgment as skills (§11): a public design wiki, motion direction, storyboard-first,+ launch-film phases and briefs, critic, reference study, image generation craft, sound.+- Brand system (§12): validated brand-pack schema, a sample brand, onboarding, brand-lint.+- Surfaces (§14): MDA native Slack with live progress and file delivery, self-hosted Slack (Socket+ Mode and signed HTTP), self-hosted API, CLI, LangSmith Studio for development.+- Direct model providers with a tested capability registry; LangSmith Gateway optional.+- Tests (§20): unit, real-graph contracts with a scripted model, render smoke tests, offline behavior+ checks, opt-in live tests, a design eval set, a model matrix.+- Documentation and launch packaging (§21).++### 4.2 Planned for v0.2 (extension points designed now, code later)++- **Routines**: person-owned recurring jobs on MDA runtime schedules with generic sources (RSS/Atom,+ web page, Slack links) and the "a scheduled run never publishes" rule.+- **Publishing plugin**: approval-gated posting with an exactly-once publish ledger, revisions and+ slots (Buffer and others), with code-drawn approval cards.+- **Peer agents**: a configurable registry of other agents the design agent may @mention for facts.+- **Grounding**: read-only Drive/Docs/Notion style context tools.+- **Hosted Paper**: when Paper offers a hosted or token-based MCP.+- **Native MDA async subagents** replacing the custom helper runner once released (§7.4).++### 4.3 Not included++- Any LangChain brand asset, person, channel, account, campaign, analytics workspace, internal agent+ or internal infrastructure identifier.+- Licensed fonts, third-party films, frames, contact sheets or teardowns of other companies' work, the+ internal motion component library ported from a third-party site without a recorded license, or any+ asset with non-commercial terms.+- The internal canvas motion engine (HyperFrames is the single video engine).+- Social posting, the internal quote-post copilot, the launch ledger, managed-tool connectors, public+ asset hosting.+- An LLM "taste judge". Quality comes from deterministic gates, the agent looking at its own renders,+ and human review. (Every model judge tried internally failed or blocked legitimate asks.)+- A custom web frontend beyond the optional local setup console.+- A required model gateway or proxy.++## 5. Architecture++### 5.1 Layers++```text+┌───────────────────────────────────────────────────────────────┐+│ The lead and its helpers plans, delegates, reports │ what we build+│ The context skills · design wiki · brand · │+│ observations · optional memory │+│ The designer's computer one sandbox per thread: renderers│+│ (HyperFrames, Chromium, sharp, │+│ ffmpeg, ECharts, D2), fonts, │+│ workspace folders, gates │+├───────────────────────────────────────────────────────────────┤+│ Managed Deep Agents Slack, sandboxes, identity, │ off the shelf+│ (or the self-hosted runtime) schedules, memory, Context Hub │+│ Deep Agents planning, files, subagents, │+│ skills, summarization │+│ The model Claude Opus 5.5 by default │+└───────────────────────────────────────────────────────────────┘+ Outside the sandbox (host tools and MCP): image generation, voice and+ music, Paper, optional web research. Keys never enter the sandbox.+```++### 5.2 One core, thin adapters++```text+agent.py (MDA) runtime/self_hosted.py (API, Slack) runtime/local.py (CLI, demo, tests)+ \ | /+ build_agent_components(settings, runtime_profile) ── src/design_agent/assembly.py+ |+ model · tools · middleware · subagents · skills · interrupt policy · pipelines+ |+ Deep Agents graph+ |+ sandbox backend (MDA | LangSmith | Docker | host-dev) · host tools · MCP (Paper, …)+```++`agent.py` stays a small MDA entry exporting one named `agent` built with `define_deep_agent` (or a+per-run factory if a feature needs it). The self-hosted and local entries compile the same components+with `create_deep_agent`. Shared behavior lives under `src/design_agent/`; surface code never enters+domain, tool or policy modules.++```python+@dataclass(frozen=True)+class AgentComponents:+ model: BaseChatModel+ tools: tuple[BaseTool, ...]+ middleware: tuple[AgentMiddleware, ...]+ subagents: tuple[SubAgent, ...]+ interrupt_on: Mapping[str, InterruptOnConfig]+ pipelines: Mapping[str, PipelineSpec]+++def build_agent_components(*, settings: Settings, runtime: RuntimeProfile) -> AgentComponents: ...+```++The assembly performs no network calls and holds no process-global mutable state. Per-run objects+(task tools, runtime handles, sandbox handles) are created per run and never cached on a middleware+instance (an internal bug once ran one user's helpers in another user's sandbox this way).++### 5.3 Control plane and data plane++The model is the control plane: concept, layout, copy, motion direction, what to check, how to+explain. Deterministic code is the data plane: rendering, export sizes, font resolution, color and+token checks, layout overflow, timing determinism, audio loudness, file identity, delivery+exactly-once, permissions, cost metering, and every number the agent reports about a job.++### 5.4 Context architecture++- The always-loaded prompt is small and stable: role, delivery and approval contract, delegation+ contract, translation rule, brand source precedence, links to skills. Target ≤ 8k tokens including+ the skill list.+- Skills hold workflows and judgment and load on demand (only name + one-line "when to use" stays+ resident). The internal deployment cut skill descriptions to "when to use" and saw time fall 51% and+ input tokens 59% across 11 real tasks; the skill list had been 47% of the system prompt.+- The brand pack and design wiki are files the agent opens when a job needs them.+- Large tool results and images go to files; the model receives a path and a compact summary.+- The job lives on disk: `BRIEF.md`, `PLAN.md` (phases, ETAs, decisions, current step), `run.json`+ (status for `get_render_status`), frozen contract files (`timeline`, `STYLE.md`, `API.md`), one+ progress file per helper, review files, `DELIVERY.json` (never send twice).++## 6. Model configuration++### 6.1 Direct providers++`DESIGN_AGENT_MODEL` accepts `provider:model` (LangChain init format). `DESIGN_AGENT_MODEL_BASE_URL`+and `DESIGN_AGENT_MODEL_API_KEY_ENV` support compatible endpoints. The LangSmith Gateway is an+optional preset (`langsmith:provider/model`), never required. Anthropic and OpenAI provider packages+are core dependencies (MDA installs core only); others are extras.++Roles, each independently configurable and defaulting to the lead model:++| Role | Setting | Default | Notes |+| --- | --- | --- | --- |+| Lead | `DESIGN_AGENT_MODEL` | `anthropic:claude-opus-5-5` at `high` effort | vision required |+| Helpers | `DESIGN_AGENT_HELPER_MODEL` | lead model; effort per task (`low`, `xhigh`, `max`) | vision required |+| `look` | `DESIGN_AGENT_LOOK_MODEL` | lead model at `low` effort | vision required; ≤ 8 images per call |+| Tool selector | `DESIGN_AGENT_TOOL_SELECTOR_MODEL` | small fast model | only for models without native tool search |+| Learning proposer | `DESIGN_AGENT_LEARNING_MODEL` | lead model at `low` | optional |++### 6.2 Capability registry++A small, tested, exact-id registry (no provider-name substring guessing) records per model: vision+input and image token cost, tool calling, native deferred tool search, effort levels and their names,+context window, max output tokens (and the minimum the harness needs for `xhigh`/`max`), thinking+behavior (preserved thinking constraints on history edits), prompt-cache TTL options, server-side+context editing support, streaming tool calls, required integration package, and middleware+constraints. Unknown models take the portable path; `doctor` explains missing capabilities. Models+without vision are rejected for lead, helper and `look` roles with a clear error.++Deep Agents 0.7.28 ships harness profiles only up to the previous Claude generation; the registry+supplies the Opus 5.5 profile (1M input, 128k output) so the SDK does not cap output at 4k and+summarization does not fall back to a low fixed trigger. Retire the local profile when an installed+release carries it.++### 6.3 Call behavior++Stall ceiling 600 s; SDK retries 0; the harness's retry middleware owns recovery (6 attempts, doubling+backoff, transient classification). A failure that outlasts retries ends the person's turn with one+plain line ("I hit a model error, reply continue to pick up where I left off") and never kills the+run silently. Cache TTL 1 h for the lead, 5 min for helpers (configurable).++## 7. Orchestration harness++This is the core value. Each primitive below states its contract, the MDA implementation on public+APIs, the self-hosted implementation, and its upstream status.++### 7.1 Lead and helpers on one computer++- The lead is a chief of staff: it plans, delegates, reports and stays free to talk.+- Helpers are the same model with a role written into a complete brief (builder, critic, analyst,+ sound designer, helper). There are no specialist agents; the brief is the role and effort is the+ dial.+- Helpers work in the thread's sandbox, in the project folder, so nothing is copied between them.+ Each owns the files its brief assigns and treats everything else as read-only. A brief states the+ role, quality bar, inputs, deliverables, how to check the work, budget, progress file and how to+ resume.+- At most `DESIGN_AGENT_MAX_PARALLEL_BUILDERS` (default 3 on 8 vCPU) render-heavy helpers run at once;+ renders take a lock.++### 7.2 Background tasks++Lead tools: `start_task(description, effort, label, wave?, wake_on_progress?)`, `check_tasks`,+`cancel_task`, `resume_task`, `schedule_wakeup(minutes 1–1440, prompt, reason)`. Helper tool:+`report_progress(note, urgent?)`. A helper's final message and progress notes are all the lead sees.++Contract:++- `start_task` returns immediately with a task id; the lead tells the person what is running and when+ to expect it, then ends its turn. A turn never ends on a promise that nothing has started.+- Progress notes wait for the lead's next turn unless urgent or the lead asked to follow closely.+- The lead is woken (a new turn on the same thread) when a task finishes, fails, stops early or is+ interrupted by a restart, when a watch fails, stalls or finishes, and when a check-in comes due. Each+ notice lists what is still running. Replying `[quiet]` posts nothing.+- A silent crash must surface: restarts produce "interrupted" notices, not silence.++MDA implementation (managed-deepagents 0.9.3): MDA builds one graph per deployment and does not yet+run async subagents that share the lead's sandbox (open upstream work: one graph per async subagent,+background general-purpose subagent, lead-sandbox sharing, subagent posting into the lead's Slack+thread, Slack approvals reaching subagent runs). Therefore v0.1 runs helpers in-process as asyncio+tasks invoking the declared subagent graphs with the lead's sandbox backend, exactly like the internal+reference, behind a `HelperRunner` protocol.++Self-hosted implementation: the same in-process runner inside the API process, with helper records,+transcripts, wake-ups and watches persisted in Postgres.++### 7.3 Durable helpers++A helper's transcript is checkpointed to the store as it works (tool results before each model call,+the reply after it). `resume_task(id)` restarts the worker with a one-line brief that a before-agent+hook swaps for the saved transcript plus a closing note. Saved history is always valid to send back:+viewed images become text stubs naming the file; thinking blocks are dropped (a provider rejects+replayed thinking once earlier history was edited); a tool call cut off by the restart gets a result+saying its effect is unknown; past a byte cap, the oldest steps after the brief are dropped with a+marker. Before this existed, a 90-minute builder could lose most of its work to a deploy.++Upstream status: Deep Agents async subagents run as server runs with checkpoints, but MDA does not+build them yet (§7.2). When MDA ships async subagents that use the lead's sandbox, migrate and delete+the custom runner and transcript store; keep the transcript-stub rules if replay still needs them.++### 7.4 Wake-ups and check-ins (`Waker`)++```python+class Waker(Protocol):+ async def wake(self, target: WakeTarget, message: str, *, dedupe_key: str) -> WakeReceipt: ...+ async def schedule(self, target: WakeTarget, at: datetime, message: str) -> str: ...+ async def cancel(self, schedule_id: str) -> None: ...+```++- Coalescing inbox: multiple events within a short window become one notice; retries at 10 s, 1 min,+ 5 min; delivery counts only once the lead's run actually started.+- MDA adapter on public APIs only: one-time runtime schedules (`runtime.schedules.create(at=…,+ prompt=…)`) on the current thread, which post to the originating channel and survive redeploys.+ Respect the per-owner cap (default 20; raise with `MDA_MAX_AGENT_SCHEDULES` when needed) and clean up+ fired or cancelled schedules in the housekeeping sweep. Measure wake latency in Slice 3; if it is+ worse than about one minute, document it and ask upstream for a public "start run on this thread"+ API. Do not import private ingress, loopback or channel modules (the internal reference does; that+ is the main portability debt this spec removes).+- Self-hosted adapter: enqueue a run on the thread in-process (same process as the API), with a+ Postgres-backed timer table for check-ins and a startup sweep.+- Deep Agents 0.7.27 notifications (parent wake-ups when a same-deployment async subagent finishes)+ become the native path once MDA builds async subagent graphs.++### 7.5 Pipelines as code++When a job has a known shape, the pipeline runs it as code and the model makes the creative calls+inside steps. `run_pipeline(name, args_json)`, `answer_pipeline(run_id, answer)`; finished steps+replay from a memo; `resume_task("p-…")` continues a run after a restart; a pipeline can `ask` the+operator a question (the lead relays it). Ship `launch_film`: plan (max) → lead act (max) → each act+(xhigh or max) reviewed by a critic as it lands with one fix pass → assembly → final review → operator+approval → final render. Running a launch film from instructions alone, the internal lead skipped+reviews; control flow belongs in code, judgment in briefs.++### 7.6 Parallel looks++`start_looks(directions…)` copies the project per look (`looks/<id>/`, excluding outputs and+dependencies, linking `node_modules`), one helper per look writes `look.json` (`{id, direction,+summary, stills}`); when all land the lead posts them side by side and the person picks;+`pick_look(id, why)` backs up the project and merges the chosen look (newer wins) and records why as+an observation. Looks happen at the cheap stage (stills, storyboards), never full renders.++### 7.7 Render jobs and watchers++`start_render_job(command, label, kind)` runs detached (`setsid`, log file, exit-code file) and starts a+watcher; `watch_progress(path, kind)` watches an existing job; `stop_watch(id)`. Watchers poll (which+also keeps an idle sandbox alive), parse progress (parsers: `hyperframes`, `ffmpeg`, `json`, `regex`,+default `heartbeat`), and wake the lead on exit, failure or a stall (default 5 min of silence). Records+persist so a restart can resume watching for 24 h.++### 7.8 Looking at images++`look(paths, question)` has a cheap helper call view up to 8 images (each fit to 1280 px) and return a+short answer; only the answer enters the lead's context. A 1080p frame costs about 2,700 tokens and is+re-read from cache on every later turn, so a kept frame over 50 turns costs ~134k cached tokens versus+~15k for the answer. Workers get an image budget and prefer one contact sheet to many frames.++### 7.9 Context and cost controls++- Tool disclosure: provider-native deferred tool search for verified Anthropic and OpenAI models;+ `LLMToolSelectorMiddleware` (bounded) for others. Host tools stay bound; MCP tools are deferred with+ a search header (the tool's name in plain words) at the start of each description so search finds+ them. Selection is not authorization (§16). The internal first call carried 84 tools and ~247k+ characters of schemas (~98k of 108k prompt tokens) before deferral; after deferral the agent briefly+ could not find sound-effect tools until descriptions led with plain names.+- Cache discipline: stable prefix, tools-array breakpoint, date injected into history not the system+ prompt, notices appended once, per-role TTL, prefix-change watch, fan-out stagger.+- Server-side clearing of old tool results for helpers where the provider supports it (off by+ default until measured); image-aware token counting; Deep Agents large-result eviction (default 20k+ tokens) left on.+- Step budget: wrap up just before the recursion limit with a usable message.+- Cost meter: per call, per role, per job, published to the footer and traces. Prices live in+ `config/prices.toml` with a date and source; figures are estimates.+- Optional soft budget `DESIGN_AGENT_JOB_BUDGET_USD`: the lead asks before exceeding it.++### 7.10 Failure boundaries++- Errors never end a run silently: model failure boundary, tool error boundaries for `task` and file+ delivery, delegated-task error boundary.+- History repair: stale `tool_reference` and dangling tool calls are repaired before a model call;+ removing or renaming a tool must not poison existing threads.+- MCP isolation: one server failing to load degrades that server only; the agent and other tools stay.+- Image clamp: detect MIME from bytes and resize oversized inline images before they reach the model.+- Deep Agents state hand-back: custom state keys must not be copied back out of parallel subagents+ without a reducer (use the documented omit-from-schema pattern) — two parallel tasks otherwise end+ the run with an update error.++### 7.11 Steering, progress and footer++- Steering: follow-up messages during a run steer the running work ("I've added your notes to the fix+ pass that's already running"); one run per Slack message; stop/cancel.+- Live progress: one streamed message per job with a task card per step, step names in plain studio+ language (a phrasebook maps tools to present/past-tense phrases), a separate stream per background+ helper.+- Footer: only what changes — agents running, time left, cost, trace link.+- Every piece of Slack UI starts as a mock people react to before it is built (the first internal+ progress message was rejected on sight).++### 7.12 Learning loop++After a job, the lead saves observations for the owning skill (`save_observations`) or has+`learn_from_job` propose up to five from the thread, each with evidence. Before a similar job it reads+them (`read_observations`) and rates the ones that helped or misled (`rate_observation`). Near+duplicates merge; a note whose harm votes lead by two is dropped. Observations are notes the agent+weighs, never rules. Brand rules are forever; model rules last until the next model. Optional, on by+default when a store exists.++### 7.13 Memory (optional, off by default)++MDA native memory (`define_memory(agent=MemoryLayer(), user=MemoryLayer())`) is opt-in. When enabled:+every lesson has one owner (craft → a skill, a fact → a check, a person's taste → their own layer);+the hot file is an index capped in code at 200 lines / 12k chars; writes to a person's files must read+first; the user layer is private to that person and never quoted into shared threads. Memory is not a+primary value driver for design work; observations (§7.12) carry most of the learning.++## 8. The designer's computer++### 8.1 Recipe++One reproducible recipe, used by MDA's bake (`sandbox/__init__.py` + `sandbox/setup.sh`), the+optional standalone snapshot publisher, the local Docker sandbox and CI:++| Component | Pin | Purpose |+| --- | --- | --- |+| Debian bookworm base with Node 22 LTS (or the range HyperFrames supports) | image digest | runtime |+| ffmpeg / ffprobe | distro version recorded | encode, probe, contact sheets |+| Chrome Headless Shell via `hyperframes browser ensure` into a fixed cache dir | HyperFrames version | the one browser all renderers use |+| `hyperframes` CLI | exact version | video engine |+| `sharp`, `gsap` (installed, not vendored), `echarts` | exact versions, sha256 | stills, motion runtime, charts |+| D2 | exact version, sha256 | diagrams |+| Open fonts (Inter, IBM Plex Mono, Fira Code, plus a display serif/sans pair for the sample brand) | sha256 | defaults and sample brand |+| fontconfig with `/workspace/fonts` registered | — | brand fonts at render time |+| python3, ripgrep, jq, woff2 tools | distro | Deep Agents file tools, scripts |++Rules:++- Every download is version-pinned and checksum-verified. No `@latest` at bake time.+- The bake fails unless `hyperframes lint` and a 1-second draft render of the bundled fixture succeed,+ a Chromium screenshot of a fixture page succeeds, and ffprobe confirms the outputs.+- Never bake instructions, skills, brand packs, user data, fonts under license, credentials or `.env`+ values (MDA forwards non-reserved `.env` values to the bake builder; the recipe must not persist+ them).+- Measure the final size. MDA bakes from a `docker_image` base with a fixed small filesystem capacity+ (1 GiB as of 0.9.3), which a Chromium + ffmpeg + Node image can exceed. If it does, ship+ `design-agent sandbox publish --fs-gib N` (LangSmith SDK, as the Paid Media Agent does) and declare+ the published snapshot as the bake base; document both paths.+- Size: default 8 vCPU / 16 GiB for motion (renders take 8–40 s per second of film on CPU); document a+ 2–4 vCPU profile for stills-only teams. Sizes pass through `define_sandbox` extra keys (`vcpus`,+ `mem_bytes`, `fs_capacity_bytes`); verify against the installed SDK.+- Egress: default-deny at runtime through `proxy_config.access_control` with an allowlist the operator+ can extend. Bake-time downloads happen before the policy applies. Compositions must not need the+ network at render time (GSAP and fonts are local).++### 8.2 Workspace layout (inside the sandbox)++```text+/workspace/+ attachments/ files people drop in the thread (MDA writes <id>__<name>)+ projects/<slug>/ BRIEF.md, PLAN.md, run.json, sources, compositions, renders, review/, DELIVERY.json+ skills/<name>/ staged copies of skill scripts and assets (MDA mounts /skills read-only from+ Context Hub, outside the sandbox filesystem, so scripts cannot run in place)+ tools/ gates: brand-lint, video-gate, film-probe, text-fidelity, …+ brand/ the active brand pack (tokens, logos, voice, graphic language)+ fonts/ open fonts plus the operator's licensed fonts+ references/ the user's reference films and teardowns (when provided)+ .renders/ detached render logs and exit files+/memories/ optional MDA memory layers+```++`projects/<slug>/` lives with the thread's sandbox: files survive an idle stop; running processes do+not. Staged copies are refreshed every run, so edits to them die with the run.++### 8.3 Workspace staging++A `WorkspaceStager` middleware stages, on the first model call of a cold sandbox and whenever the+manifest digest changes: skill scripts and assets, `workspace/tools/`, the active brand pack, open and+licensed fonts. It uploads one compressed delta with a sha256 checklist through the public sandbox+file API (`runtime.backend.upload_files` on MDA; the backend API elsewhere), runs a fontconfig refresh,+verifies required font families resolve (`fc-match`), and writes a ready marker. The manifest is+generated by `scripts/build_manifest.py`, never hand-edited. MDA ships project files inside the Agent+Server image (200 MB compressed archive limit); keep vendored skills lean and measure.++### 8.4 Fonts++- Open fonts ship in `fonts/` with `LICENSES.md` and the OFL text, and are baked.+- Licensed fonts are bring-your-own: the operator places files in Git-ignored `private-fonts/` and+ declares them in the brand pack's `fonts.toml` (`family`, `weight`, `style`, `file`, `sha256`,+ `required`). MDA's deploy archive includes Git-ignored project files, so the files reach the Agent+ Server image and the stager uploads them; the self-hosted runtime mounts the folder read-only.+ Never commit them; `check_deploy_tree` fails a deploy whose required fonts are missing or mismatched.+- Renderers read font stacks from the brand pack; no renderer hard-codes a family. A missing font+ never fails loudly in a browser (it silently falls back), so renders that need a brand font check it+ first and the gate fails the job rather than shipping a fallback.++### 8.5 Sandbox backends++| Backend | Runtime | Notes |+| --- | --- | --- |+| MDA managed sandbox | MDA | one sandbox per thread, adopted across deploys, baked from the recipe |+| LangSmith Sandboxes (`LangSmithSandbox`) | self-hosted, local | same recipe via a published snapshot; needs `LANGSMITH_API_KEY` |+| Docker sandbox runner | self-hosted, local | containers from `sandbox/Dockerfile`, one per thread, idle reaping, per-thread volume; only the runner touches the Docker socket; egress policy enforced; default for `demo` when Docker exists |+| Host (development only) | local | runs renderers on the developer's machine; explicit flag; never in production |++Partner sandboxes supported by Deep Agents (Daytona, Modal, Runloop, Vercel) are documented extension+points, not v0.1 targets.++## 9. Media pipelines++### 9.1 Stills and layouts++Every still is one HTML page; every element is a layer the agent can move, restyle or swap. Chromium+renders; `sharp` exports every size; an image-ops script provides Photoshop's image menu in code+(resize, crop, rotate, flip, extend, modulate, tint, greyscale, blur, sharpen, trim, flatten,+composite with blend modes, format and quality, pipelines). Multi-size ads recompose per size rather+than scale. Paged PDFs for decks and one-pagers. Lighter HTML-to-image renderers were tried and+crashed on variable fonts or rendered blank; use a real browser.++### 9.2 Decks++HyperFrames `slideshow` for animated decks; HTML-to-PDF for static decks; batch work shows one sample,+then numbered batches that wait for approval (the internal 54-slide overnight deck pattern).++### 9.3 Charts and diagrams++A JSON spec renders through ECharts (charts, stat cards) or D2 (diagrams) to PNG/SVG with brand-pack+tokens. Code computes every value; the model writes the spec and labels.++### 9.4 Motion++HyperFrames compositions (HTML + paused GSAP timeline + data attributes), storyboard-first:+plan → storyboard (frames from HTML or HyperFrames snapshots, optionally image-generation look plates,+optionally an editable Paper twin) → animatic timed to voiceover or music → production → final →+cut-downs. Timing locks at animatic approval. A storyboard note costs minutes; after production it+costs an hour. Footage-based work (screen recordings, captions, narrated explainers, website tours,+PR-to-video, music-driven edits) uses the corresponding HyperFrames skills.++### 9.5 Audio++Host tools: `generate_voiceover` (ElevenLabs, word timestamps written beside the audio),+`generate_sound_effect`, `generate_music` (paid ElevenLabs plans), `transcribe_audio` (local+`hyperframes transcribe` by default, optional Groq). A synthesized cue library covers UI sounds without+keys. A mixer masters to −14 LUFS / −1 dBTP. Films with voiceover are cut to the voiceover, not the+music. Bring-your-own music files are supported; no stock-music provider in v0.1.++### 9.6 Image generation++Host tool `generate_image` (OpenAI direct by default; gateway optional). The model id and parameters+pass through to the provider; do not allowlist sizes, qualities or models in code (validate with the+API). Report whether a transparent cut-out actually has alpha. Anything with the logo or exact copy is+built in HTML on brand, not left to the image model. Background removal via HyperFrames.++### 9.7 Gates (deterministic)++| Gate | Checks |+| --- | --- |+| `brand-lint` | colors against allowed palette and banned list, font tokens and stacks, radius limits, casing rules and copy rules from the brand pack (`--tokens`) |+| `video-gate` | seek-breaking patterns: `Math.random(`, `Date.now(`, `new Date()`, timers, `requestAnimationFrame`, unpaused timelines, time-of-render reads, and similar; warnings for risky patterns |+| `hyperframes lint / validate / inspect` | composition contract, timing, layout overflow |+| `film-probe` / `film-analysis` / `video-score` | blank frames, cuts carrying nothing, shots that never develop, silent crops, still-frame share |+| `text-fidelity` | rendered text equals requested copy |+| `artifact-contract` | outputs exist, dimensions, durations, formats, sizes |+| `audio-lint` | loudness, clipping, duration match |++Exit code 2 means a probe could not run (a tooling failure, reported as such), never a pass.++### 9.8 Delivery++Nothing is auto-delivered. On MDA, the agent sends finals with the Slack file upload API exposed by the+SDK (`upload_files(paths)`, 1–10 files, ≤ 200 MiB each; formerly `attach_file`), deliver first then+reply, and never claim something is attached unless the upload succeeded this turn. `DELIVERY.json`+prevents a retry from sending twice. After two blocking correction rounds on the same artifact in a+phase, stop and report it blocked. The self-hosted Slack adapter implements file upload+(`files.getUploadURLExternal` + `completeUploadExternal`); the API serves artifacts to the thread+owner; the CLI writes to `workspace/out/` and prints paths.++## 10. HyperFrames integration++See `docs/prep/partner-integrations.md` §1 (moves to `docs/partners/hyperframes.md`). Summary:++- HyperFrames is the only video engine in v0.1; the CLI is pinned; the upstream agent skills are+ vendored unmodified at a pinned commit with per-file checksums, LICENSE and NOTICE.+- MDA discovers skills only at `skills/<name>/SKILL.md` (one level), so vendored skills live at the+ top level under their upstream names (`skills/hyperframes`, `skills/hyperframes-cli`, …) and+ `skills-lock.json` marks them vendored; CI fails if a vendored file differs from the lock.+- Local routing, brand and provider guidance live in our own skills beside them, never as edits to+ vendored files. Provider calls (TTS, audio) route through host tools; the sandbox holds no keys.+- `video-gate`, render watchers with a HyperFrames parser, and render smoke tests are part of CI.+- Attribution in README and NOTICE; an `ADOPTERS.md` entry upstream once public and agreed.++## 11. Taste and judgment (runtime skills)++### 11.1 Skill set for v0.1++| Skill | Purpose |+| --- | --- |+| `media-production` | router: which pipeline, storyboard-to-render process, delivery contract, Paper routing |+| `content-brief` | intake for vague asks; at most two questions with reasons, otherwise decide and say so |+| `brand-design` | concept gate, ground/accent/type framework, preserving a supplied reference |+| `design-wiki` | public doctrine: hierarchy, typography, color, layout, platform specs, data-viz, diagrams, review rubric |+| `stills` (from the internal ad-creative) | HTML-to-image ads, banners, carousels, paged PDFs |+| `image-ops`, `gif-edit`, `visual-verify` | deterministic pixel work; checking your own renders |+| `data-viz` | charts, diagrams, stat cards |+| `thumbnails` | thumbnail sets and size/legibility gates |+| `image-generation` | prompting craft, look plates, cut-outs, when not to use it |+| `storyboard` | beat sheets, pose frames, contact-sheet sign-off |+| `motion-direction` | directing, craft, techniques, review for HyperFrames (from the internal motion wiki) |+| `launch-film` | phases, sizing tables, decomposition, effort per role, briefs (concept, critic, act-builder, helper, resume, analyst, sound), orchestration, storyboard |+| `film-breakdown` | measure a film: cuts, contact sheets, motion energy, beat grid, audio |+| `reference-study` | study a user-supplied reference frame by frame, write a teardown to `workspace/references/`, propose observations or skill edits for a person to approve |+| `sound` | voice, music, effects, mixing and mastering |+| `paper-design` | working on the Paper canvas (mode-aware) |+| vendored HyperFrames skills | composition authoring, CLI, animation, creative, media, registry, slideshow, website-to-video, PR-to-video, music-to-video, captions, overlays, explainer, general video, Remotion porting |++### 11.2 Principles the skills must encode++- Storyboard first for motion: it grounds the agent and gives people a cheap thing to react to.+- A deck is a sequence of frames; a film is a sequence of frames with something crossing between them.+ A film is an argument with a turn; a frame asks for at most two things at once.+- Fewest words on graphics: each fact once; no sub-line, caption, footer, URL or eyebrow the ask did+ not supply; explanation belongs in the reply.+- Concept first. Never ship generic abstract node/dot/network wallpaper; a weak pass is a reject.+- The agent looks at its own renders and fixes what is off, the same loop it runs on code.+- A clear ask gets finished work, not a proposal: make the concept, layout and copy calls and name+ them in one line. When options help, render them instead of describing them.+- Speak in a teammate's words: never let tool names, file paths, scores or gates reach the person+ unless they ask.++### 11.3 Rules versus observations (the bitter lesson)++The internal video rules grew to ~50,000 lines and ~2,700 prohibitions; a hand-written plugin of+~2,600 lines made better films. Measured on one brief after a model upgrade, the share of frames where+nothing moves was 10% for the model alone, 43% with stock HyperFrames skills, 57% with the full+rulebook and 18% with one small motion skill. So:++- Ship small skills that teach judgment and process; keep the brand as hard rules; express taste as+ observations the agent weighs.+- Every doctrine rule in the public wiki names its evidence: a measurement on a film the project made+ (for example with the sample brand during Slice 9 evals), or a public, linkable source. Rules whose+ only evidence is internal or third-party media are rewritten as proposed guidance or dropped.+- Credit public creators with links when a technique derives from their public work; never reproduce+ their media.+- Keep the still-frame-share and other `film-analysis` metrics as eval signals (§20), not as hard+ gates that fight the model.++## 12. Brand system++### 12.1 Brand pack++```text+workspace/brand/ (Git-ignored; defaults to examples/brands/example-studio/)+ brand.toml name, description, default formats, voice summary, file pointers+ tokens.json validated by src/design_agent/brand/schema.py+ tokens.css generated from tokens.json (CSS custom properties, neutral --brand-* prefix)+ fonts.toml families, weights, files, sha256, required flags, open fallbacks+ logos/ SVG/PNG marks with usage notes (clear space, minimum size, colorways)+ voice.md tone and copy rules+ graphic-language.md what graphics should mean, construction rules, do/don't examples+ examples/ optional approved reference outputs (own work only)+```++`tokens.json` keeps the internal schema's shape so gates port cleanly: `design.allowedColors`,+`extendedPalette`, `officialAssetColors`, `bannedColors`, `allowedFontTokens`, `knownOffBrandFonts`,+`fontStacks`, `maxRectRadiusPx`, `creativeTypography`, `diagramConstruction`, `replacementColors`;+`copy.bannedPhrases`, `warnPhrases`, `bannedChars`, `maxHashtags`, `casingRules`. Validate on load and+in `doctor`; a broken pack fails loudly.++### 12.2 Sample brand++`examples/brands/example-studio/`: a fictional brand created for this repository, with an original+SVG logo, a palette, OFL fonts and a short voice guide, licensed CC0 (or Apache-2.0) and checked for+obvious trademark collisions. Every example, fixture, test, gallery output and doc screenshot uses it.++### 12.3 Brand onboarding++A coding-agent skill (`.agents/skills/brand-onboarding/`) builds or updates the pack from what the user+provides: a brand guide PDF, a website, existing files, or a Paper file (via Paper MCP reads of tokens,+palette and type nodes). It asks at most two questions per turn, records sources and dates, never+invents rules, and asks a person to review. The setup console only points at the skill; it does not+edit the brand.++## 13. Paper integration++See `docs/prep/partner-integrations.md` §2 (moves to `docs/partners/paper.md`). Summary:++- Modes: Local (stdio `paper mcp` or `http://127.0.0.1:29979/mcp`; default for CLI and Studio),+ Bridged (the bundled bearer-authenticated bridge in front of a user's Paper Desktop, reachable over+ a tunnel the user owns; usable from MDA and self-hosted), Hosted worker (documented recipe only),+ Off (boards render in the sandbox and attach to the thread).+- MDA's `define_mcp` supports HTTP and SSE transports only (no stdio), so MDA deployments use Bridged+ mode. The local and self-hosted runtimes use `langchain-mcp-adapters` and may use stdio.+- Host-enforced tool allowlist, scheme refusal, protected brand file, default drafts file, degrade one+ missing tool not the whole MCP layer, export allowed in Local and Bridged modes.+- Verify the MCP tool naming the installed SDK produces (`{server}_{tool}` versus `{server}__{tool}`)+ and make the deferral and scope rules use the real separator.++## 14. Surfaces++### 14.1 MDA native Slack++- `channels/slack.py` with name (≤ 35 chars), description (≤ 139), icon (512×512 PNG ≤ 1 MB),+ background color, trigger behavior and bot triggers from settings; MDA routes through its Trigger+ Server, posts the final reply, reacts to the starting message, provisions the Slack app, transfers+ inbound files to `/workspace/attachments/`, and renders approval cards for interrupts.+- One Trigger channel per agent; Slack channels forbid `deploy --no-wait`; schedules and channels+ require `identity.py`.+- MDA 0.9.3 offers `runtime.channel.post` (an extra text message) but no streaming or message+ updates. Live progress, status and the footer therefore call the Slack Web API directly with the+ reserved agent connection `mda/slack-bot-token` and the channel/thread ids from `raw_event` (the+ documented pattern). Use Slack's agent streaming and status APIs where available; fall back to one+ updated message.+- Track the 0.10 line: `trigger_mode="mention|thread|all"` replaces `trigger_on_all_messages`, and shell+ environment will take precedence over the project `.env`.++### 14.2 Self-hosted Slack and API++- Slack via Bolt: Socket Mode (no public URL) or signed HTTP; streaming progress; file upload; the+ same steering, dedupe and authorization rules as MDA. Manifest in `config/slack-manifest.example.yaml`.+- FastAPI: `POST /threads/{id}/messages`, artifact downloads for the thread owner, health, bearer+ tokens mapped to callers, per-caller thread ownership. Not the LangGraph Agent Server protocol.++### 14.3 CLI++`design-agent setup | doctor [--sandbox] | demo | ask "<request>" [--file …] | brand+(validate|show|init) | fonts verify | sandbox (publish|use|test) | skills (verify|sync-vendor) | deploy+| dev | serve | slack | config (show|set|generate) | test (model|sandbox|paper|slack|db|all)`, with+`--json` where useful. `deploy` runs the preflight then `mda deploy .`; `dev` runs `mda dev .`.++### 14.4 Studio++`uv run mda dev .` opens the managed runtime in LangSmith Studio for development: model calls, tool+results, interrupts, helper runs.++## 15. Runtime profiles, persistence and deployment++| Profile | Graph | Persistence | Sandbox | Slack | Schedules |+| --- | --- | --- | --- | --- | --- |+| Local | `create_deep_agent` | in-memory checkpointer; local store file | Docker runner (default), LangSmith, or host-dev | none (CLI) | none |+| MDA | `define_deep_agent` | managed threads, checkpoints, store, Context Hub | managed, baked from recipe | native channel + direct Web API for progress | `schedules/*.py` + runtime schedules |+| Self-hosted | `create_deep_agent` behind FastAPI | Postgres checkpointer and repositories | Docker runner or LangSmith | Bolt adapter | your scheduler calls the CLI; housekeeping runs in-process |++Parity contract: for the same model, brand, skills, thread state and request, every profile exposes the+same capabilities and produces the same files. Presentation and timing may differ.++### 15.1 Managed Deep Agents (recommended)++- Requires a LangSmith organization with MDA access, an API key with deployment permission, and a+ model key. Regions: GCP US (default), GCP EU, GCP APAC, AWS US via `LANGSMITH_ENDPOINT`.+- Project layout follows MDA conventions: root `agent.py` (named `agent` export), `instructions.md`,+ `identity.py`, `channels/slack.py`, `schedules/housekeeping.py`, `sandbox/__init__.py` ++ `sandbox/setup.sh`, optional `memory.py`, optional `tools/mcp.py`, `skills/<name>/SKILL.md`,+ `[tool.mda] python-version` in `pyproject.toml`. Do not author `langgraph.json`.+- `uv run design-agent deploy`: preflight (`doctor`, brand pack, fonts, manifest, `.env` review —+ MDA forwards every non-reserved `.env` key as a deployment secret and archives ordinary project+ files even if Git-ignored), then `mda deploy .`, Slack authorization hand-off, wait for the revision,+ then a smoke message. The optional console's "Deploy agent" button runs the same action.+- One-click from GitHub: MDA has a hidden `mda prepare` used by LangSmith's GitHub-sourced builds. If+ LangSmith exposes a public "deploy this repository" flow by release, add a README button; otherwise+ the command above is the one-click path. (Open question for the MDA team.)+- `uv run mda delete` removes the deployment, sandboxes, snapshots, crons and Context Hub repos.++### 15.2 Self-hosted++`docker compose up -d --build` starts the API, Postgres and the sandbox runner; `--profile slack`+adds the Bolt worker. The API and Slack worker share Postgres. Back up Postgres and the workspace+volume. MDA's own `--push-to` path targets self-hosted LangSmith, not plain Docker; this profile is the+LangSmith-free path, following the Paid Media Agent.++## 16. Security and safety++- Untrusted inputs: model output, user files, Slack events, Paper canvas content and comments, MCP+ metadata, web pages, reference films and their transcripts. None of them can grant permission,+ change policy, reveal secrets or trigger publishing.+- Secrets: environment or deployment secrets only. Never in prompts, graph state, sandbox files,+ logs, errors, Slack blocks, fixtures, snapshots or tests. Host tools hold keys and drop files in.+- Sandbox: workspace path allowlist; no `.env`, host home, Docker socket, SSH agent or cloud metadata;+ default-deny egress at runtime; sanitized archive extraction, paths, filenames, MIME types, sizes;+ SSRF-hardened asset fetch for user-supplied URLs; artifacts move through host-controlled transfer.+- Tool authorization: selection is not authorization. Before invocation trusted code resolves the+ exact tool, validates arguments against the current schema, applies scope policy (Paper allowlist,+ protected files), and sanitizes errors.+- No outward actions in v0.1 beyond replying in the thread and editing the configured Paper drafts.+ Paper deletes, token writes and AI image generation are off unless the operator enables them.+- Licensing: CI blocks committed font binaries outside `fonts/`, media in `workspace/references/`, and+ banned identifiers; vendored files must match `skills-lock.json`.++## 17. Extraction and scrub process (from the internal reference)++1. Start a fresh repository; never import the internal git history.+2. Port through an allowlist copier (`scripts/import_from_reference.py`, internal-only, deleted before+ release) that copies only paths listed in `docs/prep/extraction-map.md`, rewrites names, and writes+ an import log with source paths and checksums (kept out of the public tree).+3. Re-vendor HyperFrames skills from upstream; do not copy the internal vendored copies.+4. Run the ban-list scan (§18.4), gitleaks over the full history, and a license inventory (every+ third-party file has a license and a NOTICE line, or it is removed).+5. Rewrite all examples, fixtures and docs against the sample brand.+6. Legal and partner review gates (§24) before the repository becomes public.++## 18. Repository, tooling and CI++### 18.1 Layout (target)++```text+agent.py · identity.py · instructions.md · memory.py.example+channels/slack.py · schedules/housekeeping.py · sandbox/{__init__.py,setup.sh,Dockerfile,README.md}+skills/<name>/ runtime skills, ours and vendored (one level; see §10)+src/design_agent/+ assembly.py · config.py · cli.py · doctor.py · demo.py · deployment.py+ models/ · harness/ · middleware/ · tools/ · pipelines/ · brand/ · paper_bridge/+ runtime/{profiles.py,mda.py,self_hosted.py,local.py,sandbox/,waker/}+ surfaces/{api/,slack/} · admin/ (optional console) · testing/ (scripted model, fakes, fixtures)+workspace/{tools/,brand/README.md,references/README.md,projects/.gitkeep}+examples/{brands/example-studio/,prompts/,README.md}+fonts/ (OFL) · private-fonts/ (ignored) · config/*.example.* · docs/ · tests/+.agents/skills/{design-agent-onboarding,brand-onboarding,vendor-sync,release-check}/+.github/{workflows/{ci,compatibility,release}.yml,ISSUE_TEMPLATE/,PULL_REQUEST_TEMPLATE.md,dependabot.yml}+README.md · AGENTS.md · CLAUDE.md · OPERATIONS.md · SPEC.md · CONTRIBUTING.md · SECURITY.md+CODE_OF_CONDUCT.md · LICENSE (Apache-2.0) · NOTICE.md · CHANGELOG.md · Makefile · pyproject.toml+uv.lock · Dockerfile · docker-compose.yml · .env.example · skills-lock.json · .gitleaks.toml+.pre-commit-config.yaml+```++### 18.2 Toolchain++Python 3.11+ (MDA supports 3.11–3.14), uv, Pydantic v2, Ruff, mypy (strict for new modules; ported+harness modules may start in a documented gradual list that shrinks to zero before v0.1), pytest,+Node only inside the sandbox recipe. One `pyproject.toml`, one lockfile, explicit upper bounds on fast+pre-1.0 packages (`managed-deepagents>=0.9.3,<0.10`, `deepagents>=0.7.28,<0.8` at the time of writing;+never a `.devN` pin in a release).++### 18.3 CI++- `ci.yml` (Python 3.11 and 3.13): lockfile install, Ruff, format, mypy, offline tests, scripted demo+ (render steps skipped without Docker, executed in the render job), MDA definition import smoke,+ `skills verify` (vendored checksums), ban-list scan, docs link check.+- Render job: build `sandbox/Dockerfile`, run the recipe probe and the render smoke tests (§20.2).+- `secrets` job: pinned gitleaks over full history.+- `compatibility.yml` weekly: `uv lock --upgrade`, latest stable MDA and Deep Agents, latest+ HyperFrames CLI and skills in a throwaway lock; run the suite; never auto-merge.+- `release.yml`: tag, changelog, GitHub release (no PyPI publish in v0.1 unless decided).++### 18.4 Ban-list scan++A test fails on any match of: LangChain brand tokens and logo file names, internal people's names,+Slack id patterns outside test fixtures that use clearly synthetic ids, `@langchain.dev`, LangSmith+workspace/deployment ids and URLs, internal snapshot names, internal agent names, the internal codename+outside `NOTICE.md`, licensed font file names outside docs, and third-party media extensions under+`workspace/references/` or `examples/`. The list lives in `tests/unit/test_public_hygiene.py` and is+reviewed at release.++## 19. Configuration (`.env.example` outline)++```dotenv+# Model (provider:model). Gateway form: langsmith:provider/model+DESIGN_AGENT_MODEL=anthropic:claude-opus-5-5+DESIGN_AGENT_MODEL_EFFORT=high+DESIGN_AGENT_HELPER_MODEL=+DESIGN_AGENT_LOOK_MODEL=+DESIGN_AGENT_TOOL_SELECTOR_MODEL=+DESIGN_AGENT_MODEL_BASE_URL=+DESIGN_AGENT_MODEL_API_KEY_ENV=+ANTHROPIC_API_KEY=+OPENAI_API_KEY=+GOOGLE_API_KEY=+LANGSMITH_API_KEY= # MDA deploy/dev, LangSmith sandboxes, tracing, optional gateway+LANGSMITH_GATEWAY_API_KEY=++# Runtime+DESIGN_AGENT_RUNTIME=local # local | mda | self_hosted+DESIGN_AGENT_SANDBOX=auto # auto | mda | langsmith | docker | host+DESIGN_AGENT_SANDBOX_SNAPSHOT=+DESIGN_AGENT_SANDBOX_VCPUS=8+DESIGN_AGENT_SANDBOX_MEM_GIB=16+DESIGN_AGENT_SANDBOX_IDLE_TTL_SECONDS=600+DESIGN_AGENT_SANDBOX_EGRESS_ALLOW=+DESIGN_AGENT_MAX_PARALLEL_BUILDERS=3+DESIGN_AGENT_JOB_BUDGET_USD=++# Brand+DESIGN_AGENT_BRAND_PATH=workspace/brand # falls back to examples/brands/example-studio+DESIGN_AGENT_PRIVATE_FONTS_DIR=private-fonts++# Media (optional)+DESIGN_AGENT_IMAGE_MODEL=+ELEVENLABS_API_KEY=+GROQ_API_KEY=++# Paper (optional)+PAPER_MODE=off # off | local | bridged+PAPER_MCP_URL= # local: http://127.0.0.1:29979/mcp or stdio; bridged: https://…/mcp+PAPER_BRIDGE_TOKEN= # bridged; MDA connection "paper-bridge" in production+PAPER_BRAND_FILE_ID= # read-only+PAPER_DRAFTS_FILE_ID=+PAPER_TEAM_ID= # bridge team check++# Optional MCP+EXA_API_KEY=++# Behavior+DESIGN_AGENT_ENABLE_PROGRESS=1+DESIGN_AGENT_ENABLE_FOOTER=1+DESIGN_AGENT_ENABLE_STEERING=1+DESIGN_AGENT_ENABLE_LEARNING=1+DESIGN_AGENT_ENABLE_TOOL_CLEARING=0++# MDA Slack appearance+DESIGN_AGENT_SLACK_NAME="Design Agent"+DESIGN_AGENT_SLACK_DESCRIPTION="On-brand design and motion from a chat thread."+DESIGN_AGENT_SLACK_BACKGROUND_COLOR=++# Self-hosted+SLACK_BOT_TOKEN=+SLACK_APP_TOKEN=+SLACK_SIGNING_SECRET=+SLACK_TRANSPORT=socket_mode+DATABASE_URL=+DESIGN_AGENT_API_TOKENS=+DESIGN_AGENT_API_HOST=127.0.0.1+DESIGN_AGENT_API_PORT=8080+```++## 20. Tests and evals++### 20.1 Deterministic unit tests++Settings and capability registry; brand schema validation and token CSS generation; brand-lint with+fixture brands; video-gate per banned pattern; manifest generation and staging deltas; font+verification; Paper scope (allowlist, schemes after unescaping, protected file, default file,+missing-tool degradation) and bridge (bearer, rebinding, path, team); MCP isolation; tool disclosure+headers; image clamp; step budget; retry classification; history repair; harness primitives (events,+policy, inbox coalescing and retries, tasks, ledger heartbeats, wake-ups, durable transcript stubs and+caps, workflow memo and resume, branches backup and merge, watch parsers incl. HyperFrames and stall,+offload, learning merge and decay, meter); delivery exactly-once; ban-list hygiene; docs links.++### 20.2 Render smoke tests (CI render job, Docker)++Inside the sandbox image: Chromium screenshot of a fixture page at three sizes with brand fonts+resolved; `hyperframes lint`, `validate`, `snapshot --at 1.0`, 2 s 1920×1080 draft render with ffprobe+duration within one frame and non-blank first/last frames; ECharts and D2 fixture renders; image-ops+pipeline; audio mixer loudness on a synthesized fixture.++### 20.3 Real-graph contract tests++Scripted model, real Deep Agents graph, real middleware, fake MCP servers, fake media providers, a fake+sandbox backend (or the Docker runner in the render job): quick ask to delivery; storyboard gate before+a film render; `start_task` → progress → completion wake-up; restart → interrupted notice →+`resume_task` from transcript; `schedule_wakeup` and quiet replies; pipeline step memo and operator+question; looks fan-out, pick and merge; render job watcher wake on exit, failure and stall; steering+into a running helper; model failure boundary message; MCP server failure isolation; Paper storyboard+twin and export; memory policy when enabled.++### 20.4 Source-blind behavior evals++Hidden from implementation details, scored by trace assertions and deterministic checks: asks at most+two questions on a vague brief, otherwise decides and names its calls; storyboards before rendering a+film; lints and snapshots before a final render; never claims an attachment that was not uploaded;+does not invent brand rules or logos (asks for the logo); keeps copy exact; respects "fewest words";+uses `look` instead of hoarding frames; reports a blocked artifact after two correction rounds; handles+Paper being unavailable; stays quiet on check-ins with nothing new.++### 20.5 Design eval set and model matrix++`tests/eval/tasks.json`: ~25 tasks on the sample brand (4-size ad set, restyle a supplied layout,+LinkedIn card, 10-slide deck, flywheel diagram, bar chart with annotation, thumbnail set, storyboard,+15 s teaser, 45 s launch film with voiceover). Graders: artifact contract, brand-lint, text fidelity,+render gates, still-frame share, duration, cost and time; plus a human review checklist (no LLM taste+judge). Run at least: the default Anthropic model, one current OpenAI vision model, and one portable+model via `LLMToolSelectorMiddleware`. Record success, cost per accepted task, time, tool precision,+unnecessary calls.++### 20.6 Opt-in live tests++`DESIGN_AGENT_LIVE_TESTS=1`: model ping, image generation, ElevenLabs voice, LangSmith sandbox bake and+probe, Paper Local mode read/write/export on a scratch file, MDA dev smoke. Never run in CI by default.++## 21. Documentation and launch packaging++### 21.1 README (mirror the Paid Media Agent)++Centered header with LangChain OSS mark, name, one-line description ("On-brand design and motion from+a chat thread. Built on Deep Agents. Deploy with Managed Deep Agents."), links (Quick start ·+Deployment · Documentation · Contributing). A hero image of the designer's computer drawn for the+sample brand. "What it does" (stills and ad sets, decks, diagrams and charts, storyboards and motion,+long jobs with live progress). Quick start (`uv sync`, `uv run design-agent setup`, coding-agent+prompt, offline demo, first asks). "Built with" (HyperFrames, Paper, Deep Agents, MDA) with partner+links. Brand and fonts. Deployment table (MDA recommended vs self-hosted). Build on it (skills, brand,+tools, pipelines). License and health links.++### 21.2 Docs++`OPERATIONS.md` (commands, MDA deployment, Slack settings, schedules, sandbox, self-hosting, models,+verification), `docs/customization.md` (brand pack, fonts, references, runtime skills, memory,+schedules), `docs/self-hosting.md`, `docs/architecture/` (README with binding invariants,+runtime-profiles, orchestration, designers-computer, media-pipelines, context-and-cost, surfaces,+security), `docs/partners/{hyperframes,paper,paper-hosted-worker}.md`, `docs/gallery/` (outputs made+by the agent for the sample brand, each with its prompt and cost), `docs/sources/official-links.md`,+`CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, `NOTICE.md`, `CHANGELOG.md`.++### 21.3 Launch++The launch blog ("How we built our Design Agent") links the repository; the GTM Engineering Live+webinar demos clone → demo → deploy → Slack ask. Partner co-promotion (HyperFrames adopters listing+and quote-post, Paper integration post and a template file for the sample brand) follows partner+sign-off. The repository can launch after the blog; it must not block it.++## 22. Implementation slices++Each slice ends with its acceptance tests green, docs updated, and a short verification note in the+pull request (not in the repository).++0. **Ground truth.** Verify current official docs, installed `managed-deepagents` 0.9.3 and+ `deepagents` 0.7.28 APIs (`define_deep_agent`, `define_sandbox` extra keys, `upload_files`,+ `runtime.schedules`, `runtime.channel`, `connections.get`, `define_mcp` naming, memory layers),+ HyperFrames CLI flags at the pinned version, Paper transports. Bake the recipe once with MDA and+ measure size and time; decide `docker_image` bake versus published snapshot. Record results in+ `docs/prep/source-inventory.md`. Acceptance: a written compatibility table; a baked sandbox that+ passes the probe.+1. **Skeleton and computer.** Repository scaffold, settings, capability registry, assembly with one+ agent and no helpers, sandbox recipe and Docker runner, workspace stager, brand schema and sample+ brand, open fonts, gates ported and brand-neutral, `doctor`, `demo` (scripted model: one still in+ three sizes). Acceptance: clean clone → `demo` renders and passes brand-lint and artifact-contract.+2. **Media pipelines.** Stills, image-ops, data-viz, thumbnails, HyperFrames motion with video-gate and+ render smoke, audio host tools and mixer, image generation, delivery contract, CLI `ask`.+ Acceptance: render smoke suite green; scripted demo renders a 4 s teaser.+3. **Orchestration harness.** Port harness and lead tools behind `HelperRunner`, `Waker`,+ `SandboxExec`; MDA waker on runtime schedules; durable helpers; pipelines (launch film); looks;+ render watchers with HyperFrames parser; look tool; learning loop. Acceptance: §20.3 contracts green;+ wake latency measured and documented.+4. **Context, cost and failure boundaries.** Tool disclosure, cache policy, clearing, step budget,+ retry and failure boundary, history repair, MCP isolation, image clamp, meter and footer data.+ Acceptance: first-call prompt token budget measured and within target; failure-path tests green.+5. **MDA deployment and Slack.** `agent.py`, `identity.py`, channel, housekeeping schedule, sandbox+ declaration, progress streaming via the Slack Web API, footer, steering, file delivery, `deploy`+ preflight. Acceptance: deploy to a test workspace; a quick ask and a storyboarded teaser complete in+ Slack with live progress, check-ins and one delivery; a redeploy mid-job yields an interrupted notice+ and a successful resume.+6. **Paper.** Local and Bridged modes, scope middleware, bridge, storyboard twin and export, brand+ import in the onboarding skill. Acceptance: unit and contract tests; opt-in live test on a scratch+ file.+7. **Self-hosted.** FastAPI, Postgres repositories (checkpoints, helper records, transcripts, wake-ups,+ watches, observations), Bolt Slack adapter with streaming and file upload, Docker compose with the+ sandbox runner. Acceptance: compose up from a clean machine; the same Slack scenarios as Slice 5.+8. **Onboarding and console.** `.agents/skills/` (onboarding, brand-onboarding, vendor-sync,+ release-check), optional setup console (Welcome → Model → Media → Brand → Paper → Deploy) over the+ same CLI actions. Acceptance: a new developer configures and deploys using only the README and a+ coding agent.+9. **Skills and taste.** Port and scrub the design wiki, motion direction, launch film (new sample-brand+ case study), storyboard, reference study, sound, image generation; re-evidence doctrine against+ sample-brand films; run the eval set and model matrix; build the gallery. Acceptance: eval report+ committed under `docs/gallery/` (outputs and metrics), human review notes recorded.+10. **Release readiness.** Docs complete, ban-list and license inventory clean, gitleaks clean, partner+ reviews, legal review, CHANGELOG, tag. Acceptance: §23.++## 23. Definition of done (v0.1)++- A clean clone runs `uv sync && uv run design-agent demo` and renders a still set and a short film+ with no API keys (Docker present), or explains exactly what is missing.+- Model configuration is direct and documented; the capability registry is tested.+- MDA deployment is one command with a preflight; Slack works with live progress, check-ins, steering,+ file delivery and restart recovery.+- Self-hosted compose works with Slack, Postgres durability and the Docker sandbox runner.+- MDA, self-hosted and local runtimes use one assembly and pass the parity contract.+- HyperFrames is pinned, vendored skills verified, render smoke green; Paper Local and Bridged modes+ pass their tests; both partners have reviewed their sections.+- Every gate is brand-neutral and driven by the brand pack; the sample brand is complete.+- The eval set ran on at least three models with recorded results; the gallery shows real outputs.+- Public docs contain no private data; ban-list, license inventory and gitleaks are clean; NOTICE is+ complete; LICENSE is Apache-2.0; security contact is explicit.+- Commands, links, install steps and examples work from a clean environment.++## 24. Open questions and gates++| # | Question | Owner | Blocks |+| --- | --- | --- | --- |+| 1 | When will MDA release async subagents sharing the lead's sandbox and Slack thread, and a public "start a run on this thread" API? | MDA team | migration off the custom helper runner (not v0.1) |+| 2 | Is there a public one-click "deploy this GitHub repository" flow (the `mda prepare` path)? | MDA team | README deploy button |+| 3 | `docker_image` bake filesystem capacity for a ~2–3 GiB media image; recommended path? | MDA team | Slice 0 decision |+| 4 | Skills Context Hub limits (file count, size) for ~700 vendored files | MDA team | vendoring scope |+| 5 | HyperFrames skills license, pin strategy, provider override, render progress, OSS key, telemetry, GSAP guidance (`partner-integrations.md` §3) | HeyGen | Slices 2, 10 |+| 6 | Paper hosted MCP, export to remote agents, tool-name stability, plan limits, Linux Desktop (`partner-integrations.md` §3) | Paper | Slice 6 scope |+| 7 | Repository name final (`design-agent` vs `content-studio`), org, and whether to publish to PyPI | LangChain marketing / OSS | Slice 10 |+| 8 | Legal review: fonts, sample brand, vendored skills, D2 binary in image, partner trademarks and logos in README | Legal | Slice 10 |+| 9 | Release timing relative to the launch blog and webinar | Marketing | none (repo must not block the blog) |diff --git a/docs/prep/extraction-map.md b/docs/prep/extraction-map.mdnew file mode 100644index 0000000..18cfd0b--- /dev/null+++ b/docs/prep/extraction-map.md@@ -0,0 +1,145 @@+# Extraction map: internal agent → Design Agent++> Internal build note. Paths on the left refer to the private source repository+> (`content-studio` @ `f87d644`, read with `git show origin/main:<path>`). Never copy a file+> wholesale without passing it through the scrub and license checks in SPEC §17. Delete+> `docs/prep/` before the first public push.++Actions:++- **KEEP**: port with light edits (names, config, imports). Behavior unchanged.+- **GENERALIZE**: port the mechanism; remove company content; move constants to config or the brand+ pack; rewrite examples against the sample brand.+- **REWRITE**: the idea survives, the code or text does not (written fresh for the public repo).+- **REPLACE**: superseded by a public upstream feature (latest MDA, Deep Agents, HyperFrames, Paper).+- **EXCLUDE**: not part of the open-source product. Never copied.+- **DEFER**: valuable, out of v1 scope; listed as a roadmap item with its extension point.++Target paths are relative to the new repository root.++## 1. Agent definition and assembly++| Source | Action | Target | Notes |+| --- | --- | --- | --- |+| `agent.py` (245) | REWRITE | `agent.py` (thin, ≤40 lines) + `src/design_agent/assembly.py` | One `build_agent_components(settings, runtime)` shared by MDA, self-host and CLI, as in the Paid Media Agent. Social, quote, LinkedIn, Notion, Webflow, handoff wiring and card-action maps are removed. Feature flags become typed `Settings` fields. |+| `subagents.py` (188) | GENERALIZE | `src/design_agent/assembly.py` (`build_subagents`) | Keep one worker declared at three effort levels plus `general-purpose`. Rewrite `WORKER_PROMPT` without the internal name, cost figures or knowledge paths; keep its contracts (read named files first, own only assigned files, progress file, `report_progress`, image budget, stop at time or quality bar, reviewers do not fix, never deliver). Effort levels must map to whatever the configured model supports (capability registry). |+| `models.py` (544) | GENERALIZE | `src/design_agent/models/` | Direct providers by default (`provider:model`), LangSmith gateway as an optional preset (`langsmith:provider/model`), as in the Paid Media Agent. Remove the hard-coded gateway origin. Keep: exact-id capability registry (vision, tool search, effort levels, output ceilings, thinking/cache behavior), the Opus fallback profile logic, stall timeout, SDK retries at 0 with our retry middleware, cache TTL per role. Prune the internal model list to verified public ids. |+| `instructions.md` (76) | REWRITE | `instructions.md` | Generic identity ("a design agent for your team"), delegation contract, delivery contract, approval rules, translation rule (speak in a teammate's words, never tool names), storyboard-first rule, brand source precedence. No peer agents, no Slack ids, no people roster, no internal deployment notes. Keep under ~80 lines; everything else lives in skills. |+| `identity.py` | KEEP | `identity.py` | `define_identity(auth=auth.langsmith_api_key())`; document MDA's Supabase identity for private per-user conversations. |+| `memory.py` (48) | GENERALIZE | `memory.py.example` (off by default) | Per-user memory off by default (privacy); shared agent memory opt-in. Document the trade-offs as the Paid Media Agent does. |+| `NOTICE.md`, `licenses/managed-deepagents-sdk-MIT.txt` | REWRITE / KEEP | `NOTICE.md`, `licenses/` | Provenance for code descending from the MIT SDK example; HyperFrames skills (Apache-2.0); OFL fonts; ECharts (Apache-2.0); vtake-skills (MIT) if graphic-overlays ships; D2 (MPL-2.0, binary in image only). |++## 2. Harness (orchestration core)++The internal `harness/` package (18 files, 6,438 lines) imports only the standard library,+langchain, langchain_core and langgraph. It is the main value to carry.++| Source | Action | Target | Notes |+| --- | --- | --- | --- |+| `harness/events.py`, `policy.py`, `inbox.py`, `notices.py` | KEEP | `src/design_agent/harness/` | Event bus, attention policy (wake now / next turn / log only), coalesced wake-up inbox with retries, notice text. |+| `harness/tasks.py`, `ledger.py`, `wakeups.py`, `protocols.py` | KEEP | same | Background task records and heartbeats, self-scheduled check-ins, `HelperRunner`/`SandboxExec` protocols. Add a `Waker` protocol (SPEC §7.4). |+| `harness/durable.py` | KEEP | same | Helper transcript checkpoints and `resume_task`. Re-verify against the latest Deep Agents: if it now checkpoints background subagents natively, REPLACE and delete ours (SPEC §7.3). |+| `harness/workflow.py` | KEEP | same | Pipelines as code (memoized steps, `ask` operator questions, resume). |+| `harness/branches.py` | KEEP | same | Parallel creative "looks" (folders per look, pick and merge with backup). |+| `harness/offload.py`, `watch.py` | KEEP | same | Detached render jobs and log watchers. Add a HyperFrames progress parser and make the default parser `heartbeat`, not `remotion`. |+| `harness/cache.py`, `context.py` | KEEP | same | Cache TTL, tools breakpoint, prefix watch, stagger gate; server-side tool-result clearing; image-aware token counts. Re-verify against current provider APIs and Deep Agents summarization. |+| `harness/meter.py` | GENERALIZE | same | Move the price table to `config/prices.toml` with a date and source link; cost is an estimate. |+| `harness/learning.py` | KEEP | same | Per-skill observation store (save, read, rate, merge, decay). Optional feature, on by default once the store exists. |+| `docs/harness/*.md` | GENERALIZE | `docs/architecture/orchestration.md` and siblings | Public explanations of each primitive, with the upstream mapping table. |+| `tests/harness/*`, `tests/test_{background,look,looks,learning,watch,pipeline,harness_surface,subagents}.py` (244 tests) | KEEP | `tests/unit/harness/`, `tests/contract/` | Rewrite fixtures that mention internal names. |++## 3. Middleware++| Source | Action | Target | Notes |+| --- | --- | --- | --- |+| `middleware/background.py`, `watch_tools.py`, `pipeline_tools.py`, `looks_tools.py`, `learning_tools.py`, `look.py`, `meter.py` | GENERALIZE | `src/design_agent/middleware/` | Type against a runtime adapter interface, not `ManagedDeepAgentRuntime` directly. `LOOK_MODEL` from config. Wake-ups go through `Waker` (MDA adapter on public APIs; self-host adapter in-process). |+| `middleware/boundary.py` (484) | REWRITE | `src/design_agent/assembly.py` + `runtime/mda.py` | Assembly of guards and parent-only middleware, subagent construction. Remove every private MDA import (`_channels.slack.middleware`, `_ingress`, `_ingress_runs`, `_loopback`, `langgraph_api.server`). |+| `middleware/model_retry.py`, `step_budget.py`, `image_clamp.py`, `tool_error_boundary.py`, `tool_history.py`, `drop_base_prompt.py`, `today.py` | KEEP | same | Model failure boundary (errors never end a run silently), step budget wrap-up, image MIME and size clamp, tool error boundaries, stale `tool_reference` repair, base prompt drop, date note. |+| `tools/disclosure.py` | GENERALIZE / REPLACE | `src/design_agent/middleware/tool_disclosure.py` | Provider-native deferred tool search for verified Anthropic/OpenAI models; `LLMToolSelectorMiddleware` otherwise (Paid Media pattern). Keep the search-header trick for deferred MCP tools. `ALWAYS_SHOWN_SERVERS` from config. Prefer the upstream middleware where it now covers this. |+| `middleware/progress.py`, `phrasebook.py`, `footer.py`, `agent_session.py`, `steering.py` | GENERALIZE | `src/design_agent/middleware/` (+ self-host Slack adapter) | Streaming progress per agent, plain-language step names, reply footer (agents running, time, cost, trace link host from config), Slack agent status, mid-job steering. Phrasebook loses Notion/Hex/Webflow/GTM/Buffer entries. Prefer native MDA Slack streaming/status APIs where the latest SDK provides them (SPEC §12). |+| `middleware/workspace.py` (467) | GENERALIZE | `src/design_agent/middleware/workspace.py` | Stage workspace tools, the active brand pack and fonts into the sandbox with a manifest and sha check; licensed-font setup becomes data-driven from `brand/fonts.toml` (no hard-coded families, no woff2 sha constants). managed-deepagents 0.9.3 has no `deployment_files` or declarative sandbox file sync; keep the stager and upload through `runtime.backend.upload_files`. Skills are mounted read-only from Context Hub outside the sandbox, so the stager must also copy skill scripts into `/workspace/skills/<name>/`. |+| `middleware/paper_scope.py` | GENERALIZE | `src/design_agent/middleware/paper_scope.py` | See partner-integrations §2.4. |+| `middleware/memory_policy.py`, `memory_hot_cap.py`, `memory_learnings.py`, `owner_memory.py` | GENERALIZE | `src/design_agent/middleware/memory/` | Layout allowlist and preference-file shape become config; hot cap stays (200 lines / 12k chars). Only installed when memory is enabled. |+| `middleware/tracing.py`, `trace_labels.py` | GENERALIZE | `src/design_agent/middleware/tracing.py` | Generic run tags (`trigger`, `surface`, `delivered`); no user ids in tags by default. |+| `middleware/slack_actions.py` | DEFER | — | Code-drawn cards are only needed for approvals in the excluded publishing module. |+| `middleware/routines.py` | DEFER (v0.2) | `src/design_agent/routines/` | Housekeeping sweep stays in v1 (§5); user-owned routines are a v0.2 slice with generic sources only. |+| `middleware/asked_only.py`, `bot_callers.py`, `agent_requests.py`, `card_replies.py`, `lazy_connection.py`, `publish_ledger.py`, `notion_scope.py`, `webflow_scope.py` | EXCLUDE (v1) | — | Internal channels, peer agents, quote cards, Managed Tools, company publishing. The exactly-once publish ledger is a documented pattern for a future publishing plugin. |++## 4. Tools++| Source | Action | Target | Notes |+| --- | --- | --- | --- |+| `tools/media.py` (707) | GENERALIZE | `src/design_agent/tools/media.py` | `generate_image` (OpenAI direct by default; model id configurable and passed through, never allowlisted; transparency reported), `generate_voiceover` / `generate_sound_effect` / `generate_music` (ElevenLabs, optional), `transcribe_audio` (local `hyperframes transcribe` default; Groq optional). Remove `fetch_epidemic_asset` (Epidemic excluded in v1). Host-side only; results dropped into `/workspace/...` as files. |+| `tools/files.py`, `projects.py`, `flags.py` | KEEP | `src/design_agent/tools/` | Binary I/O, `list_recent_projects`, `get_render_status`, flag parsing (typed settings replace most flags). |+| `tools/mcp.py` | GENERALIZE | `src/design_agent/tools/mcp.py` + `config/mcp.example.toml` | Config-driven servers. Zero servers is valid (the internal import raised "No MCP server is configured"). Ships: Paper (modes per partner doc), optional Exa (web research for references), optional GitHub read-only (for `pr-to-video`). One failing server never removes the others. |+| `tools/paper.py`, `scripts/paper_mcp_bridge.py` | GENERALIZE | `src/design_agent/tools/paper.py`, `src/design_agent/paper_bridge/` | Local and Bridged modes; the cloud-worker auth flow is not wired by default. |+| `scripts/paper_cloud_worker.py`, `paper_oauth_bootstrap.py`, `paper_oauth_macos.swift`, `docs/runbooks/paper.md` | REWRITE (docs only) | `docs/partners/paper-hosted-worker.md` | Recipe and caveats, no operator identities, no sign-in hand-off app. |+| `tools/slack.py`, `slack_read.py`, `slack_ui.py` | GENERALIZE | `src/design_agent/tools/slack.py`, `surfaces/slack/` | Thread and file reads as the asker could, file fetch; remove `ASKED_ONLY` constants. Cards deferred. |+| `tools/grounding.py` (Drive/Docs) | DEFER | — | Optional host tool later; document how to add a read-only grounding tool to the assembly. |+| `tools/agents.py`, `connect.py`, `managed_tools.py` (+ catalog), `hosted_assets.py`, `person_memory.py`, `voices.py`, `compose_quote.py`, `draft_quote.py`, `quote_card.py`, `trace_flag.py`, `ledger/*`, `social/*`, `routines.py`, `routine_options.py`, `routine_tick.py`, `schedule_run.py` | EXCLUDE (v1) / DEFER | — | Peer handoffs, Managed Tools, public asset hosting, quote copilot, launch ledger, social publishing. Routines DEFER to v0.2 with generic sources (RSS/Atom, web page, Slack links). |++## 5. MDA project declarations++| Source | Action | Target | Notes |+| --- | --- | --- | --- |+| `channels/slack.py` | GENERALIZE | `channels/slack.py` | Name, description, icon, color from settings (Paid Media pattern). Keep the @mention-only trigger option as a setting, default to the platform's default behavior. |+| `channels/reactions.py` | EXCLUDE | — | Keep only the platform's default acknowledgement (eyes). |+| `sandbox/__init__.py` | REWRITE | `sandbox/__init__.py` | Public base image (`docker_image=` a pinned public base) plus `setup.sh` bake; size from settings (default 8 vCPU / 16 GiB for motion; document smaller sizes for stills-only use); idle TTL; default timeout. No snapshot names. |+| `sandbox/setup.sh` | GENERALIZE | `sandbox/setup.sh`, `sandbox/Dockerfile` | Fold in the public parts of the internal base image (Node, ffmpeg, Chrome Headless Shell via `hyperframes browser ensure`, sharp, ECharts, D2, open fonts, fontconfig) so the whole computer is reproducible from the repository. Pin every download with a sha256. Drop `yt-dlp` (third-party video download is not a product feature), Playwright's second Chromium (point renderers at one browser), licensed fonts, brand assets and video-kit. Fail the bake on a lint + draft-render smoke test. |+| `schedules/housekeeping.py` | KEEP | `schedules/housekeeping.py` | Sweep helpers, watches and wake-ups killed by a restart; ends in code before any model call. |+| `pipelines/__init__.py`, `pipelines/launch_film.py` | GENERALIZE | `src/design_agent/pipelines/` | Keep the launch-film pipeline; paths point at the public `launch-film` skill. |+| `asset-manifest.json`, `base-image-assets.json`, `scripts/check_deploy_tree.py`, `scripts/refresh_base_assets.py` | REWRITE | `scripts/build_manifest.py`, `scripts/check_deploy_tree.py` | Generated manifest (no hand-pinning), private fonts declared in the brand pack, check that required inputs exist before deploy. No base-image upload optimization in v1 (the public recipe does not bake project files). |++## 6. Runtime skills++| Source skill | Action | Target skill | Notes |+| --- | --- | --- | --- |+| 16 HyperFrames skills (`hyperframes`, `-core`, `-cli`, `-animation`, `-creative`, `-media`, `-registry`, `faceless-explainer`, `slideshow`, `website-to-video`, `pr-to-video`, `music-to-video`, `embedded-captions`, `graphic-overlays`, `general-video`, `remotion-to-hyperframes`) | REPLACE | `skills/<upstream-name>/` (top level, listed in `skills-lock.json`) | Re-vendor from upstream at a pinned commit, unmodified, with LICENSE and NOTICE. Do not carry the 93 local edits. Remove the CDPR fan-kit asset if upstream still ships it (non-commercial terms) and any vendored GSAP file (load GSAP from the image instead). |+| `motion-studio` (engine + wiki) | GENERALIZE (wiki) / EXCLUDE (engine) | `motion-direction` (+ `references/` pages) | Port the wiki doctrine (directing, craft, techniques, sound, review) as HyperFrames-oriented guidance. Drop the canvas engine, `brand.js` palettes, mark loaders and font gates. Re-evidence rules (SPEC §11.3). |+| `launch-film` | GENERALIZE | `launch-film` | Keep phases, sizing tables, decomposition rules, effort-per-role table, every brief template, `orchestration.md`, `storyboard.md`. Remove `case-studies/agent-platform/` and `case-studies/engine-teaser/` and every line citing them; replace with a case study the agent makes for the sample brand during Slice 9. |+| `film-breakdown` | KEEP | `film-breakdown` | Measure any film the user supplies (cuts, contact sheets, motion energy, beat grid, audio). |+| `video-references` | REWRITE | `reference-study` | The method, not the library: study a user-supplied film frame by frame, write a teardown into Git-ignored `workspace/references/`, and propose observations or skill edits for a person to approve. |+| `video-storyboard` | GENERALIZE | `storyboard` | Brand paths → brand pack. |+| `ad-creative` | GENERALIZE | `stills` (or keep name `ad-creative`) | `html2png.mjs` must read fonts from the brand pack and render with open fonts when no licensed fonts are configured. |+| `data-viz` | GENERALIZE | `data-viz` | Move the hard-coded token object into brand-pack reads; replace examples that name people or LangChain diagrams. |+| `image-ops`, `gif-edit`, `visual-verify`, `film-breakdown` | KEEP | same | Generic. |+| `gpt-image` | GENERALIZE | `image-generation` | Keep craft; remove gallery entries without a clear license; brand rubric reads the brand pack. |+| `score-video` | GENERALIZE | `sound` | ElevenLabs adapters optional; synthesized cue library kept; remove Epidemic and Gemini paths. |+| `brand-design` | GENERALIZE | `brand-design` | Keep the concept gate, ground/accent/type framework; brand facts come from the brand pack. |+| `media-production` | GENERALIZE | `media-production` (router) | Request routing, storyboard-to-render process, delivery contract, Paper routing rule. |+| `content-brief` | GENERALIZE | `content-brief` | Intake for vague requests; no Notion campaign docs. |+| `youtube-thumbnail` | GENERALIZE | `thumbnails` | Craft and gates kept; `channel-today.md` (internal channel and people) removed. |+| `youtube-upload`, `youtube-workflow` | DEFER | — | Upload needs OAuth and publishing policy (v0.2 publishing plugin). |+| `paper-design` | GENERALIZE | `paper-design` | Connection-mode aware; no team/brand-book ids. |+| `routines` | DEFER (v0.2) | `routines` | Ships with the routines slice. |+| `social-learning`, `social-onboarding`, `compose-post`, `technical-blog` | EXCLUDE (v1) | — | Copy and social are outside the design scope; `compose-post`'s human-voice protocol may inform `brand/voice.md` guidance. |+| `analytics`, `community-publishing`, `draft-queue`, `social-amplification`, `quote-ideas`, `langchain-media-render`, `langchain-brand-guidelines`, `video-component-library` | EXCLUDE | — | Internal, trademarked or unlicensed. |++## 7. Workspace++| Source | Action | Target | Notes |+| --- | --- | --- | --- |+| `workspace/tools/video-gate.mjs`, `artifact-contract.mjs`, `text-fidelity.mjs`, `audio-lint.mjs`, `fetch-asset.mjs` (SSRF-hardened), `html2pdf.mjs`, `review-thumb.mjs`, `film-analysis.mjs`, `film-probe.mjs`, `video-score.mjs` | KEEP / GENERALIZE | `workspace/tools/` | Rename the `--lc-*` token prefix to a neutral `--brand-*`; remove the font name in `html2pdf.mjs`. `video-gate` stops calling brand-lint implicitly. |+| `workspace/tools/brand-lint.mjs` (1,141) | GENERALIZE | `workspace/tools/brand-lint.mjs` | Add `--tokens <path>` (default the active brand pack); move font-stack, casing and replacement-color rules into the token JSON; delete LangChain product casing rules. |+| `workspace/knowledge/brand/*`, `langchain-tokens.*`, `paper-reference.json` | REWRITE | `examples/brands/example-studio/`, `workspace/brand/README.md`, `src/design_agent/brand/schema.py` | Keep the token *schema* (`design.allowedColors`, `extendedPalette`, `officialAssetColors`, `bannedColors`, `allowedFontTokens`, `knownOffBrandFonts`, `maxRectRadiusPx`, `creativeTypography`, `diagramConstruction`, `copy.*`) as a documented, validated JSON schema. |+| `workspace/knowledge/platforms/platforms-and-content-types.md`, `brand-applications.md` | GENERALIZE | `skills/design-wiki/platforms.md` | Platform sizes and specs are generic; drop the internal email footer. |+| `workspace/knowledge/references/design-tooling-figma-paper.md` | GENERALIZE | `docs/partners/paper.md` | Public facts only. |+| `workspace/knowledge/strategy/*` | GENERALIZE (frameworks) / EXCLUDE (examples, voice corpus) | `skills/design-wiki/` | Intake framework and quality rubric survive; internal examples do not. |+| `workspace/knowledge/campaigns/*`, `references/langchain-products-glossary.md`, `hex-analytics-workspace.md`, `analytics-and-self-optimization.md`, `team/people.json` | EXCLUDE | — | Internal. |+| `workspace/video-kit/r/` (115 remocn ports), `references/` (70 films), `case-studies/` | EXCLUDE | — | Unlicensed or third-party media. `video-kit/tools/ref-analyze.py` → KEEP as `skills/film-breakdown/scripts/`. |+| `workspace/video-kit/VIDEO-DIRECTION.md`, `VIDEO-DESIGN-LANGUAGE.md`, `motion/` presets | GENERALIZE | `skills/motion-direction/` | Grammar kept; brand-correctness layer reads the brand pack; motion presets renamed off `LCMotion`. |+| `workspace/skills-lock.json` | REWRITE | `skills-lock.json` | Add `commit`, `license`, per-file `sha256`; CI verifies. |+| `fonts/*` (OFL) | KEEP | `fonts/` | Keep `LICENSES.md` and `OFL-1.1.txt`; rewrite `README.md` and `MDA-BUILD.md`. |++## 8. Tests, scripts and docs++| Source | Action | Target |+| --- | --- | --- |+| Harness, guards, Slack surface, media, memory tests (≈770 tests) | KEEP / GENERALIZE | `tests/unit`, `tests/contract` |+| MCP and Paper scope tests | GENERALIZE | `tests/unit/test_paper_scope.py`, `tests/unit/test_paper_bridge.py` |+| Workspace and assets tests (snapshot name, font pins) | REWRITE | `tests/unit/test_workspace_stager.py`, `tests/render/` |+| Social, quote, ledger, voice, handoff tests (~25 files, ~420 tests) and `tests/fixtures/ledger/*` | EXCLUDE | — |+| `scripts/evals/routines_eval.py` | DEFER | v0.2 routines slice (remove its private MDA import) |+| `scripts/traces.py`, `local_probe.py`, `reactions_eval.py`, `voice/*`, `ledger/*`, `probe_managed_tools.py` | EXCLUDE | — |+| `docs/design/tool-disclosure.md`, `docs/design/memory.md`, `docs/harness/*`, `docs/local-testing.md` | GENERALIZE | `docs/architecture/*`, `docs/development.md` |+| `docs/design/social-*`, `qt-copilot.md`, `personal-posting.md`, `scheduling-migration.md`, `docs/research/*`, `docs/runbooks/social-rollout.md`, `MIGRATION.md`, `migration-notes/*`, `.claude/skills/content-studio-traces`, `.cursor/rules/*` | EXCLUDE | — |diff --git a/docs/prep/partner-integrations.md b/docs/prep/partner-integrations.mdnew file mode 100644index 0000000..c6ddfe1--- /dev/null+++ b/docs/prep/partner-integrations.md@@ -0,0 +1,195 @@+# Partner integrations: HyperFrames and Paper++> Internal build note. It references the internal source agent for extraction purposes. Delete+> `docs/prep/` (or move its surviving facts into public docs) before the first public push.++Design Agent is co-launched with two partners. HyperFrames (HeyGen) is the video engine and Paper is+the shared design canvas. Both integrations must be first-class, attributed, pinned, testable without+private infrastructure, and degrade gracefully when the user has not connected them.++## 1. HyperFrames (HeyGen)++### 1.1 What it is to this agent++HyperFrames turns HTML into video: a composition is a web page with timing in `data-*` attributes and+motion on a paused GSAP timeline, rendered frame by frame in Chrome Headless Shell and encoded with+ffmpeg, so the same file always renders the same video. The CLI is the agent's timeline panel:++| Command | Agent use |+| --- | --- |+| `hyperframes init --non-interactive [--example …]` | scaffold a project in `/workspace/projects/<slug>/` |+| `hyperframes lint [--json]` | catch broken timing and contract violations before a render |+| `hyperframes validate` | composition contract check |+| `hyperframes inspect [--json --samples N --at t]` | overflowing text, layout drift |+| `hyperframes snapshot --at <t>` | one frame to look at (the preview server is unreachable from Slack) |+| `hyperframes render --quality draft\|standard\|high --fps 24\|30\|60 --output <file> [--variables-file …]` | final and draft renders |+| `hyperframes add <block>` | registry blocks |+| `hyperframes capture <url>` | website-to-video source capture |+| `hyperframes transcribe --model …`, `tts`, `remove-background` | media helpers |+| `hyperframes browser ensure`, `doctor` | bake-time Chrome Headless Shell install and warm-up |++Verify every flag against the pinned CLI's `--help` during Slice 0. The internal agent used a+`--resolution square-4k` flag that is not in the CLI reference; do not carry undocumented flags.++### 1.2 v1 decisions++- **HyperFrames is the only video engine in v1.** The internal agent also has a bespoke 2D canvas+ engine ("motion-studio") that is tied to its own brand palette, fonts and logos and never calls+ HyperFrames. Do not port the engine. Port its *judgment* (the motion wiki's directing, craft,+ techniques, sound and review doctrine, scrubbed and re-evidenced) as runtime skills that drive+ HyperFrames compositions.+- **Pin, do not float.** The internal sandbox installed `hyperframes@latest` at bake time and the+ skills were a June pull with no commit pin. The open-source recipe pins an exact CLI version and an+ exact upstream skills commit; a scheduled compatibility job proposes upgrades.+- **Vendor the skills unmodified.** Pull the current upstream skill set from+ `heygen-com/hyperframes` at a pinned commit into top-level `skills/<upstream-name>/` folders (MDA+ discovers skills only one level deep), with the upstream LICENSE and a NOTICE, and record each in+ `skills-lock.json` with the commit and per-file sha256. Do not reapply the internal agent's 93 local edits: they were routing and+ brand text. Put local routing, provider overrides and brand-neutral guidance in our own skills+ that sit beside the vendored ones (for example `motion-direction`, `storyboard`, `launch-film`).+ If an override needs a vendored file changed, upstream it.+- **Use the current upstream layout.** Upstream split skills since the internal June pull+ (`hyperframes-audio`, `hyperframes-keyframes`, `media-use`). Vendor what upstream ships at the+ pinned commit; do not resurrect retired internal skills.+- **Providers stay host-side.** Upstream skills can call HeyGen TTS or audio APIs with+ `$HEYGEN_API_KEY` from inside the sandbox. The sandbox never holds keys. Route voice and music+ through host tools (`generate_voiceover`, `generate_music`, `generate_sound_effect`) and, if HeyGen+ offers an open-source key or a host-side API, add a host-tool adapter for it.+- **Render watching.** Long renders run detached (`start_render_job`) with a watcher that wakes the+ lead on exit, failure or stall. Add a HyperFrames progress parser (the internal watcher had parsers+ for remotion, ffmpeg, json and regex, but none for HyperFrames, and defaulted to `remotion`).+ Ask HeyGen for machine-readable render progress (see questions).+- **Determinism gate.** Keep `video-gate` (rejects `Math.random(`, `Date.now(`, `new Date()`,+ timers, `requestAnimationFrame`, unpaused timelines and other seek-breaking patterns) and make it+ brand-neutral: it must not call a brand linter with hard-coded tokens.+- **Attribution.** README "Built with" section, NOTICE entry, the HyperFrames skills LICENSE, and a+ pull request to add Design Agent to HyperFrames' `ADOPTERS.md` once the repository is public and+ HeyGen agrees.++### 1.3 Sandbox recipe (HyperFrames parts)++Node 22 LTS (verify HyperFrames' supported range), ffmpeg, Chrome Headless Shell via+`hyperframes browser ensure` into a fixed cache dir, the pinned `hyperframes` CLI on PATH, fonts+registered with fontconfig, `text-rendering: geometricPrecision` defaults in templates. The recipe+fails the bake if `hyperframes lint` and a 1-second draft `render` of the bundled fixture composition+do not succeed and produce a non-empty MP4 with the expected duration and dimensions (ffprobe).+Do not install two Chromiums unless a renderer needs both (the internal image carried Playwright's+Chromium and HyperFrames' headless shell); prefer one and point other renderers at it.++### 1.4 HyperFrames acceptance tests++- Vendored skills match `skills-lock.json` (upstream repo, commit, path, sha256 per file).+- Fixture composition lints, validates, snapshots at t=1.0s, and renders a 2 s 1920x1080 MP4 in the+ sandbox; ffprobe confirms duration within one frame and a non-blank first and last frame.+- `video-gate` rejects each banned pattern with a fixture and passes the clean fixture.+- Watcher parses HyperFrames progress (or a heartbeat when none is emitted) and wakes the lead on+ exit 0, non-zero exit, and a stall.+- A source-blind eval: asked for a 15 s teaser, the agent lints and snapshots before rendering and+ delivers one final MP4.++## 2. Paper++### 2.1 What it is to this agent++Paper is a design canvas people and the agent both edit. The agent writes HTML onto the canvas, where+it becomes layers a designer can grab and move, and reads boards, tokens, comments and screenshots+back. It is the default surface for new visual work that people will want to point at and nudge+(layouts, storyboards, thumbnails, campaign graphics), while renders still happen in the sandbox.++### 2.2 Transport facts++- Paper's MCP server runs inside Paper Desktop. Desktop installs a `paper` CLI; the recommended+ transport is the stdio server `paper mcp`. The legacy HTTP endpoint `http://127.0.0.1:29979/mcp`+ is served only while a file is open.+- There is no documented hosted or token-based remote MCP. Free plans have MCP call limits that Pro+ lifts.+- The internal agent ran Linux Paper Desktop under Xvfb on an always-on cloud sandbox, signed in+ once as an operator through a custom sign-in hand-off app, fronted by a team-scoped bearer bridge.+ That works but is heavy, depends on undocumented Linux Desktop support, and is not a reasonable+ default for open-source users.++### 2.3 Connection modes (v1)++| Mode | When | How |+| --- | --- | --- |+| **Local** (default for the CLI and Studio) | the agent runs on the same machine as Paper Desktop | stdio `paper mcp` (preferred) or `http://127.0.0.1:29979/mcp`; host-side MCP client; no bridge |+| **Bridged** (self-host or MDA, advanced) | the agent runs elsewhere and the user runs Paper Desktop on a machine they control | the bundled `paper-bridge` (Starlette MCP proxy) in front of the local MCP, reachable over a tunnel the user owns, with a ≥32-byte bearer token, DNS-rebinding allowlist, team check and tool allowlist; the token is an MDA connection or self-host secret |+| **Hosted worker** (experimental, documented recipe only) | a team wants an always-on shared Paper session | the Linux-Desktop-under-Xvfb worker pattern, documented as a recipe with its caveats, not wired by default; replace with a partner-hosted endpoint when Paper ships one |+| **Off** | Paper not configured | boards render as PNG/PDF in the sandbox and are attached to the thread; the agent says Paper is not connected once and continues |++### 2.4 Tool policy (host-enforced)++Port the internal scope middleware, generalized:++- Allowlist reads (`get_basic_info`, `get_selection`, `get_node_info`, `get_children`,+ `get_screenshot`, `get_jsx`, `get_tree_summary`, `get_computed_styles`, `get_fill_image`,+ `find_nodes`, comment-thread reads, `get_tokens`, `get_font_family_info`, `get_guide`), edits+ (`create_artboard`, `create_page`, `write_html`, `set_text_content`, `rename_nodes`,+ `update_styles`, `duplicate_nodes`, `move_nodes`, `finish_working_on_nodes`), files (`list_resources`+ or its current name, `open_file`, `create_file`) and, in Local and Bridged modes, `export` and+ `export_combined_pdf` (the internal "Paper can't export" limit was a property of the cloud bridge,+ not of Paper).+- Deny deletes, token writes and page/file reorganization by default; they are opt-in per+ deployment and still never touch the protected brand file.+- Deny `paper-gen:` (AI image generation billed to the user's Paper plan) unless the operator+ enables it; deny `paper-asset:` and `file:` schemes after HTML-unescaping arguments.+- `PAPER_BRAND_FILE_ID` (optional) is read-only. `PAPER_DRAFTS_FILE_ID` (optional) is the default+ target when a call omits `fileId`.+- Re-check the allowlist against the server's advertised tools at connect time and degrade one+ missing tool, not the whole MCP layer. Do not pin `include_tools` in a way that turns a Paper-side+ rename into a total MCP outage. Paper renamed `list_files` to `list_resources` and made+ `get_font_family_info` file-scoped in October 2026; tool names are not yet a stable contract.+- One failing MCP server must never remove the others or the agent's other tools.++### 2.5 Workflow contracts++- Storyboards: frames go to a Paper page (editable twin) and the sign-off board is exported (Local or+ Bridged) or rendered in the sandbox (Off or Hosted) and attached to the thread. The thread always+ gets an image people can approve.+- Brand import: the brand-onboarding coding-agent skill can read a Paper file's tokens, palette and+ type nodes (`get_tokens`, `get_computed_styles`, `get_jsx`) to draft `workspace/brand/tokens.json`+ and `graphic-language.md`. A person reviews the result.+- Receipts: record Paper file id, page id and link in the project's `run.json`; never store tokens.+- Always call `get_guide(topic="paper-mcp-instructions")` once per session, pass `fileId`+ explicitly, check with `get_screenshot`, and call `finish_working_on_nodes` when done.++### 2.6 Paper acceptance tests++- Scope middleware: allowlist, denied tools, scheme refusal after unescaping, brand-file write and+ clone refusal, default file fill, missing-tool degradation (unit tests against a fake MCP server).+- Bridge: bearer compare, rebinding allowlist, path guard, team check (unit tests).+- Contract test with a fake Paper MCP through the real graph: storyboard written to a page, export+ attached, receipt recorded.+- Opt-in live test (developer machine with Paper Desktop open): read `get_basic_info`, write one+ artboard to a scratch file, screenshot it, export a PNG, clean up.++## 3. Partner questions++### For HeyGen (HyperFrames)++1. Confirm the license covering the skills folder (the package and repository are Apache-2.0).+2. Versioned skill releases or a recommended commit pin; is `hyperframes skills check` the supported+ drift check?+3. Recommended way to override routing or providers (host-side TTS) without forking skill files.+4. Where bundled SFX audio and the matting model live (the internal pull lacked the binaries).+5. Machine-readable render progress for watchers (JSON lines on stderr or a progress file).+6. Is `@latest` plus `--docker` the recommended reproducibility path, or a pinned CLI?+7. Registry pinning: should the agent pin the registry to a tag instead of `main`?+8. An open-source key or free tier for HeyGen TTS/audio, and the status of cloud render targets.+9. Telemetry defaults inside sandboxes and how to disable them.+10. GSAP licensing guidance: the upstream graphic-overlays skill vendors GSAP (GSAP Standard License);+ should open-source users load it from a CDN at render time instead?+11. Co-marketing: ADOPTERS listing, a joint example in their catalog, and a quote for the launch post.++### For Paper++1. A hosted or remote MCP, or a headless/service-account mode, for agents that run in the cloud.+2. Multi-user authorization and team scoping for a shared agent.+3. How `export` and `export_combined_pdf` bytes should reach a remote agent.+4. A supported raster import path without `paper-asset:` or `file:` URLs.+5. Tool-name stability and a version or capability endpoint.+6. Pagination for files and directories beyond 200 entries.+7. Targeting a file without changing the user's active Desktop file.+8. Agent call limits per plan and `paper-gen:` pricing.+9. Official Linux Desktop support (needed only for the hosted-worker recipe).+10. Co-marketing: a Paper integration page, a template file for the sample brand, and a quote.diff --git a/docs/prep/source-inventory.md b/docs/prep/source-inventory.mdnew file mode 100644index 0000000..5e51409--- /dev/null+++ b/docs/prep/source-inventory.md@@ -0,0 +1,67 @@+# Source inventory++> Internal build note. Lists the private and public sources this build extracts from and the+> versions it targets. Delete `docs/prep/` before the first public push; move surviving version+> facts into `CHANGELOG.md` and `docs/architecture/`.++## Sources to extract from++| Source | Revision | Role | Access |+| --- | --- | --- | --- |+| Internal design agent ("Content Studio"), MDA app | `origin/main` @ `f87d644` (2026-10-16) | primary source for harness, middleware, tools, skills, sandbox recipe, tests | private repo `content-studio` on the builder's machine (`~/Desktop/agents/content-studio`). Read committed code with `git show origin/main:<path>`; the local working tree can lag `origin/main` |+| Internal source assets (pre-MDA app) | `origin/main` @ `ccc0eec`; asset snapshot `a94f68e` | `Dockerfile.sandbox` base-image recipe, original renderers and skills | private repo `langchain-media` (`~/Desktop/agents/langchain-media`) |+| MDA SDK example lineage | `managed-deepagents-sdk` `examples/content-studio` @ `18a218a` (MIT) | origin of the internal MDA app; its MIT notice must be preserved for any code that descends from it | private SDK repo (LangChain staff); the published package is public |+| Paid Media Agent (open source) | `4b47399` | the pattern to follow: repository shape, docs, onboarding, two deploy paths, CI, release discipline | public `github.com/langchain-ai/paid-media-agent`; local `~/Desktop/agents/paid-media-agent-open-source` |+| HyperFrames | release `v0.8.169` (2026-10-17); Apache-2.0 | video engine CLI and agent skills | public `github.com/heygen-com/hyperframes`, npm `hyperframes` |+| Paper Desktop MCP | current Desktop release | shared canvas | `paper mcp` stdio CLI or `http://127.0.0.1:29979/mcp` |++The internal agent was the subject of the "How we built our Design Agent" launch post. The public+name is **Design Agent**; "Content Studio" is the internal codename and may appear only in+`NOTICE.md` provenance.++## Baseline health of the source (measured 2026-10-17)++- `origin/main` exported with `git archive`, `uv sync --frozen --all-extras --dev`, then+ `uv run --frozen pytest -q`: **2,441 passed** in 106 s, offline, no `.env`.+- 2,190 tracked files: skills 977, workspace 868, tests 140 (122 Python files, 44,822 lines,+ 1,589 test functions before parametrization), tools 57, middleware 39, docs 26, scripts 24,+ harness 18 (6,438 lines, no MDA imports), fonts 10.+- No `Makefile`, `langgraph.json`, Dockerfile, CI workflow or top-level `LICENSE` on `main`. Gates+ are listed in its `AGENTS.md` (`ruff check`, `ruff format --check`, `basedpyright`, `pytest`,+ `scripts/check_deploy_tree.py`).+- The sandbox base snapshot is built outside the repo (from `langchain-media/Dockerfile.sandbox`)+ and carries licensed fonts, the internal brand package, the video-kit and June copies of the+ HyperFrames skills. The open-source build must replace it with a public, reproducible recipe.++## Target framework versions (verify on Slice 0)++| Package | Latest stable on 2026-10-17 | Internal pin | Paid Media pin | Target |+| --- | --- | --- | --- | --- |+| `managed-deepagents` | **0.9.3** (dev: 0.10.0.dev9) | `==0.9.0.dev2` (dev build) | `>=0.6.1,<0.7` | latest stable at build time, `>=0.9.3,<0.10`; never a `.devN` pin in a release |+| `deepagents` | **0.7.28** | `>=0.7.5,<0.8` | `>=0.7.12,<0.8` | `>=0.7.28,<0.8` |+| `langchain`, `langgraph`, `langchain-anthropic`, `langchain-openai`, `langchain-mcp-adapters`, `mcp` | resolve at build | | | current compatible, explicit upper bounds on pre-1.0 packages |+| `hyperframes` (npm) | `0.8.169` | `@latest` at bake | n/a | exact pin in `sandbox/setup.sh`, upgrade through the weekly compatibility job |+| HyperFrames skills | upstream `main` at a pinned commit | June 2026 pull, hash-only lock, 93 local edits | n/a | pinned commit + per-file sha256 in `skills-lock.json`, unmodified |++The internal agent depends on private MDA modules in two places (`middleware/boundary.py` for+background wake-ups through MDA's private ingress and loopback, and `tools/connect.py` for Agent+Auth). The open-source build must use only public APIs from the latest stable release; see SPEC §7.++## Identifiers that must never reach the public repository++Scrub by category, enforced by a CI ban-list scan (SPEC §18.4):++- LangChain brand: logos, icons, marks, palettes, the token files, construction specs, graphic+ language images, brand-book Paper file ids, the internal brand package.+- People: employee names, Slack user ids, emails, voice profiles, the people roster, approver+ principals.+- Workspace and infrastructure: Slack channel and team ids, LangSmith workspace, project and+ deployment ids and URLs, snapshot names, Paper team id, Okta and sign-in hand-off details,+ managed-tool server ids, Buffer channel ids, S3/R2 hosts.+- Internal agents and programs: peer agents and their bot ids, the quote-post copilot, the launch+ ledger and its guards, internal campaigns, product glossaries, analytics workspaces.+- Licensed or third-party media: TWK Lausanne and Aeonik Mono fonts, the remocn-ported component+ library, the 70 reference-film contact sheets and teardowns, frames of LangChain films, the+ Cyberpunk fan-kit asset and terms, vendored GSAP files, third-party brand imagery in examples,+ externally sourced image galleries without a clear license.+- History: `MIGRATION.md`, `migration-notes/`, internal runbooks, trace skills, research notes.diff --git a/docs/sources/official-links.md b/docs/sources/official-links.mdnew file mode 100644index 0000000..69680f1--- /dev/null+++ b/docs/sources/official-links.md@@ -0,0 +1,96 @@+# Official engineering sources++Check the relevant primary source before changing an external contract. These APIs move weekly;+installed package behavior and a live probe outrank model memory and this list. Update the owning+architecture page when supported behavior changes.++## Deep Agents and Managed Deep Agents++- Deep Agents (OSS): <https://github.com/langchain-ai/deepagents> · docs+ <https://docs.langchain.com/oss/python/deepagents/overview>+- Deep Agents customization, subagents, skills, backends, human-in-the-loop:+ <https://docs.langchain.com/oss/python/deepagents/customization>,+ <https://docs.langchain.com/oss/python/deepagents/human-in-the-loop>+All MDA pages share the prefix `https://docs.langchain.com/langsmith/python/managed-deep-agents-`:++| Topic | Page suffixes |+| --- | --- |+| Start | `overview`, `quickstart`, `project-structure`, `migrate` |+| Agent definition | `agent-definition`, `instructions`, `skills`, `tools`, `middleware`, `runtime` |+| Integrations | `search`, `connections`, `mcp-connectors`, `mcp-endpoint` |+| State and environment | `memory`, `sandboxes`, `context-hub` |+| Identity and schedules | `identity`, `schedules` |+| Channels | `channels`, `channels-slack`, `channels-http`, `agent-owned-interrupts` |+| Develop and ship | `local-development`, `tutorial`, `deploy`, `cli`, `evals` |++- Public landing repository and changelog: <https://github.com/langchain-ai/managed-deepagents>+- Coding-agent skill for MDA projects:+ <https://github.com/langchain-ai/langchain-skills/blob/main/config/skills/managed-deep-agents/SKILL.md>+- LangSmith sandboxes: <https://docs.langchain.com/langsmith/sandboxes> · regions:+ <https://docs.langchain.com/langsmith/regions-faq> · pricing: <https://www.langchain.com/pricing>+- PyPI: <https://pypi.org/project/managed-deepagents/> (0.9.3 stable on 2026-10-17; `0.10.0.devN`+ builds are cut from feature branches, never pin them) · <https://pypi.org/project/deepagents/>+ (0.7.28)+- SDK source is private to LangChain staff (`langchain-ai/managed-deepagents-sdk`; its+ `examples/content-studio` is the MIT-licensed lineage of the internal agent). Builders with access+ may read it for current behavior, but the public repository depends only on the published package+ and public docs.++Known doc drift as of 2026-10-17 (trust the installed package): the SDK README still shows+`scope: "agent"` sandboxes (rejected at runtime); the migrate page shows `define_memory(scope="agent")`+(raises in 0.9.3; use `define_memory(agent=MemoryLayer())`); the PyPI README says Python 3.9+ (3.11++is required). Declaring a sandbox clears `permissions`; schedules require `identity.py`.++Confirm each URL resolves during Slice 0; the docs site renames pages. Record the verified set and+the package versions in `docs/prep/source-inventory.md`.++## HyperFrames (HeyGen) — video engine++- Site: <https://hyperframes.heygen.com> · Quickstart: <https://hyperframes.heygen.com/quickstart>+- Catalog: <https://hyperframes.heygen.com/catalog>+- Repository (Apache-2.0): <https://github.com/heygen-com/hyperframes> · releases+ <https://github.com/heygen-com/hyperframes/releases> · adopters list `ADOPTERS.md`+- Agent skills: `npx skills add heygen-com/hyperframes` (standalone) or the HyperFrames plugin;+ update with `npx hyperframes skills update`.+- CLI (from the internal integration; verify against the current CLI reference): `npx hyperframes+ init | lint | validate | inspect | snapshot | preview | render --output <file>`.+- Studio (desktop preview app): <https://hyperframes.dev/studio/download>++## Paper — shared design canvas++- MCP docs: <https://paper.design/docs/mcp>+- Downloads (Paper Desktop): <https://paper.design/downloads>+- Agent plugins: `claude plugin marketplace add paper-design/agent-plugins && claude plugin install+ paper-desktop@paper`; Codex: `codex mcp add paper -- /path/to/paper mcp`.+- Transport: Paper Desktop starts the MCP server and installs the `paper` CLI. The recommended+ transport is the stdio server `paper mcp`; the legacy HTTP endpoint+ `http://127.0.0.1:29979/mcp` is served only while a file is open. No hosted or token-based remote+ MCP is documented as of this writing; free plans have MCP limits that reset on Pro.++## Models and tool disclosure++- LangChain prebuilt middleware (tool search, LLM tool selector, summarization, context editing):+ <https://docs.langchain.com/oss/python/langchain/middleware/built-in>+- Anthropic tool search: <https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool>+- Anthropic context editing and compaction: <https://platform.claude.com/docs/en/build-with-claude/context-editing>+- Anthropic vision (image token cost): <https://platform.claude.com/docs/en/build-with-claude/vision>+- OpenAI tool search: <https://developers.openai.com/api/docs/guides/tools-tool-search>+- OpenAI image generation: <https://developers.openai.com/api/docs/guides/image-generation>++## Media services (optional)++- ElevenLabs text to speech and music: <https://elevenlabs.io/docs>+- FFmpeg: <https://ffmpeg.org/documentation.html>+- Chrome Headless Shell: <https://developer.chrome.com/blog/chrome-headless-shell>+- sharp: <https://sharp.pixelplumbing.com>+- Apache ECharts: <https://echarts.apache.org> · D2: <https://d2lang.com>++## Slack++- Slack agents and AI apps (streaming, status): <https://docs.slack.dev/ai/>+- Bolt for Python: <https://docs.slack.dev/tools/bolt-python/>+- Socket Mode: <https://docs.slack.dev/apis/events-api/using-socket-mode>++## Skills format++- Agent Skills specification: <https://agentskills.io/specification>