Blueprints
Explanation — what & why
A blueprint is an app model as configuration. One file (or a root file and the
part files it includes) declares everything a Vectros app needs to exist — the record schemas, a least-privilege access
profile, a service principal, optional seed data, and optional roles — with
stable identifiers so applying it twice converges instead of duplicating (the
loader always reconciles server-side via ?upsert=true, so re-applying the
same blueprint is always safe). A schema whose typeName is already claimed
by a different owner — e.g. a second blueprint modeling the same conceptual
type — must declare basedOn (see the schema reference below).
Blueprints exist to collapse "stand up a new app's data layer" from a sequence of
API calls into a single reviewable artifact. You write the file once; the CLI's
bootstrap and blueprint-test commands turn it into provisioned
infrastructure and a working scoped key (see cli.md).
Two boundaries define what a blueprint is and is not:
- It describes format, not trust. The
@vectros-ai/blueprintspackage owns the format and its structural validation only. The security boundary — the scope gate that limits the scopes a blueprint can mint — lives in the CLI binary. A blueprint is untrusted input; the binary is the trust boundary. - Its scopes are limited to an allowlist. A blueprint can request scopes on
records, schemas, search, documents, folders, inference, runs, and identity entities,
plus a few narrow exceptions (
profiles:r/u/d,profiles:c:self, a bareprofiles:conly on a clause that also declaresmember-lifecycle, andscripts:x:<name>). Every other scope is rejected when the CLI applies it. See cli.md.
This doc is the format reference the blueprint walkthroughs build on. For narrated, end-to-end builds, see the walkthroughs (getting-started, clinical-intake, agentic-sdlc, second-brain).
How-to
Scaffold, validate, and apply
The full authoring loop runs through the CLI:
vectros blueprint init my-app # scaffold ./my-app.blueprint.yaml
vectros blueprint validate ./my-app.blueprint.yaml
vectros blueprint plan ./my-app.blueprint.yaml
vectros blueprint apply ./my-app.blueprint.yaml --tenant test # provision it, no key (needs CLI 0.23.0+; CI: add --yes --confirm-existing-principal)
vectros bootstrap --blueprint ./my-app.blueprint.yaml # provision it AND mint a key for your MCP client
If another request changes the same schema, app context, role, namespace or trigger rule at the
moment blueprint apply or bootstrap is updating it, the platform answers 409 (VERSION_CONFLICT)
instead of overwriting the other change, and the command stops with the platform's message. Run it again
once the other change has finished; a re-apply converges.
You can scaffold from a bundled exemplar with init --from <name>. See
cli.md for the lifecycle commands.
A minimal blueprint
Blueprints are authored as YAML or JSON. A minimal one declares a context, one schema, an access profile, and a service principal:
name: my-app
version: 1.0.0
description: A minimal example app.
contextId: my-app
contextName: My App
schemas:
- typeName: note
displayName: Note
indexMode: HYBRID # HYBRID | SEMANTIC | TEXT | NONE
fields:
- { fieldId: title, fieldType: string, required: true, searchable: true }
- { fieldId: body, fieldType: string, searchable: true }
lookupFields: [title] # extra exact-match index(es). Do NOT list externalId:
# it's the record's first-class id (sent top-level on
# each record), with its own finder — declaring it as a
# lookup is rejected, and a field of that name can never
# hold a value (validate warns).
accessProfile:
allowedActions: [records:r, records:c, records:u, search:r, schemas:r]
servicePrincipal:
externalId: my-app
displayName: My App
indexMode, the per-field validation/renderHints, and the schema-level
capabilities/active/ownership fields are all optional — the example stays
minimal on purpose. (Omitting indexMode is not the same as HYBRID: a record with no
resolvable mode is stored but never indexed, so declare the mode you want.) Note the deliberate absence of records:d in
allowedActions: least privilege is the authoring default.
Reference — what a blueprint can express
Top-level fields
| Field | Required | Meaning |
|---|---|---|
name | yes | Stable blueprint id — the --blueprint <name> selector and idempotency key. |
version | yes | Blueprint version string. |
description | yes | Human-readable description. |
contextId | yes | The app context the profile and key bind to. 3–31 chars; lowercase letter first, then lowercase letters/digits/dashes. |
contextName | no | Human-readable context name; defaults from name. |
companyName | no | The deploying organization's own display name, distinct from contextName (which is the blueprint author's fixed name for the app). Typically templated from an input per install; forwarded to the platform to personalize platform-sent correspondence such as invitation emails. |
schemas | no | The record/surface schemas to provision (see below). |
accessProfile | yes | The least-privilege scope the bootstrap mints for the blueprint's own key. |
servicePrincipal | yes | The service principal the key is bound to. |
seed | no | Deterministic seed records and documents; each entry names its surface. |
roles | no | Reusable, multi-clause scope rules. |
identities | no | Declared principals (see the glue caveat below). |
issuers | no | Trusted third-party IdP issuers to register, for BYO-IdP token exchange (see below). |
namespaces | no | Entity-namespace registrations to declare (see below). |
scripts | no | The versioned JS source a trigger's scriptRef runs (see below). |
triggers | no | Rules that invoke a script on a schema record's CREATE/UPDATE/DELETE event (see below). |
formatVersion | with agents | The blueprint format; absent means 1. An agents section needs 2. A file that declares a format newer than the tool reads is refused with a message to upgrade @vectros-ai/cli and @vectros-ai/blueprints. |
agents | no | Stored agents (/v1/agents): a model, system prompt, tool whitelist, limits and budget per name (see below). |
identityProjectionClaims | no | Which captured IdP claim names get projected, read-only, onto access profiles in this context (see Issuers below). |
inputs | no | Install-time variables (resolved with --set/--values). |
include | no | Part files that add sections to this blueprint, for a blueprint split across files (see Splitting a blueprint below). Root file only. |
stacks | no | Named groups of the included part files that apply --stack applies one at a time (see Splitting a blueprint below). Root file only. |
Schemas
Each schema entry declares a record type:
| Field | Meaning |
|---|---|
typeName | The record type name. |
displayName | Human-readable label. |
indexMode | HYBRID (keyword + semantic), SEMANTIC, TEXT, or NONE (store-only: persisted and readable by id and lookup, never indexed, so it never appears in a search or a grounded answer). Omitting it is not HYBRID: a record with no resolvable mode is stored but not indexed. |
fields[] | Field definitions (see below). |
lookupFields[] | Fields to index for direct lookup. Bare field name (equality), or { fieldName, unique?, rangeEnabled?, sortBy?, allowOverflow? } — or, for a composite lookup over 2–3 fields together, { fieldNames: [...], sortBy?, allowOverflow? } (see Composite lookups below). rangeEnabled adds ordered from/to/prefix queries (use it for dates/sequences/scores; the order is lexical, so it's wrong for ordinal enums). sortBy sets the order an equality lookup returns — createdAt (default), lastUpdated, or another field on the schema. You can also range over that sort key (sortFrom/sortTo on a value lookup — e.g. one session's records since a timestamp). The sorted field does not need to be required: records that carry no value for it are ordered ahead of those that do, and are never inside a bounded window. sortBy and the sorted field's type are both migration-locked, so choose them when you declare the lookup; an array or object field cannot be a sortBy target. Each schema has 7 fast equality slots (range lookups use a row, not a slot; ownership ids + externalId ride their own); an 8th equality lookup needs allowOverflow. The index shape is migration-locked — pick it deliberately. A sensitive field may be an equality (blind-index) lookup, never rangeEnabled, and never a sortBy target. Up to 10. |
allowedSurfaces[] | Which typed surfaces may bind the schema: record, document, entity (identity entities in any namespace — org, client, or one you register). Defaults to [record]. user is rejected when you validate a blueprint: a user-surfaced schema is account-global and needs a root API key, which no blueprint credential holds. Model the data as a record scoped to the user, or as an entity schema. |
capabilities.auditHistory | Whether writes emit version history (platform default on). |
capabilities.triggersEnabled | Whether records of this schema fire trigger rules. Defaults to false, and is the opt-in a schema must declare before a trigger may fire on it — a blueprint declaring a trigger against a schema without it is refused at plan time. Independent of auditHistory. |
active | Whether the schema accepts new records. |
userId / scopes | Schema-level ownership defaults. scopes is an array of <namespace>:<value> entries (e.g. org:acme), the same grammar records/entities use. |
basedOn | Id of an existing schema this one customizes, required when a schema named typeName already exists in this context under a different owner. Omit when this is the first schema under that name (it becomes that name's shared base — root/unscoped credential only, no userId/scopes). Must point directly at the base (one hop); immutable once set. Mirrors the platform's basedOn schema field (data-model/reference.md). |
fileProfile, mediaKinds, maxBytes, contentTypes | fileProfile: PUBLIC_MEDIA makes a document schema a public-media type: a document type for images (no route serves them publicly). It needs allowedSurfaces: ['document'] and is never indexed (indexMode NONE or omitted); it cannot be a customization (basedOn). mediaKinds (only image), maxBytes (at most 10485760, 10 MiB, the default on create) and contentTypes (a subset of image/jpeg, image/png, image/webp, image/gif, all four by default on create) are declared with it: validate refuses them without fileProfile, even for a type already stored as public media. The profile cannot be added to a type that already has documents or variants. Leaving the profile, or any of the three settings, out of a later apply keeps the stored value; returning to a default means declaring it. Needs platform 0.50.0 or later. |
publicView | Makes the type's records readable without signing in. Where public serving is not open, a read answers 503 PUBLIC_ACCESS_NOT_LAUNCHED for an account whose public access is otherwise ready; an account that is not ready gets the 503 code for what is missing first. The keys are the platform's: mode (projection, the default, or record), fields (projection only), ownedBy, publishWhen and search (publicViewVersion is server-managed and ignored). Declared on a base schema only, with allowedSurfaces omitted or exactly ['record']; projection mode only on a schema with no userId or scopes. Any change to it (adding, changing or removing it) needs the public-publish capability (identity-access/reference.md), which the account owner's own login carries; publishing or widening it also needs your account's public access, which the account owner switches on with the developer portal API (a blueprint cannot). Leaving the key out of a later apply keeps the type's public view; null removes it. Needs platform 0.50.0 or later. |
publicView.geoPrecision | projection mode only: for each geo field listed in publicView.fields, 'exact' (the location as stored) or a whole number of metres from 100 to 100000, the minimum edge of the grid cell whose centre the public copy holds. Required for every listed geo field; refused in record mode. Changing it on a published type, in either direction, counts as making more data public. Needs platform 0.50.0 or later. |
Each field definition supports:
| Field key | Meaning |
|---|---|
fieldId | Field name. |
fieldType | Field type (e.g. string, array, reference; geo for a location, in a limited pilot: not sensitive, searchable or an enum, never a lookup or a sortBy, record and document schemas only, filterable unless filterable: false; asset/assets for images, with documentTypes). A filterable field may not start with _geo_, or be named publicCopy or public_copy_owner in any letter case: the platform keeps those for its search index. |
required / searchable / filterable | Per-field flags. |
enumValues[] | Allowed values for an enumerated field. |
validation | Validation rules: required, minLength/maxLength, min/max, pattern, email/url/phone, step/multipleOf, minItems/maxItems. |
renderHints | UI hints: label, widget (text/textarea/select/date/checkbox), order, section, helpText, displayField (mark the record's headline column — at most one per schema). |
sensitive | Marks the field as sensitive: it is removed from version history at write time, blind-indexed for lookups, excluded from the search index, and masked on read unless a token carries the reveal scope. |
inline | Keep the field on the record row when the payload is stored out of line, so it appears in list and lookup projections without includePayload — and so a trigger rule may project it into input.record. Cannot be combined with sensitive. |
targetTypeName / targetSurface / targetField / cardinality | On a reference field, the typed link target. targetTypeName and targetSurface are both required — the same typeName can exist on multiple surfaces, so the surface disambiguates the lookup. targetSurface is record, document, user, or the name of an entity-backed namespace — org, client, or one you registered via POST /v1/namespaces (see identity-access/reference.md; the namespace must already be registered and entity-backed, or the schema is rejected at authoring time). targetField defaults to the target's externalId (must be a unique lookup); cardinality = one (default) / many. The target's existence is enforced at write by default. |
documentTypes | On a field of type asset (one image) or assets (up to 20; validation.maxItems may set a lower limit), the public-media document types the field accepts, by typeName. Required on both, allowed only on them. An asset field cannot be sensitive, searchable, an enum or a reference, and is declared only on a base schema. The platform also requires a new asset field to be served by the schema's publicView (in projection mode, listed in its fields), and refuses removing an asset field or changing its type; the CLI leaves those checks to it. Asset fields are left out of public record, list and search responses. An image cannot be attached in this version (400 ASSET_NOT_ATTACHABLE). Needs platform 0.50.0 or later. |
geocode | On a geo field of a record schema, { from: [...] }: the fields of the same schema that hold its address, in order (at most 10, distinct, each string, enum or number, never sensitive). validate checks this offline and refuses it on a schema whose allowedSurfaces include document. The platform looks up the location after each write that changes the address; a record shows the progress in geocodeStatus (data-model/reference.md). Needs platform 0.50.0 or later. |
Composite lookups
A lookup can span 2–3 fields matched together as one index, declared with
fieldNames in place of fieldName:
lookupFields:
- fieldNames: [status, area] # queried together as one exact-match index
- Order is fixed at declare time. A query can match a leading run of the declared fields — the first field alone, the first two, and so on — but never a later field alone; declare a separate lookup for that. Redeclaring the same fields in a different order creates an independent lookup that only sees writes made after it was declared, not the history under the old one.
- Exact-match only. A composite lookup can't be
uniqueorrangeEnabled— declare those as a separate, single-field lookup instead. - Record schemas only.
allowedSurfacesmust be exactly['record']; document, user, and entity schemas can't declare a composite lookup. - Each leg must be a plain, single-valued, non-range field. A leg can't be
an
arrayorobjectfield (one sort-key position holds one value), areferencefield withcardinality: many, or a field that is itself declaredrangeEnabledelsewhere on the schema — any of those would index only one of several values and the conjunction would silently return a subset while looking complete. - A leg cannot also be the composite's own
sortBytarget. Within a fixed tuple every matching record shares the same value for that leg, so the sort payload would be constant and asortFrom/sortTowindow would return either everything or nothing, at double the sort-key cost. Sort by a different field,createdAt, orlastUpdatedinstead. sortByandallowOverflowstill apply otherwise:sortByorders results within a group when a query supplies fewer values than the lookup declares (seelookupFields[]above).
Access profile
accessProfile:
allowedActions: [records:cru, search:r, schemas:r]
dataScope:
"scope:org": [org_acme, null]
allowedActions— the scopes the minted key carries. Author explicitresource:opforms; coarse verbs andresource:*are rejected when authored. Subject to the CLI scope gate.roleIds— alternative toallowedActions/dataScope: compose the profile from one or more roles this same blueprint declares underroles:(below), instead of an inline clause:The effective grant is each named role's own clauses, concatenated in the order listed — never merged, so each clause keeps meaning exactly what its own author wrote. Mutually exclusive withaccessProfile: roleIds: [case-handler, hr-admin] roles: case-handler: - allowedActions: [records:r:case, records:u:case] hr-admin: - allowedActions: [records:r:hr]allowedActions; aroleIds- composed profile carries nodataScope/capabilitiesof its own — author those on the referenced roles instead. Every id must resolve to a role declared in this same blueprint, and no id may repeat.dataScope— optional ownership binding (userIdorscope:<namespace>→ value lists;scope:org/scope:clientfor those reserved namespaces, orscope:<namespace>for one you registered — org/client must be registered too, same as any other). Anullelement is the documented null sentinel: it additively grants access to tenant-level (owner-less) records in addition to the listed owners. Omittingnullrestricts the key to the listed owners only — so it will not see tenant-level/seed records.capabilities— optional list of platform capability names (distinct from a schema'scapabilities.auditHistory), e.g.capabilities: [member-lifecycle]. This package validates the shape only (non-blank, no duplicates, lowercase kebab-case, no'*') — it does not itself know which names the platform actually grants, since that set is a platform property (eight names as of this release:member-lifecycle,forensic-read,context-directory-read,delegate-mint,delegate-principal-stamp,trigger-control-plane-grant,public-publish,script-egress-declare— see identity-access/reference.md). The CLI's capability gate admits onlymember-lifecycleanddelegate-principal-stampon a blueprint it applies; any other name is rejected and nothing is minted. Each role clause below accepts the same field.
Service principal, seed, roles
servicePrincipal:
externalId: my-app
displayName: My App
seed:
- surface: record # required: `record` or `document`
typeName: note
externalId: seed-welcome
fields: { title: Welcome, body: Created by the bootstrap loader. } # externalId is the seed's top-level field above, NOT a payload field
roles:
editor:
- allowedActions: [records:cru, search:r]
dataScope:
userId: ['${{ self.userId }}']
servicePrincipal— the principal the minted key binds to.seed— deterministic records or documents (keyed byexternalIdfor idempotency). Each entry setssurfacetorecord(withfields) ordocument(with a requiredtitleandtext, and optionalfields).vectros bootstrapwrites them unless you pass--no-seed;vectros blueprint applywrites them only when you pass--seed.roles— a map of role id → ordered clauses. Each clause is an(allowedActions, dataScope)pair, evaluated per-clause at runtime. Roles are identity-agnostic and reusable; bind them to principals withvectros access grant --principal <p> --context <c> --role <id>. Every role clause passes the same CLI scope gate asaccessProfile, so a role is not a way around it.${{ self.* }}placeholders are a runtime per-principal sentinel, resolved per-request by the platform. They are only valid inside a role clause'sdataScope, aroleAssumablevalue or afragmentsvalue; using one anywhere else, a trigger's grant included, is an authoring error.
fragments — authoring sugar for a repeated dataScope. A top-level map
of name → dataScope, referenced from a clause with dataScopeRef instead of
repeating an identical dataScope verbatim:
fragments:
ownOrg:
"scope:org": ['${{ self.scope.org }}']
roles:
case-handler:
- allowedActions: [records:cru:case]
dataScopeRef: ownOrg
- allowedActions: [search:r]
dataScopeRef: ownOrg
dataScope and dataScopeRef are mutually exclusive on the same clause. A
dataScopeRef is resolved to its fragment's literal dataScope before
anything downstream (the loader, the wire payload it sends) ever sees it — a
purely local authoring convenience, never itself provisioned.
roleAssumable — which values a role's holder may become. A top-level map
of roleId → grant, naming which values, per scope:<namespace>, a holder of
that role may assume via POST /v1/auth/token/assume
(identity-access/reference.md):
roleAssumable:
hr-admin:
"scope:org": [org_engineering, org_sales]
roles:
hr-admin:
- allowedActions: [records:r]
Every key must resolve to a role this same blueprint declares under roles.
Its value grammar is narrower than a clause's dataScope: every key must be a
namespaced scope:<ns> (the principal — userId — can never be named here),
and no value may be null. vectros blueprint plan previews a role's
assumable grant alongside its clauses, since it's security-relevant — what a
holder of the role may become, not just that the role was declared.
assignableRoles — both accessProfile and each role clause may carry an optional roleId
allow-list restricting which named roles that clause may compose into a delegated access profile
(roleIds composition). Orthogonal to allowedActions/dataScope: it narrows which roles the
clause's authority may hand out, not how much data it reaches. Omitting it means no restriction; an
empty list is rejected rather than read as "compose nothing". At most 20 entries, duplicates
rejected. Entries are deliberately not resolved against this blueprint's own roles — a clause
may legitimately name a role that already exists in the context. Rejected on a roleIds-composed
accessProfile, which has no inline clause to carry it. Once a clause carries the field it can
compose only the roles it names, so name every roleId the restricted clause still needs before
adding it.
Scripts
A blueprint may declare a top-level scripts — a map of script name → { source, declaredInputContract? } — carrying the source a trigger's scriptRef runs, so a blueprint that
declares a trigger can ship the code that trigger executes. Applied in-context, before the
triggers that reference it: a scriptRef is validated when the rule is declared rather than when
it fires, so a rule naming a script with no versions in the target context is refused outright.
scripts:
notify-assignee:
source: |
// A script is a plain (classic) script: its last expression is the result,
// and `input` is a global. `export`, a top-level `return` and `await` are syntax errors.
({ notified: input.recordId });
declaredInputContract: "{ recordId: string, record: { status: string } }"
- The map key is the script's name — what a
scriptRef.nameresolves against. 1–64 characters of letters, digits,_and-. source— required, non-blank, at most 300,000 UTF-8 bytes. Nothing parses it, here or on the platform, so a syntax error stays invisible until the version first runs. It runs as a plain script, not a module: the value of its last expression is the result, andinputis a global.declaredInputContract— optional, at most 50,000 UTF-8 bytes, and descriptive only: it documents the input shape for a human reading the blueprint, and nothing enforces it.inputSchema— optional: the input contract the platform enforces on every call of the version, in the platform's small JSON Schema dialect: the root is{ type: object }; a node has atype(string,number,integer,boolean,array,object) and may have adescription(up to 2,000 characters) and anenum(1 to 100 distinct values of its type); anobjectnode may haveproperties(up to 100, each named 1 to 64 characters),requiredandadditionalProperties(falseunless set totrue); anarraynode may haveitems; nothing else, at most 5 levels deep and 16,384 bytes.validatechecks it offline with the same rules. Needs platform 0.50.0 or later.optInOperations— optional: the operation names this version declares. Which names a version may declare is the platform's decision, and declaring one needs the capability mapped to it, which a blueprint role cannot grant;validatechecks only that each entry is a string. Needs platform 0.50.0 or later.
source, declaredInputContract, inputSchema and optInOperations are all part of the version: a re-apply pushes a new version
when any of them differs from the stored one (inputSchema is compared in the form the platform stores, and optInOperations as a
set, so order and repeats do not count), and pushes nothing when none does. A blueprint that leaves inputSchema out does not
compare it, so a version stored with one (pushed another way) is kept while nothing else changes; a push for another reason stores a
version without one. A blueprint that leaves optInOperations out declares none: an absent list is the empty list, so a stored
declaration is not kept.
Both caps count UTF-8 bytes, not characters, matching the platform.
There is no path:, deliberately. A shipped script runs under its trigger's declared grant, so
it is live authority, and a blueprint is a bundle someone reviews before applying it — keeping the
source inside the bundle keeps what runs inside what was reviewed.
You cannot declare a version, and a trigger on a script this blueprint ships must use
version: latest — a pin is rejected at authoring time. Versions are assigned by the platform and
a stored version is immutable, so a blueprint declares only the current source for a name; a pin
would name a version the blueprint cannot know it produced, and would keep running superseded code
once the source was edited. A scriptRef naming a script this blueprint does not ship may still
pin — that is the "reference a script someone else pushed" case.
Re-applying an unchanged blueprint pushes nothing, and removing a scripts entry does not
delete the script — the deliberate asymmetry with triggers below. The stored source is the only
copy, and an unreferenced version is inert. Remove one deliberately with vectros scripts delete.
Script ownership is checked before a push. Each version a blueprint pushes records the
blueprint's name as its provenance. Pushing onto a script name that already exists is refused in
two cases: when the name was pushed by a different blueprint (there is no flag to override this;
rename one of the scripts), and when the name exists with no blueprint provenance, such as a script
you pushed by hand. For the second case the CLI refuses unless you pass --allow-script-adoption,
which takes that name into the blueprint's management from then on. Either refusal pushes nothing.
The reason is that an existing trigger rule on version: latest would otherwise start running the
blueprint's code under that rule's own, separately authored grant. The provenance is the blueprint's
self-declared name, not a verified identity.
Agents
agents is a map of agent name to definition (model required; description, authority, system, tools as
{ name, allowWrites? }, limits, budget). It needs formatVersion: 2. Each entry is the current definition for that
name; the platform keeps every version and never edits one. vectros blueprint apply and bootstrap write each agent with
POST /v1/agents?upsert=true in the blueprint's context, after the roles, scripts and triggers and before any key is minted:
a new name is created at version 1, an identical definition (compared after defaults are filled in) writes nothing, and a changed
one becomes the next version. For an existing agent the CLI first makes a plain create call to see its mark and version, then the
upsert; the two versions give the exact outcome (created, unchanged, 2 -> 3, adopted).
formatVersion: 2
name: intake
version: 1.0.0
description: Intake records with a triage agent.
contextId: intake
schemas: []
accessProfile:
allowedActions: [records:r, records:c]
servicePrincipal:
externalId: intake-principal
displayName: Intake
agents:
intake-triage: # the key IS the agent's name: 1-64 letters, digits, '_' and '-'
description: Summarises a new intake record and flags missing fields.
model: claude-sonnet-5-5
system: You triage intake records. Be concise.
tools:
- { name: records_get }
- { name: records_create, allowWrites: true } # a tool that changes data needs allowWrites ...
limits: { maxToolCalls: 10, maxWrites: 2 } # ... and limits.maxWrites of at least 1
budget: { maxInferenceCents: 100 }
validate checks the section offline: at most 50 tools, each named once; limits.maxWrites of at least 1 when a tool has
allowWrites: true; limits.maxToolCalls, when you set it, not 0 while tools are listed; and the name and length rules. authority is
checked for its shape only (an upper-case name such as CALLER). The platform checks the model, the tool names and the
minimum budget when the blueprint is applied. The fields, limits and defaults are in the
agents reference.
- Script tools. A tool entry can instead offer a stored script: give it a
script({ name, version }, the same reference a trigger carries,versiona version number as a string orlatest) and, optionally, adescriptionfor the model (1 to 1,024 characters, on a script tool only). The script version must declare aninputSchema; a tool on a script the blueprint ships must uselatest(a blueprint rule, as for triggers, because the blueprint cannot know which version number its source lands on; the platform itself also accepts a pinned version), andvalidaterefuses one whose shipped entry declares noinputSchema. The tool'snameis its own and must not be a catalog tool's. Saving the agent needs a credential allowed to run the script (scripts:x), and a run executes it under the run's caller's own credential; the platform checks both. Needs platform 0.50.0 or later. - Scopes. The applying credential needs
agents:c, andagents:uandagents:ras well when the agent already exists, even if nothing changed. A refusal is reported with the scopes named.agentsis control-plane: a blueprint cannot grant it. - Ownership. Each agent is marked with the blueprint's
name, set once. Another blueprint's agent of the same name is refused; an agent that exists with no mark (made by hand) is refused unless the operator passes--allow-agent-adoption, which marks it and writes the declared definition as its next version if that differs. A rename of the blueprint strands the agents it made. - Removal. Dropping an entry deletes nothing. A retired agent keeps its name, so a blueprint that still declares one fails its
apply (
409) until the agent is restored (vectros agents version <id> --restore --file <definition>; a purged agent cannot be restored) or the entry is removed. blueprint-testruns a blueprint that declares agents under names of their own: an agent keeps its name once retired, so the test applies a copy whose agent names carry a per-run suffix, then retires and purges exactly the agents it created (names up to 54 characters; needsagents:d).
Triggers
A blueprint may declare a top-level triggers — a map of trigger name → declaration, each
naming a schema event that invokes a versioned script under an explicitly declared grant. A
declared trigger fires: a record write on a schema that opts in via
capabilities.triggersEnabled dispatches the rule's script, which runs asynchronously in a sandbox
under the grant declared here. So a trigger's allowedActions/dataScope/capabilities, or the
roles its roleIds composes, are live authority — author them as narrowly as any other
credential's, and review them the same way. Applied per-context, like roles/accessProfile.
schemas:
- typeName: intake
displayName: Intake
capabilities: { triggersEnabled: true }
fields:
- { fieldId: status, fieldType: string, inline: true }
triggers:
on-intake-update:
firingSource: { schemaName: intake, event: UPDATE }
scriptRef: { name: notify-assignee, version: latest }
fields: [status]
allowedActions: [records:r:intake, records:u:intake]
dataScope: { "scope:org": ["${{ input.scope.org }}"] }
manifest: [records.get, records.update]
fields— required. The record fields projected into the script'sinput.record, and on anUPDATEfiring intoinput.previous.fields: []is the explicit "project nothing" declaration (the script still receivesinput.recordId); it is required rather than defaulted so that projecting nothing is something you state. An entry may name only a field the schema keeps inline —inline: true,filterable: true, or a lookup field (a leg or itssortBytarget) — and never one markedsensitive.recordandprevioustogether are capped at 224 KB serialised; a firing that exceeds it is not run.- ⚠️ A rule that declares any
fieldsmust be able to read what it fires on. Its grant must hold arecords:rclause covering the firing schema's type — a grant with no read at all is rejected — and that clause may not carry a literaldata_scopeconstraint (a${{ input.userId }}or${{ input.scope.<namespace> }}placeholder is fine, since it resolves to the firing record's own value). firingSource.schemaName+firingSource.event(CREATE/UPDATE/DELETE) —schemaNamemust name atypeNamethis same blueprint declares.scriptRef.name+scriptRef.version— an exact integer, or the literal"latest". For a script this blueprint ships,latestis the only accepted value (see Scripts above).- A grant —
roleIds(composed from this blueprint'sroles) or an inlineallowedActions/dataScopepair, mutually exclusive, the same XOR shapeaccessProfileuses. manifest(optional) — host-object verbs (e.g.records.get) further narrowing what the script may call on top of what the grant permits. Never widens it.dataScopevalues may use${{ input.<dim> }}, resolving to a dimension stamped on the record whose change fired the trigger. Valid only inside a trigger'sdataScope;${{ self.* }},${{ under.self.* }}and${{ member.* }}are rejected there, because they resolve against the trigger principal's identity rather than the author's.
Removing a trigger de-provisions it, on vectros bootstrap and on vectros blueprint apply --prune.
Triggers are the one block an apply reconciles by absence as well as presence: delete an entry and
re-run vectros bootstrap, and its rule and the access profile behind it are deleted, so a trigger
you removed cannot keep acting under a grant that outlived it. vectros blueprint apply deletes
nothing unless you pass --prune; without it a removed trigger stays live and the command says so.
Its service principal is kept, so re-adding the same trigger reattaches to one identity. Only a
trigger this blueprint created is removed: its stored provisionedBy marker must equal the
blueprint's name, and its service principal must be the one this blueprint would have created for
a trigger of that name. Triggers created outside this blueprint, another blueprint's triggers and
triggers with no marker are never touched. Both checks read stored markers, not verified identities,
and the name comes from the blueprint file, so a file that reuses another blueprint's name and
omits some of its triggers removes them: keep each blueprint's name unique. Nothing else a
blueprint declares is deleted by removing it.
Issuers
issuers:
- issuerId: my-idp
issuer: https://idp.example.com
jwksUri: https://idp.example.com/.well-known/jwks.json
audience: my-vectros-app
contextId: my-context
A blueprint may declare top-level issuers — trusted third-party IdP issuers to
register for BYO-IdP token exchange, each { issuerId, issuer, jwksUri, audience, contextId, subClaim?, emailClaim?, userinfoUri?, restrictedToDomain?, selfSignupPolicies?, capturedClaims?, acceptedIdTokenClientIds? }. userinfoUri points at the IdP's
OIDC userinfo endpoint: when a presented token misses emailClaim (access tokens
generally don't carry email under OIDC unless the IdP was specifically configured to
add it), Vectros falls back to calling userinfoUri with that token as the bearer
credential and reads emailClaim from its response — omit it to leave the fallback
disabled. Unlike schemas/accessProfile/roles (applied
under a per-context token), issuers are applied in the loader's bootstrap-token
phase, alongside app-context/service-principal creation — tenant-wide provisioning
config that needs the bootstrap credential's owner-only authority. (issuer, audience)
must be globally unique across every tenant (an entry without restrictedToDomain claims its pair when it is
verified, not when it is registered), unless the entry sets restrictedToDomain — a
domain already verified for your account, written as a lowercase DNS name such as acme.com
— which scopes the uniqueness to that domain: a token then matches only when its hd claim
equals it (Google Workspace emits hd natively; other identity providers need a claims-mapping
rule that emits a claim named exactly hd), so scoping an issuer whose users sign in without
one locks them out.
Each entry's contextId must equal the blueprint's own contextId — an issuer is a
trust anchor, so a blueprint may only attach one to the context it actually provisions.
@vectros-ai/cli 0.16.0+ handles a blueprint whose issuers target a context other
than the bootstrap credential's own transparently: the credential re-mints itself,
pinned to the blueprint's own context, specifically to register those issuers — no extra
authoring step is needed on your part. The loader always registers (idempotent by
issuerId) and then reconciles: editing an already-registered issuer's
subClaim, emailClaim, userinfoUri, restrictedToDomain, selfSignupPolicies or capturedClaims and
re-running bootstrap now converges on the declared values. A selfSignupPolicies entry may name additionalRoleIds
(up to 9 more roles, none repeating roleId; platform 0.50.0 or later); a re-apply replaces the whole list, each
entry's additionalRoleIds included, so declare every additional role in the blueprint. Leaving restrictedToDomain out of a re-apply
keeps an existing scope; it does not clear it. Clearing a domain scope is refused by the platform (400)
unless the registration already holds the unrestricted (issuer, audience) pair, which a registration created
scoped to a domain does not. To get an unrestricted issuer, delete the scoped registration (vectros issuers delete),
declare or register a new one without restrictedToDomain, and verify it (vectros issuers verify). A context holds
one active issuer, and the delete is refused once any user has been created or matched through the old issuer; in
that case register the new issuer under a different app context. ⚠️ The trust-anchor fields
(issuer, jwksUri, audience, contextId) stay immutable, and editing one on an
already-registered issuer now fails the whole apply with the platform's 400 rather
than being silently ignored as it once was. Issuer status is not blueprint-authorable
at all — suspend or reactivate an issuer through the API. ⚠️ From API/SDK 0.45.0, an issuer a
blueprint registers without restrictedToDomain starts pending_verification and accepts no token until its registrant proves
control of the identity provider with the API's verifyIssuer call
(identity-access/how-to.md);
an issuer that already existed is unaffected. An entry that sets restrictedToDomain is active at once:
the domain you verified for your account is what it proves, and it only ever matches that domain's
users. Verifying needs a real login from the IdP after a human
configures a claim rule there, so vectros bootstrap (or vectros blueprint apply) cannot finish it: it still completes and exits 0,
says pending verification beside the issuer, and ends its output, on stderr, with the challenge and the exact
vectros issuers verify command (@vectros-ai/cli 0.23.0 and later). --require-verified-issuers
turns a pending issuer into exit 4 (a one-line notice follows the challenge) for a pipeline that must not go green over it, and an issuer whose
challenge expired while pending is reported as unverifiable, with the delete command; nothing is deleted for
you. Adding
restrictedToDomain to an issuer that is still awaiting verification is refused by the platform (400), so
the apply fails: verify the issuer first, or delete it and apply again. (Registering, reading, updating, or
deleting an issuer directly against the API, outside a blueprint, stays confined to the
calling credential's own context — see
identity-access/reference.md
for the full field grammar, every error code, and the token-exchange contract those issuers
serve; identity-access/explanation.md
for the concept and the flow end to end.)
acceptedIdTokenClientIds lists other client ids an ID token from this identity provider may be addressed to, for an app's in-app account deletion (/v1/me/erasure) when the registration's audience is an API rather than the app (Auth0, for example): up to 10, each non-blank, at most 255 characters, each once. Leaving it out of a later apply keeps the stored list; an empty list keeps only audience. Needs platform 0.50.0 or later.
capturedClaims names additional OIDC claim names — beyond emailClaim, which keeps its own
field — to read from that issuer's tokens on every successful exchange and store as your tenant's
golden identity-provider-asserted copy for the signed-in user. Not a fixed set: name whatever your
provider actually asserts. Each is read from the verified token first, falling back to userinfoUri
(when configured) only for names still missing. Omit to capture nothing beyond email — unchanged
behaviour for every existing blueprint. At most 20 entries of at most 64 characters each; a
duplicate is rejected rather than deduplicated.
The top-level identityProjectionClaims is the other half: it declares which of those captured
names are projected, read-only, onto access profiles in this blueprint's app context, where they
surface as identityProjection on the profile. Capture and projection are separate opt-ins —
capturing stores a claim against the user, projecting exposes it on a profile — and declaring a
name no issuer captures simply never fills. A profile's projection fills once, the first time a
sign-in for that principal can supply a value (for an invited member, not until they accept and sign
in), and never updates again; editing the list therefore affects only profiles not yet filled.
⚠️ It takes effect when the app context is CREATED. Re-applying a blueprint against a context
that already exists does not change the declaration in either direction — a declared list is not
applied, and an empty list does not disable. Change an existing context's declaration through the
platform API. Like issuers, it applies in the bootstrap-token phase, because setting it needs
the platform provisioning capability only that phase's credential carries.
Namespaces
namespaces:
- namespace: team
entityBacked: true
specificityRank: 10
A blueprint may also declare top-level namespaces — entity-namespace
registrations, each { namespace, specificityRank, entityBacked?, tenantWide?, membershipRecordType?, membershipTargetField?, membershipLevelField?, membershipLevels? }. Like issuers,
these are applied in the loader's bootstrap-token phase. By default, a declared
namespace is owned by the blueprint's own contextId — it applies with a context-bound
credential, and the platform's namespace registration confines a context-bound caller to
its own context. An entry may add tenantWide: true to request a tenant-wide
registration instead (visible to every app context). That is a deliberate, narrow opt-in
with two conditions: the applying credential must hold a platform capability granted only
to the account owner, and the CLI must be run with --allow-tenant-wide-namespaces;
without the flag the CLI refuses the blueprint (exit 2) and a tenant-wide entry that
collides with an existing registration fails the apply rather than adopting it.
namespace— 2-32 chars, a lowercase letter first, then lowercase letters/digits/_/-. A closed set of words is rejected as reserved (user,record,document,entity,self,tenant,context,scope,versions,lookup) —org/clientare NOT in that set: they're reserved namespace names, not built-ins, registered the same way as any other (see identity-access/reference.md for the platform endpoint this mirrors). Signup does not register them: an account hasorgandclientonly once it registers them (for example by declaring them here). Accounts created before that change may still hold the rows signup made for them, atspecificityRank1000 (org) and 2000 (client); a rank must be unique across the account, so a registration of yours needs a different rank wherever those rows exist. A context-owned registration shadows a tenant-wide one of the same name for this context's own callers.specificityRank— an integer0..1_000_000, this namespace's position in the account's specificity order. Must be unique among this blueprint's own namespaces — a collision with the rest of the account's registrations (includingorg=1000 andclient=2000) surfaces at apply time.entityBacked(optional) — whentrue, every value in this namespace must resolve to an existing identity entity; whenfalse/omitted, values are free-form strings validated by grammar only.membershipRecordType+membershipTargetField— optional, declared together (or both omitted): which record type + field hold grants of this namespace's values.membershipRecordTypemust name atypeNamethis same blueprint declares underschemas:. Declaring this grants nobody anything on its own; a role opts in explicitly with${{ member.scope.<namespace> }}in itsdataScope.membershipLevelField+membershipLevels— optional, declared together: the field naming a grant's level, and the complete set of level labels allowed.
Registration is not idempotent server-side: a re-apply whose declaration matches what's already registered converges silently, but one that disagrees with the live registration fails the apply rather than silently overwriting it.
Inputs (install-time variables)
A blueprint may declare an inputs: block and reference values with
${{ inputs.<name> }} (plus the built-ins ${{ vectros.context }} /
${{ vectros.suffix }}). Supply values at validate/plan/apply time with --set
or --values. Inputs apply to file blueprints only.
Splitting a blueprint across files and stacks
A real app's blueprint grows to dozens of schemas and roles. You can split it into a root file and part files, and group the parts into stacks that can be applied one at a time.
Parts. The root file lists its parts under include:. Each entry is a path relative to the root
file's directory, and may use * to match within one path segment (schemas/*.part.yaml); each
pattern's matches are taken in lexical order, and the patterns in the order written. A part file is
named *.part.yaml, *.part.yml or *.part.json, so no tool mistakes it for a whole blueprint, and
it may declare only these sections: schemas, roles, roleAssumable, fragments, identities,
issuers, namespaces, scripts, triggers, agents and seed. The blueprint's identity and its
own grant stay in the root file: name, version, description, contextId, contextName,
companyName, servicePrincipal, accessProfile, identityProjectionClaims, formatVersion,
inputs, include and stacks are refused in a part.
Nothing is overridden. The parts are composed into one blueprint: lists are concatenated (the
root's entries first, then each part's), maps are combined, and a name declared twice (a schema
typeName, a role id, a trigger name, a fragment, and so on) is refused with both files and lines.
So a role, schema or trigger is always written in exactly one file, and reading that file is reading
all of it. A field that names a resource or refers to one (a schema typeName, an issuerId, a
trigger's schemaName, scriptRef.name or roleIds, a seed's typeName and externalId, and the
like) must be written out, not taken from ${{ inputs.* }}, because duplicates and stacks are decided
by those names before inputs are resolved.
Confinement. A part must live inside the root file's directory: an absolute path, a path that
climbs out with .., a URL, and a symbolic link that resolves outside the directory are all refused.
The directory is the bundle you review.
Errors name the file. Every command reads the root file and composes the whole blueprint first.
A structural or input problem is reported with the file and line it comes from, and validate and
plan add the file and line to a lint finding or gate refusal that names a resource:
✖ Malformed blueprint:
• catalog/products.part.yaml:11: schemas[4].fields[1].fieldType: Invalid input: expected string, received undefined
inputs: is declared in the root and resolved after composition, so ${{ inputs.<name> }} works in
any part. vectros blueprint flatten <root> prints the composed blueprint as one document (inputs
left unresolved), which validates and applies exactly as the split files do.
Stacks. The root file may group its parts into named stacks:. Every included file belongs to
exactly one stack, and root is reserved for what the root file itself declares (including the
access profile). A stack is a deploy unit inside one blueprint, not a separate blueprint: it shares
the blueprint's name, service principal and access profile, and moving a part from one stack to
another changes nothing about who owns what it declares. A fragment must be in the same stack as every
role that uses it, and a roleAssumable entry in the same stack as its role: both are written as part
of the role, so declaring them elsewhere would make their own stack's apply change nothing.
# my-app.blueprint.yaml (the root, abridged)
name: my-app
version: "1.0.0"
description: An app split across part files.
contextId: my-app
servicePrincipal: { externalId: my-app-loader, displayName: My App loader }
accessProfile:
allowedActions: [records:r:product, records:r:order]
include:
- identity/*.part.yaml
- catalog/*.part.yaml
- orders/*.part.yaml
stacks:
identity: [identity/*.part.yaml]
catalog: [catalog/*.part.yaml]
orders: [orders/*.part.yaml]
vectros blueprint apply <root> --stack orders --tenant test validates and gates the whole
blueprint, then writes only the orders stack's resources. The service principal, the context and the
declared identities are ensured on every apply; the access profile is written only when root is
selected (or by an apply without --stack), so a stack apply without root does not ask to confirm
an existing service principal. An apply that includes root rewrites the access profile and asks, as
a whole apply does: in a pipeline pass --confirm-existing-principal, or it exits 3. Repeat --stack to apply several. What a selected stack needs from
another stack must already be live, and is checked before anything is written; the apply is refused,
naming the stack to apply first. That covers a trigger's schema, script and roles; a schema's
reference-field targets, including a target surface that is an entity namespace; the roles a role's
assignableRoles or an issuer's self-signup policy name; every namespace a selected role, trigger,
schema or seed scopes by, and the namespace of every declared identity; with --seed, each seed's
schema; and, with root, the access profile's roles and the namespaces its dataScope and
identityOverrides name. A namespace counts as live only when it is registered where the blueprint
declares it (this context, or tenant-wide for a tenantWide one). A role's actions naming another
stack's schema (records:r:<type>) are not checked, as in a whole apply. This is a check of the
references the blueprint names, not a guarantee that an apply cannot fail part-way: the platform can
still refuse a write for a reason no name shows. It also confirms that a resource exists, not that it
matches its file: apply the stack that declares it after you change it.
Apply a split blueprint whole the first time (no --stack), so every stack and the access profile
exist; after that, apply one stack at a time as its files change. To build one up stack by stack
instead, apply them in dependency order and include root last (in the sketch above: identity, catalog,
orders, then root). vectros blueprint plan <root> --stack <name> previews the same, listing what
the stack assumes is already applied, and names any role the access profile is composed from that the
stack rewrites (that changes the service principal's grant).
A stack apply never deletes anything, and --stack cannot be combined with --prune: a trigger
removed from its file no longer belongs to any stack, so removing it is done by an apply of the whole
blueprint with --prune. Stacks limit what an apply writes, not who may apply it: the credential that
applies one stack could apply them all.
Bundled blueprints
Four blueprints ship with the library:
| Name | What it provisions |
|---|---|
task-management | Structured task tracking, shareable across sessions, agents, and users. The authoring exemplar. |
agentic-sdlc | A whole-SDLC system of record for an AI development team — decisions, designs, references, runbooks, and post-mortems as documents, plus controls, conventions, gotchas, and a glossary as records, cross-linked and recalled by meaning. |
second-brain | A personal knowledge base — capture notes, ideas, and links, then ask them anything. |
clinical-intake | A clinical intake data model (synthetic/illustrative). |
List them with vectros blueprint list; apply one with
vectros bootstrap --blueprint <name> (which also mints a key for your MCP client) or
vectros blueprint apply <name> --tenant test|live (which mints none).
Notes & limits — glue caveats
bootstrapneeds a sign-in. Applying a blueprint withbootstrapuses your storedvectros loginsession (run it once; later runs reuse it) or, with none, a bridge token from the developer portal.identities:blocks are resolved at apply time. Each entry declares akind(user, or an entity namespace —org,client, or one you registered) plus anexternalId; the loader resolves it through the ordinary identity API —createUserforkind: user,createEntity({ namespace: kind, ... })for anything else — using the bridge token's own authority, and the resolved id becomes available to the rest of the blueprint as${{ identities.<name> }}. The CLI fails closed on a blueprint that declares an entity namespace that hasn't been registered, rather than applying it partially.referencefields enforce the target at write. A blueprint can declare a typed reference between record types; by default the platform requires the referenced record to exist when the referencing record is written — so if a seed record references another, seed the target first. (To opt out for an order-independent bulk load, a schema would setcapabilities.validateReferences: false— not exposed in the bundled blueprints.) There is no reverse-reference query on this surface; to ask "which records reference X", declare the reference field as an equality lookup.- Most control-plane scopes are rejected. A blueprint cannot request scopes on keys,
app contexts, users, billing, admin,
agents, the namespace registry, or most ofprofilesandscripts— the CLI scope gate rejects them, mints nothing, and exits non-zero. The gate's allowlist does includeentities(creating and managing identity entities, includingorg/client, ownership-gated like records) and the narrow exceptions listed in cli.md. Declaring principals viaidentities:(above) is a separate mechanism — the loader resolves them itself at apply time, which is what lets seed records reference them, rather than minting anentitiesscope for the bootstrapped key.
Where to go next
- cli.md —
init,validate,plan,bootstrap, andblueprint-testoperate on these files. - mcp.md — the scoped key a blueprint mints is what an MCP agent runs on.
- sdk.md — the operations a blueprint's schemas and scopes govern.
- The blueprint walkthroughs — narrated, end-to-end builds on top of this format.