Blueprint Standard

This document defines the shared contract every MirrorNeuron and OtterDesk blueprint should follow. It is intended to make blueprints interchangeable across product cataloging, local execution, UI launch, observability, and future deployment targets.

The current standard version is 1.0.

Architecture Model

Agents are the working units of a MirrorNeuron workflow. A blueprint should describe how agents work together: what starts the graph, which messages move between agents, what each agent produces, and which runtime boundaries apply. Shared mn-agents entries are generic agent templates. A blueprint actualizes those templates into concrete workflow agents with uses, with, and config, then assembles them like reusable blocks.

Actualized agents may be deterministic workers, routers, reducers, stream processors, services, output adapters, or LLM-backed decision makers. Control templates coordinate workflow behavior such as lifecycle, retry, joins, filters, checkpoints, approval, and fanout. Data templates are the workhorse units that blueprints customize for Python execution, native modules, LLM decisions/tools, observation, sandboxed code work, edge model inference, and data services.

MirrorNeuron is the runtime system that executes the workflow in an orchestrated way. It owns scheduling, routing, run state, event capture, artifact capture, resource limits, retries, and isolation. Blueprints own the workflow shape and domain intent. This split should make workflows reliable, inspectable, and efficient across local, cloud, and edge deployments.

Not every agent should call an LLM. When an agent does call an LLM, it must reference named LLM config. Agents that generate, review, browse, shell into, or execute code should declare a sandbox boundary, because model output and untrusted inputs must not share the same trust level as ordinary deterministic workers.

Normative Language

This standard uses:

MUST for requirements that validators may enforce for every applicable blueprint.
SHOULD for recommended behavior that improves interoperability but may have justified exceptions.
MAY for optional behavior.

Validator-enforced universal requirements appear in the Required For All Blueprints checklist. Conditional requirements apply only when the blueprint uses the related feature, such as LLMs, live streams, output skills, TCP outputs, OpenShell custom images, or multi-agent handoffs.

Goals

Every blueprint should be:

Discoverable from the root catalog files.
Configurable through the same config shape.
Runnable in mock mode without external services.
Runnable with real inputs through declared adapters.
Observable through the same run store artifacts and event format.
Explainable to a product user through consistent metadata.
Safe to customize without editing runtime code.
Clear about which agents communicate, which agents call LLMs, and which agents require sandboxing or external capabilities.
Efficient enough to run in constrained edge environments when the blueprint is marked or adapted for edge use.

Required Files

Each blueprint directory must contain:

manifest.json: graph, metadata, node, adapter, and product contract.
README.md: user-facing summary and quick-start instructions.
SPEC.md: implementation and behavior specification.
LICENSE.md: license terms for the blueprint code, docs, configuration, scripts, and payloads.
TERM.md: user-facing terms of use, responsibility, warranty disclaimer, third-party service notice, and liability limitation.
config/default.json: default configuration following this standard.
payloads/: executable code, scripts, workers, support modules, sample data, or policies.

Blueprints may also contain:

scenario.json: canonical scenario input for simulation or demos.
config/overwrite.json: local or user-specific override values. This file should not be required for correctness.
knowledge/: optional LLM-agent knowledge content, such as RAG material, prompt context, domain references, embeddings metadata, or other agent knowledge sources.
payloads/.../samples: bundled demo data.
payloads/.../policies: runtime or sandbox policy files.

The root index.json must include a catalog row for each blueprint. The root category.json should include category grouping for browsing and filtering.

Identity

Every blueprint must declare stable identity in both manifest.json and config/default.json.

Required identity fields:

blueprint_id: snake_case directory-aligned id.
name: human-readable display name.
graph_id: versioned workflow id, usually <blueprint_id>_v1.
job_name: kebab-case job name.
manifest_version: manifest schema version.
standard_version: blueprint standard version, currently 1.0.

Required manifest legal reference fields:

license: relative path to the blueprint license file, usually LICENSE.md.
term: relative path to the blueprint terms file, usually TERM.md.

At runtime, the system must also assign:

run_id: unique run id, either supplied by config/env or generated by the run store.

Metadata

Each blueprint must include product metadata under manifest.json.metadata.

Required metadata:

blueprint_id
name
category
description
problem_solved
target_user
customizable_for
simulation_type
runtime_features
output
output_contract
quick_test
standard
interfaces

Conditional metadata:

llm_agent_role is required when the blueprint uses an LLM agent.

The root index.json should mirror the product-facing subset:

id
name
path
category
description
graph_id
job_name
product.problem
product.input
product.output
product.how_it_works
product.benefit
product.target_users
product.runtime_features

Config Contract

The canonical config file is config/default.json.

Required top-level config sections:

standard_version
identity
mode
metadata
inputs
simulation
llm
outputs
logging
resources
human_control
real_adapters
interfaces
execution_model

The llm section remains a top-level config section for compatibility. Model-free blueprints should declare llm.enabled: false.

Blueprint-specific sections are allowed when they describe real runtime concepts. Examples:

streams
memory
benchmark
optimization
error_handling
state
capabilities
privacy
triggers
backpressure
schemas
budgets
agent_handoffs
web_ui

Blueprint-specific sections should be referenced from interfaces.config in manifest.json.metadata and from interfaces.config_sections in config/default.json.

Config resolution order should be:

Shared default config generated for the blueprint id.
Blueprint config/default.json.
Optional config file from MN_BLUEPRINT_CONFIG_PATH.
Optional inline JSON from MN_BLUEPRINT_CONFIG_JSON.
Direct runtime overrides, including CLI flags and UI fields.
Environment values such as MN_RUN_ID, MN_RUNS_ROOT, and MN_BLUEPRINT_REVISION.

Later layers override earlier layers by deep merge.

Input Contract

Every blueprint must support these input adapters:

mock: bundled synthetic or demo inputs; required for demos and tests.
json: inline JSON object supplied in config.
file: JSON object loaded from inputs.path.
env_json: JSON object loaded from an environment variable, defaulting to MN_BLUEPRINT_INPUT_JSON.

Resolved inputs must be a JSON object. Arrays, strings, and scalar values are not valid top-level input payloads.

The resolved input source should include:

adapter
path, when applicable
description, when available
real_ready, where false means mock inputs and true means user or real-world supplied inputs

Input fields should be domain concepts, not internal implementation toggles. Examples:

Facility safety: monitored stream, cooldown policy, alert destination.
Portfolio stress: holdings, cash constraints, hedge constraints, shock assumptions.
Property alpha: target ZIP, price ceiling, history months, broker notes, financing constraints.
Drug discovery: disease or target profile, screening criteria, candidate seeds.

Product Input Contract

Each blueprint should declare manifest.json.metadata.input_contract so launchers and users can understand what the blueprint actually needs before a run starts. This product-facing contract complements, but does not replace, the executable inputs config.

Recommended shape:

