@stackbone/cli 0.3.1 → 0.3.3

package/main.js

@@ -11,13 +11,13 @@ import pino from "pino";
 import pretty from "pino-pretty";
 import { exec, execFile, spawn, spawnSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { DeleteObjectCommand, GetObjectCommand, ListObjectsV2Command, PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
 import sodium from "libsodium-wrappers";
 import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { drizzle } from "drizzle-orm/postgres-js";
 import postgres from "postgres";
 import { extractText } from "unpdf";
 import OpenAI from "openai";
-import { DeleteObjectCommand, GetObjectCommand, ListObjectsV2Command, PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
 import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
 import { format, promisify } from "node:util";
 import { createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
@@ -153,7 +153,7 @@ var init_installations = __esmMin((() => {
 		organizationSlug: organizationSlugSchema,
 		agentSlug: z.string().min(1).max(80)
 	});
-})), agentTemplateStatusSchema, agentTemplateResponseSchema, agentInstallationResponseSchema, DEFAULT_RAG_EMBEDDING_MODEL, agentManifestRagSchema, agentManifestProtocolSchema, runtimeSchema, agentManifestConnectionsSchema, recipeTriggerRefSchema, recipeActionRefSchema, agentManifestRecipeSchema, agentManifestAutomationsSchema, DEFAULT_AGENT_SCHEMA_PATH, DEFAULT_AGENT_MIGRATIONS_PATH, BUNDLE_MIGRATIONS_PATH, WORKSPACE_MANIFEST_PATH, WORKFLOW_WELL_KNOWN_DIR, WORKFLOW_STEP_FILE, WORKFLOW_VM_FILE, WORKFLOW_MANIFEST_FILE, WORKFLOW_ARTIFACTS, WORKFLOW_SCHEMAS_FILE, MANIFEST_ENTRY_KINDS, MANIFEST_ENTRY_MODES, MIN_IMAGE_VERSION_FOR_MANIFEST_V2, workflowStartSurface, workflowChatSurface, DEEP_AGENT_CHAT_SURFACE, agentManifestSchema;
+})), agentTemplateStatusSchema, agentTemplateResponseSchema, agentInstallationResponseSchema, DEFAULT_RAG_EMBEDDING_MODEL, agentManifestRagSchema, agentManifestProtocolSchema, runtimeSchema, agentManifestConnectionsSchema, recipeTriggerRefSchema, recipeActionRefSchema, agentManifestRecipeSchema, agentManifestAutomationsSchema, DEFAULT_AGENT_SCHEMA_PATH, DEFAULT_AGENT_MIGRATIONS_PATH, BUNDLE_MIGRATIONS_PATH, WORKSPACE_MANIFEST_PATH, CONFIG_SCHEMA_ARTIFACT_PATH, WORKFLOW_WELL_KNOWN_DIR, WORKFLOW_STEP_FILE, WORKFLOW_VM_FILE, WORKFLOW_MANIFEST_FILE, WORKFLOW_ARTIFACTS, WORKFLOW_SCHEMAS_FILE, MANIFEST_ENTRY_KINDS, MANIFEST_ENTRY_MODES, MIN_IMAGE_VERSION_FOR_MANIFEST_V2, workflowStartSurface, workflowChatSurface, DEEP_AGENT_CHAT_SURFACE, agentManifestSchema;
 var init_agents = __esmMin((() => {
 	init_json_object();
 	init_connectors();
@@ -270,6 +270,7 @@ var init_agents = __esmMin((() => {
 	DEFAULT_AGENT_MIGRATIONS_PATH = "./.stackbone/migrations";
 	BUNDLE_MIGRATIONS_PATH = ".well-known/migrations/v1";
 	WORKSPACE_MANIFEST_PATH = ".well-known/workspace.json";
+	CONFIG_SCHEMA_ARTIFACT_PATH = ".well-known/config/v1/config-schema.json";
 	WORKFLOW_WELL_KNOWN_DIR = ".well-known/workflow/v1";
 	WORKFLOW_STEP_FILE = "step.mjs";
 	WORKFLOW_VM_FILE = "workflow.vm.js";
@@ -501,6 +502,25 @@ var init_approvals = __esmMin((() => {
 //#endregion
 //#region ../../libs/shared/validators/src/lib/agents/contract.ts
 /**
+* Whether a box speaking protocol `version` can be registered as a deployment.
+* Pure and total: the caller passes the number the handshake reported.
+*/
+function supportsDeploymentRegistration(version) {
+	return version >= 15;
+}
+/**
+* The one sentence both doors print when a box is below the floor.
+*
+* Shared, not copied, because the wizard and `stackbone link` refuse by the same
+* rule and an operator who tries the other door must not read a different story.
+* For the same reason it names no door: there is no "register it from the
+* terminal instead" any more, and the only way out it can honestly offer is the
+* one that works everywhere — run a current image.
+*/
+function deploymentRegistrationRefusal(version) {
+	return `This box speaks protocol version ${version}. Registering a deployment needs version 15 or later, because an older box refuses the signed call that proves its secret. Update the image the box runs to a current one and try again.`;
+}
+/**
 * Validates that the negotiated `contract.version` is at or above the
 * version the SDK still executes against. Pure, table-driven, never throws.
 *
@@ -604,7 +624,7 @@ var init_deployments = __esmMin((() => {
 		agentSlug: agentSlugSchema,
 		url: z.url(),
 		hmacSecret: z.string().min(1),
-		imageTag: z.string().min(1).max(200)
+		imageTag: z.string().min(1).max(200).optional()
 	});
 	z.object({ url: z.url() });
 	deploymentResponseSchema = z.object({
@@ -3326,6 +3346,47 @@ var bootWorkspaceRuntime = async (opts, deps = {}) => {
 	};
 };
 //#endregion
+//#region ../../libs/shared/s3-client/src/lib/create-s3-compat-client.ts
+/**
+* The single S3-compatible client factory. Behind this seam it resolves the
+* addressing style (path-style unless the caller says otherwise), falls back to
+* `'us-east-1'` when the caller pins no region, and shapes the flat
+* `accessKeyId` / `secretAccessKey` pair into the SDK's `credentials` object.
+*
+* Call sites pin their region explicitly: studio and the SDK pass the one they
+* resolved, the emulator pins `'us-east-1'`.
+*/
+/**
+* Read the addressing style out of an environment value.
+*
+* Lives here, next to the factory, so the SDK and the runtime cannot drift on
+* what counts as "off". Anything unset, empty or unrecognised means path-style
+* — the safe default, since a typo'd value silently flipping a working box to
+* subdomain addressing would break every call with an error that names neither
+* the variable nor the typo.
+*/
+function parseForcePathStyle(raw) {
+	const value = raw?.trim().toLowerCase();
+	return !(value === "false" || value === "0" || value === "no" || value === "off");
+}
+function createS3CompatClient(options) {
+	return new S3Client({
+		endpoint: options.endpoint,
+		region: options.region ?? "us-east-1",
+		forcePathStyle: options.forcePathStyle ?? true,
+		credentials: {
+			accessKeyId: options.accessKeyId,
+			secretAccessKey: options.secretAccessKey
+		}
+	});
+}
+var init_create_s3_compat_client = __esmMin((() => {}));
+//#endregion
+//#region ../../libs/shared/s3-client/src/index.ts
+var init_src$12 = __esmMin((() => {
+	init_create_s3_compat_client();
+}));
+//#endregion
 //#region ../../libs/sdk/src/config.ts
 /**
 * Single seam in the SDK for reading `process.env`. Every downstream module
@@ -3356,6 +3417,7 @@ function resolveConfig(config) {
 		s3Endpoint: config.s3?.endpoint ?? env["STACKBONE_S3_ENDPOINT"],
 		s3Bucket: config.s3?.bucket ?? env["STACKBONE_S3_BUCKET"],
 		s3Region: config.s3?.region ?? env["STACKBONE_S3_REGION"] ?? "us-east-1",
+		s3ForcePathStyle: config.s3?.forcePathStyle ?? parseForcePathStyle(env["STACKBONE_S3_FORCE_PATH_STYLE"]),
 		otelExporterOtlpEndpoint: config.otel?.exporterOtlpEndpoint ?? env["OTEL_EXPORTER_OTLP_ENDPOINT"],
 		requireContract: env["STACKBONE_REQUIRE_CONTRACT"] !== "0",
 		contractTtlMs: parseTtlMs(env["STACKBONE_CONTRACT_TTL_MS"]),
@@ -3375,7 +3437,9 @@ function parseTtlMs(raw) {
 	if (!Number.isFinite(n) || n <= 0) return void 0;
 	return n;
 }
-var init_config$1 = __esmMin((() => {}));
+var init_config$1 = __esmMin((() => {
+	init_src$12();
+}));
 //#endregion
 //#region ../../libs/sdk/src/result.ts
 function ok$1(data) {
@@ -3461,7 +3525,7 @@ function createContractStore(resolved = resolveConfig({})) {
 	};
 }
 async function performHandshake(baseUrl, fetchImpl) {
-	const url = `${baseUrl}${CONTRACT_PATH}`;
+	const url = `${baseUrl}${CONTRACT_PATH$1}`;
 	let response;
 	try {
 		response = await fetchImpl(url, { method: "GET" });
@@ -3547,12 +3611,12 @@ function maybeLogDebug(debugLogged, key, contract) {
 	debugLogged.add(key);
 	console.warn(`[stackbone] contract handshake ok: baseUrl=${key} version=${contract.version} capabilities=${contract.capabilities.length}`);
 }
-var CONTRACT_PATH;
+var CONTRACT_PATH$1;
 var init_contract_handshake = __esmMin((() => {
 	init_src$13();
 	init_config$1();
 	init_result$1();
-	CONTRACT_PATH = "/api/contract";
+	CONTRACT_PATH$1 = "/api/contract";
 }));
 //#endregion
 //#region ../../libs/sdk/src/contract/capability-registry.ts
@@ -3958,7 +4022,7 @@ var init_stackbone_signature = __esmMin((() => {
 }));
 //#endregion
 //#region ../../libs/shared/crypto/src/index.ts
-var init_src$12 = __esmMin((() => {
+var init_src$11 = __esmMin((() => {
 	init_secret_cipher();
 	init_constant_time();
 	init_workflow_signature();
@@ -4035,7 +4099,7 @@ function isDecision(value) {
 }
 var SIGNATURE_HEADER, DEFAULT_TOLERANCE_SECONDS, FUTURE_DRIFT_TOLERANCE_SECONDS;
 var init_verify = __esmMin((() => {
-	init_src$12();
+	init_src$11();
 	init_result$1();
 	init_approval();
 	SIGNATURE_HEADER = STACKBONE_SIGNATURE_HEADER;
@@ -4723,7 +4787,7 @@ var init_compile = __esmMin((() => {
 }));
 //#endregion
 //#region ../../libs/shared/prompt-compiler/src/index.ts
-var init_src$11 = __esmMin((() => {
+var init_src$10 = __esmMin((() => {
 	init_compile();
 }));
 //#endregion
@@ -4793,7 +4857,7 @@ function toIso$2(value) {
 }
 var PG_UNDEFINED_TABLE$4, PG_UNIQUE_VIOLATION$2, PromptsFacade;
 var init_prompts = __esmMin((() => {
-	init_src$11();
+	init_src$10();
 	init_result$1();
 	PG_UNDEFINED_TABLE$4 = "42P01";
 	PG_UNIQUE_VIOLATION$2 = "23505";
@@ -5914,7 +5978,7 @@ var init_jobs = __esmMin((() => {
 }));
 //#endregion
 //#region ../../libs/shared/rag-core/src/index.ts
-var init_src$10 = __esmMin((() => {
+var init_src$9 = __esmMin((() => {
 	init_result();
 	init_limits();
 	init_rag_contract();
@@ -6129,7 +6193,7 @@ function resolveRetrieveModel(request, resolved) {
 }
 var DEFAULT_BATCH_SIZE, RagModule;
 var init_rag = __esmMin((() => {
-	init_src$10();
+	init_src$9();
 	init_src$13();
 	init_module_gate();
 	init_result$1();
@@ -6299,7 +6363,7 @@ var init_rag = __esmMin((() => {
 //#region ../../libs/sdk/src/surfaces/agent-local/secrets/secrets.ts
 var SecretsFacade;
 var init_secrets = __esmMin((() => {
-	init_src$12();
+	init_src$11();
 	init_result$1();
 	SecretsFacade = class {
 		constructor(_resolved, _getDatabase) {
@@ -7104,35 +7168,6 @@ var init_call_connector = __esmMin((() => {
 	connection = ((id) => connectorHandle(id));
 }));
 //#endregion
-//#region ../../libs/shared/s3-client/src/lib/create-s3-compat-client.ts
-/**
-* The single S3-compatible client factory. Behind this seam it always sets
-* `forcePathStyle: true` (MinIO and most S3-compatible backends do not support
-* virtual-host buckets), falls back to `'us-east-1'` when the caller pins no
-* region, and shapes the flat `accessKeyId` / `secretAccessKey` pair into the
-* SDK's `credentials` object.
-*
-* Call sites pin their region explicitly: studio and the SDK pass the one they
-* resolved, the emulator pins `'us-east-1'`.
-*/
-function createS3CompatClient(options) {
-	return new S3Client({
-		endpoint: options.endpoint,
-		region: options.region ?? "us-east-1",
-		forcePathStyle: true,
-		credentials: {
-			accessKeyId: options.accessKeyId,
-			secretAccessKey: options.secretAccessKey
-		}
-	});
-}
-var init_create_s3_compat_client = __esmMin((() => {}));
-//#endregion
-//#region ../../libs/shared/s3-client/src/index.ts
-var init_src$9 = __esmMin((() => {
-	init_create_s3_compat_client();
-}));
-//#endregion
 //#region ../../libs/sdk/src/surfaces/external/storage/storage.ts
 function stripEtag$1(etag) {
 	return etag?.replace(/^"|"$/g, "");
@@ -7161,7 +7196,7 @@ function toStorageError(message, cause) {
 }
 var DEFAULT_SIGNED_URL_TTL_SECONDS, StorageModule, StorageBucket, S3_CREDENTIALS_MISSING_MESSAGE, S3_BUCKET_MISSING_MESSAGE, AGENT_ID_MISSING_MESSAGE;
 var init_storage = __esmMin((() => {
-	init_src$9();
+	init_src$12();
 	init_module_gate();
 	init_result$1();
 	DEFAULT_SIGNED_URL_TTL_SECONDS = 3600;
@@ -7197,7 +7232,8 @@ var init_storage = __esmMin((() => {
 				endpoint,
 				region,
 				accessKeyId,
-				secretAccessKey
+				secretAccessKey,
+				forcePathStyle: this._resolved.s3ForcePathStyle
 			});
 			return ok$1({
 				client: this._s3,
@@ -7713,7 +7749,7 @@ function createDatabaseProfilePersistence() {
 }
 var AGENT_IDENTITY, errMessage$23, BrowserAuthProfileStore;
 var init_browser_profile_store = __esmMin((() => {
-	init_src$12();
+	init_src$11();
 	init_result$1();
 	init_ambient_client();
 	init_browser_profile_state();
@@ -8388,7 +8424,7 @@ var init_src$8 = __esmMin((() => {
 	init_browser_tools();
 	init_browser_mode_resolver();
 	init_browser_profile_store();
-	init_src$12();
+	init_src$11();
 	init_ambient_client();
 }));
 //#endregion
@@ -10197,6 +10233,7 @@ var resolveCorsAllowlist = (input) => {
 };
 //#endregion
 //#region ../../libs/runtime/workspace-runtime/src/lib/server/agent-config.ts
+init_src$13();
 var StudioAgentConfigValidationError = class extends Error {
 	constructor(errors) {
 		super("agent_config_invalid");
@@ -10211,15 +10248,6 @@ var StudioAgentConfigVersionNotFoundError = class extends Error {
 	}
 };
 /**
-* Literal location of the config JSON Schema the dev build extracts from the
-* creator's `config.schema.ts`, relative to the project root. Shared artifact
-* contract across the whole feature (`config_schema_dynamic_config`): the CLI
-* extractor writes it, the SDK type codegen reads it, and the emulator (here)
-* resolves it for the Config editor + write validation. Kept as a literal so the
-* emulator never imports `apps/cli`.
-*/
-var CONFIG_SCHEMA_ARTIFACT_PATH = ".well-known/config/v1/config-schema.json";
-/**
 * Read the extracted config JSON Schema off disk for a given project root.
 *
 * Reads `<projectRoot>/.well-known/config/v1/config-schema.json` (the build
@@ -10415,15 +10443,17 @@ var init_well_known = __esmMin((() => {
 }));
 //#endregion
 //#region ../../libs/runtime/workspace-runtime/src/lib/server/box-auth-gate.ts
-init_src$12();
+init_src$11();
 init_well_known();
 var PROXY_CHALLENGE_PATH = "/api/proxy-challenge";
+var CONTROL_PLANE_IDENTITY_PATH = "/api/control-plane-identity";
 var PUBLIC_PREFIXES = [
 	"/api/contract",
 	"/api/health",
 	"/live",
 	"/health",
 	PROXY_CHALLENGE_PATH,
+	CONTROL_PLANE_IDENTITY_PATH,
 	"/api/connect/callback",
 	"/api/connect/connected",
 	"/api/connect/token",
@@ -10470,6 +10500,14 @@ var rejectToken = (c) => c.json({
 	code: "invalid_token",
 	message: "Identity token is missing, expired, or invalid."
 }, 401);
+var rejectTokenTenant = (c) => c.json({
+	code: "invalid_token_tenant",
+	message: "Identity token is valid, but it was issued for a different organization or installation than this box serves."
+}, 401);
+var rejectUntaught = (c) => c.json({
+	code: "box_not_registered",
+	message: "This box has not been told which installation it answers for, so it cannot accept any identity token yet. Register it from the control plane (or re-run `stackbone link`) and try again."
+}, 401);
 var BEARER_RE = /^Bearer\s+(.+)$/i;
 var extractBearer = (header) => {
 	if (!header) return null;
@@ -10490,9 +10528,12 @@ var extractIdentity = (payload) => {
 };
 /**
 * Build the identity-token verifier ONCE, so the JWKS resolver (and its in-memory
-* cache) lives for the process instead of being rebuilt per request. Returns the
-* verified identity, or `null` for every failure mode — missing, malformed,
-* expired, wrong key, wrong issuer/audience, or minted for another tenant.
+* cache) lives for the process instead of being rebuilt per request.
+*
+* Signature + expiry + issuer/audience are verified BEFORE any tenant comparison,
+* so a token that failed verification is never classified from claims nobody
+* proved: an attacker cannot mint an unsigned token with a foreign `org` and have
+* the box answer "wrong tenant", which would confirm the box does not serve it.
 */
 var createIdentityTokenVerifier = (options) => {
 	const getKey = options.createJwks?.() ?? createRemoteJWKSet(new URL(options.jwksUrl), {
@@ -10501,7 +10542,10 @@ var createIdentityTokenVerifier = (options) => {
 	});
 	return async (c) => {
 		const token = extractBearer(c.req.header("authorization"));
-		if (!token) return null;
+		if (!token) return {
+			ok: false,
+			reason: "absent"
+		};
 		let payload;
 		try {
 			({payload} = await jwtVerify(token, getKey, {
@@ -10509,13 +10553,41 @@ var createIdentityTokenVerifier = (options) => {
 				audience: options.audience
 			}));
 		} catch {
-			return null;
+			return {
+				ok: false,
+				reason: "unverifiable"
+			};
 		}
 		const identity = extractIdentity(payload);
-		if (!identity) return null;
-		if (identity.org !== options.expectedOrg) return null;
-		if (identity.install !== void 0 && identity.install !== options.expectedInstall) return null;
-		return identity;
+		if (!identity) return {
+			ok: false,
+			reason: "unverifiable"
+		};
+		if (identity.org === void 0) return {
+			ok: false,
+			reason: "unverifiable"
+		};
+		const answersFor = await options.answersFor();
+		if (!answersFor) return {
+			ok: false,
+			reason: "untaught"
+		};
+		if (identity.org !== answersFor.organizationId) return {
+			ok: false,
+			reason: "wrong_tenant"
+		};
+		if (identity.install === void 0) return {
+			ok: false,
+			reason: "unverifiable"
+		};
+		if (identity.install !== answersFor.installationId) return {
+			ok: false,
+			reason: "wrong_tenant"
+		};
+		return {
+			ok: true,
+			identity
+		};
 	};
 };
 /**
@@ -10549,9 +10621,12 @@ var createBoxAuthGate = (options) => {
 	const proxySecret = options.proxyAuth?.secret;
 	const verifyIdentityToken = options.jwtAuth ? createIdentityTokenVerifier(options.jwtAuth) : void 0;
 	if (!proxySecret && !verifyIdentityToken) return async (_c, next) => next();
-	const reject = (c) => {
-		if (verifyIdentityToken && extractBearer(c.req.header("authorization")) || !proxySecret) return rejectToken(c);
-		return rejectSignature(c);
+	const reject = (c, check) => {
+		const reason = check?.ok === false ? check.reason : void 0;
+		if (reason === "untaught") return rejectUntaught(c);
+		if (reason === "wrong_tenant") return rejectTokenTenant(c);
+		if (reason === "unverifiable") return rejectToken(c);
+		return proxySecret ? rejectSignature(c) : rejectToken(c);
 	};
 	return async (c, next) => {
 		if (c.req.method === "OPTIONS") return next();
@@ -10560,23 +10635,21 @@ var createBoxAuthGate = (options) => {
 			c.set(AUTHENTICATED_CALLER_VAR, { provenance: "proxy" });
 			return next();
 		}
-		if (verifyIdentityToken) {
-			const identity = await verifyIdentityToken(c);
-			if (identity) {
-				c.set(AUTHENTICATED_CALLER_VAR, {
-					provenance: "identity",
-					...identity
-				});
-				return next();
-			}
+		const check = await verifyIdentityToken?.(c);
+		if (check?.ok) {
+			c.set(AUTHENTICATED_CALLER_VAR, {
+				provenance: "identity",
+				...check.identity
+			});
+			return next();
 		}
-		return reject(c);
+		return reject(c, check);
 	};
 };
 //#endregion
 //#region ../../libs/runtime/workspace-runtime/src/lib/server/contract.ts
 init_src$13();
-var STACKBONE_CLI_BUILD_VERSION = "0.3.1";
+var STACKBONE_CLI_BUILD_VERSION = "0.3.3";
 /**
 * Capabilities the local emulator advertises on `GET /api/contract`, derived
 * from the route registry above so the advertised set and the mounted routes
@@ -10597,7 +10670,7 @@ var EMULATOR_CAPABILITIES = Object.keys({
 	"browser.provider": "/api/browser-provider"
 });
 var buildContractResponse = () => contractResponseSchema.parse({
-	version: 14,
+	version: 15,
 	minSupported: 1,
 	capabilities: [...EMULATOR_CAPABILITIES],
 	build: {
@@ -10975,7 +11048,7 @@ async function runLogTail(stream, filters, startTailer) {
 }
 //#endregion
 //#region ../../libs/runtime/workspace-runtime/src/lib/handlers/actor.ts
-init_src$12();
+init_src$11();
 function readActorUserId(c) {
 	const verified = readVerifiedIdentity(c);
 	if (verified?.userId) return verified.userId;
@@ -11036,7 +11109,7 @@ var requireCapability = (capability) => {
 };
 //#endregion
 //#region ../../libs/runtime/workspace-runtime/src/lib/handlers/prompts-handlers.ts
-init_src$11();
+init_src$10();
 init_src$13();
 var PG_UNIQUE_VIOLATION$1 = "23505";
 var withClient$3 = async (opts, fn) => {
@@ -11327,8 +11400,8 @@ var createPromptsRouter = (opts) => {
 };
 //#endregion
 //#region ../../libs/runtime/workspace-runtime/src/lib/services/storage.ts
-init_src$10();
 init_src$9();
+init_src$12();
 var ObjectNotFoundError = class extends Error {
 	constructor(message = "object_not_found") {
 		super(message);
@@ -11339,7 +11412,8 @@ var buildClient = (options) => createS3CompatClient({
 	endpoint: options.endpoint,
 	region: options.region || "us-east-1",
 	accessKeyId: options.accessKey,
-	secretAccessKey: options.secretKey
+	secretAccessKey: options.secretKey,
+	...options.forcePathStyle === void 0 ? {} : { forcePathStyle: options.forcePathStyle }
 });
 var listBuckets$1 = async (options) => ({ items: [{
 	name: options.bucket,
@@ -11595,7 +11669,7 @@ var createStorageRouter = (storageOptions) => {
 };
 //#endregion
 //#region ../../libs/runtime/workspace-runtime/src/lib/services/secrets.ts
-init_src$12();
+init_src$11();
 init_src$13();
 var StudioSecretNotFoundError = class extends Error {
 	constructor() {
@@ -24816,7 +24890,7 @@ var init_resume_interrupt = __esmMin((() => {
 }));
 //#endregion
 //#region ../../libs/runtime/workspace-runtime/src/lib/evals/eval-approval-answer.ts
-init_src$12();
+init_src$11();
 init_resume_interrupt();
 init_guardrail_park();
 /** The route the box records a decision on. */
@@ -27185,7 +27259,7 @@ var createSessionsRouter = (deps) => {
 };
 //#endregion
 //#region ../../libs/runtime/workspace-runtime/src/lib/handlers/approval-callback.ts
-init_src$12();
+init_src$11();
 init_src$13();
 var buildCallbackPayload = (approval, decision) => ({
 	status: decision.decision === "approve" ? "approved" : "rejected",
@@ -28293,7 +28367,7 @@ var mapRunToRagJob = (run) => ({
 });
 //#endregion
 //#region ../../libs/runtime/workspace-runtime/src/lib/handlers/rag-handlers.ts
-init_src$10();
+init_src$9();
 init_src$13();
 var RAG_DIMENSIONS$1 = 1536;
 var RAG_DISTANCE$1 = "cosine";
@@ -28571,7 +28645,7 @@ var init_readiness$1 = __esmMin((() => {
 }));
 //#endregion
 //#region ../../libs/runtime/workspace-runtime/src/lib/handlers/rag-write-handlers.ts
-init_src$10();
+init_src$9();
 init_readiness$1();
 var createMinioRagWriteStorage = (storage) => ({
 	putManagedObject: async (key, body, contentType) => {
@@ -28837,7 +28911,7 @@ var basename$1 = (key) => {
 //#endregion
 //#region ../../libs/runtime/workspace-runtime/src/lib/handlers/rag-router.ts
 init_src$13();
-init_src$10();
+init_src$9();
 /**
 * Builds the Hono router mounted at `/api/rag` by the emulator server. Studio RAG
 * explorer + managed WRITE surface (V9 + feature 30, F76/F5). Reads/writes the
@@ -32393,7 +32467,7 @@ var init_src$1 = __esmMin((() => {
 	init_token_cache_key();
 	init_get_token();
 	init_src$3();
-	init_src$12();
+	init_src$11();
 	init_schema();
 	init_grant_refresh_ports();
 	init_grant_refresh_runtime();
@@ -32459,7 +32533,7 @@ function errorMessage$1(err) {
 }
 //#endregion
 //#region ../../libs/runtime/workspace-runtime/src/lib/handlers/connect-handlers.ts
-init_src$12();
+init_src$11();
 init_src$1();
 init_src$3();
 init_src$2();
@@ -40152,7 +40226,7 @@ var init_src = __esmMin((() => {
 //#region ../../libs/runtime/workspace-runtime/src/lib/catalog/system-entries.ts
 var RESERVED_ROLES, isSystemEntry;
 var init_system_entries = __esmMin((() => {
-	init_src$10();
+	init_src$9();
 	init_src();
 	RESERVED_ROLES = {
 		agent: new Set([RAG_INGEST_ROLE]),
@@ -40738,8 +40812,7 @@ var redisConnection = (redisUrl) => {
 	const db = path === "" ? void 0 : Number(path);
 	if (db !== void 0 && !Number.isInteger(db)) throw new Error(`Invalid Redis database in URL path: '${url.pathname}' (expected an integer)`);
 	return {
-		host: url.hostname,
-		port: url.port ? Number(url.port) : 6379,
+		url: redisUrl,
 		...db === void 0 ? {} : { db },
 		maxRetriesPerRequest: null
 	};
@@ -41152,6 +41225,7 @@ var init_connections = __esmMin((() => {
 		s3SecretKey: "STACKBONE_S3_SECRET_KEY",
 		s3Bucket: "STACKBONE_S3_BUCKET",
 		s3Region: "STACKBONE_S3_REGION",
+		s3ForcePathStyle: "STACKBONE_S3_FORCE_PATH_STYLE",
 		agentConfig: "STACKBONE_AGENT_CONFIG",
 		port: "PORT",
 		mode: "STACKBONE_MODE",
@@ -41160,7 +41234,7 @@ var init_connections = __esmMin((() => {
 	buildAgentEnv = (base, injection, options) => {
 		const env = {
 			...base,
-			[STACKBONE_ENV_KEYS.contractVersion]: String(14),
+			[STACKBONE_ENV_KEYS.contractVersion]: String(15),
 			[STACKBONE_ENV_KEYS.agentId]: injection.agentId,
 			[STACKBONE_ENV_KEYS.postgresUrl]: injection.services.postgresUrl,
 			[STACKBONE_ENV_KEYS.s3Endpoint]: injection.services.s3Endpoint,
@@ -41168,6 +41242,7 @@ var init_connections = __esmMin((() => {
 			[STACKBONE_ENV_KEYS.s3SecretKey]: injection.services.s3SecretKey,
 			[STACKBONE_ENV_KEYS.s3Bucket]: injection.services.s3Bucket,
 			[STACKBONE_ENV_KEYS.s3Region]: injection.services.s3Region,
+			[STACKBONE_ENV_KEYS.s3ForcePathStyle]: String(injection.services.s3ForcePathStyle),
 			[STACKBONE_ENV_KEYS.port]: String(injection.agentPort),
 			[STACKBONE_ENV_KEYS.mode]: options.mode,
 			[STACKBONE_ENV_KEYS.secretKey]: options.secretKey
@@ -42777,7 +42852,7 @@ async function failApprovalHookStep(params) {
 var deepAgentBridgeLogger, deriveWorkflowSteps, degradedReasonFor, resolveWorkflowRefs, applySdkContractEnv, extractWorldRunIdFromFlowBody, loadProjectRuntime, mountWorkflowRuntime;
 var init_runtime_mount = __esmMin((() => {
 	init_connections();
-	init_src$10();
+	init_src$9();
 	init_src();
 	init_registry$1();
 	init_readiness$1();
@@ -44912,7 +44987,8 @@ var init_mount = __esmMin((() => {
 			[STACKBONE_ENV_KEYS.s3AccessKey, services.s3AccessKey],
 			[STACKBONE_ENV_KEYS.s3SecretKey, services.s3SecretKey],
 			[STACKBONE_ENV_KEYS.s3Bucket, services.s3Bucket],
-			[STACKBONE_ENV_KEYS.s3Region, services.s3Region]
+			[STACKBONE_ENV_KEYS.s3Region, services.s3Region],
+			[STACKBONE_ENV_KEYS.s3ForcePathStyle, String(services.s3ForcePathStyle)]
 		];
 		const seeded = [];
 		for (const [name, value] of wanted) if (env[name] === void 0 || env[name] === "") {
@@ -44999,8 +45075,8 @@ var init_mount = __esmMin((() => {
 //#endregion
 //#region ../../libs/runtime/workspace-runtime/src/lib/server/emulator-server.ts
 init_src$13();
-init_src$12();
-init_src$10();
+init_src$11();
+init_src$9();
 init_workflow_guardrails();
 init_src$1();
 init_recurring_jobs_registry();
@@ -45021,6 +45097,28 @@ init_well_known();
 * agents run IN-PROCESS behind it, not on a port of their own.
 */
 var DEV_INSTALLATION_ID = "local-dev";
+/**
+* STA-594 — the teach call's body: the control plane's installation id and the
+* organization it belongs to. `null` when the body is not that, so a signed call
+* with a mistyped field is refused loudly instead of recording an empty identity
+* the box would then answer for.
+*/
+var readControlPlaneIdentityBody = (raw) => {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return null;
+	}
+	if (!parsed || typeof parsed !== "object") return null;
+	const { installationId, organizationId } = parsed;
+	if (typeof installationId !== "string" || installationId.trim() === "") return null;
+	if (typeof organizationId !== "string" || organizationId.trim() === "") return null;
+	return {
+		installationId,
+		organizationId
+	};
+};
 var buildEmulatorApp = (opts, hooks = {}) => {
 	const app = new Hono();
 	const agentBaseUrl = `http://127.0.0.1:${opts.injection.agentPort}`;
@@ -45043,7 +45141,8 @@ var buildEmulatorApp = (opts, hooks = {}) => {
 			"x-stackbone-session",
 			"x-stackbone-conversation",
 			"x-api-key",
-			"anthropic-version"
+			"anthropic-version",
+			STACKBONE_SIGNATURE_HEADER
 		],
 		exposeHeaders: ["X-Stackbone-Run-Id"]
 	}));
@@ -45053,7 +45152,7 @@ var buildEmulatorApp = (opts, hooks = {}) => {
 	}));
 	if (opts.proxyChallenge?.secret) {
 		const challengeSecret = opts.proxyChallenge.secret;
-		app.get(PROXY_CHALLENGE_PATH, (c) => {
+		app.get(PROXY_CHALLENGE_PATH, async (c) => {
 			const url = new URL(c.req.url);
 			const ok = verifyStackboneSignature({
 				secret: challengeSecret,
@@ -45066,10 +45165,43 @@ var buildEmulatorApp = (opts, hooks = {}) => {
 			});
 			const body = {
 				ok,
-				identityVerification: opts.jwtAuth ? "armed" : "unarmed"
+				identityVerification: !opts.jwtAuth ? "unarmed" : await opts.jwtAuth.answersFor() ? "armed" : "untaught"
 			};
 			return c.json(body, ok ? 200 : 401);
 		});
+		const learn = opts.learnControlPlaneIdentity;
+		if (learn) app.post(CONTROL_PLANE_IDENTITY_PATH, async (c) => {
+			const url = new URL(c.req.url);
+			const raw = await c.req.raw.clone().text();
+			if (!verifyStackboneSignature({
+				secret: challengeSecret,
+				header: c.req.header("stackbone-signature"),
+				payload: proxyRequestPayload({
+					method: "POST",
+					path: url.pathname + url.search,
+					body: raw
+				})
+			})) return c.json({
+				ok: false,
+				code: "invalid_signature"
+			}, 401);
+			const learned = readControlPlaneIdentityBody(raw);
+			if (!learned) return c.json({
+				ok: false,
+				code: "invalid_body",
+				message: "Expected a JSON body naming installationId and organizationId, both non-empty strings."
+			}, 400);
+			try {
+				await learn(learned);
+			} catch (err) {
+				return c.json({
+					ok: false,
+					code: "not_recorded",
+					message: err instanceof Error ? err.message : String(err)
+				}, 500);
+			}
+			return c.json({ ok: true });
+		});
 	}
 	app.get("/api/contract", (c) => c.json(buildContractResponse()));
 	app.get("/", (c) => c.html(renderStudioStub({
@@ -45175,6 +45307,7 @@ var buildEmulatorApp = (opts, hooks = {}) => {
 		secretKey: opts.injection.services.s3SecretKey,
 		bucket: opts.injection.services.s3Bucket,
 		region: opts.injection.services.s3Region,
+		forcePathStyle: opts.injection.services.s3ForcePathStyle,
 		agentId: opts.agent.slug
 	};
 	app.route("/api/storage", createStorageRouter(storageOptions));
@@ -45194,12 +45327,12 @@ var buildEmulatorApp = (opts, hooks = {}) => {
 		invocations: opts.invocations,
 		...hooks.resolveRagIngestTrigger ? { resolveRagIngestTrigger: hooks.resolveRagIngestTrigger } : {}
 	}));
-	const secretsOptions = { connectionString: opts.injection.services.postgresUrl };
-	app.route("/api/secrets", createSecretsRouter(secretsOptions));
-	const privilegedSecretsOptions = {
+	const secretsOptions = {
 		connectionString: opts.injection.services.postgresUrl,
 		...opts.secretKey ? { cipherKeyBase64: opts.secretKey } : {}
 	};
+	app.route("/api/secrets", createSecretsRouter(secretsOptions));
+	const privilegedSecretsOptions = secretsOptions;
 	app.route("/api/model-provider", createModelProviderRouter(privilegedSecretsOptions, { ...opts.bootEnv ?? {} }, { ...hooks.retryDegradedDeepAgents ? { onProviderSaved: hooks.retryDegradedDeepAgents } : {} }));
 	app.route("/api/browser-provider", createBrowserProviderRouter(privilegedSecretsOptions));
 	app.route("/api/browser-profiles", createBrowserProfilesRouter({ connectionString: opts.injection.services.postgresUrl }));
@@ -45916,7 +46049,8 @@ var buildDevServices = (ports) => ({
 	s3AccessKey: DEV_SERVICE_CREDENTIALS.s3AccessKey,
 	s3SecretKey: DEV_SERVICE_CREDENTIALS.s3SecretKey,
 	s3Bucket: DEV_SERVICE_CREDENTIALS.s3Bucket,
-	s3Region: DEV_SERVICE_CREDENTIALS.s3Region
+	s3Region: DEV_SERVICE_CREDENTIALS.s3Region,
+	s3ForcePathStyle: true
 });
 var buildDevRedisUrl = (redisPort) => `redis://127.0.0.1:${redisPort}`;
 var DEV_AGENT_SECRET_KEY = createHash("sha256").update(STUDIO_LOCAL_DEV_ENCRYPTION_KEY).digest("base64");
@@ -46229,7 +46363,7 @@ var calls_workflow_ts_default = "import { z } from \"zod\";\nimport { streamDeep
 var plain_workflow_ts_default = "import { z } from \"zod\";\n\n/**\n * Workflow \"{{name}}\" — a durable pipeline.\n *\n * Each `\"use step\"` is a durable checkpoint: kill the runtime mid-run and it\n * resumes from the last completed step instead of replaying everything.\n */\n\n// THE contract — sibling exports next to the bare workflow function. The build\n// harvests these (by convention) into the manifest + a live validator. The\n// parameter type is DERIVED from `inputSchema` (`z.infer`), so there is no\n// second type that drifts.\nexport const inputSchema = z.object({\n  message: z.string().describe(\"The input to process\"),\n});\n\nexport const outputSchema = z.object({\n  message: z.string(),\n  processed: z.boolean(),\n});\n\ntype {{Name}}Input = z.infer<typeof inputSchema>;\n\nexport async function {{export}}(input: {{Name}}Input) {\n  \"use workflow\";\n\n  const result = await processMessage(input); // step 1 — durable checkpoint\n  return result;\n}\n\nasync function processMessage(input: {{Name}}Input) {\n  \"use step\";\n  // Replace this with the deterministic work of your step (DB write, HTTP call,\n  // an LLM call, …). Returning a value records it as the step's checkpoint.\n  return { message: input.message, processed: true };\n}\n";
 //#endregion
 //#region src/services/scaffold/template-loader.ts
-var SDK_TEMPLATE_VERSION = "0.3.0";
+var SDK_TEMPLATE_VERSION = "0.3.1";
 var PREFIX = "./templates/";
 var templates = new Map(Object.entries(/* @__PURE__ */ Object.assign({
 	"./templates/deep-agents/index.ts.tmpl": index_ts_default,
@@ -46515,10 +46649,10 @@ var createIdentityTokenProvider = (opts) => {
 	let token = null;
 	return {
 		current: () => token,
-		refresh: async () => {
+		refresh: async (target) => {
 			let minted;
 			try {
-				minted = await opts.mint();
+				minted = await opts.mint(target);
 			} catch {
 				minted = null;
 			}
@@ -46530,34 +46664,28 @@ var createIdentityTokenProvider = (opts) => {
 //#endregion
 //#region src/services/identity-token.service.ts
 /** Route the control plane mints the box-facing identity JWT on (better-auth jwt plugin). */
-var IDENTITY_TOKEN_PATH = "/api/auth/token";
+var IDENTITY_TOKEN_PATH = "/api/auth/token/organization";
 /**
 * Builds the provider for `ctx`, which MUST be the control-plane context — the
 * token is minted by the control plane, never by the box it is presented to.
-*/
-var createIdentityTokenService = (ctx) => createIdentityTokenProvider({ mint: async () => {
-	return (await ctx.http.get(IDENTITY_TOKEN_PATH))?.token;
-} });
-/**
-* The organization id a minted identity token carries, or `null` when it carries
-* none (or is not a readable JWT).
 *
-* Read WITHOUT verifying, on purpose: the signature is the box's business, not
-* ours. All the CLI needs is which tenant the control plane minted for, so it can
-* refuse to address a box that serves a different one instead of sending a token
-* the box will reject. `/api/auth/token` is session-scoped and mints for the
-* caller's earliest-joined organization, so an operator who belongs to several
-* gets a token for one of them and 401s on the rest.
-*/
-var identityTokenOrganizationId = (token) => {
-	const payload = token.split(".")[1];
-	if (!payload) return null;
-	try {
-		const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
-		return typeof claims.org === "string" && claims.org.length > 0 ? claims.org : null;
-	} catch {
-		return null;
-	}
+* `organization` is the slug of the organization the target box runs in, and
+* `installation` is the control plane's id for that box. A caller with no
+* membership there, or naming a box that is not one of that organization's
+* installations, gets no token: the control plane refuses, `refresh()` resolves
+* to `null`, and nothing is substituted.
+*/
+var createIdentityTokenService = (ctx, organization, installation) => {
+	const provider = createIdentityTokenProvider({ mint: async (target) => {
+		return (await ctx.http.get(`${IDENTITY_TOKEN_PATH}?org=${encodeURIComponent(target.organization)}&install=${encodeURIComponent(target.installation)}`))?.token;
+	} });
+	return {
+		current: () => provider.current(),
+		refresh: () => provider.refresh({
+			organization,
+			installation
+		})
+	};
 };
 //#endregion
 //#region src/services/organization.service.ts
@@ -46714,28 +46842,6 @@ var directoryLookupFailed = (installationId, cause) => {
 	});
 };
 /**
-* Refuse a box that serves a DIFFERENT organization than the one the minted
-* identity token names, before a single call is addressed to it.
-*
-* `GET /api/auth/token` is session-scoped, not organization-scoped: it mints one
-* `org` claim per account, the earliest-joined membership. The box hard-rejects a
-* token whose `org` is not its own tenant, so for an operator who belongs to more
-* than one organization every box outside that first one answers 401 — and the
-* retry cannot help, because the re-mint asks the same endpoint and gets the same
-* token back. Left alone the operator reads "Run `stackbone login`", a remedy
-* that can never work.
-*
-* Only a DEFINITE mismatch refuses. A token with no `org` claim (or one this
-* build cannot read) falls through to the box's own answer rather than inventing
-* a second verdict about a shape we do not understand.
-*/
-var assertIdentityServesOrg = async (ctx, token, org, installationId) => {
-	const mintedFor = identityTokenOrganizationId(token);
-	if (mintedFor === null || mintedFor === org.id) return;
-	const owner = (await getMyOrganizations(ctx).catch(() => [])).find((o) => o.id === mintedFor);
-	throwAuth(`Agent ${installationId} belongs to organization "${org.slug}", but your identity credential is minted for ${owner ? `"${owner.slug}"` : "another organization"}, and the agent's box refuses a credential from anywhere else.`, "Stackbone mints one identity credential per account, for the organization you joined first. Reaching a box in another organization is not supported yet.");
-};
-/**
 * Resolves the full studio routing context a surface verb needs: the
 * installation it targets (`resolveAgentTarget`) plus the datapath (the
 * customer's own box vs the running local emulator) and the effective
@@ -46827,10 +46933,8 @@ var resolveStudioTarget = async (ctx, flagValue, deps = {}) => {
 		throw directoryLookupFailed(installationId, err);
 	}
 	if (!runtimeUrl) return throwRuntimeNotConfigured(installationId);
-	const identity = makeIdentity(ctx);
-	const token = await identity.refresh();
-	if (!token) return throwAuth(`Agent ${installationId} is registered, but this session could not mint the credential it requires.`, "Run `stackbone login` to refresh your session, then retry.");
-	await assertIdentityServesOrg(ctx, token, org, installationId);
+	const identity = makeIdentity(ctx, org.slug, installationId);
+	if (!await identity.refresh()) return throwAuth(`Agent ${installationId} is registered in organization "${org.slug}", but the control plane did not return the credential its box requires for that organization.`, `Retry — if the control plane is unreachable or erroring, that is the likeliest cause and nothing here needs fixing. If it keeps failing, run \`stackbone login\` to refresh your session; and if that does not help either, check you are still a member of "${org.slug}" with \`stackbone organization list\`.`);
 	const http = makeAdapter({
 		apiUrl: runtimeUrl,
 		tokenStore: ctx.tokenStore,
@@ -47799,10 +47903,19 @@ var buildWorkspaceBundle = async (options) => {
 		migrationsDir: options.migrationsDir,
 		outDir
 	});
+	const hasConfigSchema = options.hasConfigSchema ?? await exists$1(resolve(projectRoot, "config.schema.ts"));
+	if (hasConfigSchema) {
+		const configSchema = await options.resolveConfigSchema?.() ?? null;
+		if (configSchema) {
+			const artifactPath = resolve(outDir, CONFIG_SCHEMA_ARTIFACT_PATH);
+			await mkdir(dirname(artifactPath), { recursive: true });
+			await writeFile(artifactPath, JSON.stringify(configSchema), "utf8");
+		} else logger?.warn(`This workspace declares ${CONFIG_SCHEMA_SOURCE}, but no config JSON Schema was produced for the bundle. Studio's config editor will fall back to a raw JSON field and writes will not be validated.`);
+	}
 	const manifest = deriveWorkspaceManifest({
 		workspace,
 		workflowManifest,
-		hasConfigSchema: options.hasConfigSchema ?? await exists$1(resolve(projectRoot, "config.schema.ts")),
+		hasConfigSchema,
 		defaults: options.defaults,
 		deepAgentExternals
 	});
@@ -47864,6 +47977,181 @@ var resolveAgentDbConfig = (agentRoot) => {
 	};
 };
 //#endregion
+//#region src/dev/extract-config-schema.ts
+/** Directory the extracted artifact lives in, relative to the workspace root.
+*  A subdir of its own, parallel to the workflow well-known tree. */
+var CONFIG_WELL_KNOWN_DIR = ".well-known/config/v1";
+/** The shipped artifact: the single JSON Schema (JSON only, no live sidecar). */
+var CONFIG_SCHEMA_FILE = "config-schema.json";
+/** The intermediate esbuild bundle (harmless to leave behind, like the workflow
+*  sidecar). NOT the deliverable — `config-schema.json` is. */
+var CONFIG_SCHEMA_BUNDLE = "config-schema.mjs";
+/**
+* Extract the workspace's single config JSON Schema. Defensive by contract: an
+* absent `config.schema.ts` degrades to `null` SILENTLY (the editor stays
+* free-form); a DECLARED-but-inconvertible schema degrades to `null` plus one
+* noisy warning; and a total bundle failure degrades to `null` plus one coarse
+* warning. It NEVER throws — a broken config schema must not break the dev build.
+*/
+var extractConfigSchema = async (projectRoot, opts = {}) => {
+	const loader = opts.loader ?? defaultConfigSchemaLoader;
+	const warnings = [];
+	const emit = (msg) => {
+		warnings.push(msg);
+		opts.logger?.warn(msg);
+	};
+	let loaded;
+	try {
+		loaded = await loader(projectRoot);
+	} catch (err) {
+		emit(`[config-schema] config schema extraction bundle failed; no config schema is available — the Config editor will fall back to a raw JSON field. Cause: ${errMessage$2(err)}`);
+		return {
+			schema: null,
+			warnings
+		};
+	}
+	if (loaded.configSchema == null) return {
+		schema: null,
+		warnings
+	};
+	try {
+		return {
+			schema: loaded.toJsonSchema(loaded.configSchema),
+			warnings
+		};
+	} catch (err) {
+		emit(`[config-schema] config.schema.ts could not be converted to JSON Schema — the Config editor will fall back to a raw JSON field. Cause: ${errMessage$2(err)}`);
+		return {
+			schema: null,
+			warnings
+		};
+	}
+};
+/**
+* Extract the config schema and WRITE the artifact. When the schema is non-null,
+* writes `<projectRoot>/.well-known/config/v1/config-schema.json` (compact JSON,
+* like `manifest.json`) and returns `written: true`. When the schema is null
+* (absent or inconvertible), REMOVES any stale `config-schema.json` so a deleted
+* or broken schema does not leave a phantom artifact, and returns `written:
+* false`. Never throws (mirrors `extractConfigSchema`).
+*/
+var buildConfigSchema = async (projectRoot, opts = {}) => {
+	const { schema, warnings } = await extractConfigSchema(projectRoot, opts);
+	const outfile = resolve(projectRoot, CONFIG_WELL_KNOWN_DIR, CONFIG_SCHEMA_FILE);
+	if (schema == null) {
+		await rm(outfile, { force: true });
+		return {
+			schema: null,
+			warnings,
+			written: false
+		};
+	}
+	await mkdir(resolve(projectRoot, CONFIG_WELL_KNOWN_DIR), { recursive: true });
+	await writeFile(outfile, JSON.stringify(schema), "utf8");
+	return {
+		schema,
+		warnings,
+		written: true
+	};
+};
+var errMessage$2 = (err) => err instanceof Error ? err.message : String(err);
+/**
+* The default loader: when `config.schema.ts` exists at the project root, emit an
+* entry that re-exports ONLY its `configSchema` (static member access for
+* tree-shaking), esbuild-bundle it to
+* `<projectRoot>/.well-known/config/v1/config-schema.mjs`, import it back, and
+* read `configSchema` + `toJsonSchema`. When the file is ABSENT, return
+* `{ configSchema: null, toJsonSchema: () => null }` WITHOUT bundling — an absent
+* schema is silent, not a warning.
+*
+* Resolved FROM THE PROJECT: esbuild + zod come from the workspace's own
+* node_modules (like `buildWorkflows` resolves `@workflow/builders`), so the
+* bundle uses the SAME zod the schema was authored with and the heavy esbuild
+* tree stays out of the published CLI bundle.
+*/
+var defaultConfigSchemaLoader = async (projectRoot) => {
+	try {
+		await access(resolve(projectRoot, CONFIG_SCHEMA_SOURCE));
+	} catch {
+		return {
+			configSchema: null,
+			toJsonSchema: () => null
+		};
+	}
+	const projectRequire = createRequire(resolve(projectRoot, "package.json"));
+	let esbuild;
+	try {
+		esbuild = await import(pathToFileURL(projectRequire.resolve("esbuild")).href);
+	} catch (err) {
+		throw new Error(`Cannot resolve esbuild from the workspace (needed to extract the config schema). Cause: ${errMessage$2(err)}`);
+	}
+	const entry = buildEntrySource$1();
+	const outfile = resolve(projectRoot, CONFIG_WELL_KNOWN_DIR, CONFIG_SCHEMA_BUNDLE);
+	await esbuild.build({
+		stdin: {
+			contents: entry,
+			resolveDir: projectRoot,
+			sourcefile: "config-schema-entry.ts",
+			loader: "ts"
+		},
+		bundle: true,
+		packages: "external",
+		format: "esm",
+		platform: "node",
+		target: "node22",
+		treeShaking: true,
+		outfile,
+		logLevel: "silent"
+	});
+	const mod = await import(`${pathToFileURL(outfile).href}?v=${Date.now()}`);
+	if (typeof mod.toJsonSchema !== "function") throw new Error(`config-schema.mjs did not export the expected { configSchema, toJsonSchema } shape.`);
+	return {
+		configSchema: mod.configSchema ?? null,
+		toJsonSchema: mod.toJsonSchema
+	};
+};
+/**
+* Generate the bundle entry source. It NAMESPACE-imports `config.schema.ts` and
+* reads `configSchema` with DIRECT static member access — so esbuild tree-shakes
+* everything else and a MISSING export is simply `undefined` (→ `null`), never a
+* bundle-breaking "no matching export".
+*
+* The converter is REPLICATED here (not imported from the workflow extractor): it
+* runs inside the emitted `.mjs` with the PROJECT's own zod. It is byte-for-byte
+* the workflow extractor's converter MINUS the `half` parameter — config is a
+* single input-shaped object, so the Standard-Schema fallback invokes the
+* `.input` converter directly.
+*/
+var buildEntrySource$1 = () => {
+	return [
+		`import { z } from 'zod';`,
+		`import * as cfg from './config.schema.ts';`,
+		`// Non-Zod Standard Schema fallback. Per @standard-schema/spec, ~standard`,
+		`// .jsonSchema is a Converter { input(opts), output(opts) } of FUNCTIONS — so`,
+		`// we INVOKE the input converter to get the actual JSON Schema (config is an`,
+		`// input-shaped object). Returning the Converter object verbatim folds`,
+		`// non-serialisable functions that JSON.stringify drops → a phantom {} schema.`,
+		`const std = (s) => {`,
+		`  const c = s && s['~standard'] && s['~standard'].jsonSchema;`,
+		`  const fn = c && c.input;`,
+		`  return typeof fn === 'function' ? fn({ target: 'draft-2020-12' }) : null;`,
+		`};`,
+		`const carriesFns = (o) =>`,
+		`  o != null && typeof o === 'object' && Object.values(o).some((v) => typeof v === 'function');`,
+		`export const toJsonSchema = (s) => {`,
+		`  if (s == null) return null;`,
+		`  let out;`,
+		`  try { out = z.toJSONSchema(s); }`,
+		`  catch (e) { out = std(s); if (out == null) throw e; }`,
+		`  // A result carrying functions is a non-serialisable phantom; degrade to`,
+		`  // null + a noisy warning instead of writing garbage to the artifact.`,
+		`  if (carriesFns(out)) throw new Error('schema is non-serialisable (carries functions)');`,
+		`  return out;`,
+		`};`,
+		`export const configSchema = cfg.configSchema ?? null;`
+	].join("\n");
+};
+//#endregion
 //#region src/dev/detect-workflow-streaming.ts
 /** `getWritable` imported from the literal `'workflow'` package (single or
 *  double quotes, other named imports around it allowed). */
@@ -47933,7 +48221,7 @@ var extractWorkflowSchemas = async (projectRoot, workflows, opts) => {
 			schemas[w.name] = { ...NULL_PAIR };
 			schedules[w.name] = [];
 		}
-		emit(`[workflow-schema] schema extraction bundle failed; no workflow input/output schemas are available — Playgrounds will fall back to a raw JSON field. Cause: ${errMessage$2(err)}`);
+		emit(`[workflow-schema] schema extraction bundle failed; no workflow input/output schemas are available — Playgrounds will fall back to a raw JSON field. Cause: ${errMessage$1(err)}`);
 		return {
 			schemas,
 			schedules,
@@ -47996,11 +48284,11 @@ var convertHalf = (workflowName, half, schema, toJsonSchema, emit) => {
 	try {
 		return toJsonSchema(schema, half);
 	} catch (err) {
-		emit(`[workflow-schema] workflow "${workflowName}" declares an ${half}Schema that could not be converted to JSON Schema — the Playground will show a raw JSON field for it. Cause: ${errMessage$2(err)}`);
+		emit(`[workflow-schema] workflow "${workflowName}" declares an ${half}Schema that could not be converted to JSON Schema — the Playground will show a raw JSON field for it. Cause: ${errMessage$1(err)}`);
 		return null;
 	}
 };
-var errMessage$2 = (err) => err instanceof Error ? err.message : String(err);
+var errMessage$1 = (err) => err instanceof Error ? err.message : String(err);
 /**
 * The default loader: generate an entry that re-exports ONLY each workflow's
 * `inputSchema`/`outputSchema` (resolved from the workflow module or a
@@ -48022,9 +48310,9 @@ var defaultWorkflowSchemaLoader = async (projectRoot, workflows, outDir) => {
 	try {
 		esbuild = await import(pathToFileURL(projectRequire.resolve("esbuild")).href);
 	} catch (err) {
-		throw new Error(`Cannot resolve esbuild from the workspace (needed to extract workflow schemas). Cause: ${errMessage$2(err)}`);
+		throw new Error(`Cannot resolve esbuild from the workspace (needed to extract workflow schemas). Cause: ${errMessage$1(err)}`);
 	}
-	const entry = await buildEntrySource$1(projectRoot, workflows);
+	const entry = await buildEntrySource(projectRoot, workflows);
 	const outfile = resolve(outDir, WORKFLOW_WELL_KNOWN_DIR, WORKFLOW_SCHEMAS_FILE);
 	await esbuild.build({
 		stdin: {
@@ -48059,7 +48347,7 @@ var defaultWorkflowSchemaLoader = async (projectRoot, workflows, outDir) => {
 * Schema source per workflow: a `<base>.contract.ts` sibling when it exists (the
 * clean variant — only zod, no closure), else the workflow module itself.
 */
-var buildEntrySource$1 = async (projectRoot, workflows) => {
+var buildEntrySource = async (projectRoot, workflows) => {
 	const lines = [
 		`import { z } from 'zod';`,
 		`// Non-Zod Standard Schema fallback. Per @standard-schema/spec, ~standard`,
@@ -48709,7 +48997,7 @@ var withEntry = (workflows, seed) => {
 		export: seed.export
 	}].sort((a, b) => a.name.localeCompare(b.name));
 };
-var errMessage$1 = (err) => err instanceof Error ? err.message : String(err);
+var errMessage = (err) => err instanceof Error ? err.message : String(err);
 /**
 * Resolve both platform-managed workflows and return the workspace's workflow
 * list with them spliced in, ready for the compiler (which already knows how to
@@ -48725,14 +49013,14 @@ var seedManagedWorkflows = async (projectRoot, workflows, logger, deps = {}) =>
 		logger.info(`rag-ingest workflow: using the ${seed.active === "default" ? "platform default" : "creator override"} (${seed.module})`);
 		result = withEntry(result, seed);
 	} catch (err) {
-		logger.warn({ err: errMessage$1(err) }, "failed to seed the default rag-ingest workflow — RAG upload ingest may be unavailable");
+		logger.warn({ err: errMessage(err) }, "failed to seed the default rag-ingest workflow — RAG upload ingest may be unavailable");
 	}
 	try {
 		const seed = await seedMappingSuggest(projectRoot);
 		logger.info(`mapping-suggest workflow: using the ${seed.active === "default" ? "platform default" : "creator override"} (${seed.module})`);
 		result = withEntry(result, seed);
 	} catch (err) {
-		logger.warn({ err: errMessage$1(err) }, "failed to seed the default mapping-suggest workflow — Auto-map may be unavailable");
+		logger.warn({ err: errMessage(err) }, "failed to seed the default mapping-suggest workflow — Auto-map may be unavailable");
 	}
 	return resolveSystemWorkflows(result);
 };
@@ -48969,6 +49257,7 @@ var buildWorkspace = async (ctx, outDirArg, deps = {}) => {
 	const discover = deps.discoverWorkspace ?? discoverWorkspace;
 	const build = deps.buildWorkspaceBundle ?? buildWorkspaceBundle;
 	const seedManaged = deps.seedManagedWorkflows ?? seedManagedWorkflows;
+	const extractSchema = deps.extractConfigSchema ?? extractConfigSchema;
 	const projectRoot = ctx.cwd;
 	const outDir = resolve(projectRoot, outDirArg ?? "dist/workspace-bundle");
 	const workspace = await discover(projectRoot);
@@ -48991,6 +49280,7 @@ var buildWorkspace = async (ctx, outDirArg, deps = {}) => {
 				workflows: workspace.workflows,
 				logger: { warn: (msg) => ctx.logger.warn(msg) }
 			}),
+			resolveConfigSchema: () => extractSchema(projectRoot, { logger: { warn: (msg) => ctx.logger.warn(msg) } }).then((result) => result.schema),
 			logger: {
 				info: (msg) => ctx.logger.info(msg),
 				warn: (msg) => ctx.logger.warn(msg)
@@ -49067,8 +49357,48 @@ var RUNTIME_PORT = 8080;
 var POSTGRES_IMAGE$1 = "pgvector/pgvector:pg17";
 /** Redis image the generated compose runs (BullMQ backs the durable World). */
 var REDIS_IMAGE$1 = "redis:7-alpine";
+/**
+* S3-compatible object storage the generated compose runs.
+*
+* The compose already ships a pgvector Postgres BECAUSE of managed RAG — and
+* managed RAG stores the uploaded ORIGINAL in object storage before it chunks
+* and embeds it (`putManagedObject`). Shipping the vector database without a
+* bucket delivers half of that feature: ingestion fails at the first upload,
+* `client.storage` returns `s3_credentials_missing`, and Studio's file browser
+* has nothing to talk to — while `/health` still answers `ok`, because it only
+* probes Postgres and Redis.
+*
+* Same image and pin as `stackbone dev`'s compose, so the emulator and the
+* deliverable run the identical backend.
+*/
+var MINIO_IMAGE$1 = "minio/minio:RELEASE.2025-03-12T18-04-18Z";
+/** Access key the bundled MinIO is created with. The secret is generated per package. */
+var MINIO_ACCESS_KEY = "stackbone";
+/** Bucket the init container creates, and the agent's `STACKBONE_S3_BUCKET`. */
+var MINIO_BUCKET = "stackbone";
+/**
+* Host port the bundled MinIO's S3 API is published on.
+*
+* Published, unlike Postgres and Redis, and that is deliberate: Studio's file
+* browser hands the operator's BROWSER a presigned download URL, and a presigned
+* URL carries the endpoint it was signed with. Signed against the compose-internal
+* `http://minio:9000`, the link resolves only inside the compose network. The
+* README explains the one-line fix (point `STACKBONE_S3_ENDPOINT` at a host both
+* the container and the browser can reach) — publishing the port is what makes
+* that fix possible at all.
+*/
+var MINIO_PORT = 9e3;
 /** A fresh 32-byte key, base64 — the format `STACKBONE_SECRET_KEY` expects. */
 var generateSecretKey = () => randomBytes(32).toString("base64");
+/**
+* A fresh root password for the bundled MinIO.
+*
+* `base64url`, not `base64`: this value travels through a `.env` line, a compose
+* interpolation and a `/bin/sh -c` entrypoint, and `+` `/` `=` survive that trip
+* badly. Generated per package rather than hardcoded because, unlike Postgres and
+* Redis, this service publishes a port on the host.
+*/
+var generateStoragePassword = () => randomBytes(24).toString("base64url");
 var renderDockerfile = (input) => `# Generated by \`stackbone package\`. Two lines is the whole build: the Stackbone
 # runtime base already carries the server and its pinned dependencies, so this
 # image adds only your workspace. No monorepo, no npm install, seconds to build.
@@ -49077,10 +49407,10 @@ COPY ${input.workspaceDirName}/ /app/workspace/
 `;
 var renderCompose = (input) => {
 	const image = input.imageTag;
-	return `# Generated by \`stackbone package\`. Brings up the agent with a Postgres and a
-# Redis of its own. If you already run those, delete both services here and point
-# DATABASE_URL / WORKFLOW_REDIS_URL in .env at yours — read the README first, the
-# database has one requirement.
+	return `# Generated by \`stackbone package\`. Brings up the agent with a Postgres, a
+# Redis and an object store of its own. If you already run those, delete the
+# services here and point DATABASE_URL / WORKFLOW_REDIS_URL / STACKBONE_S3_* in
+# .env at yours — read the README first, the database has one requirement.
 
 services:
   postgres:
@@ -49112,6 +49442,45 @@ services:
       retries: 20
     restart: unless-stopped
 
+  minio:
+    # S3-compatible object storage: the agent's own files (\`client.storage\`), the
+    # originals managed RAG ingests, and what Studio's file browser lists.
+    image: ${MINIO_IMAGE$1}
+    command: ['server', '/data']
+    environment:
+      MINIO_ROOT_USER: ${MINIO_ACCESS_KEY}
+      MINIO_ROOT_PASSWORD: \${MINIO_ROOT_PASSWORD:?set MINIO_ROOT_PASSWORD in .env}
+    ports:
+      # Published so a presigned download link can be opened from a browser —
+      # see "Downloads from the file browser" in the README.
+      - '${MINIO_PORT}:9000'
+    volumes:
+      - agent-objects:/data
+    healthcheck:
+      test: ['CMD', 'mc', 'ready', 'local']
+      interval: 5s
+      timeout: 5s
+      retries: 20
+    restart: unless-stopped
+
+  minio-create-bucket:
+    # Creates the bucket once, then exits 0. \`mc mb -p\` is idempotent, so it is a
+    # no-op on every later start. The agent waits for it to SUCCEED rather than
+    # for MinIO to be healthy: a bucket that does not exist yet fails the agent's
+    # first upload with a NoSuchBucket nobody would connect back to this file.
+    image: ${MINIO_IMAGE$1}
+    restart: 'no'
+    depends_on:
+      minio:
+        condition: service_healthy
+    entrypoint: >
+      /bin/sh -c "
+        mc alias set local http://minio:9000 ${MINIO_ACCESS_KEY} \\"$$MINIO_ROOT_PASSWORD\\" &&
+        mc mb -p local/${MINIO_BUCKET}
+      "
+    environment:
+      MINIO_ROOT_PASSWORD: \${MINIO_ROOT_PASSWORD:?set MINIO_ROOT_PASSWORD in .env}
+
   agent:
 ${input.imageArchiveName !== void 0 ? `    # Loaded from ${input.imageArchiveName} — there is nothing to build here.
     image: ${image}` : `    build:
@@ -49121,9 +49490,17 @@ ${input.imageArchiveName !== void 0 ? `    # Loaded from ${input.imageArchiveNam
     env_file:
       - .env
     environment:
-      # Point the agent at the two services above. Override in .env to use your own.
+      # Point the agent at the three services above. Override in .env to use your own.
       DATABASE_URL: \${DATABASE_URL:-postgres://stackbone:\${POSTGRES_PASSWORD:-stackbone}@postgres:5432/stackbone}
       WORKFLOW_REDIS_URL: \${WORKFLOW_REDIS_URL:-redis://redis:6379}
+      STACKBONE_S3_ENDPOINT: \${STACKBONE_S3_ENDPOINT:-http://minio:9000}
+      STACKBONE_S3_ACCESS_KEY: \${STACKBONE_S3_ACCESS_KEY:-${MINIO_ACCESS_KEY}}
+      STACKBONE_S3_SECRET_KEY: \${STACKBONE_S3_SECRET_KEY:-\${MINIO_ROOT_PASSWORD}}
+      STACKBONE_S3_BUCKET: \${STACKBONE_S3_BUCKET:-${MINIO_BUCKET}}
+      STACKBONE_S3_REGION: \${STACKBONE_S3_REGION:-us-east-1}
+      # MinIO addresses buckets by path. A managed bucket that only answers to the
+      # bucket-as-subdomain form (AWS S3, Railway Buckets) needs this set to false.
+      STACKBONE_S3_FORCE_PATH_STYLE: \${STACKBONE_S3_FORCE_PATH_STYLE:-true}
     ports:
       # The agent serves on ${RUNTIME_PORT} inside the container. Change the LEFT
       # number to publish it elsewhere on the host.
@@ -49133,25 +49510,51 @@ ${input.imageArchiveName !== void 0 ? `    # Loaded from ${input.imageArchiveNam
         condition: service_healthy
       redis:
         condition: service_healthy
+      minio-create-bucket:
+        condition: service_completed_successfully
     restart: unless-stopped
 
 volumes:
   agent-postgres:
   agent-redis:
+  agent-objects:
 `;
 };
-var renderEnvFile = (input, secretKey) => `# Generated by \`stackbone package\` for ${input.agentName}.
+/**
+* The `.env` and the `.env.example` are ONE template rendered twice.
+*
+* They differ only in the two secret lines: the real file carries freshly minted
+* values so `docker compose up -d` works untouched, the example carries
+* placeholders so it can be committed next to the folder. Keeping them as one
+* string is what stops the committed template from drifting into a stale list of
+* variables the runtime no longer reads.
+*/
+var renderEnv = (input, secrets) => {
+	const generated = secrets !== null;
+	return `${generated ? `# Generated by \`stackbone package\` for ${input.agentName}.
+#
+# Bringing this up with the bundled Postgres, Redis and MinIO needs NOTHING else
+# filled in — the secrets below are already generated and the endpoints default
+# to the compose services. Set them explicitly only to use your own infrastructure.` : `# Template for the \`.env\` \`stackbone package\` generates for ${input.agentName}.
 #
-# Bringing this up with the bundled Postgres and Redis needs NOTHING else filled
-# in — the key below is already generated and the two URLs default to the compose
-# services. Set them explicitly only to use your own infrastructure.
+# The packaged folder already contains a working \`.env\` with both secrets minted.
+# This file is the committable copy: it documents every variable the agent reads
+# and carries NO secret values. Filling it in by hand is only needed when you
+# rebuild the folder somewhere the original \`.env\` did not travel.`}
 
 # ---- Keep this safe ----------------------------------------------------------
 # Every secret this agent stores in its database is encrypted with this key. It
 # cannot live in the database it protects. LOSE IT AND YOU LOSE THOSE SECRETS —
 # there is no recovery, they have to be entered again. Changing it has the same
 # effect as losing it.
-STACKBONE_SECRET_KEY=${secretKey}
+${generated ? `STACKBONE_SECRET_KEY=${secrets.secretKey}` : `# Generate with: openssl rand -base64 32
+STACKBONE_SECRET_KEY=`}
+
+# Root password of the bundled object store, which also serves as the agent's
+# STACKBONE_S3_SECRET_KEY. Unlike the database and Redis, this service publishes
+# a port on the host — leave this value strong, or do not publish the port.
+${generated ? `MINIO_ROOT_PASSWORD=${secrets.storagePassword}` : `# Generate with: openssl rand -base64 24 | tr '+/' '-_' | tr -d '='
+MINIO_ROOT_PASSWORD=`}
 
 # ---- Your infrastructure (optional here) -------------------------------------
 # Uncomment to point the agent at a Postgres and a Redis you already run, instead
@@ -49159,7 +49562,31 @@ STACKBONE_SECRET_KEY=${secretKey}
 # agent creates its own schema on first boot. It must have the pgvector extension
 # available — see the README.
 # DATABASE_URL=postgres://user:password@host:5432/dbname?sslmode=require
-# WORKFLOW_REDIS_URL=redis://host:6379
+# WORKFLOW_REDIS_URL=redis://default:password@host:6379
+# Managed Redis always wants a password, and some require TLS — use rediss:// for
+# those. Percent-encode a password containing / + = or @, or the URL will not parse.
+
+# ---- Object storage ----------------------------------------------------------
+# The agent stores its own files here (\`client.storage\`), and managed RAG keeps
+# every ingested original here before it chunks and embeds it. Left alone, these
+# point at the MinIO this compose file starts.
+#
+# Uncomment to use a managed bucket instead (AWS S3, Cloudflare R2, Azure Blob,
+# Google Cloud Storage, Railway Buckets — anything S3-compatible). Create the
+# bucket first; the agent never creates one.
+# STACKBONE_S3_ENDPOINT=https://s3.eu-west-1.amazonaws.com
+# STACKBONE_S3_ACCESS_KEY=
+# STACKBONE_S3_SECRET_KEY=
+# STACKBONE_S3_BUCKET=
+# STACKBONE_S3_REGION=eu-west-1
+#
+# Addressing style. \`true\` puts the bucket in the PATH
+# (\`https://host/bucket/key\`), which is what MinIO and Cloudflare R2 accept.
+# Set it to \`false\` for a bucket that only answers to the SUBDOMAIN form
+# (\`https://bucket.host/key\`) — AWS S3 and Railway Buckets are the common ones.
+# Symptom of the wrong value: every call fails with NoSuchBucket or a 403 even
+# though the credentials are right.
+# STACKBONE_S3_FORCE_PATH_STYLE=true
 
 # ---- Optional ----------------------------------------------------------------
 # Set if your database role is not allowed to create schemas; you then apply the
@@ -49167,13 +49594,19 @@ STACKBONE_SECRET_KEY=${secretKey}
 # where it lives.
 # STACKBONE_SKIP_MIGRATIONS=1
 `;
+};
+var renderEnvFile = (input, secrets) => renderEnv(input, secrets);
+/** The committable, secret-free twin of the generated `.env`. */
+var renderEnvExample = (input) => renderEnv(input, null);
 var renderInventory = (label, names) => names.length === 0 ? `No ${label}.` : names.map((n) => `- \`${n}\``).join("\n");
 var renderReadme = (input) => {
 	const offline = input.imageArchiveName;
 	return `# ${input.agentName}
 
-A Stackbone agent, packaged to run in your own environment. It talks to a Postgres
-and a Redis that you control, and needs no connection to Stackbone to run.
+A Stackbone agent, packaged to run in your own environment. It talks to a Postgres,
+a Redis and an object store that you control, and needs no connection to Stackbone
+to run. This folder starts all three for you; swapping in your own is a few lines
+in \`.env\`.
 
 ## What you are running
 
@@ -49214,10 +49647,36 @@ prints it again. You need that value only if you later connect this deployment t
 a Stackbone control plane. Copy it somewhere safe now if there is any chance you
 will. Anyone who can read these logs can read it too.
 
-## Using your own Postgres and Redis
+## Downloads from the file browser
+
+Everything the agent itself does with files works out of the box. One thing does
+not, and it is worth thirty seconds of your time now rather than a puzzled bug
+report later.
+
+When Studio's file browser offers you a download, it hands your BROWSER a signed,
+time-limited link. That link points at whatever address the agent knows the object
+store by — and by default that address is \`http://minio:9000\`, a name that only
+exists inside this compose network. Your browser cannot resolve it, so the
+download fails while every upload, every RAG ingestion and every listing works.
+
+If anyone will download files from the file browser, set \`STACKBONE_S3_ENDPOINT\`
+in \`.env\` to an address that BOTH the container and the browser can reach — the
+host's own name or IP, on the published port:
 
-Delete the \`postgres\` and \`redis\` services from \`docker-compose.yml\`, then set
-\`DATABASE_URL\` and \`WORKFLOW_REDIS_URL\` in \`.env\`.
+\`\`\`bash
+STACKBONE_S3_ENDPOINT=http://the-host-you-run-this-on:${MINIO_PORT}
+\`\`\`
+
+Port \`${MINIO_PORT}\` is published for exactly this. If nobody needs those downloads,
+delete the \`ports:\` block from the \`minio\` service and keep the object store off
+the network entirely.
+
+## Using your own Postgres, Redis and bucket
+
+Delete the \`postgres\`, \`redis\`, \`minio\` and \`minio-create-bucket\` services from
+\`docker-compose.yml\` (and the \`depends_on\` entries naming them), then set
+\`DATABASE_URL\`, \`WORKFLOW_REDIS_URL\` and the \`STACKBONE_S3_*\` variables in \`.env\`.
+Do them one at a time if you prefer — the four services are independent.
 
 **The database has one requirement: the \`pgvector\` extension must be available.**
 The agent runs \`CREATE EXTENSION IF NOT EXISTS vector\` while creating its schema.
@@ -49244,6 +49703,32 @@ and apply these by hand first, in filename order:
 
 Both live inside the image; \`docker run --rm ${input.imageTag} ls <path>\` lists them.
 
+Redis needs no preparation, only a reachable URL. Managed instances hand out a
+password, so the URL carries one — \`redis://default:password@host:6379\`. Use
+\`rediss://\` where the provider requires TLS (Upstash, ElastiCache with encryption
+in transit), and percent-encode a password containing \`/\`, \`+\`, \`=\` or \`@\`. The
+agent PINGs Redis before it starts and stops with the reason if it cannot: a
+rejected password fails right away, and a Redis still starting up is retried for
+30 seconds first.
+
+For the bucket, any S3-compatible storage works — AWS S3, Cloudflare R2, Azure
+Blob, Google Cloud Storage, Railway Buckets, another MinIO. **Create the bucket
+first**; the agent never creates one. Then fill in the five \`STACKBONE_S3_*\`
+variables, and check the sixth:
+
+\`\`\`bash
+STACKBONE_S3_FORCE_PATH_STYLE=true    # bucket in the path:      https://host/bucket/key
+STACKBONE_S3_FORCE_PATH_STYLE=false   # bucket as a subdomain:   https://bucket.host/key
+\`\`\`
+
+MinIO and Cloudflare R2 take the first. AWS S3 and Railway Buckets want the
+second. Get it wrong and every call fails with \`NoSuchBucket\` or a bare 403 while
+the credentials are perfectly valid — which is a genuinely confusing hour, so it
+is worth checking before you conclude the keys are wrong.
+
+The agent writes only under a prefix of its own inside that bucket, so a bucket
+shared with something else stays tidy.
+
 ## Running it somewhere other than Compose
 
 The agent serves on port **${RUNTIME_PORT}** by default, and binds whatever
@@ -49335,6 +49820,7 @@ var runPackage = async (ctx, args, deps = {}) => {
 	const build = deps.buildWorkspace ?? buildWorkspace;
 	const docker = deps.runDocker ?? runDockerCommand;
 	const makeKey = deps.generateSecretKey ?? generateSecretKey;
+	const makeStoragePassword = deps.generateStoragePassword ?? generateStoragePassword;
 	const projectRoot = ctx.cwd;
 	const outDir = resolve(projectRoot, args["out-dir"] ?? "dist/deploy");
 	const { bundle } = await build(ctx, void 0, deps);
@@ -49354,16 +49840,21 @@ var runPackage = async (ctx, args, deps = {}) => {
 		recursive: true,
 		force: true
 	});
-	const secretKey = makeKey();
+	const secrets = {
+		secretKey: makeKey(),
+		storagePassword: makeStoragePassword()
+	};
 	const written = [
 		"Dockerfile",
 		"docker-compose.yml",
 		".env",
+		".env.example",
 		"README.md"
 	];
 	await writeFile(join(outDir, "Dockerfile"), renderDockerfile(templateInput), "utf8");
 	await writeFile(join(outDir, "docker-compose.yml"), renderCompose(templateInput), "utf8");
-	await writeFile(join(outDir, ".env"), renderEnvFile(templateInput, secretKey), "utf8");
+	await writeFile(join(outDir, ".env"), renderEnvFile(templateInput, secrets), "utf8");
+	await writeFile(join(outDir, ".env.example"), renderEnvExample(templateInput), "utf8");
 	await writeFile(join(outDir, "README.md"), renderReadme(templateInput), "utf8");
 	if (args.offline) {
 		ctx.logger.info(`Building ${imageTag} and saving it to ${IMAGE_ARCHIVE_NAME} (~150 MB)`);
@@ -49392,9 +49883,11 @@ var runPackage = async (ctx, args, deps = {}) => {
 		...degraded.length > 0 ? [`  degraded     ${degraded.map((d) => d.name).join(", ")} — shipped, but they will not run`] : [],
 		`  serves on    ${RUNTIME_PORT} (or PORT, when the host assigns one)`,
 		"",
-		"The .env holds a freshly generated STACKBONE_SECRET_KEY. Everything this",
-		"agent stores is encrypted with it and it cannot be recovered — hand the",
-		"folder over intact, and keep a copy of that key somewhere safe.",
+		"The .env holds two freshly generated secrets: STACKBONE_SECRET_KEY, which",
+		"encrypts everything this agent stores and cannot be recovered, and",
+		"MINIO_ROOT_PASSWORD for the bundled object store. Hand the folder over",
+		"intact, and keep a copy of that key somewhere safe. The .env.example next",
+		"to it carries the same variables with no values, for committing.",
 		...args.offline ? [] : [
 			"",
 			`Whoever runs this needs to reach ${templateInput.baseImage} once, to pull it.`,
@@ -49440,181 +49933,6 @@ var createPackageCommand = defineVerb({
 	handler: ({ ctx, args }) => runPackage(ctx, args)
 });
 //#endregion
-//#region src/dev/extract-config-schema.ts
-/** Directory the extracted artifact lives in, relative to the workspace root.
-*  A subdir of its own, parallel to the workflow well-known tree. */
-var CONFIG_WELL_KNOWN_DIR = ".well-known/config/v1";
-/** The shipped artifact: the single JSON Schema (JSON only, no live sidecar). */
-var CONFIG_SCHEMA_FILE = "config-schema.json";
-/** The intermediate esbuild bundle (harmless to leave behind, like the workflow
-*  sidecar). NOT the deliverable — `config-schema.json` is. */
-var CONFIG_SCHEMA_BUNDLE = "config-schema.mjs";
-/**
-* Extract the workspace's single config JSON Schema. Defensive by contract: an
-* absent `config.schema.ts` degrades to `null` SILENTLY (the editor stays
-* free-form); a DECLARED-but-inconvertible schema degrades to `null` plus one
-* noisy warning; and a total bundle failure degrades to `null` plus one coarse
-* warning. It NEVER throws — a broken config schema must not break the dev build.
-*/
-var extractConfigSchema = async (projectRoot, opts = {}) => {
-	const loader = opts.loader ?? defaultConfigSchemaLoader;
-	const warnings = [];
-	const emit = (msg) => {
-		warnings.push(msg);
-		opts.logger?.warn(msg);
-	};
-	let loaded;
-	try {
-		loaded = await loader(projectRoot);
-	} catch (err) {
-		emit(`[config-schema] config schema extraction bundle failed; no config schema is available — the Config editor will fall back to a raw JSON field. Cause: ${errMessage(err)}`);
-		return {
-			schema: null,
-			warnings
-		};
-	}
-	if (loaded.configSchema == null) return {
-		schema: null,
-		warnings
-	};
-	try {
-		return {
-			schema: loaded.toJsonSchema(loaded.configSchema),
-			warnings
-		};
-	} catch (err) {
-		emit(`[config-schema] config.schema.ts could not be converted to JSON Schema — the Config editor will fall back to a raw JSON field. Cause: ${errMessage(err)}`);
-		return {
-			schema: null,
-			warnings
-		};
-	}
-};
-/**
-* Extract the config schema and WRITE the artifact. When the schema is non-null,
-* writes `<projectRoot>/.well-known/config/v1/config-schema.json` (compact JSON,
-* like `manifest.json`) and returns `written: true`. When the schema is null
-* (absent or inconvertible), REMOVES any stale `config-schema.json` so a deleted
-* or broken schema does not leave a phantom artifact, and returns `written:
-* false`. Never throws (mirrors `extractConfigSchema`).
-*/
-var buildConfigSchema = async (projectRoot, opts = {}) => {
-	const { schema, warnings } = await extractConfigSchema(projectRoot, opts);
-	const outfile = resolve(projectRoot, CONFIG_WELL_KNOWN_DIR, CONFIG_SCHEMA_FILE);
-	if (schema == null) {
-		await rm(outfile, { force: true });
-		return {
-			schema: null,
-			warnings,
-			written: false
-		};
-	}
-	await mkdir(resolve(projectRoot, CONFIG_WELL_KNOWN_DIR), { recursive: true });
-	await writeFile(outfile, JSON.stringify(schema), "utf8");
-	return {
-		schema,
-		warnings,
-		written: true
-	};
-};
-var errMessage = (err) => err instanceof Error ? err.message : String(err);
-/**
-* The default loader: when `config.schema.ts` exists at the project root, emit an
-* entry that re-exports ONLY its `configSchema` (static member access for
-* tree-shaking), esbuild-bundle it to
-* `<projectRoot>/.well-known/config/v1/config-schema.mjs`, import it back, and
-* read `configSchema` + `toJsonSchema`. When the file is ABSENT, return
-* `{ configSchema: null, toJsonSchema: () => null }` WITHOUT bundling — an absent
-* schema is silent, not a warning.
-*
-* Resolved FROM THE PROJECT: esbuild + zod come from the workspace's own
-* node_modules (like `buildWorkflows` resolves `@workflow/builders`), so the
-* bundle uses the SAME zod the schema was authored with and the heavy esbuild
-* tree stays out of the published CLI bundle.
-*/
-var defaultConfigSchemaLoader = async (projectRoot) => {
-	try {
-		await access(resolve(projectRoot, CONFIG_SCHEMA_SOURCE));
-	} catch {
-		return {
-			configSchema: null,
-			toJsonSchema: () => null
-		};
-	}
-	const projectRequire = createRequire(resolve(projectRoot, "package.json"));
-	let esbuild;
-	try {
-		esbuild = await import(pathToFileURL(projectRequire.resolve("esbuild")).href);
-	} catch (err) {
-		throw new Error(`Cannot resolve esbuild from the workspace (needed to extract the config schema). Cause: ${errMessage(err)}`);
-	}
-	const entry = buildEntrySource();
-	const outfile = resolve(projectRoot, CONFIG_WELL_KNOWN_DIR, CONFIG_SCHEMA_BUNDLE);
-	await esbuild.build({
-		stdin: {
-			contents: entry,
-			resolveDir: projectRoot,
-			sourcefile: "config-schema-entry.ts",
-			loader: "ts"
-		},
-		bundle: true,
-		packages: "external",
-		format: "esm",
-		platform: "node",
-		target: "node22",
-		treeShaking: true,
-		outfile,
-		logLevel: "silent"
-	});
-	const mod = await import(`${pathToFileURL(outfile).href}?v=${Date.now()}`);
-	if (typeof mod.toJsonSchema !== "function") throw new Error(`config-schema.mjs did not export the expected { configSchema, toJsonSchema } shape.`);
-	return {
-		configSchema: mod.configSchema ?? null,
-		toJsonSchema: mod.toJsonSchema
-	};
-};
-/**
-* Generate the bundle entry source. It NAMESPACE-imports `config.schema.ts` and
-* reads `configSchema` with DIRECT static member access — so esbuild tree-shakes
-* everything else and a MISSING export is simply `undefined` (→ `null`), never a
-* bundle-breaking "no matching export".
-*
-* The converter is REPLICATED here (not imported from the workflow extractor): it
-* runs inside the emitted `.mjs` with the PROJECT's own zod. It is byte-for-byte
-* the workflow extractor's converter MINUS the `half` parameter — config is a
-* single input-shaped object, so the Standard-Schema fallback invokes the
-* `.input` converter directly.
-*/
-var buildEntrySource = () => {
-	return [
-		`import { z } from 'zod';`,
-		`import * as cfg from './config.schema.ts';`,
-		`// Non-Zod Standard Schema fallback. Per @standard-schema/spec, ~standard`,
-		`// .jsonSchema is a Converter { input(opts), output(opts) } of FUNCTIONS — so`,
-		`// we INVOKE the input converter to get the actual JSON Schema (config is an`,
-		`// input-shaped object). Returning the Converter object verbatim folds`,
-		`// non-serialisable functions that JSON.stringify drops → a phantom {} schema.`,
-		`const std = (s) => {`,
-		`  const c = s && s['~standard'] && s['~standard'].jsonSchema;`,
-		`  const fn = c && c.input;`,
-		`  return typeof fn === 'function' ? fn({ target: 'draft-2020-12' }) : null;`,
-		`};`,
-		`const carriesFns = (o) =>`,
-		`  o != null && typeof o === 'object' && Object.values(o).some((v) => typeof v === 'function');`,
-		`export const toJsonSchema = (s) => {`,
-		`  if (s == null) return null;`,
-		`  let out;`,
-		`  try { out = z.toJSONSchema(s); }`,
-		`  catch (e) { out = std(s); if (out == null) throw e; }`,
-		`  // A result carrying functions is a non-serialisable phantom; degrade to`,
-		`  // null + a noisy warning instead of writing garbage to the artifact.`,
-		`  if (carriesFns(out)) throw new Error('schema is non-serialisable (carries functions)');`,
-		`  return out;`,
-		`};`,
-		`export const configSchema = cfg.configSchema ?? null;`
-	].join("\n");
-};
-//#endregion
 //#region src/dev/generate-config-types.ts
 /** Path of the generated artifact relative to the agent root. */
 var CONFIG_TYPES_RELATIVE_PATH = join(".stackbone", "config.d.ts");
@@ -54060,7 +54378,7 @@ var buildHandler$2 = (ctx, flags) => protectedCommand(async (innerCtx) => {
 			tunnelUrl: session.publicUrl,
 			localUrl: session.emulatorUrl,
 			deeplink,
-			contractVersion: 14,
+			contractVersion: 15,
 			capabilityCount: EMULATOR_CAPABILITIES.length,
 			agentName: agent.name,
 			colors: process.stdout.isTTY === true
@@ -55386,9 +55704,10 @@ new version means deploying a new image and re-running \`link\`.
 
 Turn this project into a folder someone else can run, with no access to
 Stackbone and no knowledge of it. The folder holds your compiled workspace and
-four generated files: a two-line \`Dockerfile\`, a \`docker-compose.yml\` that also
-brings up a Postgres and a Redis, an \`.env\` carrying a freshly generated
-\`STACKBONE_SECRET_KEY\`, and a \`README.md\` written for whoever receives it.
+five generated files: a two-line \`Dockerfile\`, a \`docker-compose.yml\` that also
+brings up a Postgres, a Redis and an object store, an \`.env\` carrying freshly
+generated secrets, an \`.env.example\` you can commit, and a \`README.md\` written
+for whoever receives it.
 
 \`\`\`sh
 stackbone package                          # writes dist/deploy
@@ -55423,9 +55742,10 @@ What lands in the output directory:
 dist/deploy/
   workspace/          # the compiled bundle, exactly what \`stackbone build\` writes
   Dockerfile          # FROM the published runtime base, COPY workspace/
-  docker-compose.yml  # the agent, a Postgres with pgvector, a Redis
-  .env                # a generated STACKBONE_SECRET_KEY; nothing you must fill in
-  README.md           # how to start it, use your own database, run it without Compose
+  docker-compose.yml  # the agent, a Postgres with pgvector, a Redis, a MinIO
+  .env                # generated secrets; nothing you must fill in
+  .env.example        # the same variables with no values, safe to commit
+  README.md           # how to start it, use your own services, run it without Compose
   agent-image.tar     # only with --offline
 \`\`\`
 
@@ -55442,8 +55762,9 @@ to build. That variant needs Docker installed and running where you package, and
 it emits no \`build:\` block in the compose file: building is the thing the flag
 exists to avoid.
 
-**Two things to tell whoever runs it.** Both are already in the generated
-README, and both fail in a way that reads like a bug in your agent.
+**Three things to tell whoever runs it.** All three are already in the
+generated README, and all three fail in a way that reads like a bug in your
+agent.
 
 The database needs the **\`pgvector\` extension available**. The first boot runs
 \`CREATE EXTENSION IF NOT EXISTS vector\` while creating its schema, so a stock
@@ -55453,6 +55774,16 @@ Postgres applies most of the schema and then stops with
 of your own and the extension has to be available there, which on many managed
 databases only an administrator can create.
 
+**Downloads from the dashboard's file browser need a reachable endpoint.** The
+bundled MinIO answers to \`http://minio:9000\`, a name that only exists inside the
+Compose network. Everything the agent itself does with files works with that
+address, and so does RAG ingestion. A download link is the exception: the
+dashboard signs it and hands it to a **browser**, which cannot resolve that
+name. If anyone will download files, set \`STACKBONE_S3_ENDPOINT\` in \`.env\` to an
+address both the container and the browser reach, such as
+\`http://the-host-you-run-this-on:9000\`. Port \`9000\` is published for exactly
+that.
+
 **The agent serves on port 8080, or on \`PORT\` when the host sets one.** Hosts
 that assign a port and expect the application to adopt it (Cloud Run, Railway,
 Heroku, App Runner) need no extra configuration. Point their health check at
@@ -55460,9 +55791,23 @@ Heroku, App Runner) need no extra configuration. Point their health check at
 while \`/health\` also probes the database, which the very first boot is still
 creating.
 
+**Using a managed bucket instead.** Any S3-compatible storage works (AWS S3,
+Cloudflare R2, Azure Blob, Google Cloud Storage, another MinIO). Create the
+bucket first, because the agent never creates one, then fill in the
+\`STACKBONE_S3_*\` variables in \`.env\`. One of them decides how the bucket is
+addressed: \`STACKBONE_S3_FORCE_PATH_STYLE=true\` puts the bucket in the path
+(\`https://host/bucket/key\`), which MinIO and Cloudflare R2 accept, and \`false\`
+puts it in a subdomain (\`https://bucket.host/key\`), which AWS S3 expects. The
+wrong value fails every call with \`NoSuchBucket\` or a bare 403 while the
+credentials are valid, so check it before you suspect the keys.
+
 **Hand the folder over intact.** The generated \`.env\` holds the only copy of
 \`STACKBONE_SECRET_KEY\`, and everything the agent stores is encrypted with it.
-Losing it or changing it makes those secrets unreadable, with no recovery.
+Losing it or changing it makes those secrets unreadable, with no recovery. It
+also holds \`MINIO_ROOT_PASSWORD\` for the bundled object store, which the Compose
+file refuses to start without. The \`.env.example\` next to it carries the same
+variables with no values, so the folder can go into a repository while the \`.env\`
+stays out of it.
 
 **JSON payload**
 
@@ -55470,7 +55815,7 @@ Losing it or changing it makes those secrets unreadable, with no recovery.
 {
   "schema_version": 1,
   "outDir": "/abs/path/dist/deploy",
-  "files": ["Dockerfile", "docker-compose.yml", ".env", "README.md"],
+  "files": ["Dockerfile", "docker-compose.yml", ".env", ".env.example", "README.md"],
   "imageTag": "acme-agent:latest",
   "baseImage": "ghcr.io/stackbone/stackbone-workspace-runtime:node24-base",
   "workflows": ["onboarding", "rag-ingest", "mapping-suggest"],
@@ -55504,6 +55849,7 @@ What lands in the output directory:
 \`\`\`text
 dist/workspace-bundle/
   .well-known/workspace.json                    # the manifest the runtime reads first
+  .well-known/config/v1/config-schema.json      # your config.schema.ts, as JSON Schema
   .well-known/workflow/v1/step.mjs              # your compiled workflow steps
   .well-known/workflow/v1/workflow.vm.js        # the workflow bundle the VM runs
   .well-known/workflow/v1/manifest.json         # workflow ids, schemas, schedules
@@ -55523,6 +55869,14 @@ the container logs a warning naming the file and starts runs **unvalidated** —
 a start that your laptop rejects would be accepted in production. The warning is
 the thing to grep for after a deploy.
 
+\`config-schema.json\` is your \`config.schema.ts\`, converted to JSON Schema at
+build time. The container has no TypeScript, so it reads this file to render the
+config form in the dashboard and to validate every save. Write no
+\`config.schema.ts\` and the build ships no file, which is fine: config stays
+free-form. Write one the build cannot convert and it warns instead of failing,
+ships without the file, and the dashboard falls back to a raw JSON field with no
+validation on save. See [\`stackbone.config\`](/docs/sdk/config#typed-config).
+
 Each deep agent is bundled with its own dependencies inlined, except for the
 packages that must stay a single copy per process. If one of your dependencies
 cannot survive bundling, keep it out with \`build.external\`. See
@@ -56808,19 +57162,20 @@ datastores locally as in production**. You import that client directly
 inside a tool's execution or a workflow \`'use step'\`; there is no handler
 wiring to configure.
 
-| Variable                  | Points at                                                                                  |
-| ------------------------- | ------------------------------------------------------------------------------------------ |
-| \`PORT\`                    | The port the emulator listens on.                                                          |
-| \`STACKBONE_POSTGRES_URL\`  | Local Postgres on \`:5433\` with the \`stackbone_dev\` database.                               |
-| \`STACKBONE_S3_ENDPOINT\`   | MinIO on \`:9004\`.                                                                          |
-| \`STACKBONE_S3_BUCKET\`     | \`stackbone-dev\`.                                                                           |
-| \`STACKBONE_S3_ACCESS_KEY\` | \`stackbone\`.                                                                               |
-| \`STACKBONE_S3_SECRET_KEY\` | \`stackbone-secret\`.                                                                        |
-| \`STACKBONE_S3_REGION\`     | \`us-east-1\` (MinIO accepts any region).                                                    |
-| \`STACKBONE_AGENT_ID\`      | The slug of the workspace (the multi-tenant key prefix for storage and observability).     |
-| \`WORKFLOW_REDIS_URL\`      | Local Redis on \`:6380\`, the durable backend the workflow runtime replays from.             |
-| \`MODEL_PROVIDER_API_KEY\`  | The model-provider key, when one resolves (see below). Absent for a keyless local gateway. |
-| \`MODEL_PROVIDER_BASE_URL\` | The OpenAI-compatible base URL, when one resolves. Absent means the OpenRouter default.    |
+| Variable                        | Points at                                                                                                        |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| \`PORT\`                          | The port the emulator listens on.                                                                                |
+| \`STACKBONE_POSTGRES_URL\`        | Local Postgres on \`:5433\` with the \`stackbone_dev\` database.                                                     |
+| \`STACKBONE_S3_ENDPOINT\`         | MinIO on \`:9004\`.                                                                                                |
+| \`STACKBONE_S3_BUCKET\`           | \`stackbone-dev\`.                                                                                                 |
+| \`STACKBONE_S3_ACCESS_KEY\`       | \`stackbone\`.                                                                                                     |
+| \`STACKBONE_S3_SECRET_KEY\`       | \`stackbone-secret\`.                                                                                              |
+| \`STACKBONE_S3_REGION\`           | \`us-east-1\` (MinIO accepts any region).                                                                          |
+| \`STACKBONE_S3_FORCE_PATH_STYLE\` | \`true\`, the addressing style MinIO speaks. See [\`stackbone.storage\`](/docs/sdk/storage#path-style-or-subdomain). |
+| \`STACKBONE_AGENT_ID\`            | The slug of the workspace (the multi-tenant key prefix for storage and observability).                           |
+| \`WORKFLOW_REDIS_URL\`            | Local Redis on \`:6380\`, the durable backend the workflow runtime replays from.                                   |
+| \`MODEL_PROVIDER_API_KEY\`        | The model-provider key, when one resolves (see below). Absent for a keyless local gateway.                       |
+| \`MODEL_PROVIDER_BASE_URL\`       | The OpenAI-compatible base URL, when one resolves. Absent means the OpenRouter default.                          |
 
 > See [Configuration → Environment variables](/docs/cli/configuration#environment-variables)
 > for the full list.
@@ -58823,14 +59178,31 @@ A deployed agent never configures storage by hand. The runtime injects these
 environment variables when your container boots, and the ambient \`stackbone\`
 client reads them on first use:
 
-| Env var the runtime injects | Holds                                                          |
-| --------------------------- | -------------------------------------------------------------- |
-| \`STACKBONE_S3_ACCESS_KEY\`   | Access key for the agent's physical bucket.                    |
-| \`STACKBONE_S3_SECRET_KEY\`   | Secret access key.                                             |
-| \`STACKBONE_S3_ENDPOINT\`     | S3-compatible endpoint (MinIO in \`stackbone dev\`).             |
-| \`STACKBONE_S3_BUCKET\`       | The physical bucket your logical buckets are namespaced under. |
-| \`STACKBONE_S3_REGION\`       | Region, defaults to \`'us-east-1'\` when unset.                  |
-| \`STACKBONE_AGENT_ID\`        | The agent identity prepended to every key.                     |
+| Env var the runtime injects     | Holds                                                          |
+| ------------------------------- | -------------------------------------------------------------- |
+| \`STACKBONE_S3_ACCESS_KEY\`       | Access key for the agent's physical bucket.                    |
+| \`STACKBONE_S3_SECRET_KEY\`       | Secret access key.                                             |
+| \`STACKBONE_S3_ENDPOINT\`         | S3-compatible endpoint (MinIO in \`stackbone dev\`).             |
+| \`STACKBONE_S3_BUCKET\`           | The physical bucket your logical buckets are namespaced under. |
+| \`STACKBONE_S3_REGION\`           | Region, defaults to \`'us-east-1'\` when unset.                  |
+| \`STACKBONE_S3_FORCE_PATH_STYLE\` | How the bucket is addressed. Defaults to \`true\`.               |
+| \`STACKBONE_AGENT_ID\`            | The agent identity prepended to every key.                     |
+
+### Path-style or subdomain
+
+\`STACKBONE_S3_FORCE_PATH_STYLE\` decides where the bucket name goes in the URL,
+and different backends disagree:
+
+| Value            | URL shape                 | Backends that want it   |
+| ---------------- | ------------------------- | ----------------------- |
+| \`true\` (default) | \`https://host/bucket/key\` | MinIO, Cloudflare R2    |
+| \`false\`          | \`https://bucket.host/key\` | AWS S3, Railway Buckets |
+
+The default is \`true\` because that is what MinIO speaks, and MinIO is what
+\`stackbone dev\` runs. If your deployment points at a bucket that only answers to
+the subdomain form, every call fails with \`NoSuchBucket\` or a bare 403 even
+though the credentials are correct. That is the symptom of this one variable, so
+check it before you conclude the keys are wrong.
 
 If you need explicit configuration (for a local script or a test) you can
 pass an \`s3\` block to \`createClient()\` instead of relying on the injected env:
@@ -58844,7 +59216,8 @@ const sb = createClient({
     secretAccessKey: '…',
     endpoint: 'http://localhost:9000',
     bucket: 'my-bucket',
-    // region defaults to 'auto'
+    // region defaults to 'us-east-1'
+    // forcePathStyle defaults to true; set false for AWS S3
   },
   agentId: 'local-agent',
 });
@@ -58852,9 +59225,9 @@ const bucket = sb.storage.from('uploads');
 \`\`\`
 
 Missing any required value surfaces \`s3_credentials_missing\`,
-\`s3_bucket_missing\` or \`agent_id_missing\` with a hint naming what to set:
-\`region\` is the only one that never trips the missing-credential
-errors because of the \`'auto'\` default.
+\`s3_bucket_missing\` or \`agent_id_missing\` with a hint naming what to set.
+\`region\` and \`forcePathStyle\` never trip those errors, because both carry a
+default (\`'us-east-1'\` and \`true\`).
 
 ## Upload, download, list, remove
 
@@ -60134,7 +60507,10 @@ export const configSchema = z.object({
 
 That one file drives three things at once: the form the operator sees in
 the dashboard, the validation applied when they save, and your types.
-Generate the types with:
+
+\`stackbone build\` converts the schema to JSON Schema and writes it into
+the bundle, so a deployed container renders the same form your laptop
+does. Generate the types with:
 
 \`\`\`sh
 stackbone config types
@@ -60621,22 +60997,23 @@ workspace works zero-config locally. Each variable falls back to a typed
 config field if you pass one to \`createClient\`, but you rarely need to:
 the runtime provides them all:
 
-| Env var                     | Feeds                                   | Provided by \`stackbone dev\` |
-| --------------------------- | --------------------------------------- | --------------------------- |
-| \`STACKBONE_API_URL\`         | Control-plane calls                     | ✅ (local tunnel)           |
-| \`STACKBONE_INSTALLATION_ID\` | Identifies the install                  | ✅                          |
-| \`STACKBONE_AGENT_ID\`        | Workspace identity + storage key prefix | ✅                          |
-| \`HMAC_SECRET\`               | Signs Stackbone Connect broker calls    | ✅                          |
-| \`STACKBONE_POSTGRES_URL\`    | \`stackbone.database\` + \`stackbone.rag\`  | ✅ (local Postgres)         |
-| \`STACKBONE_SECRET_KEY\`      | Decrypts \`stackbone.secrets\`            | ✅                          |
-| \`WORKFLOW_REDIS_URL\`        | Durable workflow execution backend      | ✅ (local Redis)            |
-| \`STACKBONE_S3_ENDPOINT\`     | \`stackbone.storage\`                     | ✅ (local MinIO)            |
-| \`STACKBONE_S3_BUCKET\`       | \`stackbone.storage\`                     | ✅ (\`stackbone-dev\`)        |
-| \`STACKBONE_S3_ACCESS_KEY\`   | \`stackbone.storage\`                     | ✅                          |
-| \`STACKBONE_S3_SECRET_KEY\`   | \`stackbone.storage\`                     | ✅                          |
-| \`STACKBONE_S3_REGION\`       | \`stackbone.storage\`                     | ✅                          |
-| \`MODEL_PROVIDER_API_KEY\`    | \`stackbone.ai\`                          | ❗ **you supply it**        |
-| \`MODEL_PROVIDER_BASE_URL\`   | \`stackbone.ai\` (override)               | ❗ **you supply it**        |
+| Env var                         | Feeds                                   | Provided by \`stackbone dev\` |
+| ------------------------------- | --------------------------------------- | --------------------------- |
+| \`STACKBONE_API_URL\`             | Control-plane calls                     | ✅ (local tunnel)           |
+| \`STACKBONE_INSTALLATION_ID\`     | Identifies the install                  | ✅                          |
+| \`STACKBONE_AGENT_ID\`            | Workspace identity + storage key prefix | ✅                          |
+| \`HMAC_SECRET\`                   | Signs Stackbone Connect broker calls    | ✅                          |
+| \`STACKBONE_POSTGRES_URL\`        | \`stackbone.database\` + \`stackbone.rag\`  | ✅ (local Postgres)         |
+| \`STACKBONE_SECRET_KEY\`          | Decrypts \`stackbone.secrets\`            | ✅                          |
+| \`WORKFLOW_REDIS_URL\`            | Durable workflow execution backend      | ✅ (local Redis)            |
+| \`STACKBONE_S3_ENDPOINT\`         | \`stackbone.storage\`                     | ✅ (local MinIO)            |
+| \`STACKBONE_S3_BUCKET\`           | \`stackbone.storage\`                     | ✅ (\`stackbone-dev\`)        |
+| \`STACKBONE_S3_ACCESS_KEY\`       | \`stackbone.storage\`                     | ✅                          |
+| \`STACKBONE_S3_SECRET_KEY\`       | \`stackbone.storage\`                     | ✅                          |
+| \`STACKBONE_S3_REGION\`           | \`stackbone.storage\`                     | ✅                          |
+| \`STACKBONE_S3_FORCE_PATH_STYLE\` | \`stackbone.storage\`                     | ✅ (\`true\`)                 |
+| \`MODEL_PROVIDER_API_KEY\`        | \`stackbone.ai\`                          | ❗ **you supply it**        |
+| \`MODEL_PROVIDER_BASE_URL\`       | \`stackbone.ai\` (override)               | ❗ **you supply it**        |
 
 The two model-provider values are the only ones you bring yourself, and you
 have two ways to do it: export them in your shell, or save them once on the
@@ -63304,7 +63681,7 @@ var createInitCommand = (ctx) => defineCommand({
 });
 //#endregion
 //#region src/services/deployments.service.ts
-init_src$12();
+init_src$11();
 init_src$13();
 var registerDeployment = async (ctx, body) => {
 	return parseResponse$1(deploymentResponseSchema, await ctx.http.post("/api/v1/deployments", body), "POST /api/v1/deployments");
@@ -63318,7 +63695,7 @@ var readIdentityVerification = async (response) => {
 		return "unknown";
 	}
 	const state = body?.identityVerification;
-	return state === "armed" || state === "unarmed" ? state : "unknown";
+	return state === "armed" || state === "unarmed" || state === "untaught" ? state : "unknown";
 };
 var verifyDeploymentSecret = async (args) => {
 	const fetchImpl = args.fetchImpl ?? fetch;
@@ -63361,6 +63738,151 @@ var verifyDeploymentSecret = async (args) => {
 	});
 	return readIdentityVerification(response);
 };
+/**
+* STA-594/595 — tell the box which installation it answers for, the step between
+* proving the secret and writing the deployment.
+*
+* The browser wizard has always done this; `link` did not, and the box that
+* results is worse than unregistered: it refuses every browser and every CLI call
+* with a 401, because a box that was never taught answers for nothing. So this is
+* fail-closed like the challenge above it — a box that cannot be taught is not
+* registered at all, rather than registered and mute.
+*
+* Signed with the SAME secret the challenge proved, over METHOD.path.BODY, so the
+* exact bytes sent are the exact bytes signed: a body swapped in flight no longer
+* verifies and the box cannot be pointed at somebody else's installation.
+*/
+var teachDeploymentIdentity = async (args) => {
+	const fetchImpl = args.fetchImpl ?? fetch;
+	const teachUrl = new URL(CONTROL_PLANE_IDENTITY_PATH, args.url).toString();
+	const body = JSON.stringify({
+		installationId: args.installationId,
+		organizationId: args.organizationId
+	});
+	const header = buildStackboneSignatureHeader({
+		secrets: [args.secret],
+		payload: proxyRequestPayload({
+			method: "POST",
+			path: CONTROL_PLANE_IDENTITY_PATH,
+			body
+		})
+	});
+	let response;
+	try {
+		response = await fetchImpl(teachUrl, {
+			method: "POST",
+			headers: {
+				"stackbone-signature": header,
+				"content-type": "application/json"
+			},
+			body
+		});
+	} catch (cause) {
+		throw new StackboneCliError({
+			code: "generic",
+			message: `Could not reach the deployed container at ${args.url} to tell it which installation it answers for`,
+			suggestion: "Check the box is still reachable, then re-run `stackbone link`. Nothing was registered.",
+			cause
+		});
+	}
+	if (response.ok) return;
+	if (response.status === 404) throw new StackboneCliError({
+		code: "generic",
+		message: `The container at ${args.url} runs an image from before boxes could be told which installation they answer for, so it would refuse every browser and every CLI call`,
+		suggestion: "Upgrade the image and re-run `stackbone link`. Nothing was registered."
+	});
+	throw new StackboneCliError({
+		code: "generic",
+		message: `The container at ${args.url} could not record which installation it answers for: ${await readRefusal(response)}`,
+		suggestion: "Fix what the box reported, then re-run `stackbone link`. Nothing was registered."
+	});
+};
+/** The box's own sentence when it has one, and its status code when it does not. */
+var readRefusal = async (response) => {
+	try {
+		const message = (await response.json())?.message;
+		if (typeof message === "string" && message.length > 0) return message;
+	} catch {}
+	return `it answered ${response.status}`;
+};
+//#endregion
+//#region src/services/handshake.service.ts
+init_src$13();
+/** Public, credential-free handshake every deployed box serves. */
+var CONTRACT_PATH = "/api/contract";
+/**
+* Something is at that address, but it is not a Stackbone box: a gateway's error
+* page, a company site, a load balancer in front of the wrong service. Kept
+* distinct from "nothing answered" because the remedy is different — one is an
+* address to correct, the other a machine to go and look at.
+*/
+var notAHandshake = (url, status, cause) => new StackboneCliError({
+	code: "generic",
+	message: `${url} answered with HTTP ${status}, but not with a Stackbone box handshake`,
+	suggestion: "Check --url points at the box itself: a company site, or a load balancer in front of the wrong service, answers just like this.",
+	cause
+});
+/**
+* Asks a box which protocol version it speaks, before it is registered.
+*
+* Uses a DIRECT `fetch` — `ctx.http` refuses absolute URLs on purpose (it only
+* ever talks to the control plane), and this is a cross-host call to the
+* customer's own box. The handshake is public and takes no credential, which is
+* what makes it usable here: at this point in `link` nothing has been registered,
+* so there is no identity to present anyway.
+*/
+var readBoxContract = async (args) => {
+	const fetchImpl = args.fetchImpl ?? fetch;
+	let contractUrl;
+	try {
+		contractUrl = new URL(CONTRACT_PATH, args.url).toString();
+	} catch (cause) {
+		throw new StackboneCliError({
+			code: "generic",
+			message: `--url is not a valid URL: ${args.url}`,
+			suggestion: "Pass the full public URL of the deployed agent, e.g. https://agent.example.com",
+			cause
+		});
+	}
+	let response;
+	try {
+		response = await fetchImpl(contractUrl, { method: "GET" });
+	} catch (cause) {
+		throw new StackboneCliError({
+			code: "generic",
+			message: `Nothing answered at ${args.url}, so there is no way to read which protocol version that box speaks`,
+			suggestion: "Check --url is the public address of the running container and that this machine can reach it.",
+			cause
+		});
+	}
+	let body;
+	try {
+		body = await response.json();
+	} catch (cause) {
+		throw notAHandshake(args.url, response.status, cause);
+	}
+	const parsed = contractResponseSchema.safeParse(body);
+	if (!response.ok || !parsed.success) throw notAHandshake(args.url, response.status, parsed.success ? body : parsed.error);
+	return parsed.data;
+};
+/**
+* Refuses a box this product cannot register, whatever door it came through.
+*
+* Pure and total: it reads the version the handshake reported and nothing else.
+* The floor is `MIN_SUPPORTED_DEPLOYMENT_REGISTRATION_CONTRACT_VERSION`, NOT the
+* SDK-wide `MIN_SUPPORTED_CONTRACT_VERSION` — that one is 1, the handshake schema
+* already refuses anything below 1, and a guard built on it could never fire.
+* The sentence comes from the shared source the browser wizard prints too, so an
+* operator who tries the other door reads the same story about the same box.
+*/
+var assertBoxCanBeRegistered = (contract) => {
+	if (supportsDeploymentRegistration(contract.version)) return;
+	throw new StackboneCliError({
+		code: "generic",
+		message: deploymentRegistrationRefusal(contract.version),
+		suggestion: "Re-run `stackbone link` once the box is running a current image."
+	});
+};
 //#endregion
 //#region src/commands/link/link.command.ts
 var requireLinkField = (value, flag, description) => {
@@ -63390,6 +63912,7 @@ var requireLinkField = (value, flag, description) => {
 */
 var identityVerificationWarning = (state) => {
 	if (state === "armed") return null;
+	if (state === "untaught") return "This box verifies browser identity but has not been told which installation it answers for, so it refuses every browser and every CLI call. Register it — `stackbone link` does this for you.";
 	if (state === "unarmed") return "This box does not verify browser identity, so Studio and the CLI cannot reach it — the deployment is registered, but every screen and every box command will be refused with a 401. Set STACKBONE_CONTROL_PLANE_URL on the container to your control plane address and restart it.";
 	return "This box does not report whether it verifies browser identity — it runs an image from before boxes said so. The deployment is registered either way; upgrade the image to find out whether Studio can reach it at all.";
 };
@@ -63448,23 +63971,34 @@ var runLink = async (ctx, args) => {
 	const activeOrg = await getActiveOrganization(ctx);
 	const agent = await getAgentByOwnerAndSlug(ctx, activeOrg.slug, chosenSlug);
 	if (!ctx.flags.json) log.step(`Linking ${targetDir} to ${agent.slug}`);
+	if (!ctx.flags.json) log.step("Reading the box protocol version");
+	assertBoxCanBeRegistered(await readBoxContract({ url }));
 	if (!ctx.flags.json) log.step("Verifying the --secret against the deployed container");
-	const identityVerification = await verifyDeploymentSecret({
+	const challengeVerification = await verifyDeploymentSecret({
 		url,
 		secret
 	});
-	const identityWarning = identityVerificationWarning(identityVerification);
-	if (identityWarning && !ctx.flags.json) log.warn(identityWarning);
-	const [localDev, deployment] = await Promise.all([upsertLocalDevInstallation(ctx, {
+	const localDev = await upsertLocalDevInstallation(ctx, {
 		creatorOrganizationSlug: activeOrg.slug,
 		agentTemplateSlug: agent.slug
-	}), registerDeployment(ctx, {
+	});
+	if (!ctx.flags.json) log.step("Telling the box which installation it answers for");
+	await teachDeploymentIdentity({
+		url,
+		secret,
+		installationId: localDev.id,
+		organizationId: localDev.organizationId
+	});
+	const identityVerification = challengeVerification === "untaught" ? "armed" : challengeVerification;
+	const identityWarning = identityVerificationWarning(identityVerification);
+	if (identityWarning && !ctx.flags.json) log.warn(identityWarning);
+	const deployment = await registerDeployment(ctx, {
 		organizationSlug: activeOrg.slug,
 		agentSlug: agent.slug,
 		url,
 		hmacSecret: secret,
 		imageTag: tag
-	})]);
+	});
 	await writeProjectConfig(ctx, agent, {
 		root: targetDir,
 		force: true
@@ -65746,7 +66280,7 @@ if (shouldReexecUnderWinpty({
 if (isVersionFlag(rawArgs)) {
 	process.stdout.write(`${formatVersionOutput({
 		cliVersion: STACKBONE_CLI_BUILD_VERSION,
-		contractVersion: 14
+		contractVersion: 15
 	})}\n`);
 	process.exit(0);
 }