@usenaive-sdk/blueprints 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -44,7 +44,8 @@ interface Template {
  * Every blueprint and the templates it carries. `agency` defaults to `blank` — a working agency
  * with no specialism is a safe thing to get by accident. `media` has NO default on purpose: its
  * two crews spend money in different ways, so defaulting one of them is a bill the operator did
- * not choose.
+ * not choose. `web` carries one crew today, so `publisher` is its default for the reason `blank` is
+ * `agency`'s: the only thing you can get is the thing you meant.
  */
 declare const BLUEPRINTS: Record<string, {
     templates: readonly string[];
@@ -80,7 +81,15 @@ declare const AppDeclSchema: z.ZodObject<{
     mcp: z.ZodOptional<z.ZodString>;
     env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
         from_env: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        generate: z.ZodLiteral<true>;
     }, z.core.$strip>]>>>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    migrations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    buckets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        public: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 /**
  * A cron on the agent — a platform deployment (§12) minus what `up` fills in: `agent_id`, and the
@@ -111,6 +120,8 @@ declare const AgentDeclSchema: z.ZodObject<{
         }>;
     }, z.core.$strip>;
     description: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodString>;
+    required: z.ZodOptional<z.ZodBoolean>;
     system: z.ZodOptional<z.ZodString>;
     tools: z.ZodOptional<z.ZodObject<{
         default_config: z.ZodObject<{
@@ -136,6 +147,31 @@ declare const AgentDeclSchema: z.ZodObject<{
         url: z.ZodURL;
         headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     }, z.core.$strip>>>;
+    window: z.ZodOptional<z.ZodEnum<{
+        immediate: "immediate";
+        priority: "priority";
+        loose: "loose";
+    }>>;
+    multiagent: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        agents: z.ZodArray<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<{
+            type: "agent";
+            name: string;
+        }, string>>, z.ZodObject<{
+            type: z.ZodLiteral<"agent">;
+            name: z.ZodString;
+            version: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"self">;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"advisor">;
+            model: z.ZodString;
+        }, z.core.$strip>]>>;
+        type: z.ZodLiteral<"coordinator">;
+        board: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodNull]>>;
+    output_schema: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    structured_output_required: z.ZodOptional<z.ZodBoolean>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     allowed_apps: z.ZodOptional<z.ZodArray<z.ZodString>>;
     identity: z.ZodOptional<z.ZodString>;
     schedules: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -196,6 +232,90 @@ declare const SkillDeclSchema: z.ZodObject<{
 declare const IdentityDeclSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     name: z.ZodString;
+    legal: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        state: z.ZodEnum<{
+            AL: "AL";
+            AK: "AK";
+            AZ: "AZ";
+            AR: "AR";
+            CA: "CA";
+            CO: "CO";
+            CT: "CT";
+            DE: "DE";
+            DC: "DC";
+            FL: "FL";
+            GA: "GA";
+            HI: "HI";
+            ID: "ID";
+            IL: "IL";
+            IN: "IN";
+            IA: "IA";
+            KS: "KS";
+            KY: "KY";
+            LA: "LA";
+            ME: "ME";
+            MD: "MD";
+            MA: "MA";
+            MI: "MI";
+            MN: "MN";
+            MS: "MS";
+            MO: "MO";
+            MT: "MT";
+            NE: "NE";
+            NV: "NV";
+            NH: "NH";
+            NJ: "NJ";
+            NM: "NM";
+            NY: "NY";
+            NC: "NC";
+            ND: "ND";
+            OH: "OH";
+            OK: "OK";
+            OR: "OR";
+            PA: "PA";
+            RI: "RI";
+            SC: "SC";
+            SD: "SD";
+            TN: "TN";
+            TX: "TX";
+            UT: "UT";
+            VT: "VT";
+            VA: "VA";
+            WA: "WA";
+            WV: "WV";
+            WI: "WI";
+            WY: "WY";
+        }>;
+        name_options: z.ZodArray<z.ZodString>;
+        naics_code: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>>;
+    wallet: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+        network: z.ZodOptional<z.ZodEnum<{
+            "eip155:84532": "eip155:84532";
+            "eip155:8453": "eip155:8453";
+        }>>;
+        policy: z.ZodOptional<z.ZodObject<{
+            per_tx_cap_micro_usd: z.ZodOptional<z.ZodNumber>;
+            daily_cap_micro_usd: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            low_balance_micro_usd: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+        network: z.ZodOptional<z.ZodEnum<{
+            "eip155:84532": "eip155:84532";
+            "eip155:8453": "eip155:8453";
+        }>>;
+        policy: z.ZodOptional<z.ZodObject<{
+            per_tx_cap_micro_usd: z.ZodOptional<z.ZodNumber>;
+            daily_cap_micro_usd: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            low_balance_micro_usd: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>]>>;
+    cards: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        load_micro_usd: z.ZodNumber;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 declare const ProjectSchema: z.ZodObject<{
     name: z.ZodString;
@@ -223,6 +343,90 @@ declare const ProjectSchema: z.ZodObject<{
     identities: z.ZodDefault<z.ZodArray<z.ZodObject<{
         description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         name: z.ZodString;
+        legal: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            description: z.ZodString;
+            state: z.ZodEnum<{
+                AL: "AL";
+                AK: "AK";
+                AZ: "AZ";
+                AR: "AR";
+                CA: "CA";
+                CO: "CO";
+                CT: "CT";
+                DE: "DE";
+                DC: "DC";
+                FL: "FL";
+                GA: "GA";
+                HI: "HI";
+                ID: "ID";
+                IL: "IL";
+                IN: "IN";
+                IA: "IA";
+                KS: "KS";
+                KY: "KY";
+                LA: "LA";
+                ME: "ME";
+                MD: "MD";
+                MA: "MA";
+                MI: "MI";
+                MN: "MN";
+                MS: "MS";
+                MO: "MO";
+                MT: "MT";
+                NE: "NE";
+                NV: "NV";
+                NH: "NH";
+                NJ: "NJ";
+                NM: "NM";
+                NY: "NY";
+                NC: "NC";
+                ND: "ND";
+                OH: "OH";
+                OK: "OK";
+                OR: "OR";
+                PA: "PA";
+                RI: "RI";
+                SC: "SC";
+                SD: "SD";
+                TN: "TN";
+                TX: "TX";
+                UT: "UT";
+                VT: "VT";
+                VA: "VA";
+                WA: "WA";
+                WV: "WV";
+                WI: "WI";
+                WY: "WY";
+            }>;
+            name_options: z.ZodArray<z.ZodString>;
+            naics_code: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>>>;
+        wallet: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+            network: z.ZodOptional<z.ZodEnum<{
+                "eip155:84532": "eip155:84532";
+                "eip155:8453": "eip155:8453";
+            }>>;
+            policy: z.ZodOptional<z.ZodObject<{
+                per_tx_cap_micro_usd: z.ZodOptional<z.ZodNumber>;
+                daily_cap_micro_usd: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+                low_balance_micro_usd: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+            network: z.ZodOptional<z.ZodEnum<{
+                "eip155:84532": "eip155:84532";
+                "eip155:8453": "eip155:8453";
+            }>>;
+            policy: z.ZodOptional<z.ZodObject<{
+                per_tx_cap_micro_usd: z.ZodOptional<z.ZodNumber>;
+                daily_cap_micro_usd: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+                low_balance_micro_usd: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>]>>;
+        cards: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            load_micro_usd: z.ZodNumber;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>>;
     vaults: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -252,7 +456,15 @@ declare const ProjectSchema: z.ZodObject<{
         mcp: z.ZodOptional<z.ZodString>;
         env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
             from_env: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            generate: z.ZodLiteral<true>;
         }, z.core.$strip>]>>>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        migrations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        buckets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            public: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>>;
     agents: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -267,6 +479,8 @@ declare const ProjectSchema: z.ZodObject<{
             }>;
         }, z.core.$strip>;
         description: z.ZodOptional<z.ZodString>;
+        role: z.ZodOptional<z.ZodString>;
+        required: z.ZodOptional<z.ZodBoolean>;
         system: z.ZodOptional<z.ZodString>;
         tools: z.ZodOptional<z.ZodObject<{
             default_config: z.ZodObject<{
@@ -292,6 +506,31 @@ declare const ProjectSchema: z.ZodObject<{
             url: z.ZodURL;
             headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         }, z.core.$strip>>>;
+        window: z.ZodOptional<z.ZodEnum<{
+            immediate: "immediate";
+            priority: "priority";
+            loose: "loose";
+        }>>;
+        multiagent: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            agents: z.ZodArray<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<{
+                type: "agent";
+                name: string;
+            }, string>>, z.ZodObject<{
+                type: z.ZodLiteral<"agent">;
+                name: z.ZodString;
+                version: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"self">;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"advisor">;
+                model: z.ZodString;
+            }, z.core.$strip>]>>;
+            type: z.ZodLiteral<"coordinator">;
+            board: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodNull]>>;
+        output_schema: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        structured_output_required: z.ZodOptional<z.ZodBoolean>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         allowed_apps: z.ZodOptional<z.ZodArray<z.ZodString>>;
         identity: z.ZodOptional<z.ZodString>;
         schedules: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -307,6 +546,11 @@ declare const ProjectSchema: z.ZodObject<{
             budget_micro_usd: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
     }, z.core.$strip>>>;
+    crew_per_client: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        role: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
     removed: z.ZodDefault<z.ZodObject<{
         apps: z.ZodDefault<z.ZodArray<z.ZodString>>;
         agents: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -320,6 +564,7 @@ declare const ProjectSchema: z.ZodObject<{
 }, z.core.$strip>;
 type AppDecl = z.infer<typeof AppDeclSchema>;
 type AgentDecl = z.infer<typeof AgentDeclSchema>;
+type CrewPerClientDecl = NonNullable<ProjectConfig["crew_per_client"]>[number];
 type ScheduleDecl = z.infer<typeof ScheduleDeclSchema>;
 type SkillDecl = z.infer<typeof SkillDeclSchema>;
 type IdentityDecl = z.infer<typeof IdentityDeclSchema>;
@@ -340,6 +585,101 @@ interface DefineInput extends z.input<typeof ProjectSchema> {
 /** The one export a `naive.config.ts` calls. Identity plus validation; the object comes back frozen. */
 declare function defineProject({ templates, ...input }: DefineInput): Readonly<ProjectConfig>;
 
+/**
+ * The blueprint install (`canonical-spec §29.6`) — one applied declaration per
+ * (organization, project), and the drift a `revision_conflict` names.
+ *
+ * `naive up` needed no server-side state while the only writer was a person with a clone: its
+ * working tree was the manifest. The studio applying the same declaration makes two writers on one
+ * organization, and neither can see the other. This row is what they share.
+ *
+ * It is not a second source of truth for what is provisioned — apps, agents, skills, identities and
+ * vaults stay keyed by name on their own routes. It records *that* an apply happened, with what, by
+ * whom, and against which revision.
+ */
+
+/**
+ * What one apply did to one resource. This is the vocabulary `naive up` has printed since it
+ * existed; it is written HERE, and imported by `@usenaive-sdk/blueprints`, for the reason
+ * `CLAUDE.md §2` gives: the hosted apply publishes the engine's report on the install (below), so
+ * it is a wire shape, and a wire shape has exactly one definition. The engine re-exports these two
+ * names unchanged, so nothing downstream of it learns a second word for the same thing.
+ */
+declare const ResourceActionSchema: z.ZodEnum<{
+    created: "created";
+    updated: "updated";
+    unchanged: "unchanged";
+    deleted: "deleted";
+    refused: "refused";
+}>;
+type ResourceAction = z.infer<typeof ResourceActionSchema>;
+/** One line of an apply: what was named, what happened to it, and — for a refusal — why. */
+declare const ResourceReportSchema: z.ZodObject<{
+    name: z.ZodString;
+    action: z.ZodEnum<{
+        created: "created";
+        updated: "updated";
+        unchanged: "unchanged";
+        deleted: "deleted";
+        refused: "refused";
+    }>;
+    id: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ResourceReportLine = z.infer<typeof ResourceReportSchema>;
+/**
+ * Which of the declared crew an apply takes (§31.2), by declared name. Omitting it from the apply
+ * body means everything; a selection missing a `required` agent or app is `validation_failed`.
+ */
+declare const BlueprintSelectionSchema: z.ZodObject<{
+    agents: z.ZodArray<z.ZodString>;
+    apps: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type BlueprintSelection = z.infer<typeof BlueprintSelectionSchema>;
+
+/**
+ * The report vocabulary `up` speaks (`workstreams/10-blueprints.md §2` item 4) and the handful of
+ * client-side moves every resource kind shares: one line per attempt with refusals caught into
+ * the report, drift as "a declared field whose live value differs", 404 as "not yet", full
+ * cursor pagination, and the by-name tombstone behind `removed`.
+ */
+
+type ResourceReport = ResourceReportLine;
+
+/**
+ * A coordinator's roster, declared by NAME (`canonical-spec §31.6`, §28).
+ *
+ * At runtime a roster entry is `{type:"agent", id:"agt_…", version?}`; in a declaration no agent has
+ * an id yet, so the entry carries the declared `name` where the id goes and is otherwise the
+ * runtime's own `RosterEntrySchema` — `self` and `advisor` unchanged. `up()` resolves the names in
+ * a second pass, once every agent of the declaration has been created or patched and so has an id.
+ */
+
+/** `MultiagentField` with the roster by name: `true | false | null | {type:"coordinator", agents, board?}`. */
+declare const DeclMultiagentField: z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+    agents: z.ZodArray<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<{
+        type: "agent";
+        name: string;
+    }, string>>, z.ZodObject<{
+        type: z.ZodLiteral<"agent">;
+        name: z.ZodString;
+        version: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"self">;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"advisor">;
+        model: z.ZodString;
+    }, z.core.$strip>]>>;
+    type: z.ZodLiteral<"coordinator">;
+    board: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodNull]>;
+type DeclMultiagent = z.infer<typeof DeclMultiagentField>;
+type DeclRoster = Extract<DeclMultiagent, {
+    type: "coordinator";
+}>;
+declare const hasRoster: (value: DeclMultiagent | undefined) => value is DeclRoster;
+
 declare const CONFIG_CANDIDATES: readonly ["naive.config.ts", "naive.config.js", "naive.config.mjs", "naive.config.json"];
 type ConfigLoad = {
     ok: true;
@@ -392,20 +732,80 @@ declare function collectFiles(source: FileSource): Record<string, string>;
 declare function contentHash(files: Record<string, string>): string;
 
 /**
- * The report vocabulary `up` speaks (`workstreams/10-blueprints.md §2` item 4) and the handful of
- * client-side moves every resource kind shares: one line per attempt with refusals caught into
- * the report, drift as "a declared field whose live value differs", 404 as "not yet", full
- * cursor pagination, and the by-name tombstone behind `removed`.
+ * core-gaps: U8-database — `apps[].migrations` in `naive up` (`canonical-spec §37`). Each entry is a
+ * path under the config's directory, with `*` allowed in the file name (`sql/*.sql`); files match
+ * in name order within one entry and entries in declaration order, so `0001_…`, `0002_…` is the
+ * whole ordering story. A file's migration name is its base name without the extension, and
+ * `POST /v1/apps/{id}/db/migrations` applies each once: a replay is a no-op, changed SQL under a
+ * kept name is `409 version_conflict`, which the report carries by name.
+ *
+ * A hosted apply has no checkout: the publisher read the files and shipped them on the app's built
+ * tree (`canonical-spec §31.1`), so they arrive as `opts.migrations` by app name.
  */
 
-type ResourceAction = "created" | "updated" | "unchanged" | "deleted" | "refused";
-interface ResourceReport {
+interface MigrationFile {
     name: string;
-    action: ResourceAction;
-    id?: string;
-    url?: string | null;
-    /** Why, for `refused`; what would happen, for a dry-run line that needs explaining. */
-    reason?: string;
+    sql: string;
+}
+/** The files each pattern names, in order, each read once; a pattern that names nothing refuses. */
+declare function migrationFiles(patterns: readonly string[], dir: string): MigrationFile[];
+
+/**
+ * Apps in `naive up`: upsert by `GET /v1/apps?name=` (§29.2), `env` written as write-only secrets
+ * only when the live `value_hash` differs from the local one (ADR-0354, ADR-0357), and the
+ * `deploy_dir` shipped only when its content hash differs from the newest live deployment's
+ * (ADR-0357). Live secret names the config does not declare are reported, never deleted
+ * (ADR-0352). `mcp` is patched on drift, absent meaning `null` (§29.5); the platform mints the
+ * app's `VETTA_MCP_TOKEN` itself, so nothing here ever holds that token.
+ *
+ * A hosted apply also arrives with a PLATFORM ENVIRONMENT (`PlatformEnv`, §29.7) — the base URL, the
+ * identity the install runs as, and a scoped key it will mint for an app that asks. That layer is
+ * read before `{ from_env }`'s own environment, and a declaration may ask for a value nobody has
+ * with `{ generate: true }`. Both are provisioned ONCE per app, because a value the platform invents
+ * has no stable digest and rewriting it every apply would rotate a live credential.
+ *
+ * An app also records the project that made it (ADR-0375), and that stamp is compared before any
+ * write: a name this project does not own is refused rather than adopted, which is what standing
+ * up a second blueprint did to the first one's live deployment.
+ */
+
+/** The platform environment's variable names (`canonical-spec §29.7`) — fixed, never inferred. */
+declare const PLATFORM_ENV: {
+    /** The base URL of the API this apply ran through. */
+    readonly api_url: "NAIVE_API_URL";
+    /** The identity the install runs as, when the declaration declares exactly one. */
+    readonly identity_id: "NAIVE_IDENTITY_ID";
+    /** The install's `project` — the row the app's own context lookup lands on (§31.8). */
+    readonly project: "NAIVE_PROJECT";
+    /** A scoped organization API key minted for the app that asks for it. */
+    readonly api_key: "NAIVE_API_KEY";
+};
+/**
+ * WHAT THE PLATFORM PROVIDES A HOSTED APPLY, AND THE ONE DISTINCTION THAT MATTERS
+ * (`canonical-spec §29.7`).
+ *
+ * Absent on a laptop apply, which reads the author's shell and nothing else — the hosted path gains
+ * a layer, the local path does not lose one.
+ *
+ * **What the platform KNOWS it always tells the app; what the platform must INVENT it invents only
+ * on request, and only once.** That is not a stylistic split. A known value has a stable digest, so
+ * the `value_hash` compare that makes `naive up` idempotent (§29.2) can say `unchanged` about it and
+ * re-asserting it every apply costs nothing. An invented one never matches its own previous digest,
+ * so re-inventing it every apply would rotate a live credential under a build that still holds the
+ * old one — and, for a minted key, leave one dead `api_key` row behind per apply.
+ */
+interface PlatformEnv {
+    /**
+     * Values the platform knows. Written to every app this apply deploys that declares an `env` —
+     * whether or not the declaration names them, which is the `VETTA_MCP_TOKEN` precedent (§29.2) —
+     * and read FIRST by a `{ from_env }` that does name them.
+     */
+    known: Record<string, string>;
+    /**
+     * Values the platform must invent, by variable name, given the app that asked. Called at most
+     * once per app, and only when that app holds no secret of that name.
+     */
+    minted?: Record<string, (app: string) => Promise<string>>;
 }
 
 /**
@@ -449,6 +849,12 @@ interface UpReport {
      * used to abort the whole apply before any write; it is now a line here and nothing else.
      */
     skipped: string[];
+    /**
+     * Declared agents and apps the operator's `select` left out (`canonical-spec §31.2`): not created,
+     * not armed, not briefed, and — when one already exists — left exactly as it is. A choice, kept
+     * apart from `skipped` (rows this client could not read) and from a `refused` line (an attempt).
+     */
+    deselected: string[];
 }
 interface UpOptions {
     /** Plan only: reads happen, writes do not, and the report says what apply would do. */
@@ -460,8 +866,108 @@ interface UpOptions {
      * (ADR-0375). Off by default — adopting by default is what overwrote a live deployment.
      */
     adopt?: boolean;
+    /**
+     * The built trees, by app name, for an apply that runs where there is no checkout: the platform
+     * applying a published artifact on an operator's behalf (`canonical-spec §31.1`). The bytes come
+     * out of the artifact's object-store entry, in the same file map `deploy_dir` would have been
+     * collected into — which is why `collectFiles` takes both and there is one digest (`files.ts`).
+     *
+     * Present ⇒ the disk is never read for an app, and an app whose tree is not in the map is refused
+     * by name rather than deployed empty. Absent ⇒ `dir` + `deploy_dir`, exactly as before.
+     */
+    trees?: Record<string, Record<string, string>>;
+    /**
+     * Why a declared app is absent from `trees`, by app name — an object-store read that failed
+     * rather than an object that was never uploaded. Both come out of `builtTree` as one refusal;
+     * only the caller that did the reading can tell them apart, so only it can say (`apps.ts`).
+     */
+    tree_errors?: Record<string, string>;
+    /**
+     * core-gaps: U8-database — each app's `migrations`, by app name, as the publisher shipped them on
+     * its built tree (`canonical-spec §31.1`); read only when `trees` is present. An app that declares
+     * migrations and is absent here is refused by name (`migrations.ts`).
+     */
+    migrations?: Record<string, MigrationFile[]>;
+    /**
+     * A skill's bytes by slug, for a hosted apply of a published declaration that carries them
+     * inline (`canonical-spec §42.8`). A hosted skill absent from this map is still refused by name.
+     */
+    skills?: Record<string, string>;
+    /**
+     * What an app's `{ from_env }` reads (`apps.ts`). The process's own environment by default —
+     * the author's shell, which is the whole point of `from_env` on a laptop. A hosted apply has no
+     * shell and passes the operator's **answers** instead (`canonical-spec §31.2`): the same
+     * declaration, resolved against the only environment that apply has.
+     */
+    env?: Record<string, string | undefined>;
+    /**
+     * THE PLATFORM ENVIRONMENT (`canonical-spec §29.7`) — what the platform itself provides an app,
+     * read BEFORE `env` and written whether or not the declaration names it.
+     *
+     * Present only on a hosted apply, and that is the whole of the local/hosted difference: `naive up`
+     * from a checkout passes none, reads the author's shell, and behaves exactly as it always has.
+     *
+     * `NAIVE_IDENTITY_ID` is filled in here rather than by the caller, because the id does not exist
+     * until this run has created the identity — identities are upserted before apps for the same
+     * reason agents reference them by name.
+     */
+    platform?: PlatformEnv;
+    /**
+     * Which of the declared crew to provision, by name (§31.2). Omitted means everything, which is what
+     * every apply before this option did. A name the declaration lacks, or a `required` one left out,
+     * is a `BlueprintRefusal` before anything is read — the one thrown escape `up` has, because it is
+     * the caller's input that is wrong and not a resource that could not be made.
+     */
+    select?: BlueprintSelection;
+    /**
+     * The install this crew belongs to — what a template agent's `metadata.project` names (§31.8).
+     * Defaults to `config.name`, which is the install `naive up` files under. A hosted apply files
+     * under the customer's own `project` and passes it here, so the runtime's lookup of the latest
+     * applied install lands on the row that exists.
+     */
+    project?: string;
+    /**
+     * What dials an app's own address before its crew is briefed (`awaitServing`). The platform's
+     * `fetch` by default; a test hands in a fake. It is NOT the client's `fetch`, which on a hosted
+     * apply loops back into the API and never leaves the isolate.
+     */
+    probe?: typeof globalThis.fetch;
 }
+/** The crew this apply takes (`UpOptions.select`), and the names it leaves out. */
+declare function selectCrew(config: Readonly<ProjectConfig>, select: BlueprintSelection | undefined): {
+    apps: readonly AppDecl[];
+    agents: readonly AgentDecl[];
+    deselected: string[];
+};
 /** Plan → apply → report. Every refusal is one line in the report, never a thrown escape. */
 declare function up(config: Readonly<ProjectConfig>, client: VettaClient, opts?: UpOptions): Promise<UpReport>;
 
-export { type AgentDecl, type AppDecl, BLUEPRINTS, BlueprintRefusal, CONFIG_CANDIDATES, type ConfigLoad, type CredentialDecl, type DefineInput, type FileSource, type IdentityDecl, type ProjectConfig, type ResourceAction, type ResourceReport, type ScheduleDecl, type SkillDecl, type Template, type TemplateChoice, type TemplateKind, type UpOptions, type UpReport, type VaultDecl, chooseTemplate, collectFiles, contentHash, defineProject, loadConfig, parseProject, up };
+/**
+ * Agents in `naive up`: upsert by name with a drift-only PATCH, `allowed_apps` names resolved to
+ * app ids in the `apps` tool config (§29.3), the platform config passthrough (`system`, `skills`,
+ * `mcp_servers`) verbatim, and `identity` attached after the upsert, never revoked (ADR-0353).
+ *
+ * An agent's `schedules` are the one bounded exception to "nothing is deleted by omission"
+ * (ADR-0355): deployments have no name, so the declared list is owned as a **complete set** keyed
+ * by exact `cron`. Matched rows are patched where other fields drifted, missing crons are created,
+ * and the agent's rows whose cron is not declared are deleted. The prune reaches only deployments
+ * of agents this blueprint declares with `schedules`; an agent without the key keeps whatever it has.
+ *
+ * **The match is the cron STRING, not the schedule it denotes.** `"0 8 * * 1"` and `"0 08 * * 1"`
+ * fire at the same minute and are two different keys: re-spelling a declared cron is read as the
+ * declared one being absent and an undeclared one being live, so it is a DELETE plus a CREATE, not
+ * a PATCH. The new row is a new `dep_` id with a fresh `next_run_at`, and whatever the old row's
+ * `enabled: false` was holding back is gone. Nothing here parses cron — a client that normalised
+ * the string would have to agree with the server's parser forever to stay idempotent, and the day
+ * they disagreed every apply would churn every schedule. Edit a cron and expect a new deployment.
+ */
+
+/**
+ * What every template agent's `system` opens with (§31.8): the one paragraph that turns the setup
+ * answers into something the crew acts on. The `project_context` tool it names is offered only to
+ * an agent whose metadata names a project with an applied install — exactly the agents this is
+ * prepended for.
+ */
+declare const PROJECT_CONTEXT_PREAMBLE: string;
+
+export { type AgentDecl, type AppDecl, BLUEPRINTS, BlueprintRefusal, CONFIG_CANDIDATES, type ConfigLoad, type CredentialDecl, type CrewPerClientDecl, type DefineInput, type FileSource, type IdentityDecl, type MigrationFile, PLATFORM_ENV, PROJECT_CONTEXT_PREAMBLE, type PlatformEnv, type ProjectConfig, type ResourceAction, type ResourceReport, type ScheduleDecl, type SkillDecl, type Template, type TemplateChoice, type TemplateKind, type UpOptions, type UpReport, type VaultDecl, chooseTemplate, collectFiles, contentHash, defineProject, hasRoster, loadConfig, migrationFiles, parseProject, selectCrew, up };