{
  "input_contract": {
    "schema_version": "mn.blueprint.input_contract.v1",
    "required_inputs": [
      {
        "name": "portfolio",
        "type": "object",
        "description": "Holdings, cash constraints, and exposure assumptions.",
        "example": {}
      }
    ],
    "optional_inputs": [
      {
        "name": "seed",
        "type": "integer",
        "description": "Deterministic replay seed.",
        "example": 42
      }
    ],
    "supported_adapters": ["mock", "json", "file", "env_json"],
    "profiles": {
      "mock": {"adapter": "mock", "description": "Bundled synthetic inputs."},
      "sample_file": {"adapter": "file", "path": "inputs/sample.json"},
      "live_stream": {"adapter": "mock", "streams": ["primary_stream"]},
      "connector": {"adapter": "mock", "input_skills": ["source_folder"]}
    },
    "privacy_classification": "internal",
    "validation_rules": [],
    "resolved_artifact": "inputs.json"
  }
}

Launchers should use this contract and metadata.init_config_review.fields to ask only about meaningful runtime values such as data source, stream endpoint, model endpoint, output destination, or human-control mode.

Stream Inputs

Blueprints that consume live or replayed streams should declare those inputs under streams or inputs.streams.

Supported stream kinds:

audio
video
data
multimodal

Supported stream transports:

file
http
https
rtsp
rtmp
webrtc
websocket
socketio
tcp
udp
sse
kafka
mqtt
custom

Recommended stream shape:

{
  "streams": {
    "primary_video": {
      "kind": "video",
      "transport": "rtsp",
      "uri": "rtsp://127.0.0.1:8554/local-camera",
      "codec": "h264",
      "sample_interval_seconds": 5,
      "enabled": true
    },
    "agent_audio": {
      "kind": "audio",
      "transport": "websocket",
      "url": "wss://example.test/audio",
      "codec": "pcm16",
      "sample_rate_hz": 16000,
      "enabled": true
    },
    "events": {
      "kind": "data",
      "transport": "socketio",
      "url": "https://example.test/events",
      "namespace": "/blueprint",
      "event": "observation",
      "enabled": true
    }
  }
}

Each stream entry should include:

kind
transport
uri or url
enabled
media details when applicable, such as codec, sample_rate_hz, frame_rate, or resolution
protocol details when applicable, such as namespace, event, topic, headers_env, or auth_env

Stream credentials and headers should be referenced by environment variable names, not embedded as literal secrets.

Input Skill Definitions

Blueprint inputs may also be declared as skill-backed sources. Use an input skill when the blueprint needs a reusable integration capability rather than a one-time JSON payload or raw stream.

Input skills are useful for sources such as:

Google Drive folders
Slack channels
email inboxes
calendars
issue trackers
databases
object storage buckets
webhook endpoints

Input skills should be declared under input_skills or inputs.skills.

Recommended input skill shape:

{
  "input_skills": {
    "deal_room": {
      "skill": "google_drive.folder",
      "connector": "google_drive",
      "folder_id": "drive-folder-id",
      "live": true,
      "events": {
        "on_change": "folder_content_changed"
      },
      "sync": {
        "mode": "incremental",
        "include_mime_types": [
          "application/pdf",
          "application/vnd.google-apps.document",
          "text/csv"
        ]
      }
    },
    "ops_channel": {
      "skill": "slack.channel",
      "connector": "slack",
      "channel_id": "slack-channel-id",
      "live": true,
      "events": {
        "on_message": "slack_message_received",
        "on_file": "slack_file_shared"
      }
    }
  }
}

Each input skill should include:

skill: stable skill type, such as google_drive.folder or slack.channel.
connector: connector or integration family.
source identity fields, such as folder_id, channel_id, database_id, bucket, or path.
live: whether the source should emit runtime events when content changes.
events: blueprint event types emitted by live updates.
sync: optional backfill, polling, filtering, or incremental sync settings.

When live is false, the input skill is read once during load_inputs and the resolved content is recorded in inputs.json or referenced from the run artifact.

When live is true, the blueprint should:

record the initial source state during load_inputs
subscribe, poll, or receive webhooks through the connector
emit typed events when source content changes
include enough source metadata in event payloads to correlate updates without storing secrets

Live input skill events must follow the normal event contract in events.jsonl. Example event types:

folder_content_changed
drive_file_added
drive_file_updated
slack_message_received
slack_file_shared

Input skill credentials must be managed by the connector or referenced by environment variable names. Blueprint config must not contain literal OAuth tokens, bot tokens, refresh tokens, cookies, or private keys.

Knowledge Contract

Blueprints may include a knowledge/ directory beside config/ and payloads/ for LLM-agent knowledge content such as RAG material, prompt context, domain references, embeddings metadata, or other agent knowledge sources.

The knowledge/ directory is optional. If present, it must contain exactly these standard subdirectories:

init/: bundled or base knowledge shipped with the blueprint.
custom/: user- or customer-provided knowledge.
learned/: runtime-, feedback-, or experience-derived knowledge.

The standard does not prescribe file formats, indexing behavior, retrieval precedence, embedding strategy, or how agents use these folders. Blueprints and runtime integrations may decide those details.

Output Contract

Every blueprint must always write local logs, events, and run artifacts through the local_run_store output adapter. This local observability output is mandatory even when the blueprint also writes to external destinations.

Default run root:

~/.mn/runs/<run_id>/

Required run artifacts:

run.json: run id, blueprint id, status, timestamps, paths, and failure details when relevant.
config.json: resolved runtime config.
inputs.json: resolved input payload.
events.jsonl: append-only typed runtime events.
errors.jsonl: error-only stream containing mn.error.v1 envelopes plus run context.
timeline.jsonl: append-only normalized execution timeline using mn.timeline.v1.
observability_summary.json: compact closeout summary for trace, duration, counts, retries, resources, and links.
result.json: complete machine-readable result.
final_artifact.json: user-facing final result or compact artifact.

Optional run artifacts:

job.json: scheduler, host, or orchestration metadata.
web_ui.json: UI launch metadata.
web/index.html: static report or output page.
ui.json: UI state or richer dashboard metadata.
logs.jsonl: structured runtime logs when logs are persisted separately from events.jsonl.
events.log: optional human-readable lifecycle event mirror.
errors.log: optional human-readable error mirror.
events.index.json: index metadata for rotated lifecycle events.
logs.index.json: index metadata for rotated or segmented structured logs.
errors.index.json: index metadata for rotated error records.
timeline.json: compact ordered mirror regenerated when the run closes.
human.jsonl: sparse human collaboration notices, input requests, and responses, mirrored to events.jsonl.
resources.jsonl: CPU, GPU, memory, and LLM token usage samples captured for the run.

result.json should contain enough context to audit the run without reading stdout. final_artifact.json should contain the durable product answer, not internal logs.

Shared Failure Contract

Runtime, SDK/API, and UI must normalize failures into the shared mn.error.v1 envelope. Blueprints should emit ordinary failure events through the shared run store and workflow helpers; they should not invent blueprint-specific error schemas.

