--- name: nuday-blueprints description: Author, review and promote NuDay Blueprints (versioned, declarative bundles of an agent and its skills, guardrails, guidelines, tools, MCP servers, plugins, knowledge bases and triggers) from an IDE or the nuday CLI. Use when a person wants to change an agent graph through a reviewed plan, promote it between tenancies or environments, compare versions, or roll back. metadata: source: nuday catalog: platform category: development priority: '24' --- # NuDay Blueprints A **blueprint** is a declarative, versioned bundle of NuDay resources: an agent and everything it binds. Its stable id is its NAME (a slug) inside a tenancy; each save is an immutable numbered version (v1, v2, ...). Nothing in the tenancy changes until a reviewed **plan** is **applied**. Applying runs as the person: it can never do more than they could do in the UI. ## Tools (NuDay MCP, /mcp/complete) | Tool | Use | |---|---| | `nuday_blueprint_list` | The tenancy's blueprints, saved and running versions | | `nuday_blueprint_get` | One blueprint by name; with include_body, the packed blueprint to edit | | `nuday_blueprint_versions` | Version history: numbers, authors, times, change summaries | | `nuday_blueprint_compare` | Field-level diff between two saved versions | | `nuday_blueprint_plan` | Save ONE new version (optional) and preview its changes in a target | | `nuday_blueprint_apply` | Apply a reviewed plan; returns a durable operation id | | `nuday_blueprint_run` | Poll an operation until it is done | | `nuday_blueprint_restore` | Restore an earlier version as a NEW version, then plan it | ## The authoring loop 1. Discover: `nuday_blueprint_list`, then `nuday_blueprint_get` (include_body) for the blueprint you will change. Note its saved version id. 2. Edit the packed blueprint (or the files of a blueprint directory; see the CLI below). Reference resources by address (kind/name), never by id; secrets are declared by name only, never as values. 3. Plan: `nuday_blueprint_plan` with the edited blueprint, the saved version id you started from as the expected base (base_check true), a one-line change summary, and an idempotency key you reuse on retry. 4. Show the person the returned markdown: every action with its reason, the risk set (code, secrets, network), the signature status, and any approval reasons. Blocked actions must be fixed first. 5. Apply only after the person explicitly approves THIS plan: `nuday_blueprint_apply` with the plan id and, when the plan has risks, the risk consent hash it returned (consent to exactly that risk set). When an agent calls these tools through the NuDay MCP server, `nuday_blueprint_apply` and `nuday_blueprint_restore` are gated in the catalog: the call itself pauses for a person's approval first. That approval is separate from the plan's own approval in NuDay, and neither replaces the person's review of the plan. 6. Poll `nuday_blueprint_run` until done. Report the result. ## Six rules for AI clients 1. **Discover before creating.** List and get first; reuse the existing blueprint name instead of creating a near-duplicate. 2. **One save per logical change.** One plan call with one edited blueprint per change, built on the version you read. On error code stale-base, someone saved in between: fetch the intervening version, merge, show the person, and plan again. Never overwrite blindly. 3. **Say what is saved and what is running.** A saved version is not live until an apply succeeds. Report it as "Saved v13; v12 is still running" (the status lines in the responses say exactly this). 4. **Poll operations; never assume.** An apply is asynchronous. A gated plan (a production tenancy, deletes, replaces, a grown risk set) waits for ANOTHER person's approval in NuDay Approval Requests; you cannot approve it and must not tell the person it is applied. 5. **Disambiguate versions.** "Yesterday's version" or "the one before" can match several versions: list them with times and authors, and ask when more than one fits. 6. **Never claim a rollback reverses business data.** A restore brings back configuration, prompts and tool source. It never restores data (documents, memory, threads, run history), secret values or revoked credentials, and resources a newer version deleted come back with new ids. Say so whenever you restore. ## Error codes permission-denied (ask an admin), not-found, invalid-blueprint (fix the file), stale-base (rule 2), stale-plan (plan again), policy-blocked (blocked actions or missing risk consent), approval-required (a second person approves), busy (another apply runs), idempotency-conflict (a used key with a different request), apply-failed (see the failed address). ## Files and the CLI A blueprint directory extends the agent-template layout: ``` blueprint.yaml # manifest: name, version, parameters, secrets, policy blueprint.lock.json # content hashes (generated, committed) blueprint.sig.json # signatures (optional) environments/.yaml # params + per-address merge patches agents/.yml skills//SKILL.md guardrails/.md guidelines/.md tools/.py mcp_servers/.yaml plugins/.yaml knowledge_bases/.yml triggers/.yml organizations/.yml # tenancy blueprints: root.yml is the target org llm_providers/ llm_configs/ backends/ llm_budgets/ routing/ roles/ role_bindings/ grants/ hitl_resolvers/ saved_evaluations/ alert_rules/ apps/ ``` A tenancy blueprint (`export --org-id `) carries the org tree and every tenant-owned resource. Credentials are `{secret: NAME}` references and people (role members, alert recipients) are parameters with no default: ask the person for them, never invent them. A secret value is bound only when the person applies (`--secret NAME=env:VAR`); never put a value in a file, a plan or a message. ```bash nuday blueprint export --agent-id -o ./support # snapshot (signed by this environment) nuday blueprint export --org-id -o ./acme # a whole tenancy nuday blueprint validate ./support --remote # server normalization + hash nuday blueprint plan ./support --tenant --env staging --format md nuday blueprint apply --plan plan.json --consent-risks nuday blueprint diff ./support version: ``` ## Signing and command-running MCP servers Signatures prove who published a blueprint, never that it is safe. A blueprint signed by a publisher key this environment trusts (platform admins manage trusted publishers) may include stdio MCP servers, and only in tenancies whose admin turned on signed stdio servers. Unsigned blueprints never can.