@usenaive-sdk/blueprints 0.1.0 → 0.3.0

package/dist/index.js

@@ -92,7 +92,10 @@ var AUDIT_ACTIONS_P3 = [
   "app.secret_deleted",
   "app.domain_connected",
   "app.domain_disconnected",
-  "app.db_queried"
+  "app.db_queried",
+  /** A ticket was minted that lets one browser past an app's own operator gate (§29.7). */
+  "app.entered",
+  "blueprint.installed"
 ];
 var AUDIT_ACTIONS = [
   ...AUDIT_ACTIONS_SHIPPED,
@@ -239,7 +242,16 @@ var StopReasonSchema = z4.enum([
    * Distinct from `awaiting_input`: nobody is being asked for anything, so no human can unblock it —
    * the child's completion does. Reporting `idle`/`end_turn` here would claim the task was finished.
    */
-  "awaiting_delegation"
+  "awaiting_delegation",
+  /**
+   * The turn yielded because the agent asked the operator a question and cannot proceed without
+   * the answer (§7.1). Distinct from all three neighbours, and none can stand in: `awaiting_input`
+   * says only that there is nothing left to do, so a client reading it renders a bare composer
+   * where a specific answer is owed; `awaiting_approval` says the block is a tool call to allow or
+   * deny, and its route carries a verb and no payload; `awaiting_delegation` says no human can
+   * unblock it at all. What is being asked is the parked `pending_actions` row.
+   */
+  "awaiting_answer"
 ]);
 var ThreadRoleSchema = z4.enum(["coordinator", "member"]);
 var MessageSchema = z4.object({
@@ -252,10 +264,57 @@ var ToolResultSchema = z4.object({
   is_error: z4.boolean().optional(),
   content: z4.string().optional()
 });
+var QuestionFieldBase = {
+  key: z4.string().min(1).max(64),
+  label: z4.string().min(1).max(200),
+  help: z4.string().max(500).optional()
+};
+var QuestionFieldSchema = z4.discriminatedUnion("type", [
+  z4.object({
+    ...QuestionFieldBase,
+    type: z4.literal("text"),
+    placeholder: z4.string().max(200).optional()
+  }),
+  z4.object({
+    ...QuestionFieldBase,
+    type: z4.literal("choice"),
+    /**
+     * Plain strings: the option is both the value and the label, because the answer is read back by
+     * a model, which wants the words and not an id. Fewer than two is not a choice, and more than
+     * twelve is a list — which belongs in the prompt.
+     */
+    options: z4.array(z4.string().min(1).max(200)).min(2).max(12),
+    multiple: z4.boolean().default(false),
+    /**
+     * The free-text escape, and it defaults to **true** on purpose: the agent wrote the options and
+     * the agent is the one that does not know the answer, so an operator must always be able to say
+     * something it did not think of. A question that truly admits only its list opts out explicitly.
+     */
+    other: z4.boolean().default(true)
+  })
+]);
+var QuestionSchema = z4.object({
+  prompt: z4.string().min(1).max(1e3),
+  fields: z4.array(QuestionFieldSchema).min(1).max(3)
+});
+var AnswersSchema = z4.record(
+  z4.string().min(1).max(64),
+  z4.union([z4.string().max(2e3), z4.array(z4.string().max(2e3)).min(1).max(12)])
+).refine((answers) => Object.keys(answers).length <= 3, {
+  message: "a question has at most 3 fields, so an answer has at most 3 keys"
+});
 var PendingActionSchema = z4.object({
+  kind: z4.enum(["tool", "question"]).default("tool"),
   tool_call_id: z4.string(),
   name: z4.string(),
-  args: z4.record(z4.string(), z4.unknown())
+  args: z4.record(z4.string(), z4.unknown()),
+  /**
+   * Present iff `kind` is `"question"`, and it is the parse of `args` rather than a second source
+   * of truth: `args` is what the model called and therefore what replays byte-identically, while
+   * `question` is what a renderer reads without having to know that `ask_operator`'s arguments
+   * happen to be the question. Same content, two jobs.
+   */
+  question: QuestionSchema.optional()
 });
 var SessionSchema = z4.object({
   id: idOf("ses"),
@@ -314,6 +373,10 @@ var ToolConfirmationSchema = z4.object({
   decision: z4.enum(["allow", "deny"]),
   reason: z4.string().optional()
 });
+var SessionAnswerSchema = z4.object({
+  tool_call_id: z4.string(),
+  answers: z4.record(z4.string(), z4.union([z4.string(), z4.array(z4.string())]))
+});
 
 // ../core/src/schema/event.ts
 import { z as z5 } from "zod";
@@ -756,6 +819,11 @@ var AppSecretSchema = z11.object({
   value_hash: z11.string().nullable(),
   created_at: Timestamp
 });
+var AppEntrySchema = z11.object({
+  object: z11.literal("app_entry"),
+  url: z11.string(),
+  ticket: z11.string()
+});
 var AppDomainStatusSchema = z11.enum(["pending", "connected", "failed"]);
 var AppDomainSchema = z11.object({
   object: z11.literal("app_domain"),
@@ -768,36 +836,168 @@ var AppDomainSchema = z11.object({
 var ENV_NAME = /^[A-Z_][A-Z0-9_]*$/;
 var APP_NAME = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
 
-// ../core/src/schema/vault.ts
+// ../core/src/schema/install.ts
 import { z as z12 } from "zod";
-var VaultCredentialKindSchema = z12.enum(["env_var", "static_bearer", "mcp_oauth"]);
-var VaultSchema = z12.object({
+var BlueprintInstallSourceSchema = z12.enum(["studio", "cli"]);
+var ResourceActionSchema = z12.enum(["created", "updated", "unchanged", "deleted", "refused"]);
+var ResourceReportSchema = z12.object({
+  name: z12.string().min(1),
+  action: ResourceActionSchema,
+  /** The `agt_`/`app_`/`ses_`… the line resolved to. Absent on a refusal that never got an id. */
+  id: z12.string().optional(),
+  /** An app's hostname once its build went live; `null` while it has none. Apps only. */
+  url: z12.string().nullable().optional(),
+  reason: z12.string().optional()
+});
+var BlueprintReportSchema = z12.object({
+  skills: z12.array(ResourceReportSchema),
+  identities: z12.array(ResourceReportSchema),
+  vaults: z12.array(ResourceReportSchema),
+  apps: z12.array(ResourceReportSchema),
+  agents: z12.array(ResourceReportSchema),
+  schedules: z12.array(ResourceReportSchema),
+  intake: z12.array(ResourceReportSchema),
+  skipped: z12.array(z12.string())
+});
+var BlueprintInstallSchema = z12.object({
+  id: idOf("bpi"),
+  object: z12.literal("blueprint_install"),
+  /** The customer's own `defineProject({ name })` — the same word `app.project` stamps (§29.2). */
+  project: z12.string().min(1),
+  /** The pair the declaration resolved to; `null` for a declaration that names no blueprint. */
+  blueprint: z12.string().nullable(),
+  template: z12.string().nullable(),
+  /**
+   * Applies, not versions of anything: 1 on the first apply, +1 on each one after, whichever writer
+   * made it. It is not an agent version and it never rolls back.
+   */
+  revision: z12.number().int().positive(),
+  /**
+   * The blueprint artifact version this came from, or `null` when it was applied from a working
+   * tree — an operator editing a clone has no version to name.
+   */
+  artifact_version: z12.string().nullable(),
+  /**
+   * The setup answers this project was configured with (§7.1 fields, keyed by their `key`), so a
+   * re-apply does not re-ask and both writers configure from the same answers. Configuration only:
+   * a secret is a vault credential (§23) or an app secret (§29.2), and neither is ever an answer.
+   */
+  answers: z12.record(z12.string(), z12.unknown()),
+  /**
+   * NO `declaration` ON THE WIRE, and that is the reconciliation of §29.6 with §31.1.
+   *
+   * The applied bytes are stored — a `revision_conflict` names the paths two writers disagree at,
+   * and it can only do that by holding what was applied. They are not published. An apply that
+   * names a published `blueprint` and `template` sends no declaration: the server reads the
+   * catalog's, which §31.1 says never leaves it. Echoing it back on the 201 (and again on every
+   * later list) would hand any organization that can sign up the whole private config of a
+   * blueprint it has installed nothing of — every agent's system prompt, its `mcp_servers`, its
+   * vault credential declarations and its app `env` keys. A caller that sent a declaration already
+   * has it, so nothing is lost by not saying it twice.
+   */
+  source: BlueprintInstallSourceSchema,
+  /**
+   * WHAT THE APPLY DID, or `null` when it did nothing but record.
+   *
+   * An apply that sends its own `declaration` has already reconciled it — that is what `naive up`
+   * is — so the row it writes is a record and this is `null`. An apply that names a **published**
+   * pair has reconciled nothing: it was never given the bytes (§31.1), so the server reads them
+   * from the catalog and runs the same engine over them, and this is what that run reported.
+   *
+   * It is stored rather than only returned because a refusal inside a successful apply — an app
+   * whose `env` reads a variable no hosted run has, a session refused for credit — is the one fact
+   * a person needs after the screen that showed it is gone.
+   */
+  report: BlueprintReportSchema.nullable(),
+  applied_at: Timestamp,
+  created_at: Timestamp
+});
+
+// ../core/src/schema/blueprint.ts
+import { z as z13 } from "zod";
+var BlueprintScheduleSchema = z13.object({
+  agent: z13.string().min(1),
+  cron: z13.string().min(1),
+  timezone: z13.string().nullable(),
+  /** The message each fire opens its session with — the sentence worth printing. */
+  input: z13.string().min(1),
+  budget_micro_usd: MicroUsdField.nonnegative()
+});
+var BlueprintCrewSchema = z13.object({
+  name: z13.string().min(1),
+  description: z13.string().nullable(),
+  model: z13.string().min(1),
+  briefed: z13.boolean()
+});
+var BlueprintAppSchema = z13.object({
+  name: z13.string().min(1),
+  type: AppTypeSchema,
+  description: z13.string().nullable()
+});
+var ContentHashSchema = z13.string().regex(/^[0-9a-f]{64}$/, "a lowercase sha-256 hex digest");
+var BlueprintTreeSchema = z13.object({
+  /** `apps[].name` in the declaration — the same name §31.5 prints and the install ensures by. */
+  app: z13.string().min(1),
+  content_hash: ContentHashSchema
+});
+var BlueprintArtifactSchema = z13.object({
+  id: idOf("bpa"),
+  object: z13.literal("blueprint_artifact"),
+  /** The machine — its repository, screens and `/api/*`. */
+  blueprint: z13.string().min(1),
+  /** Which of that blueprint's templates provides the crew. */
+  template: z13.string().min(1),
+  /** The blueprint repository's own released version. Stored, never parsed (ADR-0401). */
+  version: z13.string().min(1),
+  /**
+   * The built trees, one per deployable app, ordered as the declaration orders its apps. Never
+   * empty: an artifact that built nothing is not an artifact, and the column behind it says so
+   * (migration 0040) exactly as the single `content_hash` it replaces was `not null`.
+   */
+  trees: z13.array(BlueprintTreeSchema).min(1),
+  /**
+   * The setup questions, asked by the studio **before** provisioning. `QuestionField` (§7.1) is
+   * reused rather than restated: a setup question and a question a parked agent asks are the same
+   * object at different times, so one component renders both.
+   */
+  questions: z13.array(QuestionFieldSchema),
+  schedules: z13.array(BlueprintScheduleSchema),
+  /** Who the crew is, and what it deploys — §31.5. Derived from `declaration`, never stored twice. */
+  agents: z13.array(BlueprintCrewSchema),
+  apps: z13.array(BlueprintAppSchema),
+  published_at: Timestamp
+});
+
+// ../core/src/schema/vault.ts
+import { z as z14 } from "zod";
+var VaultCredentialKindSchema = z14.enum(["env_var", "static_bearer", "mcp_oauth"]);
+var VaultSchema = z14.object({
   id: idOf("vlt"),
-  object: z12.literal("vault"),
+  object: z14.literal("vault"),
   identity_id: idOf("idn").nullable(),
-  display_name: z12.string().min(1).max(128),
-  credential_count: z12.number().int().nonnegative(),
+  display_name: z14.string().min(1).max(128),
+  credential_count: z14.number().int().nonnegative(),
   created_at: Timestamp
 });
-var VaultCredentialSchema = z12.object({
+var VaultCredentialSchema = z14.object({
   id: idOf("vcr"),
-  object: z12.literal("vault_credential"),
+  object: z14.literal("vault_credential"),
   vault_id: idOf("vlt"),
   kind: VaultCredentialKindSchema,
   /** For `env_var`, the environment variable name. For the MCP kinds, a display label. */
-  key: z12.string().min(1).max(128),
+  key: z14.string().min(1).max(128),
   /** The exact destination host an `env_var` credential is bound to. Never a wildcard. */
-  host: z12.string().nullable(),
+  host: z14.string().nullable(),
   /** The exact MCP server URL an `mcp_*` token is matched to. */
-  mcp_server_url: z12.url().nullable(),
-  placeholder_ref: z12.string(),
+  mcp_server_url: z14.url().nullable(),
+  placeholder_ref: z14.string(),
   expires_at: Timestamp.nullable(),
   last_injected_at: Timestamp.nullable(),
   created_at: Timestamp
 });
 
 // ../core/src/schema/social.ts
-import { z as z13 } from "zod";
+import { z as z15 } from "zod";
 var SOCIAL_PLATFORMS = [
   "bluesky",
   "facebook",
@@ -819,19 +1019,19 @@ var SOCIAL_TEXT_PLATFORMS = [
   "threads",
   "x"
 ];
-var SocialPlatformSchema = z13.enum(SOCIAL_PLATFORMS);
-var SocialTextPlatformSchema = z13.enum(SOCIAL_TEXT_PLATFORMS);
-var SocialAccountSchema = z13.object({
-  id: z13.string().min(1),
-  object: z13.literal("social_account"),
+var SocialPlatformSchema = z15.enum(SOCIAL_PLATFORMS);
+var SocialTextPlatformSchema = z15.enum(SOCIAL_TEXT_PLATFORMS);
+var SocialAccountSchema = z15.object({
+  id: z15.string().min(1),
+  object: z15.literal("social_account"),
   identity_id: idOf("idn"),
   platform: SocialPlatformSchema,
-  username: z13.string().nullable(),
-  display_name: z13.string().nullable(),
-  avatar_url: z13.url().nullable(),
+  username: z15.string().nullable(),
+  display_name: z15.string().nullable(),
+  avatar_url: z15.url().nullable(),
   connected_at: Timestamp.nullable()
 });
-var SocialPostStatusSchema = z13.enum([
+var SocialPostStatusSchema = z15.enum([
   "draft",
   "scheduled",
   "processing",
@@ -839,44 +1039,44 @@ var SocialPostStatusSchema = z13.enum([
   "failed",
   "deleted"
 ]);
-var SocialPostSchema = z13.object({
-  id: z13.string().min(1),
-  object: z13.literal("social_post"),
+var SocialPostSchema = z15.object({
+  id: z15.string().min(1),
+  object: z15.literal("social_post"),
   identity_id: idOf("idn"),
-  title: z13.string(),
-  platforms: z13.array(SocialTextPlatformSchema),
+  title: z15.string(),
+  platforms: z15.array(SocialTextPlatformSchema),
   status: SocialPostStatusSchema,
   scheduled_at: Timestamp.nullable(),
   posted_at: Timestamp.nullable(),
-  error: z13.string().nullable()
+  error: z15.string().nullable()
 });
-var SocialUploadSchema = z13.object({
-  id: z13.string().min(1),
-  object: z13.literal("social_upload"),
+var SocialUploadSchema = z15.object({
+  id: z15.string().min(1),
+  object: z15.literal("social_upload"),
   identity_id: idOf("idn"),
-  type: z13.enum(["image", "video", "document"]),
-  url: z13.url().nullable()
+  type: z15.enum(["image", "video", "document"]),
+  url: z15.url().nullable()
 });
-var SocialAnalyticsSchema = z13.object({
-  object: z13.literal("social_analytics"),
+var SocialAnalyticsSchema = z15.object({
+  object: z15.literal("social_analytics"),
   identity_id: idOf("idn"),
-  resource_id: z13.string().min(1),
+  resource_id: z15.string().min(1),
   platform: SocialPlatformSchema.nullable(),
-  data: z13.unknown()
+  data: z15.unknown()
 });
-var SocialCommentSchema = z13.object({
-  id: z13.string().min(1),
-  object: z13.literal("social_comment"),
+var SocialCommentSchema = z15.object({
+  id: z15.string().min(1),
+  object: z15.literal("social_comment"),
   identity_id: idOf("idn"),
-  post_id: z13.string().min(1),
-  platforms: z13.array(SocialPlatformSchema),
+  post_id: z15.string().min(1),
+  platforms: z15.array(SocialPlatformSchema),
   status: SocialPostStatusSchema,
   posted_at: Timestamp.nullable(),
-  data: z13.unknown()
+  data: z15.unknown()
 });
 
 // src/define.ts
-import { z as z14 } from "zod";
+import { z as z16 } from "zod";
 
 // src/template.ts
 var BLUEPRINTS = {
@@ -915,84 +1115,113 @@ function chooseTemplate(blueprint, template) {
 var BlueprintRefusal = class extends Error {
   name = "BlueprintRefusal";
 };
-var EnvValueSchema = z14.union([z14.string(), z14.object({ from_env: z14.string().min(1) })]);
-var AppDeclSchema = z14.object({
+var EnvValueSchema = z16.union([
+  z16.string(),
+  z16.object({ from_env: z16.string().min(1) }),
+  z16.object({ generate: z16.literal(true) })
+]);
+var AppDeclSchema = z16.object({
   /** Becomes a hostname, so the grammar is the platform's `APP_NAME` (a DNS label). */
-  name: z14.string().regex(APP_NAME, "a lowercase DNS label, 63 characters or fewer"),
+  name: z16.string().regex(APP_NAME, "a lowercase DNS label, 63 characters or fewer"),
   type: AppTypeSchema,
-  description: z14.string().optional(),
+  description: z16.string().optional(),
   /** A directory whose files are collected and shipped as the app's file-map deployment. */
-  deploy_dir: z14.string().min(1).optional(),
+  deploy_dir: z16.string().min(1).optional(),
   /** The path the app itself serves MCP on (§29.5); `fullstack` only. Absent means none. */
   mcp: AppMcpPathSchema.optional(),
   /** Written as the app's write-only secrets (§29.2) on every apply; names follow the platform's `ENV_NAME`. */
-  env: z14.record(z14.string().regex(ENV_NAME), EnvValueSchema, { error: "keyed by environment variable name (A-Z, 0-9, _)" }).optional()
+  env: z16.record(z16.string().regex(ENV_NAME), EnvValueSchema, { error: "keyed by environment variable name (A-Z, 0-9, _)" }).optional()
 });
-var ScheduleDeclSchema = z14.object({
-  cron: z14.string().min(1),
-  timezone: z14.string().min(1).optional(),
+var ScheduleDeclSchema = z16.object({
+  cron: z16.string().min(1),
+  timezone: z16.string().min(1).optional(),
   /** The message every fire opens its session with (`input_template` on the wire). */
-  input: z14.string().min(1),
+  input: z16.string().min(1),
   budget_micro_usd: MicroUsdField.nonnegative(),
-  identity: z14.string().min(1).optional(),
-  enabled: z14.boolean().optional()
+  identity: z16.string().min(1).optional(),
+  enabled: z16.boolean().optional()
 });
-var AgentDeclSchema = z14.object({
-  name: z14.string().min(1),
-  model: z14.string().min(1),
+var AgentDeclSchema = z16.object({
+  name: z16.string().min(1),
+  model: z16.string().min(1),
   budget: BudgetSchema,
-  description: z14.string().optional(),
-  system: z14.string().optional(),
+  description: z16.string().optional(),
+  system: z16.string().optional(),
   tools: ToolsetSchema.optional(),
-  skills: z14.array(SkillRefSchema).optional(),
-  mcp_servers: z14.array(McpServerSchema).optional(),
+  skills: z16.array(SkillRefSchema).optional(),
+  mcp_servers: z16.array(McpServerSchema).optional(),
   /** Declared app *names*; `up` resolves them to `app_` ids in `tools.configs.apps` (§29.3). */
-  allowed_apps: z14.array(z14.string()).optional(),
+  allowed_apps: z16.array(z16.string()).optional(),
   /** A declared identity *name*; `up` attaches it after the agent upsert (§22). */
-  identity: z14.string().min(1).optional(),
+  identity: z16.string().min(1).optional(),
   /** The agent's deployments as a complete set: declared → owned, and the rest are pruned (ADR-0355). */
-  schedules: z14.array(ScheduleDeclSchema).optional()
+  schedules: z16.array(ScheduleDeclSchema).optional(),
+  /**
+   * The first thing this agent reads, once, on the apply that **creates** it (`canonical-spec
+   * §31.4`). It is what turns a provisioned crew into a crew that has started working.
+   *
+   * Neither of its neighbours can carry it. A `schedule` fires again and again; an intake happens
+   * exactly once, at creation, and never on a later apply of the same agent. `system` is standing
+   * instruction re-read every turn; an intake is a message the agent is sent.
+   *
+   * `budget_micro_usd` is optional here and required on a schedule, because a cron spends
+   * repeatedly and unattended while an intake spends once, at an apply a person is watching. Absent
+   * means the agent's own `budget` governs.
+   */
+  intake: z16.object({ message: z16.string().min(1), budget_micro_usd: MicroUsdField.nonnegative().optional() }).optional()
 });
-var CredentialDeclSchema = z14.object({
+var CredentialDeclSchema = z16.object({
   kind: VaultCredentialKindSchema,
-  key: z14.string().min(1).max(128),
+  key: z16.string().min(1).max(128),
   /** The one exact destination host an `env_var` is bound to. */
-  host: z14.string().min(1).optional(),
+  host: z16.string().min(1).optional(),
   /** The MCP server URL a `static_bearer` / `mcp_oauth` token is matched to. */
-  mcp_server_url: z14.url().optional(),
-  value: z14.object({ from_env: z14.string().min(1) })
+  mcp_server_url: z16.url().optional(),
+  value: z16.object({ from_env: z16.string().min(1) })
 });
-var VaultDeclSchema = z14.object({
+var VaultDeclSchema = z16.object({
   name: VaultSchema.shape.display_name,
-  identity: z14.string().min(1).optional(),
-  credentials: z14.array(CredentialDeclSchema)
+  identity: z16.string().min(1).optional(),
+  credentials: z16.array(CredentialDeclSchema)
 });
-var SkillDeclSchema = z14.object({
-  slug: z14.string().regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase letters, digits and dashes"),
-  file: z14.string().min(1)
+var SkillDeclSchema = z16.object({
+  slug: z16.string().regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase letters, digits and dashes"),
+  file: z16.string().min(1)
 });
 var IdentityDeclSchema = IdentitySchema.pick({ name: true, description: true }).partial({
   description: true
 });
-var RemovedSchema = z14.object({
-  apps: z14.array(z14.string().min(1)).default([]),
-  agents: z14.array(z14.string().min(1)).default([]),
-  skills: z14.array(z14.string().min(1)).default([]),
-  identities: z14.array(z14.string().min(1)).default([]),
-  vaults: z14.array(z14.string().min(1)).default([])
+var RemovedSchema = z16.object({
+  apps: z16.array(z16.string().min(1)).default([]),
+  agents: z16.array(z16.string().min(1)).default([]),
+  skills: z16.array(z16.string().min(1)).default([]),
+  identities: z16.array(z16.string().min(1)).default([]),
+  vaults: z16.array(z16.string().min(1)).default([])
 });
-var KeptSchema = z14.object({ agents: z14.array(z14.string().min(1)).default([]) });
-var ProjectSchema = z14.object({
-  name: z14.string().min(1),
+var KeptSchema = z16.object({ agents: z16.array(z16.string().min(1)).default([]) });
+var ProjectSchema = z16.object({
+  name: z16.string().min(1),
   /** The machine this project runs: its repo, its screens, its `/api/*` (`template.ts`). */
-  blueprint: z14.string().min(1).optional(),
+  blueprint: z16.string().min(1).optional(),
   /** Which of that blueprint's templates provides the crew; a blueprint with a default may omit it. */
-  template: z14.string().min(1).optional(),
-  skills: z14.array(SkillDeclSchema).default([]),
-  identities: z14.array(IdentityDeclSchema).default([]),
-  vaults: z14.array(VaultDeclSchema).default([]),
-  apps: z14.array(AppDeclSchema).default([]),
-  agents: z14.array(AgentDeclSchema).default([]),
+  template: z16.string().min(1).optional(),
+  /**
+   * What a person is asked BEFORE the crew is provisioned (`canonical-spec §31.2`).
+   *
+   * `QuestionField` is reused rather than restated: a setup question and a question a parked agent
+   * asks mid-run are the same object asked at different times, so a blueprint author writes one
+   * shape and one component renders both. These are published on the artifact — they are the whole
+   * reason the catalog has a `questions` column — and the answers a person gives go on the install
+   * (§29.6), never into the tree, because the tree is identical for everyone.
+   *
+   * **Configuration only.** A secret is a vault credential or an app secret; neither is an answer.
+   */
+  questions: z16.array(QuestionFieldSchema).default([]),
+  skills: z16.array(SkillDeclSchema).default([]),
+  identities: z16.array(IdentityDeclSchema).default([]),
+  vaults: z16.array(VaultDeclSchema).default([]),
+  apps: z16.array(AppDeclSchema).default([]),
+  agents: z16.array(AgentDeclSchema).default([]),
   removed: RemovedSchema.default({ apps: [], agents: [], skills: [], identities: [], vaults: [] }),
   kept: KeptSchema.default({ agents: [] })
 });
@@ -1168,6 +1397,48 @@ async function loadConfig(dir) {
   return validate(path, raw);
 }
 
+// src/files.ts
+import { createHash } from "node:crypto";
+import { readFileSync as readFileSync2, readdirSync, statSync } from "node:fs";
+import { join as join2, relative, sep } from "node:path";
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist"]);
+var MAX_FILE_BYTES = 8 * 1024 * 1024;
+function collectFiles(source) {
+  if (typeof source !== "string") return fromMap(source);
+  const root = source;
+  const files = {};
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (SKIP_DIRS.has(entry.name) || entry.name.startsWith(".env")) continue;
+      const full = join2(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile() && statSync(full).size <= MAX_FILE_BYTES) {
+        files[relative(root, full).split(sep).join("/")] = readFileSync2(full).toString("base64");
+      }
+    }
+  };
+  walk(root);
+  return files;
+}
+function fromMap(map) {
+  const files = {};
+  for (const [path, base64] of Object.entries(map)) {
+    const segments = path.split("/");
+    if (segments.some((segment) => SKIP_DIRS.has(segment) || segment.startsWith(".env"))) continue;
+    if (Buffer.from(base64, "base64").length > MAX_FILE_BYTES) continue;
+    files[path] = base64;
+  }
+  return files;
+}
+function contentHash(files) {
+  const hash = createHash("sha256");
+  for (const [path, base64] of Object.entries(files).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+    const bytes = Buffer.from(base64, "base64");
+    hash.update(`${path}\0${bytes.length}\0`).update(bytes);
+  }
+  return hash.digest("hex");
+}
+
 // src/up.ts
 import { createHash as createHash3 } from "node:crypto";
 import { readFileSync as readFileSync3 } from "node:fs";
@@ -1175,7 +1446,7 @@ import { resolve as resolve3 } from "node:path";
 
 // src/report.ts
 import { ApiError, send } from "@usenaive-sdk/vetta";
-import { z as z15 } from "zod";
+import { z as z17 } from "zod";
 function message2(error) {
   return error instanceof Error ? error.message : String(error);
 }
@@ -1205,10 +1476,10 @@ async function absent(work) {
     throw error;
   }
 }
-var PageShape = z15.object({
-  data: z15.array(z15.unknown()),
-  has_more: z15.boolean(),
-  next_cursor: z15.string().nullable()
+var PageShape = z17.object({
+  data: z17.array(z17.unknown()),
+  has_more: z17.boolean(),
+  next_cursor: z17.string().nullable()
 });
 function rowLabel(row) {
   const { object, id } = row ?? {};
@@ -1241,7 +1512,7 @@ async function tombstone(name, current, remove, dryRun) {
 
 // src/agents.ts
 function desiredTools(decl, current, ids) {
-  if (decl.allowed_apps === void 0) return decl.tools;
+  if (ids === void 0) return decl.tools;
   const base = decl.tools ?? current?.tools ?? { default_config: { permission: "allow" }, configs: {} };
   const appsTool = base.configs["apps"] ?? { enabled: true, permission: base.default_config.permission };
   return {
@@ -1266,14 +1537,14 @@ async function createAgent(client, decl, tools, identityId) {
   if (identityId !== void 0) await client.identities.attach(created.id, identityId);
   return { name: decl.name, action: "created", id: created.id };
 }
-async function upsertAgent(client, decl, existing, ids, dryRun) {
+async function upsertAgent(client, decl, existing, ids, dryRun, scoped) {
   const unresolved = (decl.allowed_apps ?? []).filter((name) => !ids.apps.has(name));
   const identityId = decl.identity === void 0 ? void 0 : ids.identities.get(decl.identity);
   const missing = unresolved.length > 0 ? `allowed_apps needs app "${unresolved[0]}"` : decl.identity !== void 0 && identityId === void 0 ? `identity needs "${decl.identity}"` : null;
   if (missing !== null && !dryRun) {
     return { name: decl.name, action: "refused", reason: `${missing}, which was not provisioned in this run` };
   }
-  const appIds = (decl.allowed_apps ?? []).flatMap((name) => ids.apps.get(name) ?? []);
+  const appIds = decl.allowed_apps !== void 0 ? decl.allowed_apps.flatMap((name) => ids.apps.get(name) ?? []) : scoped;
   const current = existing.find((agent) => agent.name === decl.name) ?? null;
   const tools = desiredTools(decl, current, appIds);
   if (!current) return dryRun ? { name: decl.name, action: "created" } : createAgent(client, decl, tools, identityId);
@@ -1295,6 +1566,15 @@ async function upsertAgent(client, decl, existing, ids, dryRun) {
   }
   return { name: decl.name, action: "updated", id: current.id };
 }
+async function openIntake(client, agent, decl, dryRun) {
+  if (dryRun || agent.id === void 0) return { name: agent.name, action: "created" };
+  const started = await client.sessions.create({
+    agent_id: agent.id,
+    message: decl.message,
+    ...decl.budget_micro_usd !== void 0 ? { budget_micro_usd: decl.budget_micro_usd } : {}
+  });
+  return { name: agent.name, action: "created", id: started.id };
+}
 async function upsertSchedule(client, agent, decl, current, identityIds, dryRun) {
   const name = `${agent.name} @ ${decl.cron}`;
   if (agent.action === "refused") throw new Error(`agent "${agent.name}" was not provisioned in this run`);
@@ -1337,40 +1617,8 @@ async function reconcileSchedules(client, agent, declared, live, identityIds, dr
 }
 
 // src/apps.ts
-import { createHash as createHash2 } from "node:crypto";
+import { createHash as createHash2, randomBytes } from "node:crypto";
 import { resolve as resolve2 } from "node:path";
-
-// src/files.ts
-import { createHash } from "node:crypto";
-import { readFileSync as readFileSync2, readdirSync, statSync } from "node:fs";
-import { join as join2, relative, sep } from "node:path";
-var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist"]);
-var MAX_FILE_BYTES = 8 * 1024 * 1024;
-function collectFiles(root) {
-  const files = {};
-  const walk = (dir) => {
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      if (SKIP_DIRS.has(entry.name) || entry.name.startsWith(".env")) continue;
-      const full = join2(dir, entry.name);
-      if (entry.isDirectory()) walk(full);
-      else if (entry.isFile() && statSync(full).size <= MAX_FILE_BYTES) {
-        files[relative(root, full).split(sep).join("/")] = readFileSync2(full).toString("base64");
-      }
-    }
-  };
-  walk(root);
-  return files;
-}
-function contentHash(files) {
-  const hash = createHash("sha256");
-  for (const [path, base64] of Object.entries(files).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
-    const bytes = Buffer.from(base64, "base64");
-    hash.update(`${path}\0${bytes.length}\0`).update(bytes);
-  }
-  return hash.digest("hex");
-}
-
-// src/apps.ts
 async function findApp(client, name, skipped) {
   const rows = await listAll(client.config, "/v1/apps", AppSchema, skipped, { name });
   return rows.find((app) => app.name === name) ?? null;
@@ -1381,25 +1629,74 @@ function ownershipRefusal(name, project, owner) {
   return `app "${name}" is owned by ${held}; this project is "${project}". Rename the app in your config, or re-run \`naive up --adopt\` to ${verb} it.`;
 }
 var ensureApp = (client, body) => client.apps.create(body);
-function resolveEnv(decl) {
-  const env = {};
-  for (const [name, value] of Object.entries(decl.env ?? {})) {
+var PLATFORM_ENV = {
+  /** The base URL of the API this apply ran through. */
+  api_url: "NAIVE_API_URL",
+  /** The identity the install runs as, when the declaration declares exactly one. */
+  identity_id: "NAIVE_IDENTITY_ID",
+  /** A scoped organization API key minted for the app that asks for it. */
+  api_key: "NAIVE_API_KEY"
+};
+function planEnv(decl, opts) {
+  if (decl.env === void 0) return [];
+  const plan = /* @__PURE__ */ new Map();
+  for (const [name, value] of Object.entries(decl.env)) {
     if (typeof value === "string") {
-      env[name] = value;
+      plan.set(name, { name, value });
+      continue;
+    }
+    if ("generate" in value) {
+      plan.set(name, { name, invent: async () => generated() });
       continue;
     }
-    const local = process.env[value.from_env];
-    if (local === void 0) throw new Error(`env ${name} reads local variable ${value.from_env}, which is not set`);
-    env[name] = local;
+    const known = opts.platform?.known[value.from_env];
+    const mint = opts.platform?.minted?.[value.from_env];
+    if (known !== void 0) plan.set(name, { name, value: known });
+    else if (mint !== void 0) plan.set(name, { name, invent: () => mint(decl.name) });
+    else {
+      const local = opts.env[value.from_env];
+      if (local === void 0) throw new Error(`env ${name} reads local variable ${value.from_env}, which is not set`);
+      plan.set(name, { name, value: local });
+    }
+  }
+  for (const [name, value] of Object.entries(opts.platform?.known ?? {})) plan.set(name, { name, value });
+  return [...plan.values()];
+}
+async function materialize(plan, held, dryRun) {
+  const values = {};
+  const unmade = [];
+  for (const one of plan) {
+    if (one.value !== void 0) values[one.name] = one.value;
+    else if (held.has(one.name)) continue;
+    else if (dryRun) unmade.push(one.name);
+    else values[one.name] = await invent(one);
   }
-  return env;
+  return { values, unmade };
 }
+async function invent(one) {
+  try {
+    return await one.invent();
+  } catch (cause) {
+    throw new Error(
+      `env ${one.name} is provisioned by the platform, and could not be: ${cause instanceof Error ? cause.message : String(cause)}`
+    );
+  }
+}
+var generated = () => randomBytes(32).toString("base64url");
+var EMPTY = /* @__PURE__ */ new Set();
 function secretHash(name, value) {
   return createHash2("sha256").update(`${name}\0`).update(value).digest("hex");
 }
-function localTree(decl, dir) {
+function builtTree(decl, opts) {
   if (!decl.deploy_dir) return null;
-  const files = collectFiles(resolve2(dir, decl.deploy_dir));
+  const hosted = opts.trees;
+  if (hosted !== void 0 && hosted[decl.name] === void 0) {
+    const failed = opts.tree_errors?.[decl.name];
+    throw new Error(
+      `app "${decl.name}" declares deploy_dir "${decl.deploy_dir}", but this apply was handed no built tree for it` + (failed === void 0 ? "" : `: ${failed}`)
+    );
+  }
+  const files = collectFiles(hosted?.[decl.name] ?? resolve2(opts.dir, decl.deploy_dir));
   return { files, hash: contentHash(files) };
 }
 async function writeApp(client, id, env, tree) {
@@ -1419,7 +1716,7 @@ async function settleDeploy(client, id) {
     await new Promise((resolve4) => setTimeout(resolve4, SETTLE_MS));
   }
 }
-async function createApp(client, decl, env, opts, appIds) {
+async function createApp(client, decl, env, tree, opts, appIds) {
   const created = await ensureApp(client, {
     name: decl.name,
     type: decl.type,
@@ -1428,12 +1725,12 @@ async function createApp(client, decl, env, opts, appIds) {
     ...decl.mcp !== void 0 ? { mcp: decl.mcp } : {}
   });
   appIds.set(decl.name, created.id);
-  await writeApp(client, created.id, env, localTree(decl, opts.dir));
+  await writeApp(client, created.id, env, tree);
   return { name: decl.name, action: "created", id: created.id, url: (await client.apps.get(created.id)).url };
 }
 async function upsertApp(client, decl, opts, appIds) {
-  const env = resolveEnv(decl);
-  const names = Object.keys(env);
+  const declared = planEnv(decl, opts);
+  const names = declared.map((one) => one.name);
   const note = (notes) => notes.length > 0 ? { reason: notes.join("; ") } : {};
   const mcpPlan = decl.mcp !== void 0 ? [`will set mcp ${decl.mcp}`] : [];
   const current = await findApp(client, decl.name, opts.skipped);
@@ -1446,7 +1743,8 @@ async function upsertApp(client, decl, opts, appIds) {
         ...note([...willSet, ...mcpPlan, ...decl.deploy_dir ? [`will deploy ${decl.deploy_dir}`] : []])
       };
     }
-    return createApp(client, decl, env, opts, appIds);
+    const { values } = await materialize(declared, EMPTY, false);
+    return createApp(client, decl, values, builtTree(decl, opts), opts, appIds);
   }
   const owned = current.project === opts.project;
   if (!owned && !opts.adopt) {
@@ -1471,19 +1769,21 @@ async function upsertApp(client, decl, opts, appIds) {
   if (!owned && !opts.dryRun) {
     await ensureApp(client, { name: decl.name, type: decl.type, project: opts.project, adopt: true });
   }
-  const live = decl.env === void 0 ? [] : (await client.apps.secrets(current.id)).data;
-  const unmanaged = live.map((secret) => secret.name).filter((name) => !(name in env));
+  const live = declared.length === 0 ? [] : (await client.apps.secrets(current.id)).data;
+  const managed = new Set(names);
+  const unmanaged = live.map((secret) => secret.name).filter((name) => !managed.has(name));
   const held = new Map(live.map((secret) => [secret.name, secret.value_hash]));
+  const { values: env, unmade } = await materialize(declared, new Set(held.keys()), opts.dryRun);
   const staleEnv = Object.fromEntries(
     Object.entries(env).filter(([name, value]) => held.get(name) !== secretHash(name, value))
   );
-  const staleNames = Object.keys(staleEnv);
+  const staleNames = [...Object.keys(staleEnv), ...unmade];
   const patch = {
     ...decl.description !== void 0 && decl.description !== current.description ? { description: decl.description } : {},
     ...(decl.mcp ?? null) !== current.mcp ? { mcp: decl.mcp ?? null } : {}
   };
   const drifted = Object.keys(patch).length > 0;
-  const tree = localTree(decl, opts.dir);
+  const tree = builtTree(decl, opts);
   const newest = tree ? (await client.apps.deployments(current.id, { limit: 1 })).data[0] : void 0;
   const stale = tree !== null && newest?.content_hash !== tree.hash;
   const action = !owned || drifted || stale || staleNames.length > 0 ? "updated" : "unchanged";
@@ -1531,14 +1831,14 @@ async function upsertVault(client, decl, existing, identityIds, dryRun) {
   }
   return { name: decl.name, action: "unchanged", id: current.id };
 }
-async function upsertCredential(client, vault, decl, existing, dryRun) {
+async function upsertCredential(client, vault, decl, existing, dryRun, from) {
   const name = `${vault.name} / ${decl.key}`;
   if (vault.action === "refused") throw new Error(`vault "${vault.name}" was not provisioned in this run`);
   const current = existing.find(
     (row) => row.kind === decl.kind && row.key === decl.key && row.host === (decl.host ?? null) && row.mcp_server_url === (decl.mcp_server_url ?? null)
   );
   if (current) return { name, action: "unchanged", id: current.id };
-  const value = process.env[decl.value.from_env];
+  const value = from[decl.value.from_env];
   if (value === void 0) throw new Error(`credential ${decl.key} reads local variable ${decl.value.from_env}, which is not set`);
   if (dryRun || vault.id === void 0) return { name, action: "created" };
   const created = await client.vaults.credentials.create(vault.id, {
@@ -1552,7 +1852,17 @@ async function upsertCredential(client, vault, decl, existing, dryRun) {
 }
 
 // src/up.ts
+function identityEnv(config, ids) {
+  if (config.identities.length !== 1) return {};
+  const id = ids.get(config.identities[0].name);
+  return id === void 0 ? {} : { [PLATFORM_ENV.identity_id]: id };
+}
 async function upsertSkill(client, decl, opts) {
+  if (opts.hosted) {
+    throw new Error(
+      `skill "${decl.slug}" is declared as the file "${decl.file}", and a hosted apply has no checkout to read it from. Push it with \`naive up\` from a clone, or publish it as part of the blueprint.`
+    );
+  }
   const content = readFileSync3(resolve3(opts.dir, decl.file), "utf8");
   const sha256 = createHash3("sha256").update(content).digest("hex");
   const current = await absent(client.skills.get(decl.slug));
@@ -1629,10 +1939,11 @@ async function up(config, client, opts = {}) {
   const dryRun = opts.dry_run ?? false;
   const dir = opts.dir ?? process.cwd();
   const ids = { apps: /* @__PURE__ */ new Map(), identities: /* @__PURE__ */ new Map() };
-  const report = { dry_run: dryRun, ...applied(config), skills: [], identities: [], vaults: [], apps: [], agents: [], schedules: [], skipped: [] };
+  const report = { dry_run: dryRun, ...applied(config), skills: [], identities: [], vaults: [], apps: [], agents: [], schedules: [], intake: [], skipped: [] };
   const owner = { project: config.name, adopt: opts.adopt ?? false, skipped: report.skipped };
+  const hosted = opts.trees !== void 0;
   for (const decl of config.skills) {
-    await attempt(report.skills, decl.slug, () => upsertSkill(client, decl, { dryRun, dir }));
+    await attempt(report.skills, decl.slug, () => upsertSkill(client, decl, { dryRun, dir, hosted }));
   }
   for (const decl of config.identities) {
     await attempt(report.identities, decl.name, () => upsertIdentity(client, decl, dryRun, ids.identities));
@@ -1643,29 +1954,59 @@ async function up(config, client, opts = {}) {
     const vaultId = line.action === "unchanged" ? line.id : void 0;
     const rows = vaultId === void 0 ? [] : await listAll(client.config, `/v1/vaults/${vaultId}/credentials`, VaultCredentialSchema, report.skipped);
     for (const cred of decl.credentials) {
-      await attempt(report.vaults, `${decl.name} / ${cred.key}`, () => upsertCredential(client, line, cred, rows, dryRun));
+      await attempt(
+        report.vaults,
+        `${decl.name} / ${cred.key}`,
+        () => upsertCredential(client, line, cred, rows, dryRun, opts.env ?? process.env)
+      );
     }
   }
+  const platform = opts.platform && {
+    ...opts.platform,
+    known: { ...opts.platform.known, ...identityEnv(config, ids.identities) }
+  };
   for (const decl of config.apps) {
-    await attempt(report.apps, decl.name, () => upsertApp(client, decl, { ...owner, dryRun, dir }, ids.apps));
+    await attempt(
+      report.apps,
+      decl.name,
+      () => upsertApp(
+        client,
+        decl,
+        { ...owner, dryRun, dir, trees: opts.trees, tree_errors: opts.tree_errors, env: opts.env ?? process.env, platform },
+        ids.apps
+      )
+    );
   }
   const existing = config.agents.length > 0 || config.removed.agents.length > 0 || config.kept.agents.length > 0 ? await listAll(client.config, "/v1/agents", AgentSchema, report.skipped) : [];
   const deployments = config.agents.some((decl) => decl.schedules !== void 0) ? await listAll(client.config, "/v1/deployments", DeploymentSchema, report.skipped) : [];
+  const scoped = config.apps.length > 0 ? [...ids.apps.values()] : void 0;
+  const briefed = [];
   for (const decl of config.agents) {
-    const line = await attempt(report.agents, decl.name, () => upsertAgent(client, decl, existing, ids, dryRun));
+    const line = await attempt(
+      report.agents,
+      decl.name,
+      () => upsertAgent(client, decl, existing, ids, dryRun, scoped)
+    );
     if (decl.schedules !== void 0) {
       await reconcileSchedules(client, line, decl.schedules, deployments, ids.identities, dryRun, report.schedules);
     }
+    if (decl.intake !== void 0 && line.action === "created") briefed.push([line, decl.intake]);
   }
   reportKept(config, existing, report.agents);
   await applyRemoved(client, config.removed, { agents: existing, vaults }, owner, report);
+  for (const [line, decl] of briefed) {
+    await attempt(report.intake, line.name, () => openIntake(client, line, decl, dryRun));
+  }
   return report;
 }
 export {
   BLUEPRINTS,
   BlueprintRefusal,
   CONFIG_CANDIDATES,
+  PLATFORM_ENV,
   chooseTemplate,
+  collectFiles,
+  contentHash,
   defineProject,
   loadConfig,
   parseProject,