{
  "schema_version": "mn.error.v1",
  "code": "workflow.step.timeout",
  "desc": "Workflow step timed out",
  "details": {
    "message": "Step missed its heartbeat deadline.",
    "category": "timeout",
    "retryable": false,
    "step_id": "prepare_income_workpapers",
    "agent_id": "income_preparer",
    "attempt": 2,
    "max_attempts": 2
  },
  "severity": "ERROR",
  "occurred_at": "2026-06-04T12:34:56.000Z",
  "event_id": "evt_...",
  "trace_id": "trc_...",
  "span_id": "spn_...",
  "remediation": "Check agent heartbeat, runtime node health, and step timeout settings.",
  "links": [
    {"rel": "errors", "artifact_id": "errors_jsonl"},
    {"rel": "events", "artifact_id": "events_jsonl"},
    {"rel": "logs", "artifact_id": "logs_jsonl"}
  ]
}

Limits are platform-level and apply after redaction:

code: 128 chars.
desc: 160 chars.
details.message: 2 KiB.
remediation: 1 KiB.
Full event/API error envelope: 16 KiB.
Single JSONL event, log, or error record: 64 KiB.

Oversized values are replaced with a bounded object such as {"truncated": true, "chars": 12000, "preview": "..."} and should link to the relevant artifacts. job_failed, workflow_step_failed, sandbox_job_failed, retry exhaustion, scheduler failures, and recovery failures must include error: mn.error.v1. Existing reason and status_reason fields remain compatibility fields derived from error.desc when available.

events.jsonl, logs.jsonl, and errors.jsonl rotate at 10 MiB by default and keep five rotated segments per run. Current files keep their existing names; rotated files use numbered suffixes such as events.001.jsonl, logs.001.jsonl, and errors.001.jsonl. Artifact indexes and API responses must expose stable artifact IDs such as events_jsonl, events_jsonl_001, logs_jsonl_001, and errors_jsonl_001 with size, hash, content type, and download URL.

Trace, Timeline, And Summary Contract

Every run must have one stable run-level trace_id in run.json. Records written through shared observability helpers must carry trace_id and a per-record span_id; callers may provide trace_id, span_id, and parent_span_id, and the runtime must preserve those values. Generated ids use trc_<urlsafe-random> and spn_<urlsafe-random>.

timeline.jsonl contains normalized execution records using mn.timeline.v1:

{
  "schema_version": "mn.timeline.v1",
  "ts": "2026-06-04T12:34:56.000Z",
  "run_id": "run_...",
  "blueprint_id": "finance_example",
  "trace_id": "trc_...",
  "span_id": "spn_...",
  "parent_span_id": "spn_...",
  "type": "workflow_step_failed",
  "phase": "running_worker",
  "step_id": "prepare_income_workpapers",
  "agent_id": "income_preparer",
  "status": "failed",
  "duration_ms": 120000,
  "summary": "Workflow step timed out",
  "links": [{"rel": "errors", "artifact_id": "errors_jsonl"}],
  "details": {}
}

observability_summary.json is written before observability closes on success and failure. It includes status, duration, trace id, event/log/error/warning/timeline/artifact counts, retry count, failed step or agent when known, slowest phases or steps when durations are available, resource peaks, token totals, and artifact links for events_jsonl, logs_jsonl, errors_jsonl, timeline_jsonl, and timeline_json.

The same redaction and truncation rules used for mn.error.v1 apply to timeline details and summary fields. timeline.jsonl is append-only; timeline.json is a compact ordered mirror and may be truncated for very large runs while retaining the full JSONL stream.

Product Output Contract

Every blueprint should declare metadata.output_contract.final_artifact and metadata.output_contract.artifacts.

The final artifact should include these user-facing fields when the blueprint can produce them:

type
executive_summary
recommended_action
confidence
evidence
next_steps
source_refs

The artifact list should include durable records for run.json, config.json, inputs.json, events.jsonl, result.json, final_artifact.json, logs, resources, human events when enabled, web UI metadata when enabled, and output-skill delivery attempts when configured. Each record should include artifact_id, type, schema_version, path, mime_type, and producer.

Blueprints may also declare skill-backed output destinations. Output skills are optional fan-out destinations, not replacements for local logs and events.

Output skills are useful for destinations such as:

Google Drive files or folders
Slack channels or direct messages
email messages
issue tracker comments
databases
object storage buckets
webhook endpoints

Output skills should be declared under output_skills or outputs.skills.

Recommended output skill shape:

{
  "output_skills": {
    "archive_report": {
      "skill": "google_drive.write_file",
      "connector": "google_drive",
      "folder_id": "drive-folder-id",
      "filename_template": "{blueprint_id}-{run_id}-report.json",
      "content": "final_artifact",
      "enabled": true
    },
    "notify_ops": {
      "skill": "slack.send_message",
      "connector": "slack",
      "channel_id": "slack-channel-id",
      "content": "summary",
      "include_run_link": true,
      "enabled": true
    }
  }
}

Each output skill should include:

skill: stable skill type, such as google_drive.write_file or slack.send_message.
connector: connector or integration family.
destination identity fields, such as folder_id, channel_id, database_id, bucket, path, or webhook_url_env.
content: what to send, such as final_artifact, result, summary, events, logs, or a named artifact.
enabled
optional formatting fields, such as filename_template, message_template, mime_type, or include_run_link

Multiple output skills may be enabled at the same time. The blueprint should treat them as a fan-out list: write the local run store first, then attempt each enabled output skill.

Each output skill attempt should emit an event, for example:

output_skill_started
output_skill_completed
output_skill_failed
drive_file_written
slack_message_sent

Failures in optional output skills should be recorded in events.jsonl and result.json. They should fail the whole run only when the output skill is marked as required.

Output skill credentials must be managed by the connector or referenced by environment variable names. Blueprint config must not contain literal OAuth tokens, bot tokens, refresh tokens, cookies, or private keys.

TCP Output Port Convention

Some outputs expose a TCP service instead of only writing files or connector messages. Examples include web UIs, report preview servers, callback receivers, local dashboards, stream preview pages, and connector bridge endpoints.

TCP output services should use fixed externally reachable ports so users, launchers, tunnels, and downstream tools know where to connect. These are external, host, or tunnel ports, not necessarily the internal container or process bind ports.

Port assignment rules:

Use 8080 for the first or primary TCP output.
If 8080 is already taken, use 8081 as the fallback.
If the blueprint needs two TCP output ports, use 8080 and 8081 in that order.
If both 8080 and 8081 are unavailable, or more than two TCP output ports are required, the blueprint should require an explicit config override instead of choosing a random port.

Recommended TCP output config shape:

{
  "outputs": {
    "tcp": {
      "enabled": true,
      "ports": [
        {
          "name": "web_ui",
          "external_port": 8080,
          "protocol": "http",
          "url_path": "/",
          "required": true
        },
        {
          "name": "secondary_output",
          "external_port": 8081,
          "protocol": "http",
          "url_path": "/",
          "required": false
        }
      ]
    }
  }
}

When a TCP output is launched, the blueprint should write the resolved external port and external URL to the relevant artifact, usually web_ui.json, ui.json, or result.json. It should also emit events such as tcp_output_started, tcp_output_available, and tcp_output_failed.

TCP output port failures should follow error_handling: use retry for temporary bind failures, use skip only for optional secondary outputs, and use stop when a required TCP output such as a primary web UI cannot bind to 8080 or the declared fallback.

Artifact Contract

Artifacts are durable files or objects produced by a blueprint. Every user-facing report, extracted file, model-generated result, static page, image, table, or structured summary should be represented as a named artifact when it may be consumed by users, output skills, replay, tests, or later blueprint steps.

Recommended artifact record shape:

{
  "artifact_id": "final_report",
  "type": "report",
  "schema_version": "mn.artifact.report.v1",
  "path": "final_artifact.json",
  "mime_type": "application/json",
  "created_at": "2026-05-13T12:00:00Z",
  "producer": "ranking_reporting",
  "source_refs": [
    "inputs:portfolio",
    "event:llm_decision:3"
  ]
}

Each artifact record should include:

artifact_id: stable name within the run.
type: domain-readable type, such as report, summary, dataset, image, video_clip, html, model_output, or debug_bundle.
schema_version: schema id for structured artifacts.
path: run-store relative path or external destination reference.
mime_type
created_at: UTC ISO timestamp.
producer: worker, stage, agent, or output skill that produced it.
source_refs: optional references to input records, events, files, messages, streams, or prior artifacts.

final_artifact.json should identify its schema or schema version when possible. If it wraps multiple artifacts, it should include an artifacts list with artifact records.

Named artifacts may be routed through output skills by setting content to the artifact id. Output skills should record the artifact id and destination reference in their completion event payload.

Event And Observability Contract

Every event in events.jsonl must be one JSON object per line with:

ts: UTC ISO timestamp.
run_id
blueprint_id
type: stable snake_case event type.
payload: JSON object.

Required lifecycle events:

run_started
inputs_loaded
run_completed or run_failed

Recommended lifecycle events:

simulation_step_started
simulation_state_observed
llm_decision
simulation_state_updated
artifact_written
web_ui_available

Blueprint-specific events are encouraged when they expose useful product behavior. Event names should be stable and domain-readable, for example:

door_camera_frame_analyzed
door_camera_face_detected
benchmark_step_scored
targets_ready
pipeline_complete

Status logging may also write JSONL to stderr, but stderr is not the durable observability surface. The run store is the system of record.

Secrets and sensitive environment values must be redacted from config summaries, logs, and events.

Logging Contract

Logs are diagnostic narrative. Events are durable state, product, and lifecycle facts. Errors are always recorded as events and may also be written to logs.

Canonical log levels:

TRACE: very detailed execution flow, usually disabled by default.
DEBUG: developer-oriented diagnostic details.
INFO: normal progress and high-level runtime milestones.
WARN: unexpected but recoverable conditions.
ERROR: operation failed, but the process may continue depending on error_handling.
CRITICAL: execution cannot continue safely.

The default log level is INFO. WARN is canonical. WARNING may be accepted as a compatibility alias, but persisted logs should normalize it to WARN.

When logs are persisted to logs.jsonl or stderr JSONL, each log line should include:

ts: UTC ISO timestamp.
run_id
blueprint_id
level
component: worker, stage, adapter, connector, or module name.
message: human-readable diagnostic text.
event_id, when the log explains a durable event.
trace_id, when correlating work across stages.
span_id, when correlating a nested operation.
source_ref, when the log relates to a stream item, input file, connector record, output skill, or artifact.
error, when applicable, with type, message, and optionally a redacted stack or code.

Recommended logging config shape:

{
  "logging": {
    "level": "INFO",
    "events_jsonl": true,
    "logs_jsonl": true,
    "stderr_jsonl": true,
    "redact_env_secrets": true,
    "redact_fields": [
      "api_key",
      "token",
      "authorization",
      "cookie",
      "password",
      "private_key"
    ]
  }
}

Blueprints should not rely on logs for product state. If a fact is needed for audit, UI, replay, downstream skills, or final artifacts, it should be emitted as an event or artifact record.

Secret redaction must happen before a log line is written. Raw prompts, connector payloads, headers, OAuth tokens, cookies, private keys, and full environment dumps must not be logged unless explicitly redacted.

Resource Observability Contract

Every blueprint should declare resources even if resource sampling is only best-effort in the local runner. The resource channel records operational signals that help compare runs, debug regressions, and decide whether a blueprint is ready for hosted or edge execution.

Recommended resource config shape:

{
  "resources": {
    "enabled": true,
    "sample_interval_seconds": 10,
    "gpu_enabled": "auto",
    "gpu_sample_interval_seconds": 60,
    "history_window_hours": 24,
    "raw_retention_hours": 48,
    "rollup_bucket_seconds": 3600
  }
}

When enabled, resource samples should be written to resources.jsonl. Samples may include CPU, memory, disk, GPU, queue depth, and LLM token usage. Resource sampling failures should be recorded as events or logs, but they should not fail the blueprint unless the blueprint explicitly marks resource enforcement as required.

Human-Control Contract

Every blueprint must declare human_control in config, even when no human approval is needed.

Supported modes:

disabled: the blueprint only writes local decision-support artifacts and has no high-impact action to approve. It must include reason.
notice_only: the blueprint may emit human_notice events for review, but it does not block artifact writing on approval.
approval_required: the blueprint must request approval before applying or recommending high-impact actions. It must declare allowed_decisions, timeout_seconds, default_action, and blocked_actions.

Human-control events use the existing human channel and are mirrored to events.jsonl:

human_notice
human_input_requested
human_input_received
human_input_timeout
human_decision_applied

The manifest should mirror the policy under metadata.human_control so catalog and launch UI code can explain the review behavior before a run starts.

Status Transparency Contract

Every blueprint should declare metadata.status_contract and emit status events from the run store. Standard phases are:

loading_inputs
running_worker
waiting_for_human
writing_artifacts
completed

Each phase should define start_event, progress_event, completion_event, and failure_event. The shared events are blueprint_phase_started, blueprint_status, blueprint_phase_completed, and blueprint_phase_failed.

Long-running, stream, service, or multi-stage blueprints should emit progress or heartbeat blueprint_status events so users can tell whether work is still active. Web UI surfaces must read status from run-store events rather than private worker state.

Runtime Workflow Control Contract

Blueprints that use flow.steps for multi-step execution should declare runtime workflow control so MirrorNeuron can keep progress durable, bounded, and recoverable. The source of truth is the step ledger stored on the job as workflow_state; nodes and agents are workers, not the durable progress authority.

Required runtime shape:

{
  "runtime": {
    "workflow_control": {
      "schema_version": "mn.workflow.runtime_control.v1",
      "enabled": true,
      "source_of_truth": "flow.steps",
      "state_ledger": {
        "enabled": true,
        "persisted_field": "workflow_state",
        "step_statuses": [
          "pending",
          "ready",
          "queued",
          "running",
          "retry_wait",
          "blocked",
          "completed",
          "partial",
          "skipped",
          "failed"
        ],
        "message_ledger": true,
        "delivery_semantics": "at_least_once_with_idempotency"
      },
      "attempts": {
        "dispatch_metadata": [
          "workflow_run_id",
          "step_id",
          "attempt_id",
          "attempt",
          "deadline_at",
          "heartbeat_deadline_at",
          "idempotency_key"
        ],
        "stale_attempt_outputs": "ignore",
        "retry_policy_source": "flow.steps[].control.retry",
        "timeout_source": "flow.steps[].control.timeout_seconds"
      },
      "liveness": {
        "event": "agent_beacon",
        "interval_ms": 15000,
        "timeout_ms": 45000,
        "required": true,
        "missed_action": "fail_attempt"
      },
      "reconciliation": {
        "interval_ms": 2000,
        "on_timeout": "fail_attempt_then_retry",
        "on_missed_beacon": "fail_attempt_then_retry",
        "on_retry_exhausted": "apply_step_failure_policy"
      },
      "pause_cancel": {
        "pause_mode": "stop_active_attempts",
        "resume_mode": "reconcile_from_workflow_state",
        "cancel_mode": "terminate_active_attempts"
      },
      "events": [
        "workflow_step_attempt_started",
        "workflow_step_beacon",
        "workflow_step_attempt_completed",
        "workflow_step_attempt_timed_out",
        "workflow_step_attempt_retry_scheduled",
        "workflow_step_blocked",
        "workflow_step_completed",
        "workflow_step_failed",
        "workflow_message_dead_lettered"
      ]
    }
  }
}

Every flow.steps[] entry should declare bounded control policy:

control.timeout_seconds: positive integer for the current attempt deadline
control.retry.max_attempts: positive integer
control.retry.backoff_seconds: non-negative number
control.failure_policy: the result after retry exhaustion, such as fail, partial, skip, or fail-closed behavior

Executor node rendering should project the same step policy into the runtime node config:

timeout_seconds
max_attempts
retry_backoff_ms
beacon_enabled: true
beacon_interval_ms: 15000
beacon_timeout_ms: 45000
beacon_missed_action: "fail_attempt"
agent_beacon_required: true for Python executor steps

Plain-code stages must still use an executor agent. For Python scripts, prefer the shared mn_blueprint_support.python_executor_template_node(...) or python_executor_runtime_binding(...) helpers, which declare the stage through mn-agents.data_python_executor@1.0.0. Do not launch stage code through an untracked helper process or a blueprint-specific wrapper just to run ordinary Python.

The status contract should connect UI surfaces to the workflow ledger:

{
  "metadata": {
    "status_contract": {
      "heartbeat_required": true,
      "heartbeat_event": "agent_beacon",
      "beacon_event": "agent_beacon",
      "beacon_interval": "15s",
      "beacon_timeout": "45s",
      "beacon_missed_action": "fail_attempt",
      "runtime_state_source": "workflow_state",
      "attempt_event": "workflow_step_attempt_started",
      "retry_event": "workflow_step_attempt_retry_scheduled",
      "blocked_event": "workflow_step_blocked",
      "terminal_step_events": [
        "workflow_step_completed",
        "workflow_step_partial",
        "workflow_step_skipped",
        "workflow_step_failed"
      ]
    }
  }
}

The UI should prefer workflow_state for job details. A step that is alive should show recent beacon timing, a step in backoff should show retry timing, and a dependency problem should show blocked reason rather than an indefinite running state.

Observability Dashboard Contract

Blueprint dashboards should be declared in metadata and config, then rendered by the shared web UI from run-store files.

Standard panels:

current_status
recent_events
pending_human_requests
output_artifacts
resource_usage
errors

Conditional panels:

Stream blueprints: input_lag, backpressure
LLM blueprints: llm_calls, token_budget, llm_retries
Output-skill blueprints: output_skill_attempts, output_skill_failures

Error Handling Contract

Every blueprint must record errors, even when the runtime chooses to continue.

Supported error handling modes:

retry: attempt the operation again according to a bounded retry policy.
skip: record the error and continue with the next item, event, stream frame, message, file, or optional output.
stop: record the error, mark the run or worker as failed, and stop the current execution path.

Blueprints may configure error handling globally and override it per stage, stream, input skill, output skill, or worker.

Recommended error policy shape:

{
  "error_handling": {
    "default_mode": "stop",
    "policies": {
      "stream_frame": {
        "mode": "skip",
        "max_consecutive_errors": 10
      },
      "llm_call": {
        "mode": "retry",
        "max_attempts": 3,
        "backoff_seconds": 2
      },
      "required_output": {
        "mode": "stop"
      }
    }
  }
}

Each recorded error event should include:

error_type
message
mode
stage or component
attempt, when retrying
source_ref, when the error relates to a stream item, file, message, input skill, or output skill
recoverable: boolean

Recommended error event types:

error_recorded
retry_scheduled
item_skipped
run_failed

retry should always be bounded by max attempts, elapsed time, or another explicit limit.

skip is appropriate for stream processing, batch item processing, optional connector reads, and optional output fan-out where one bad item should not invalidate the whole run.

stop is appropriate when required inputs cannot load, config is invalid, required output delivery fails, or the blueprint can no longer produce a trustworthy final artifact.

The selected error mode changes control flow only. It must not suppress logs, events, or final error summaries.

State And Checkpoint Contract

Long-running service, live-input, stream, or multi-stage blueprints should declare how runtime state is stored and resumed.

Recommended state config shape:

{
  "state": {
    "enabled": true,
    "checkpoint_interval": {
      "events": 100,
      "seconds": 60
    },
    "resume_mode": "latest_checkpoint",
    "idempotency_key_fields": [
      "source_ref",
      "event_id"
    ]
  }
}

Supported resume_mode values:

none: do not resume; each launch starts fresh.
latest_checkpoint: resume from the newest checkpoint.
replay_events: rebuild state by replaying events.jsonl.
manual: require the user or orchestration layer to choose a checkpoint.

Checkpoints should be written under the run store or a declared state path. They should include the checkpoint timestamp, producer component, source position, and any idempotency keys needed to avoid duplicate processing.

Live input events, stream frames, connector records, and external messages should have stable source_ref values. After restart, the blueprint should use those references to skip already processed items or replay them deterministically.

Capability And Permission Contract

Blueprints should declare external capabilities before runtime so users and launch UIs can review what the blueprint is allowed to do.

Recommended capabilities shape:

{
  "capabilities": {
    "required": [
      "llm.call",
      "filesystem.write",
      "stream.subscribe"
    ],
    "optional": [
      "google_drive.read",
      "google_drive.write",
      "slack.read",
      "slack.send",
      "network.egress"
    ]
  }
}

Common capability names:

llm.call
google_drive.read
google_drive.write
slack.read
slack.send
network.egress
stream.subscribe
filesystem.read
filesystem.write

Required external capabilities should be shown during UI or init config review before launch. Optional capabilities may be disabled by config, but if enabled they should still be visible in review.

Capability declarations are not credential storage. Credentials must be managed by connectors, environment references, or the runtime.

Privacy And Redaction Contract

Blueprints that process user, business, operational, financial, health, media, or connector data should declare data classification and handling rules.

Supported data classes:

public
internal
confidential
regulated

Recommended privacy config shape:

{
  "privacy": {
    "default_classification": "internal",
    "rules": {
      "public": {
        "log": true,
        "send_to_llm": true,
        "send_to_output_skills": true
      },
      "internal": {
        "log": "metadata_only",
        "send_to_llm": true,
        "send_to_output_skills": true
      },
      "confidential": {
        "log": "redacted",
        "send_to_llm": "allowed_configs_only",
        "send_to_output_skills": "approved_destinations_only"
      },
      "regulated": {
        "log": "redacted",
        "send_to_llm": false,
        "send_to_output_skills": "approved_destinations_only"
      }
    }
  }
}

Privacy rules should define whether each class may be:

logged
included in durable events
sent to named LLM_CONFIG entries
sent through output skills
stored in artifacts

The blueprint must redact or omit environment tokens, OAuth credentials, cookies, private keys, passwords, authorization headers, and connector secrets from logs, events, artifacts, and output skills unless the value is explicitly a safe reference such as an environment variable name.

When content is transformed for privacy, the blueprint should emit a redaction or filtering event with metadata about what class of data was changed, without recording the sensitive content itself.

Trigger And Scheduling Contract

Blueprints should declare how runs start and what keeps them active.

Supported trigger types:

manual
scheduled
live_input
webhook
stream
service
batch

Recommended trigger config shape:

{
  "triggers": {
    "type": "service",
    "sources": [
      "input_skills.deal_room",
      "input_skills.ops_channel"
    ],
    "schedule": null
  }
}

If an input skill has live: true, the blueprint should declare a live_input trigger or another trigger that explains how live updates are received. Scheduled triggers should use a stable schedule representation owned by the orchestration layer rather than ad hoc worker sleep loops.

Top-level manifest type: "service" means the blueprint expects to remain active after initialization. Omitted top-level type means the blueprint defaults to a finite batch run.

Backpressure And Rate Limit Contract

Blueprints that consume live inputs, streams, connector events, or high-volume batches should declare backpressure behavior and rate limits.

Recommended backpressure config shape:

{
  "backpressure": {
    "max_events_per_second": 10,
    "queue_size": 1000,
    "drop_policy": "skip_with_error",
    "max_concurrency": 4,
    "connectors": {
      "google_drive": {
        "max_reads_per_minute": 60,
        "max_writes_per_minute": 10
      }
    },
    "llm": {
      "max_calls_per_minute": 30,
      "max_concurrent_calls": 2
    }
  }
}

Supported drop_policy values:

block: stop accepting new work until capacity is available.
sample: process a representative subset.
drop_oldest: discard oldest queued work first.
drop_newest: discard newest incoming work first.
skip_with_error: skip the item, record an error event, and continue.

Dropped, sampled, skipped, or rate-limited items should be recorded as events. Budget or rate-limit violations should follow the configured error_handling mode.

Determinism And Replay Contract

Blueprints should make mock, test, and replay runs reproducible when the domain allows it.

Recommended determinism config shape:

{
  "determinism": {
    "enabled": true,
    "seed_field": "seed",
    "frozen_clock": null,
    "replay": {
      "from_inputs": "inputs.json",
      "from_events": "events.jsonl",
      "llm_mode": "mock"
    }
  }
}

Deterministic blueprints should declare:

seed_field: input or config field used for deterministic randomness.
frozen_clock: optional timestamp used to stabilize time-dependent output.
replay inputs: usually inputs.json.
replay events: usually events.jsonl for live or multi-stage runs.
mock LLM behavior: fake, fixture, or recorded response mode.

When deterministic mode is enabled, replay runs should produce comparable final artifacts and event sequences, allowing expected differences such as timestamps, run ids, and explicitly nondeterministic external service responses.

Schema Validation Contract

Blueprints should declare schemas or schema ids for the surfaces other tools consume.

Recommended schema config shape:

{
  "schemas": {
    "config": "mn.blueprint.config.v1",
    "inputs": "mn.blueprint.inputs.v1",
    "events": "mn.blueprint.events.v1",
    "final_artifact": "mn.blueprint.final_artifact.v1",
    "input_skills": "mn.blueprint.input_skills.v1",
    "output_skills": "mn.blueprint.output_skills.v1"
  }
}

Schemas may begin as inline ids before concrete schema files exist. When schema files are present, the schema id should resolve to a local file, package resource, or documented registry entry.

Schema validation should cover:

config
inputs
events
final artifacts
input skills
output skills
agent handoff messages

Validation failures should be recorded as errors and follow error_handling.

Resource Budget Contract

Blueprints may declare resource budgets to keep local and hosted runs predictable.

Recommended budget config shape:

{
  "budgets": {
    "max_runtime_seconds": 600,
    "max_llm_calls": 20,
    "max_llm_tokens": 20000,
    "max_connector_reads": 500,
    "max_connector_writes": 20,
    "max_disk_mb": 250,
    "max_stream_duration_seconds": 3600
  }
}

Budget checks may apply globally or per component. When a budget is exceeded, the blueprint should emit a budget event and then follow the configured error_handling mode.

Recommended budget event types:

budget_warning
budget_exceeded
rate_limited

Agent Handoff Contract

Multi-agent and multi-worker blueprints should declare how messages move between stages.

Recommended handoff shape:

{
  "agent_handoffs": {
    "targets_ready": {
      "producer": "target_discovery",
      "consumer": "structure_generation",
      "message_type": "targets_ready",
      "payload_schema": "mn.science.targets_ready.v1",
      "error_policy": "retry",
      "artifact_owner": "structure_generation"
    }
  }
}

Each handoff should define:

message_type
payload_schema
producer
consumer
error_policy: retry, skip, or stop
artifact_owner: worker or stage responsible for durable artifacts derived from the message

Handoff messages should be replayable when they affect durable state or final artifacts. If a message cannot be replayed, the blueprint should state why in the handoff definition.

Execution Model

Every blueprint should follow this shared lifecycle:

load_metadata
resolve_config
load_inputs
start_run_store
observe_simulation_state
call_llm_agent
apply_decision_to_simulation
emit_events
write_final_artifact

Blueprints may insert domain-specific steps, such as:

seed_large_context
retrieve_working_memory
score_all_context_vs_optimized_memory
sample_video_frame
evaluate_binding
rank_candidates

Domain-specific steps should preserve the shared lifecycle ordering around config, inputs, run store, events, and final artifacts.

Pre-Launch Hook

Blueprints may include scripts/pre-launch.sh when a run needs host-side services before validation or worker submission, such as a local RTSP mapper, tunnel, or filesystem watcher. The hook is optional; blueprints without it launch normally.

Launchers start scripts/pre-launch.sh before launch-time input validation. The hook may be long-lived and must write the file named by MN_PRE_LAUNCH_READY_FILE once the required service is usable. Launchers wait for that file and fail the run cleanly if it is not written before the timeout.

Launchers provide these environment variables:

MN_RUN_ID
MN_RUN_DIR
MN_RUNS_ROOT
MN_BLUEPRINT_BUNDLE_DIR
MN_BLUEPRINT_CONFIG_JSON
MN_PRE_LAUNCH_READY_FILE

MN_PRE_LAUNCH_TIMEOUT_SECONDS may override the launcher wait timeout.

The hook should log to stdout/stderr, avoid mutating tracked blueprint files, and terminate cleanly on SIGTERM. Launchers record pre_launch.log and pre_launch_process.json in the run directory and stop the process on failed validation, failed submission, cancellation, or run-resource cleanup.

Manifest Graph Contract

manifest.json must declare:

entrypoints
nodes
edges
initial_inputs
requirements with minimum cpu, gpu, memory, and disk
input_validation with a rules list, even when no custom rules are needed yet
license
term

The manifest graph is the actualized-agent communication contract. It should make the workflow inspectable without reading every payload script. A reader should be able to identify the templates used, the concrete agents produced from those templates, their responsibilities, their message handoffs, and the runtime concerns that matter for reliability or edge execution.

Each node should include:

node_id
alias, when the node is rendered from a shared template and needs a job-specific user-facing name
display_name, when a title-cased or spaced variant is useful for UI surfaces
type
role, when useful
agent_type
config.command, for executable nodes
config.workdir
config.upload_path or config.upload_paths, when payload files must be staged
config.output_message_type, when the node emits graph messages
uses, when the node is rendered from a shared mn-agents template
config.llm_config, when the agent calls an LLM
sandbox or service config, when the agent runs untrusted code, generated code, browser automation, shell commands, custom images, or network-facing services

Edges must include:

edge_id
from_node
to_node
message_type

Multi-agent workflows should keep message types stable and explicit. Avoid implicit handoffs through shared files unless the artifact is also declared in metadata or output contracts.

Long-running blueprints should set top-level manifest type: "service". Finite batch blueprints should omit top-level type.

Shared Agent Aliases

Shared mn-agents templates often use generic implementation names such as ingress, runtime, router, worker, or visual_detector. A blueprint may customize those shared/template agents with alias and optional display_name so Job Details, progress views, graph views, logs, and dashboards can show domain-specific names.

alias is the canonical field for blueprint-level renaming. It is display-only. It must not change scheduling, event routing, persisted IDs, service registration, node_id, uses, or message contracts.

Display name precedence is:

alias
display_name
label
role
stable id (id, agent_id, or node_id)

Use aliases when a shared agent becomes a job-specific noun. Prefer concise snake_case aliases for stable product surfaces, and use display_name only when a human-readable title is useful.

Example:

{
  "metadata": {
    "agent_templates": {
      "nodes": [
        {
          "node_id": "ingress",
          "alias": "video_monitor",
          "display_name": "Video Monitor",
          "uses": "mn-agents.control_router@1.0.0"
        },
        {
          "node_id": "video_frame_tick_source",
          "alias": "frame_sampler",
          "display_name": "Frame Sampler",
          "uses": "mn-agents.data_module@1.0.0"
        }
      ]
    }
  }
}

Workflow workers under runtime.bindings.*.workers[] may also declare aliases:

{
  "runtime": {
    "bindings": {
      "detect_visual_targets": {
        "workers": [
          {
            "id": "visual_target_detector",
            "alias": "visual_target_detector",
            "display_name": "Visual Target Detector",
            "role": "Run visual detection"
          },
          {
            "id": "quality_controller",
            "alias": "quality_controller",
            "display_name": "Quality Controller",
            "role": "Review alert quality"
          }
        ]
      }
    }
  }
}

When a blueprint uses shared template nodes, preserve both identities:

Stable runtime identity: node_id, worker id, uses, edge endpoints, and event worker IDs.
User-facing identity: alias, then display_name, then existing labels and roles.

Do not rename a stable runtime id just to improve UI text. If the runtime id is part of edges, persisted events, or service registration, keep it stable and add alias. If a workflow worker id is newly introduced and not yet part of a compatibility contract, it should already be a job-specific noun such as video_monitor, frame_sampler, quality_controller, or watch_summary_writer.

Runtime infrastructure agents are not blueprint workers. If transport or wrapper agents appear in graph data, UI surfaces should label them as system/runtime infrastructure rather than showing raw names such as runtime as if they were domain agents.

Custom OpenShell Image Port Note

Agents that run with a customized OpenShell image should declare any input or output ports that must be reachable from outside the sandbox. This applies to custom images declared with fields such as custom_openshell_image and runners such as MirrorNeuron.Sandbox.OpenShell.

If an OpenShell agent consumes or exposes a network service, the blueprint should use SSH port tunneling to verify and preserve connectivity for those ports. This includes:

input stream ports, such as RTSP, WebRTC, WebSocket, Socket.IO, TCP, UDP, HTTP, or webhook listener ports
output service ports, such as local dashboards, preview servers, callback URLs, report servers, or connector bridge endpoints
model, tool, or helper service ports that must be reached from inside the OpenShell sandbox

Recommended OpenShell port declaration shape:

{
  "openshell": {
    "custom_image": "person_detector/openshell_sandbox",
    "ports": [
      {
        "name": "video_input",
        "direction": "input",
        "protocol": "rtsp",
        "container_port": 8554,
        "external_port": 8554,
        "tunnel": "ssh",
        "required": true
      },
      {
        "name": "dashboard_output",
        "direction": "output",
        "protocol": "http",
        "container_port": 7860,
        "external_port": 8080,
        "tunnel": "ssh",
        "required": false
      }
    ]
  }
}

Each declared port should include:

name
direction: input, output, or bidirectional
protocol
container_port: internal container or process port, when applicable
external_port: host or tunnel port exposed outside the sandbox
host_port, when separately fixed by the runtime
tunnel: usually ssh for OpenShell network bridging
required: whether failure to establish the tunnel should stop the run

Before the agent starts processing live input or publishing output, the runtime should verify that required SSH tunnels are established and that the declared ports are reachable from the side that needs them. Tunnel setup, verification, and failures should be recorded as events, such as openshell_tunnel_started, openshell_tunnel_verified, and openshell_tunnel_failed.

OpenShell tunnel failures should follow error_handling: use retry for temporary tunnel setup issues, skip only for optional output ports, and stop when a required input or output port cannot be reached.

LLM Config Contract

LLM usage is part of the shared blueprint standard. Any blueprint that calls a language, vision-language, embedding, reranking, or multimodal model must declare those model settings in llm.

One blueprint may have one or many named LLM_CONFIG entries. The llm section is the registry for those entries.

LLM use is an agent capability, not a workflow default. Prefer deterministic agents when rules, simulation, routing, validation, aggregation, or formatting can be handled without model inference. Reserve LLM agents for judgment, language, multimodal interpretation, planning, code generation, or other tasks that need model behavior.

Recommended shape:

{
  "llm": {
    "enabled": true,
    "default_config": "primary",
    "configs": {
      "primary": {
        "provider": "docker_model_runner",
        "mode": "openai_compatible",
        "runtime_model": "gemma4:e2b",
        "model": "gemma4:e2b",
        "api_base": "auto",
        "backend": "llama.cpp",
        "context_size": 4096,
        "mock_mode": "fake",
        "timeout_seconds": 60,
        "num_retries": 1,
        "max_tokens": 700
      },
      "vision": {
        "provider": "ollama",
        "mode": "ollama",
        "model": "nemotron3:33b",
        "api_base": "http://192.168.4.173:11434",
        "mock_mode": "fake"
      }
    },
    "agents": {
      "analyst": {
        "llm_config": "primary",
        "role": "Portfolio stress-test analyst"
      },
      "frame_observer": {
        "llm_config": "vision",
        "role": "Safety observation agent"
      }
    }
  }
}

Model-free blueprints should keep the llm section but set:

{
  "llm": {
    "enabled": false
  }
}

Each LLM_CONFIG entry should include:

provider
mode
model
api_base
mock_mode
timeout, retry, and token fields when supported
credential reference fields when needed, such as api_key_env
for runtime-managed local models, provider: "docker_model_runner" plus runtime_model, backend, and optional context_size

For local Docker Model Runner models, api_base: "auto" lets MirrorNeuron inject http://localhost:12434/engines/v1 for HostLocal workers and http://model-runner.docker.internal/engines/v1 for container or sandbox workers. The default runtime model alias is gemma4:e2b, resolved to Docker's ai/gemma4:E2B.

Each agent that uses an LLM must reference a named config with llm_config. Agents must not repeat model values that already live in llm.configs.

Allowed agent-level fields:

llm_config: required named reference to llm.configs.<name>.
role
responsibilities
prompt or instruction text
tool and output schema declarations

Agent prompts, worker manifests, manifest environment blocks, and script defaults should quote the config reference only, for example LLM_CONFIG.primary or llm.configs.primary. They must not restate the concrete model, api_base, credential, timeout, retry, or max-token values. Manifest node environments should reference resolved config-derived environment names rather than literal model settings.

Domain-specific model sections such as vl_model should be folded into llm.configs unless they contain non-LLM stream or device settings. For example, a video blueprint should keep stream source fields in streams, but place the vision-language model endpoint in llm.configs.vision.

LLM agents that generate, modify, review, browse, shell into, install dependencies for, or execute code should run in a declared sandbox, such as OpenShell or another runtime-supported isolation boundary. The blueprint should declare relevant sandbox image, file access, network access, service ports, and output artifacts so MirrorNeuron can enforce the boundary and record what happened.

Mock mode must be available for quick tests and offline demos.

Model endpoints, credentials, and provider-specific values should be configurable through config and environment, not hard-coded inside worker logic.

mn blueprint validate and mn blueprint run check runtime-managed local models after service preflight and before input validation. Missing models fail with a fix such as mn model install gemma4:e2b; incompatible hardware fails unless the operator explicitly uses --force.

UI Contract

Blueprints may expose:

no UI
static HTML output
Gradio dashboard
custom UI adapter

Supported web UI adapters:

none
static_html
gradio
custom

UI configuration belongs under web_ui. If a UI is enabled, the blueprint should write web_ui.json with at least:

enabled
adapter
url, when a server is launched
port, when a TCP server is launched
run_id
run_dir

Input UIs should collect config/input values and pass them through the normal config and input adapters. Output UIs should read from the run store instead of private worker state.

Quick Test Contract

Every blueprint should define metadata.quick_test.

Quick tests should:

Use mock inputs by default.
Avoid external services unless explicitly enabled.
Be deterministic where possible.
Complete quickly enough for local validation.
Emit the same required run artifacts as normal runs.

When a quick test is disabled, the metadata must explain why and provide the safest available validation path.

Configuration Review Contract

Blueprints with operationally sensitive or environment-specific defaults should declare metadata.init_config_review.

Use init config review for fields such as:

stream URI or URL
llm.configs.<name>.api_base
llm.configs.<name>.model
Slack or notification destination
credentials reference
data source path

Each review field should include:

path
label
default
description

The review step should let the user keep defaults or provide overrides before launch.

Validation Checklist

Use this checklist to separate universal requirements from feature-specific requirements.

Required For All Blueprints

It appears in index.json.
It has manifest.json, README.md, SPEC.md, LICENSE.md, TERM.md, and config/default.json.
manifest.json.metadata.blueprint_id matches the directory name.
manifest.json.license points to LICENSE.md.
manifest.json.term points to TERM.md.
config/default.json.identity.blueprint_id matches the directory name.
It declares standard version 1.0.
It supports mock, json, file, and env_json input adapters.
It always writes local logs, events, and required run artifacts through local_run_store.
It emits run_started, inputs_loaded, and completion or failure events.
It records every error and declares whether recoverable errors use retry, skip, or stop.
It has a deterministic mock path or explains why quick test is disabled.
Its product metadata explains input, output, user, problem, benefit, and runtime features.
Blueprint-specific config sections are declared in interfaces.
Sensitive values are not written into durable logs or artifacts.

Required When Applicable

Connector-backed inputs are declared as input skills with source identity, live behavior, and event types.
External output destinations are declared as output skills and combined as fan-out after local run-store writes.
TCP outputs use fixed external ports: 8080 for primary output and 8081 for fallback or secondary output.
Persisted logs use structured records and canonical levels: TRACE, DEBUG, INFO, WARN, ERROR, and CRITICAL.
Long-running service, live, or stream blueprints declare state, checkpoint, resume, and idempotency behavior.
Blueprints that require external systems declare required and optional capabilities before launch.
Blueprints that need host-side setup before validation or submission use the standard scripts/pre-launch.sh hook and signal readiness through MN_PRE_LAUNCH_READY_FILE.
Blueprints that process sensitive, business, operational, financial, health, media, or connector data classify handled data and define logging, LLM, output-skill, and artifact behavior.
Blueprints with scheduled, live, webhook, stream, service, or batch execution declare trigger type.
Live, stream, or high-volume blueprints declare backpressure and rate-limit behavior.
Deterministic or replayable blueprints declare seed, replay inputs/events, and mock LLM behavior.
Blueprints with validator-consumed schemas declare schema ids for config, inputs, events, final artifacts, input skills, output skills, and handoffs.
Blueprints with runtime, LLM, connector, disk, or stream limits declare resource budgets.
Blueprints with flow.steps declare runtime.workflow_control, use workflow_state as the runtime state source, and expose workflow attempt, retry, blocked, and terminal step events in metadata.status_contract.
Every flow.steps[] entry has positive control.timeout_seconds, bounded retry attempts, and a declared failure policy.
Multi-agent graphs declare handoff message type, payload schema, producer, consumer, error policy, and artifact ownership.
Shared/template agents and workflow workers declare alias when their stable runtime IDs are generic or implementation-oriented.
Python executor workflow workers require agent_beacon liveness and render step timeout, retry, and beacon policy into the runtime node config.
Agents using customized OpenShell images declare required input/output ports and verify SSH tunnels before processing.
External endpoints and model settings are configurable when used.
LLM-using blueprints declare model usage under llm.configs.
Agents reference named LLM_CONFIG entries instead of repeating concrete model settings.

Durable artifacts include artifact metadata such as artifact_id, type, schema_version, path, mime_type, created_at, and producer.
Blueprints declare schemas before validators enforce them.
Blueprints declare resource budgets before they are needed for hosted execution.
Blueprints declare privacy rules even when data is expected to be only public or internal.

Versioning

The standard should change only when the cross-blueprint contract changes.

Patch-level changes can clarify wording without changing standard_version.

Increment the standard version when adding, removing, or renaming:

required config sections
required adapters
required run artifacts
required event fields
lifecycle steps that validators enforce

Blueprints may support a newer standard while keeping compatibility fields for 1.0 during migration.

Blueprint Standard

On this page