@azx-pbc/helix-cli 0.2.0 → 0.4.0

package/dist/helix.js

@@ -10,7 +10,9 @@ var options = {
   token: { type: "string" },
   promote: { type: "boolean" },
   "display-name": { type: "string" },
+  description: { type: "string" },
   visibility: { type: "string" },
+  path: { type: "string" },
   help: { type: "boolean" }
 };
 function parseCliArgs(argv) {
@@ -19,33 +21,94 @@ function parseCliArgs(argv) {
 }
 
 // src/client.ts
-import { z as z19 } from "zod";
+import { z as z27 } from "zod";
 
 // ../shared/src/visibility.ts
 import { z } from "zod";
+var MAX_VISIBILITY_GROUPS = 10;
+var VisibilityGroupIdsSchema = z.array(z.string().min(1)).max(MAX_VISIBILITY_GROUPS);
 var VisibilitySchema = z.discriminatedUnion("mode", [
   z.object({ mode: z.literal("internal") }),
-  z.object({ mode: z.literal("group"), groupId: z.string().min(1) }),
+  z.object({ mode: z.literal("group"), groupIds: VisibilityGroupIdsSchema }),
   z.object({ mode: z.literal("password") }),
   z.object({ mode: z.literal("public") })
 ]);
 var VISIBILITY_MODES = ["internal", "group", "password", "public"];
 var VisibilityModeSchema = z.enum(VISIBILITY_MODES);
+function assertWritableGroupIds(ids) {
+  return ids.every((id) => !/[,\s]/.test(id));
+}
+var WRITABLE_GROUP_ID_MESSAGE = "a group id cannot contain a comma or whitespace (check for a pasted list)";
+var WritableVisibilitySchema = VisibilitySchema.refine(
+  (v) => v.mode !== "group" || assertWritableGroupIds(v.groupIds),
+  { message: WRITABLE_GROUP_ID_MESSAGE, path: ["groupIds"] }
+);
 
-// ../shared/src/app.ts
+// ../shared/src/directory.ts
 import { z as z2 } from "zod";
+var DirectoryGroupSchema = z2.object({
+  /** Object id — a GUID under Entra, a readable fixture id in dev. */
+  id: z2.string().min(1),
+  displayName: z2.string().min(1),
+  /**
+   * Whether this is a security group — the only kind the `groups` claim carries,
+   * so the only kind worth scoping an app to. Reported rather than filtered so
+   * the picker can mark an ineligible group with a reason instead of hiding it;
+   * "the group I searched for isn't listed" is a worse failure than a greyed-out
+   * row.
+   *
+   * **Absent means "not read", not "false".** The batch id→name resolve does not
+   * always return it, and defaulting an unread flag to `true` made the same group
+   * show as eligible in one view and ineligible in another depending on which
+   * query resolved last. A client should treat absent as eligible-but-unknown and
+   * never let it overwrite a value it does know.
+   */
+  securityEnabled: z2.boolean().optional()
+});
+var DIRECTORY_UNAVAILABLE_REASONS = [
+  "no-consent",
+  "no-credential",
+  "not-configured"
+];
+var DirectoryUnavailableReasonSchema = z2.enum(DIRECTORY_UNAVAILABLE_REASONS);
+var DirectoryGroupsResponseSchema = z2.discriminatedUnion("available", [
+  z2.object({
+    available: z2.literal(true),
+    groups: z2.array(DirectoryGroupSchema)
+  }),
+  z2.object({
+    available: z2.literal(false),
+    reason: DirectoryUnavailableReasonSchema,
+    /** Operator-facing sentence; the SPA shows it in the degradation banner. */
+    detail: z2.string().min(1),
+    /** The Graph permission an administrator would have to grant. */
+    missingPermission: z2.string().min(1).optional()
+  })
+]);
+
+// ../shared/src/app.ts
+import { z as z3 } from "zod";
 var SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
-var AppSchema = z2.object({
-  id: z2.uuid(),
-  slug: z2.string().min(1).max(63).regex(SLUG_PATTERN, "must be a lowercase DNS label (a-z, 0-9, hyphen)"),
-  displayName: z2.string().min(1).max(200),
+var APP_DESCRIPTION_MAX = 500;
+var AppSchema = z3.object({
+  id: z3.uuid(),
+  slug: z3.string().min(1).max(63).regex(SLUG_PATTERN, "must be a lowercase DNS label (a-z, 0-9, hyphen)"),
+  displayName: z3.string().min(1).max(200),
+  /**
+   * What the app is for, in one sentence. Plain text (≤ {@link APP_DESCRIPTION_MAX}
+   * chars) — it renders as a subtitle in list rows and the detail header, so
+   * markdown would invite a wall of text in a table cell. Optional on the wire
+   * like `url`/`ownerId`: the CLI parses this schema, and every row predating
+   * the field carries none. Never `null` — an unset description omits the key.
+   */
+  description: z3.string().max(APP_DESCRIPTION_MAX).optional(),
   visibility: VisibilitySchema,
   /** The version currently served; null before the first deploy. */
-  currentVersionId: z2.uuid().nullable(),
+  currentVersionId: z3.uuid().nullable(),
   /** When set, the app is archived: the edge serves 410 + Clear-Site-Data (§7). */
-  archivedAt: z2.iso.datetime().nullable(),
-  createdAt: z2.iso.datetime(),
-  updatedAt: z2.iso.datetime(),
+  archivedAt: z3.iso.datetime().nullable(),
+  createdAt: z3.iso.datetime(),
+  updatedAt: z3.iso.datetime(),
   /**
    * Where this app is served, computed control-plane-side from the deployment's
    * apps base (`APP_PUBLIC_BASE`) — so clients render a URL instead of
@@ -54,55 +117,514 @@ var AppSchema = z2.object({
    * CLI against an older portal. Clients that lack it fall back to composing the
    * slug onto `appPublicBase` from `GET /api/v1/config`.
    */
-  url: z2.url().optional()
-});
+  url: z3.url().optional(),
+  /**
+   * Who owns this app — the creator's Entra `oid` (ADR-0048). The **identity**
+   * half: this is what `scope=mine` and `ownsApp` compare against, and it is
+   * never what a screen renders.
+   *
+   * Optional for the same reason as `url`: the CLI parses this schema, and rows
+   * predating the approvals work carry no owner at all.
+   */
+  ownerId: z3.string().optional(),
+  /**
+   * The owner's claims as captured at create time. The **display** half: render
+   * these, never compare them. `ownerId` is the Entra `oid` (ADR-0048) — an
+   * opaque directory object id since the re-base, opaque-by-accident (an
+   * email) on rows created before it — so display travels separately. Absent
+   * for rows created before the columns existed; fall back to `ownerId` (the
+   * pre-re-base rows where it is still an email are the one case where the
+   * fallback renders something readable).
+   */
+  ownerName: z3.string().optional(),
+  ownerEmail: z3.string().optional()
+});
+var AppListItemSchema = AppSchema.extend({
+  /** When the most recent version was created; null before the first deploy. */
+  lastDeployAt: z3.iso.datetime().nullable(),
+  /** `number` of the version currently served; null before the first promote. */
+  liveVersionNumber: z3.int().positive().nullable(),
+  /** Highest `preview`-status version; null when none exists. */
+  latestPreviewNumber: z3.int().positive().nullable()
+});
+var APP_LIST_SCOPES = ["mine", "all"];
+var AppListScopeSchema = z3.enum(APP_LIST_SCOPES);
 
 // ../shared/src/version.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 var VERSION_STATUSES = ["preview", "live", "archived"];
-var VersionStatusSchema = z3.enum(VERSION_STATUSES);
-var VersionSchema = z3.object({
-  id: z3.uuid(),
-  appId: z3.uuid(),
+var VersionStatusSchema = z4.enum(VERSION_STATUSES);
+var DEPLOY_OUTCOMES = [
+  "canonical",
+  "rerooted",
+  "nested",
+  "ambiguous",
+  "unsalvageable"
+];
+var DeployReportSchema = z4.object({
+  /** The planner revision that produced this, for reading old rows later. */
+  plannerVersion: z4.int().nonnegative(),
+  outcome: z4.enum(DEPLOY_OUTCOMES),
+  /** The chosen bundle root (`""` = archive root). */
+  root: z4.string().max(1024),
+  /** How many files were uploaded after re-rooting. */
+  fileCount: z4.int().nonnegative(),
+  /** Count of dropped files, keyed by reason (junk/outside-root/…). */
+  drops: z4.record(z4.string().max(64), z4.int().nonnegative()).default({}),
+  /** Problem kinds surfaced (missing-reference, secret-dropped, …). */
+  problems: z4.array(z4.string().max(64)).max(50).default([]),
+  /** Candidate roots the planner considered. */
+  candidates: z4.array(z4.string().max(1024)).max(20).default([])
+});
+var VersionSchema = z4.object({
+  id: z4.uuid(),
+  appId: z4.uuid(),
   /** Monotonic per app, 1-based. */
-  number: z3.int().positive(),
+  number: z4.int().positive(),
   /** Blob key prefix for this version's assets, e.g. `apps/<appId>/7/`. */
-  blobPrefix: z3.string().min(1),
+  blobPrefix: z4.string().min(1),
   status: VersionStatusSchema,
-  createdAt: z3.iso.datetime()
+  createdAt: z4.iso.datetime(),
+  /** Client-asserted salvage provenance (ADR-0038); absent on CLI uploads. */
+  deployReport: DeployReportSchema.optional()
 });
 
 // ../shared/src/manifest.ts
-import { z as z4 } from "zod";
-var LlmCapabilitySchema = z4.object({
-  models: z4.array(z4.string()).default([]),
+import { z as z8 } from "zod";
+
+// ../shared/src/providers.ts
+import { z as z7 } from "zod";
+
+// ../shared/src/env.ts
+import { z as z5 } from "zod";
+var ENVS = ["prod", "dev"];
+var EnvSchema = z5.enum(ENVS);
+
+// ../shared/src/secrets.ts
+import { z as z6 } from "zod";
+var FORBIDDEN_HEADER_NAMES = /* @__PURE__ */ new Set([
+  "host",
+  "content-length",
+  "transfer-encoding",
+  "connection",
+  "te",
+  "upgrade",
+  "expect",
+  "trailer"
+]);
+var HEADER_TOKEN = /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/;
+var HEADER_VALUE_SAFE = /^[\t\x20-\x7e]*$/;
+var HEADER_VALUE_WIRE = /^[\t\x20-\x7e\x80-\xff]*$/;
+var headerName = (from) => {
+  const base = z6.string().min(1);
+  return (from === "request" ? base.max(64).regex(HEADER_TOKEN, "must be an RFC 7230 token") : base).transform((n) => n.trim().toLowerCase()).refine((n) => !FORBIDDEN_HEADER_NAMES.has(n), "reserved header name").refine((n) => !n.startsWith("x-helix-"), "reserved header prefix");
+};
+var headerTemplate = (from) => from === "request" ? z6.string().max(512).regex(HEADER_VALUE_SAFE) : z6.string().regex(HEADER_VALUE_WIRE);
+var injectionRecipe = (from) => z6.discriminatedUnion("kind", [
+  /** `Authorization: Bearer <secret>` — the common case. */
+  z6.object({ kind: z6.literal("header-bearer") }),
+  /** Arbitrary header; `{}` in `template` is replaced with the secret. */
+  z6.object({
+    kind: z6.literal("header"),
+    name: headerName(from),
+    template: headerTemplate(from).default("{}")
+  }),
+  /** Query parameter `?<param>=<secret>`. */
+  z6.object({ kind: z6.literal("query"), param: z6.string().min(1) }),
+  /**
+   * HMAC over a timestamp. The signed input is the timestamp string **alone** —
+   * not the method, path, query, or body — so injection is a pure function of
+   * (private key, now) and needs no request context.
+   *
+   * The canonical form lives in the KIND NAME, deliberately. A scheme that signs
+   * method+path+body is a *sibling kind* (`hmac-request`) — a code change with
+   * tests, reviewed — never an admin-editable canonical-string template.
+   * Canonicalization is where implementations of this family go wrong, and it
+   * does not belong in a text box.
+   *
+   * SHA-256, lowercase-hex, and ISO-8601-with-milliseconds are fixed rather than
+   * configurable. Each would carry a default, and `app_secrets.injection` is a
+   * schemaless JSON column, so adding a knob later is purely additive with no
+   * migration — while fixing them now removes the weak-algorithm and
+   * unencodable-digest failure classes outright.
+   *
+   * The stored value is a JSON blob carrying both halves of the key pair
+   * ({@link HmacCredentialSchema}): regenerating the pair changes both, and a
+   * blob rotates atomically through the existing rotate route.
+   */
+  z6.object({
+    kind: z6.literal("hmac-timestamp"),
+    /** Header carrying the timestamp that is also the entire signed input. */
+    timestampHeader: headerName(from),
+    /** Header carrying the rendered credential + signature. */
+    authHeader: headerName(from).default("authorization"),
+    /**
+     * Value written to `authHeader`. `{credential}` and `{signature}` are
+     * substituted. Named rather than the `header` kind's bare `{}` because there
+     * are two substitutions: the convention is one value ⇒ `{}`, more than one ⇒
+     * named placeholders. Positional `{}` here would let a swapped template
+     * produce a well-formed header that silently fails to authenticate.
+     *
+     * Both placeholders are required. This recipe writes exactly two headers,
+     * one of them the timestamp, so there is no configuration where the public
+     * credential id travels elsewhere — omitting `{credential}` means the
+     * upstream can never identify the key and every call 401s.
+     */
+    template: headerTemplate(from).refine((t) => t.includes("{signature}"), "template must contain {signature}").refine((t) => t.includes("{credential}"), "template must contain {credential}")
+  }).refine(
+    (r) => r.timestampHeader !== r.authHeader,
+    "timestampHeader and authHeader must differ \u2014 the second write overwrites the first"
+  )
+]);
+var InjectionRecipeSchema = injectionRecipe("request");
+var StoredInjectionRecipeSchema = injectionRecipe("stored");
+var HeaderNameSchema = headerName("request");
+var HmacCredentialSchema = z6.object({
+  credential: z6.string().min(1),
+  key: z6.string().min(1)
+});
+var SECRET_SCOPES = ["app", "global", "platform"];
+var SecretScopeSchema = z6.enum(SECRET_SCOPES);
+var SecretMetadataSchema = z6.object({
+  id: z6.string(),
+  name: z6.string().min(1),
+  scope: SecretScopeSchema,
+  /** Partition tier (dev-mode §6): a dev fetch injects only `dev` connection secrets. */
+  env: EnvSchema,
+  /**
+   * The **stored** parser, not the strict one — this field describes a row, and
+   * the SPA re-parses this schema on every response. Using the strict parser here
+   * would let the portal return a name the browser then refuses, moving the read
+   * failure from the server to the client, where it presents as a dead page.
+   *
+   * `null` = the stored recipe is unreadable (it names a reserved header, or is
+   * not a recipe at all). The credential still exists and is still deletable; it
+   * cannot be rotated, and egress fails its hop closed. Recipes are immutable by
+   * design, so recovery is delete-and-recreate.
+   */
+  injection: StoredInjectionRecipeSchema.nullable(),
+  createdBy: z6.string(),
+  createdAt: z6.string(),
+  rotatedAt: z6.string().nullable().optional(),
+  lastUsedAt: z6.string().nullable().optional(),
+  boundApps: z6.array(z6.string()).default([])
+});
+var SecretCreateRequestSchema = z6.object({
+  name: z6.string().min(1).max(64).regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase letters, digits, and hyphens"),
+  value: z6.string().min(1),
+  /** Target tier (dev-mode §6). Defaults `prod`; `dev` configures a dev-tier credential. */
+  env: EnvSchema.default("prod"),
+  injection: InjectionRecipeSchema.default({ kind: "header-bearer" })
+});
+var SecretRotateRequestSchema = z6.object({ value: z6.string().min(1) });
+var SecretGrantRequestSchema = z6.object({ appSlug: z6.string().min(1) });
+
+// ../shared/src/providers.ts
+var PROVIDER_KINDS = ["rest-delegated"];
+var ProviderKindSchema = z7.enum(PROVIDER_KINDS);
+var PROVIDER_REF_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+var PROVIDER_REF_MAX = 64;
+var ProviderRefSchema = z7.string().min(1).max(PROVIDER_REF_MAX).regex(PROVIDER_REF_PATTERN, "lowercase letters, digits, and hyphens");
+var TokenPlacementSchema = z7.discriminatedUnion("kind", [
+  /** `Authorization: Bearer <access token>` — the default placement. */
+  z7.strictObject({ kind: z7.literal("header-bearer") }),
+  /** The access token verbatim in the named header (no template machinery). */
+  z7.strictObject({ kind: z7.literal("header"), name: HeaderNameSchema })
+]);
+var ScopeTokenSchema = z7.string().min(1).max(256).regex(/^[\x21\x23-\x5b\x5d-\x7e]+$/, "must be an RFC 6749 scope token");
+var API_ORIGIN_RULE = "an API destination is an origin \u2014 scheme://host[:port], no path, query, credentials, or fragment";
+var BARE_ORIGIN = /^https?:\/\/[^/?#@\\]*(?:\/)?$/i;
+var ApiOriginSchema = z7.url({ protocol: /^https?$/ }).superRefine((value, ctx) => {
+  if (!BARE_ORIGIN.test(value)) {
+    ctx.addIssue({ code: "custom", message: API_ORIGIN_RULE });
+    return;
+  }
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    ctx.addIssue({ code: "custom", message: API_ORIGIN_RULE });
+    return;
+  }
+  if (url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
+    ctx.addIssue({ code: "custom", message: API_ORIGIN_RULE });
+  }
+}).transform((value) => new URL(value).origin);
+var URL_PARSER_CONTROLS = /[\t\n\r]/g;
+var ENDPOINT_USERINFO = /^https?:\/\/[/\\]*[^/?#\\]*@/i;
+var OAuthEndpointSchema = z7.url({ protocol: /^https?$/ }).refine(
+  (value) => !ENDPOINT_USERINFO.test(value.replace(URL_PARSER_CONTROLS, "")),
+  "a vendor endpoint URL must not carry userinfo \u2014 client auth is never configured in the URL"
+);
+var MAX_API_ORIGINS = 16;
+var MAX_REQUESTED_SCOPES = 32;
+var noDuplicates = (values) => new Set(values).size === values.length;
+var ApiOriginsSchema = z7.array(ApiOriginSchema).min(1, "a provider needs at least one API destination \u2014 nothing can bind to it otherwise").max(MAX_API_ORIGINS).refine(noDuplicates, "duplicate API destination");
+var RequestedScopesSchema = z7.array(ScopeTokenSchema).max(MAX_REQUESTED_SCOPES).refine(noDuplicates, "duplicate requested scope");
+var ProviderDisplayNameSchema = z7.string().min(1).max(200);
+var ProviderEditableFieldsSchema = z7.strictObject({
+  displayName: ProviderDisplayNameSchema,
+  authorizeEndpoint: OAuthEndpointSchema,
+  tokenEndpoint: OAuthEndpointSchema,
+  requestedScopes: RequestedScopesSchema.default([]),
+  apiOrigins: ApiOriginsSchema,
+  tokenPlacement: TokenPlacementSchema.default({ kind: "header-bearer" })
+});
+var ProviderConfigSchema = ProviderEditableFieldsSchema.extend({
+  ref: ProviderRefSchema,
+  kind: ProviderKindSchema.default("rest-delegated")
+});
+var ProviderCreateRequestSchema = ProviderConfigSchema.extend({
+  env: EnvSchema,
+  clientId: z7.string().min(1),
+  clientSecret: z7.string().min(1)
+});
+var undefinedKeysMeanAbsence = (body) => {
+  if (typeof body !== "object" || body === null) return body;
+  const withoutUndefined = { ...body };
+  for (const key of Object.keys(withoutUndefined)) {
+    if (withoutUndefined[key] === void 0) delete withoutUndefined[key];
+  }
+  return withoutUndefined;
+};
+var OWN_PROTO_KEY_RULE = "an own __proto__ key is not a provider field \u2014 the body is refused whole";
+var ProviderUpdateRequestSchema = z7.preprocess(
+  (body, ctx) => {
+    const normalized = undefinedKeysMeanAbsence(body);
+    if (typeof normalized === "object" && normalized !== null && Object.hasOwn(normalized, "__proto__")) {
+      ctx.addIssue({ code: "custom", message: OWN_PROTO_KEY_RULE });
+    }
+    return normalized;
+  },
+  ProviderEditableFieldsSchema.extend({
+    requestedScopes: RequestedScopesSchema,
+    tokenPlacement: TokenPlacementSchema,
+    revision: z7.int().positive(),
+    clientId: z7.string().min(1).optional(),
+    clientSecret: z7.string().min(1).optional(),
+    /**
+     * The invalidation acknowledgement ({@link CONFIRM_INVALIDATION_FIELD}):
+     * the client sets it to `true` when submitting a sensitive delta through
+     * the review panel. Absent or
+     * `false` against a sensitive delta is the 409
+     * `confirmation_required` rejection — nothing is applied; against a
+     * non-sensitive edit it is irrelevant and ignored. Not stored: it is
+     * consent for the mutation, never provider state.
+     */
+    confirmInvalidation: z7.boolean().optional()
+  })
+);
+var ConnectionProviderSchema = ProviderEditableFieldsSchema.extend({
+  requestedScopes: RequestedScopesSchema,
+  tokenPlacement: TokenPlacementSchema,
+  id: z7.uuid(),
+  revision: z7.int().positive(),
+  ref: ProviderRefSchema,
+  kind: ProviderKindSchema,
+  env: EnvSchema,
+  clientIdMaterial: z7.string().min(1),
+  clientSecretMaterial: z7.string().min(1),
+  createdAt: z7.iso.datetime(),
+  updatedAt: z7.iso.datetime()
+});
+var ProviderMetadataSchema = ConnectionProviderSchema.omit({
+  clientIdMaterial: true,
+  clientSecretMaterial: true
+});
+var ProviderListResponseSchema = z7.strictObject({
+  callbackUrl: z7.url(),
+  providers: z7.array(ProviderMetadataSchema)
+});
+var ProviderExportDocumentSchema = z7.strictObject({
+  version: z7.literal(1),
+  provider: ProviderConfigSchema
+});
+var CatalogueProviderSchema = z7.strictObject({
+  ref: ProviderRefSchema,
+  kind: ProviderKindSchema,
+  displayName: z7.string().min(1).max(200),
+  apiOrigins: ApiOriginsSchema,
+  env: EnvSchema
+});
+var SENSITIVE_PROVIDER_FIELDS = [
+  "clientId",
+  "authorizeEndpoint",
+  "tokenEndpoint",
+  "requestedScopes",
+  "apiOrigins",
+  "tokenPlacement"
+];
+var CONFIRM_INVALIDATION_FIELD = "confirmInvalidation";
+var SensitiveProviderFieldSchema = z7.enum(SENSITIVE_PROVIDER_FIELDS);
+var PROVIDER_DIFF_FIELDS = [
+  "displayName",
+  "authorizeEndpoint",
+  "tokenEndpoint",
+  "requestedScopes",
+  "apiOrigins",
+  "tokenPlacement"
+];
+var ProviderDiffFieldSchema = z7.enum(PROVIDER_DIFF_FIELDS);
+var ProviderImportPreviewRequestSchema = z7.strictObject({
+  document: ProviderExportDocumentSchema,
+  mode: z7.enum(["create", "update"]).optional(),
+  env: EnvSchema.optional(),
+  targetId: z7.uuid().optional()
+});
+var ProviderImportCollisionSchema = z7.strictObject({
+  providerId: z7.uuid(),
+  ref: ProviderRefSchema,
+  env: EnvSchema
+});
+var ProviderImportPreviewTargetSchema = z7.strictObject({
+  providerId: z7.uuid(),
+  ref: ProviderRefSchema,
+  env: EnvSchema,
+  displayName: z7.string().min(1).max(200),
+  revision: z7.int().positive()
+});
+var ProviderImportPreviewDiffEntrySchema = z7.strictObject({
+  field: ProviderDiffFieldSchema,
+  current: z7.union([z7.string(), z7.array(z7.string()), TokenPlacementSchema]),
+  imported: z7.union([z7.string(), z7.array(z7.string()), TokenPlacementSchema])
+});
+var ProviderImportPreviewResponseSchema = z7.discriminatedUnion("mode", [
+  z7.strictObject({ mode: z7.literal(null), provider: ProviderConfigSchema }),
+  z7.strictObject({
+    mode: z7.literal("create"),
+    env: EnvSchema,
+    provider: ProviderConfigSchema,
+    collision: ProviderImportCollisionSchema.nullable()
+  }),
+  z7.strictObject({
+    mode: z7.literal("update"),
+    target: ProviderImportPreviewTargetSchema,
+    diff: z7.array(ProviderImportPreviewDiffEntrySchema),
+    sensitiveFields: z7.array(SensitiveProviderFieldSchema)
+  })
+]);
+var ProviderImportCreateRequestSchema = z7.strictObject({
+  mode: z7.literal("create"),
+  document: ProviderExportDocumentSchema,
+  env: EnvSchema,
+  clientId: z7.string().min(1),
+  clientSecret: z7.string().min(1)
+});
+var ProviderImportUpdateRequestSchema = z7.strictObject({
+  mode: z7.literal("update"),
+  document: ProviderExportDocumentSchema,
+  targetId: z7.uuid(),
+  revision: z7.int().positive(),
+  clientId: z7.string().min(1).optional(),
+  clientSecret: z7.string().min(1).optional(),
+  [CONFIRM_INVALIDATION_FIELD]: z7.boolean().optional()
+});
+var ProviderImportRequestSchema = z7.discriminatedUnion("mode", [
+  ProviderImportCreateRequestSchema,
+  ProviderImportUpdateRequestSchema
+]);
+var ProviderImportResponseSchema = z7.strictObject({
+  outcome: z7.enum(["created", "updated"]),
+  provider: ProviderMetadataSchema
+});
+var BoundAppSchema = z7.strictObject({
+  id: z7.uuid(),
+  slug: z7.string().max(63).regex(SLUG_PATTERN, "must be a lowercase DNS label (a-z, 0-9, hyphen)"),
+  displayName: z7.string().min(1).max(200)
+});
+var ProviderImpactSchema = z7.strictObject({
+  providerId: z7.uuid(),
+  ref: ProviderRefSchema,
+  env: EnvSchema,
+  displayName: z7.string().min(1).max(200),
+  revision: z7.int().positive(),
+  boundApps: z7.array(BoundAppSchema),
+  connections: z7.number().int().nonnegative(),
+  pendingAttempts: z7.number().int().nonnegative()
+});
+var ConfirmationRequiredDetailsSchema = z7.strictObject({
+  impact: ProviderImpactSchema,
+  sensitiveFields: z7.array(SensitiveProviderFieldSchema).optional()
+});
+var ProviderDeleteRequestSchema = z7.strictObject({
+  [CONFIRM_INVALIDATION_FIELD]: z7.boolean().optional()
+});
+var ProviderDeleteResponseSchema = z7.strictObject({
+  outcome: z7.enum(["deleted", "already_removed"])
+});
+
+// ../shared/src/manifest.ts
+var LlmCapabilitySchema = z8.object({
+  models: z8.array(z8.string()).default([]),
   /**
    * Per-app daily LLM spend cap in USD; unset ⇒ unbounded. Denominated in
    * dollars (not tokens) so the cap means the same thing across models — the
    * edge prices each call via `@azx-pbc/shared` pricing and enforces a daily +
    * rolling-hour burst window off the frozen `costMicroUsd` ledger column.
    */
-  dollarsPerDay: z4.number().positive().optional()
-});
-var DataCapabilitySchema = z4.object({
-  user: z4.boolean().default(false),
-  collections: z4.array(z4.string().min(1)).default([]),
-  sharedRead: z4.array(z4.string().min(1)).default([]),
-  sharedWrite: z4.array(z4.string().min(1)).default([]),
-  writesPerDay: z4.int().positive().optional(),
-  bytesPerDay: z4.int().positive().optional()
-});
-var FetchConnectionSchema = z4.object({
-  origin: z4.url(),
-  connection: z4.string().min(1).optional()
-});
-var FetchCapabilitySchema = z4.object({
-  /** Opt-in transparent `fetch` shim injected at serve time (fetch-proxy §3.2). */
-  shim: z4.boolean().default(false),
+  dollarsPerDay: z8.number().positive().optional()
+});
+var KEY_MAX_CHARS = 256;
+var PRINTABLE_ASCII = /^[\x20-\x7e]*$/;
+function isValidDataKey(key) {
+  return key.length > 0 && key.length <= KEY_MAX_CHARS && PRINTABLE_ASCII.test(key) && // After the ASCII test this can only be a leading/trailing 0x20 — but it
+  // is the one character in the allowlist that is invisible at a grant's
+  // edges, so it gets its own rule.
+  key === key.trim();
+}
+var DATA_KEY_RULE = "must be 1\u2013256 printable ASCII characters (0x20\u20130x7E) with no leading or trailing space";
+var DataKeySchema = z8.string().refine(isValidDataKey, { message: DATA_KEY_RULE });
+var DataCapabilitySchema = z8.object({
+  user: z8.boolean().default(false),
+  collections: z8.array(DataKeySchema).default([]),
+  sharedRead: z8.array(DataKeySchema).default([]),
+  sharedWrite: z8.array(DataKeySchema).default([]),
+  /** ADR-0042: authorize every key starting with one of these prefixes (read). */
+  sharedReadPrefixes: z8.array(DataKeySchema).default([]),
+  /** ADR-0042: authorize every key starting with one of these prefixes (write). */
+  sharedWritePrefixes: z8.array(DataKeySchema).default([]),
+  writesPerDay: z8.int().positive().optional(),
+  bytesPerDay: z8.int().positive().optional()
+}).superRefine((d, ctx) => {
+  if (d.sharedWritePrefixes.length > 0 && d.writesPerDay === void 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["writesPerDay"],
+      message: "a writesPerDay budget is required alongside sharedWritePrefixes \u2014 a prefix grant allows runtime row creation, so the grant and its bound are approved together (ADR-0042)"
+    });
+  }
+});
+var FetchConnectionSchema = z8.strictObject({
+  origin: z8.url(),
+  connection: z8.string().min(1).optional(),
+  provider: ProviderRefSchema.optional(),
+  required: z8.boolean().optional()
+}).superRefine((c, ctx) => {
+  if (c.connection !== void 0 && c.provider !== void 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["provider"],
+      message: "an origin binds at most one credential source \u2014 declare a stored secret (connection) or an OAuth provider (provider), not both"
+    });
+  }
+});
+var FetchCapabilitySchema = z8.object({
+  /**
+   * Legacy view of the fetch-shim grant. The grant is declared first-class as
+   * {@link ShimCapabilitySchema} (`capabilities.shim.fetch`); this boolean is
+   * the pre-`capabilities.shim` spelling, still accepted on input and kept synchronized
+   * with the canonical block on every parse (see {@link CapabilitiesSchema}) —
+   * new manifests should declare `capabilities.shim`, not this field.
+   */
+  shim: z8.boolean().default(false),
   /** Origins reached through the proxy (mode `proxy`); direct stays in `externalOrigins`. */
-  origins: z4.array(FetchConnectionSchema).default([]),
+  origins: z8.array(FetchConnectionSchema).default([]),
   /** Per-app daily proxied-request budget; unset ⇒ unbounded (fetch-proxy §7). */
-  requestsPerDay: z4.int().positive().optional()
+  requestsPerDay: z8.int().positive().optional()
+});
+var ShimCapabilitySchema = z8.object({
+  fetch: z8.boolean().default(false),
+  connect: z8.boolean().default(false)
 });
 var SCOPE_SEGMENT = /^[A-Za-z0-9\-._~]+$/;
 function isValidServiceWorkerScope(scope) {
@@ -115,42 +637,84 @@ function isValidServiceWorkerScope(scope) {
   }
   return !first.startsWith("_");
 }
-var OfflineCapabilitySchema = z4.object({
+var OfflineCapabilitySchema = z8.object({
   /**
    * URL path prefix the worker controls, e.g. `/app/`. Leading and trailing
    * slash required; never root, never a `_`-prefixed platform namespace.
    */
-  scope: z4.string().refine(isValidServiceWorkerScope, {
+  scope: z8.string().refine(isValidServiceWorkerScope, {
     message: "scope must be a non-root path prefix with a leading and trailing slash, and must not start with a reserved `_` segment (e.g. `/app/`)"
   })
 });
-var CapabilitiesSchema = z4.object({
+var CapabilitiesSchema = z8.object({
   llm: LlmCapabilitySchema.optional(),
   data: DataCapabilitySchema.optional(),
   /** Platform-registered MCP servers this app may reach (§6.1, exposed as REST). */
-  mcp: z4.array(z4.string()).default([]),
+  mcp: z8.array(z8.string()).default([]),
   /** Extra CSP `connect-src` origins for **direct** browser calls (§4.4). */
-  externalOrigins: z4.array(z4.url()).default([]),
+  externalOrigins: z8.array(z8.url()).default([]),
   /** Governed outbound HTTP via the fetch-proxy / egress plane (in build, M4.5). */
   fetch: FetchCapabilitySchema.optional(),
   /** Platform-owned, scope-confined service worker for offline cold boot (ADR-0035). */
-  offline: OfflineCapabilitySchema.optional()
+  offline: OfflineCapabilitySchema.optional(),
+  /** Injected platform helpers — the first-class shim grant. */
+  shim: ShimCapabilitySchema.optional()
+}).transform((caps) => {
+  const legacyShim = caps.fetch?.shim ?? false;
+  const fetchOn = legacyShim || (caps.shim?.fetch ?? false);
+  const connectOn = caps.shim?.connect ?? false;
+  const fetch2 = caps.fetch ?? (fetchOn ? { shim: fetchOn, origins: [] } : void 0);
+  return {
+    ...caps,
+    fetch: fetch2 === void 0 ? void 0 : { ...fetch2, shim: fetchOn },
+    ...fetchOn || connectOn ? { shim: { fetch: fetchOn, connect: connectOn } } : {}
+  };
+});
+var ProviderBindingStatusSchema = z8.strictObject({
+  /** The manifest origin as declared (matches `FetchConnection.origin`). */
+  origin: z8.string(),
+  /** The bound provider reference. */
+  ref: ProviderRefSchema,
+  /**
+   * Whether an approval that granted this binding still matches the provider
+   * row's current identity — the {@link isProviderBindingEffective} rule
+   * (the one definition; the portal never re-derives the comparison). `false`
+   * means the provider was deleted or a sensitive edit stale-dated the stamp.
+   */
+  effective: z8.boolean()
 });
-var AppManifestSchema = z4.object({
+var AppManifestSchema = z8.object({
   /** App slug; matches `App.slug`. */
-  app: z4.string().min(1),
+  app: z8.string().min(1),
   visibility: VisibilitySchema,
-  capabilities: CapabilitiesSchema.default({ mcp: [], externalOrigins: [] })
+  capabilities: CapabilitiesSchema.default({ mcp: [], externalOrigins: [] }),
+  /**
+   * Effectiveness of every provider-bound origin in `capabilities`, computed
+   * server-side on the read (never stored). Absent when the manifest declares
+   * no provider binding — every payload without one keeps its exact shape.
+   */
+  providerBindings: z8.array(ProviderBindingStatusSchema).optional()
 });
 
 // ../shared/src/approval.ts
-import { z as z5 } from "zod";
+import { z as z9 } from "zod";
 
 // ../shared/src/pricing.ts
 var MODEL_PRICING = {
   // Anthropic. NB `structuredOutputs` is deliberately absent on 4-7/4-6/sonnet-4-6:
-  // structured outputs are supported on Fable 5, Opus 4.8 and Haiku 4.5 but not on
-  // those three, so the flag is opt-in per model rather than per provider.
+  // structured outputs are supported on the Fable 5 line, Opus 5, Sonnet 5, Opus 4.8
+  // and Haiku 4.5 but not on those three, so the flag is opt-in per model rather
+  // than per provider.
+  // Fable 5.1 sits above Fable 5 at the same per-token rate, but its cache *reads*
+  // bill at 0.025x base input rather than the 0.1x every other model uses — the
+  // one reason `cacheReadMultiplier` exists.
+  "claude-fable-5-1": {
+    inputPerMTok: 10,
+    outputPerMTok: 50,
+    provider: "anthropic",
+    cacheReadMultiplier: 0.025,
+    structuredOutputs: true
+  },
   "claude-fable-5": {
     inputPerMTok: 10,
     outputPerMTok: 50,
@@ -163,12 +727,12 @@ var MODEL_PRICING = {
     provider: "anthropic",
     structuredOutputs: true
   },
-  // NB list rates. Sonnet 5 has promotional $2/$10 pricing through 2026-08-31; this
-  // table drives the **cost gate**, so the list price is the safe number — it
-  // over-estimates spend during the promo rather than under-billing once it lapses.
+  // Sonnet 5's $2/$10 was introductory pricing through 2026-08-31; Anthropic made
+  // it the standard price and cancelled the scheduled rise to $3/$15. This is now
+  // the list rate, so the cost gate no longer over-estimates Sonnet 5 spend.
   "claude-sonnet-5": {
-    inputPerMTok: 3,
-    outputPerMTok: 15,
+    inputPerMTok: 2,
+    outputPerMTok: 10,
     provider: "anthropic",
     structuredOutputs: true
   },
@@ -181,56 +745,108 @@ var MODEL_PRICING = {
   "claude-opus-4-7": { inputPerMTok: 5, outputPerMTok: 25, provider: "anthropic" },
   "claude-opus-4-6": { inputPerMTok: 5, outputPerMTok: 25, provider: "anthropic" },
   "claude-sonnet-4-6": { inputPerMTok: 3, outputPerMTok: 15, provider: "anthropic" },
+  // Near-term churn: haiku-4-5's only two Foundry versions both stop serving
+  // 2026-10-19 (measured eastus2 2026-09-16). Not a cut — first-party serving
+  // is unaffected — but expect the Foundry deployments to need a successor.
   "claude-haiku-4-5": {
     inputPerMTok: 1,
     outputPerMTok: 5,
     provider: "anthropic",
     structuredOutputs: true
   },
-  // OpenAI — VERIFY against current published rates before production billing.
-  // Every model here resolves to a snapshot new enough for `response_format`
-  // json_schema, so `structuredOutputs` is set across the board.
-  "gpt-4o": { inputPerMTok: 2.5, outputPerMTok: 10, provider: "openai", structuredOutputs: true },
-  "gpt-4o-mini": {
-    inputPerMTok: 0.15,
-    outputPerMTok: 0.6,
+  // OpenAI. Every model here resolves to a snapshot new enough for `response_format`
+  // json_schema (that floor is `gpt-4o-2024-08-06`), so `structuredOutputs` is set
+  // across the board.
+  //
+  // The current generation — GPT-6 and GPT-5.x — is reasoning models throughout, so
+  // `reasoning` is set on all of them. On chat/completions that flag means exactly
+  // one thing here: send `max_completion_tokens`, not `max_tokens`. OpenAI has
+  // deprecated `max_tokens` outright and reasoning models reject it, so the flag is
+  // the forward-compatible setting even where a model would still accept both.
+  "gpt-6-astra": {
+    inputPerMTok: 10,
+    outputPerMTok: 50,
     provider: "openai",
+    reasoning: true,
+    minCompletionTokens: 25e3,
     structuredOutputs: true
   },
-  "gpt-4.1": { inputPerMTok: 2, outputPerMTok: 8, provider: "openai", structuredOutputs: true },
-  "gpt-4.1-mini": {
-    inputPerMTok: 0.4,
-    outputPerMTok: 1.6,
+  "gpt-5.6-sol": {
+    inputPerMTok: 4,
+    outputPerMTok: 20,
     provider: "openai",
+    reasoning: true,
+    minCompletionTokens: 25e3,
     structuredOutputs: true
   },
-  "gpt-4.1-nano": {
-    inputPerMTok: 0.1,
-    outputPerMTok: 0.4,
+  "gpt-5.6-terra": {
+    inputPerMTok: 2,
+    outputPerMTok: 12,
     provider: "openai",
+    reasoning: true,
+    minCompletionTokens: 25e3,
     structuredOutputs: true
   },
-  o3: {
-    inputPerMTok: 2,
-    outputPerMTok: 8,
+  "gpt-5.6-luna": {
+    inputPerMTok: 0.2,
+    outputPerMTok: 1.2,
+    provider: "openai",
+    reasoning: true,
+    minCompletionTokens: 25e3,
+    structuredOutputs: true
+  },
+  "gpt-5.1": {
+    inputPerMTok: 1.25,
+    outputPerMTok: 10,
+    provider: "openai",
+    reasoning: true,
+    minCompletionTokens: 25e3,
+    structuredOutputs: true
+  },
+  "gpt-5-mini": {
+    inputPerMTok: 0.25,
+    outputPerMTok: 2,
     provider: "openai",
     reasoning: true,
     minCompletionTokens: 25e3,
     structuredOutputs: true
   },
-  "o4-mini": {
-    inputPerMTok: 1.1,
-    outputPerMTok: 4.4,
+  "gpt-5-nano": {
+    inputPerMTok: 0.05,
+    outputPerMTok: 0.4,
     provider: "openai",
     reasoning: true,
     minCompletionTokens: 25e3,
     structuredOutputs: true
+  },
+  // Previous generations, kept curated so a deployed app's manifest keeps working.
+  // Rates re-verified 2026-09-14 and unchanged.
+  //
+  // `gpt-4o-mini`, `o3` and `o4-mini` were deliberately cut (2026-09-16) rather
+  // than retained on that principle: Azure AI Foundry's RP refuses any model
+  // whose *default* version is `Deprecating` (`ServiceModelDeprecating`), so
+  // they could never ride the one-flag Foundry path, and the current generation
+  // covers their price points first-party. A manifest still naming one gets the
+  // edge's `model_not_allowed` (no price configured) — the cut is the break.
+  "gpt-4o": { inputPerMTok: 2.5, outputPerMTok: 10, provider: "openai", structuredOutputs: true },
+  "gpt-4.1": { inputPerMTok: 2, outputPerMTok: 8, provider: "openai", structuredOutputs: true },
+  "gpt-4.1-mini": {
+    inputPerMTok: 0.4,
+    outputPerMTok: 1.6,
+    provider: "openai",
+    structuredOutputs: true
+  },
+  "gpt-4.1-nano": {
+    inputPerMTok: 0.1,
+    outputPerMTok: 0.4,
+    provider: "openai",
+    structuredOutputs: true
   }
 };
 
 // ../shared/src/approval.ts
 var RISK_LEVELS = ["low", "med", "high"];
-var RiskSchema = z5.enum(RISK_LEVELS);
+var RiskSchema = z9.enum(RISK_LEVELS);
 var APPROVAL_STATUSES = [
   "pending",
   "approved",
@@ -238,134 +854,195 @@ var APPROVAL_STATUSES = [
   "withdrawn",
   "needs_changes"
 ];
-var ApprovalStatusSchema = z5.enum(APPROVAL_STATUSES);
-var DeltaSchema = z5.object({
-  path: z5.string(),
-  from: z5.union([z5.string(), z5.number(), z5.boolean()]).optional(),
-  to: z5.union([z5.string(), z5.number(), z5.boolean()]).optional()
-});
-var ApprovalRequestSchema = z5.object({
-  id: z5.string(),
-  appId: z5.string(),
+var ApprovalStatusSchema = z9.enum(APPROVAL_STATUSES);
+var ProviderStampSchema = z9.strictObject({
+  /** The env-unique reference the manifest binds (the catalogue/manifest key). */
+  ref: ProviderRefSchema,
+  /** Which partition the stamped row lives in — a ref may exist in both. */
+  env: EnvSchema,
+  /** The surrogate row id — delete+recreate mints a new one, dangling old stamps. */
+  providerId: z9.uuid(),
+  /** The row's revision at filing; a sensitive edit advances it. */
+  revision: z9.int().positive()
+});
+var DeltaSchema = z9.object({
+  path: z9.string(),
+  from: z9.union([z9.string(), z9.number(), z9.boolean()]).optional(),
+  to: z9.union([z9.string(), z9.number(), z9.boolean()]).optional(),
+  /**
+   * The provider stamps recorded **at filing** for a provider-bound origin
+   * delta — one per env-partitioned `connection_providers` row that
+   * existed under the bound ref when the request was filed (an
+   * approval records the provider's `ref` + `providerId` + `revision`, and
+   * env partitioning makes a ref's full identity the set of its rows).
+   *
+   * This is the payload half of the apply-time conflict: approving a request
+   * whose stamps no longer match the provider's current identity/revision
+   * approves nothing — an old pending approval cannot approve access to a
+   * newer configuration. Consumers read the rule itself from
+   * {@link isProviderBindingEffective}; none re-derives the comparison.
+   */
+  providerStamps: z9.array(ProviderStampSchema).optional(),
+  /**
+   * The requesting app's visibility **at filing**: `true` when the app was
+   * `public`, `false` (stamped as not-public) otherwise. The
+   * warning — a public app's anonymous visitors can never connect a vendor
+   * account — is data on the request, so the queue card needs no extra fetch.
+   * The flag never auto-rejects.
+   */
+  publicApp: z9.boolean().optional(),
+  /**
+   * This delta's own severity as classified at filing — what the request-level
+   * `risk` is the max of. Absent on requests filed before the field existed
+   * (deltas are stored as JSON, so nothing backfills them); renderers fall
+   * back to the aggregate rather than guessing.
+   */
+  risk: RiskSchema.optional()
+});
+var PriorDecisionsSchema = z9.object({
+  /** Prior *decided* (non-pending) requests on this app — the history count. */
+  total: z9.number().int().nonnegative(),
+  /** Prior denied requests touching an overlapping policy area (quiet signal). */
+  deniedSameArea: z9.number().int().nonnegative(),
+  /** Prior denied requests sharing an exact delta path (loud signal; ⊆ area). */
+  deniedSameGrant: z9.number().int().nonnegative(),
+  /** The most recent decided request (any status), for the "last decision" line. */
+  last: z9.object({
+    status: ApprovalStatusSchema,
+    note: z9.string().nullable(),
+    decidedBy: z9.string().nullable(),
+    decidedAt: z9.string()
+  }).optional()
+});
+var ApprovalRequestSchema = z9.object({
+  id: z9.string(),
+  appId: z9.string(),
   /** Joined for the admin queue / banner; not a column. */
-  appSlug: z5.string().optional(),
-  appDisplayName: z5.string().optional(),
+  appSlug: z9.string().optional(),
+  appDisplayName: z9.string().optional(),
   status: ApprovalStatusSchema,
   risk: RiskSchema,
-  deltas: z5.array(DeltaSchema),
-  baseSnapshot: z5.unknown(),
-  requestedBy: z5.string(),
-  reason: z5.string().nullable().optional(),
-  decidedBy: z5.string().nullable().optional(),
-  decisionNote: z5.string().nullable().optional(),
-  createdAt: z5.string(),
-  decidedAt: z5.string().nullable().optional()
-});
-var ManifestUpdateResultSchema = z5.object({
+  deltas: z9.array(DeltaSchema),
+  baseSnapshot: z9.unknown(),
+  requestedBy: z9.string(),
+  reason: z9.string().nullable().optional(),
+  decidedBy: z9.string().nullable().optional(),
+  decisionNote: z9.string().nullable().optional(),
+  createdAt: z9.string(),
+  decidedAt: z9.string().nullable().optional(),
+  /** Sibling-decision context for the admin queue (issue #26); read-side only. */
+  priorDecisions: PriorDecisionsSchema.optional()
+});
+var ManifestUpdateResultSchema = z9.object({
   manifest: AppManifestSchema,
-  applied: z5.array(DeltaSchema),
-  pending: z5.string().nullable()
+  applied: z9.array(DeltaSchema),
+  pending: z9.string().nullable()
 });
-var VisibilityUpdateResultSchema = z5.object({
+var VisibilityUpdateResultSchema = z9.object({
   app: AppSchema,
-  applied: z5.array(DeltaSchema),
-  pending: z5.string().nullable()
+  applied: z9.array(DeltaSchema),
+  pending: z9.string().nullable()
 });
-var ApprovalDecisionRequestSchema = z5.object({
-  note: z5.string().max(2e3).optional()
+var ApprovalDecisionRequestSchema = z9.object({
+  note: z9.string().max(2e3).optional()
 });
 var CURATED_LLM_MODELS = Object.keys(MODEL_PRICING);
 
 // ../shared/src/health.ts
-import { z as z6 } from "zod";
-var HealthStateSchema = z6.enum(["ok", "degraded", "error"]);
-var HealthCheckSchema = z6.object({
+import { z as z10 } from "zod";
+var HealthStateSchema = z10.enum(["ok", "degraded", "error"]);
+var HealthCheckSchema = z10.object({
   /** Stable identifier an alert rule can key on, e.g. `registry-projection`. */
-  name: z6.string(),
+  name: z10.string(),
   status: HealthStateSchema,
   /** Operator-facing one-liner: what is wrong, and for how long. */
-  detail: z6.string().optional(),
+  detail: z10.string().optional(),
   /** Wall-clock instant this check last succeeded. Report-only — never the
    *  basis of a staleness decision (see the monotonic note in the edge's
    *  registry projection). */
-  lastSuccessAt: z6.iso.datetime().optional(),
+  lastSuccessAt: z10.iso.datetime().optional(),
   /** Numeric facts a dashboard or a log-based metric can key on. */
-  metrics: z6.record(z6.string(), z6.number()).optional()
+  metrics: z10.record(z10.string(), z10.number()).optional()
 });
-var HealthStatusSchema = z6.object({
+var HealthStatusSchema = z10.object({
   /** The roll-up: the worst state across `checks` (see `worstHealthState`). */
   status: HealthStateSchema,
-  service: z6.string(),
+  service: z10.string(),
   /** Process uptime in seconds. */
-  uptime: z6.number().nonnegative(),
+  uptime: z10.number().nonnegative(),
   /** Absent means the service reports liveness only (portal and egress today). */
-  checks: z6.array(HealthCheckSchema).optional()
+  checks: z10.array(HealthCheckSchema).optional()
 });
 
 // ../shared/src/api.ts
-import { z as z7 } from "zod";
-var CreateAppRequestSchema = z7.object({
+import { z as z11 } from "zod";
+var CreateAppRequestSchema = z11.object({
   slug: AppSchema.shape.slug,
   displayName: AppSchema.shape.displayName,
-  visibility: VisibilitySchema.default({ mode: "internal" }),
+  /** Optional one-line plain-text summary; rendered as a subtitle in the portal. */
+  description: AppSchema.shape.description,
+  visibility: WritableVisibilitySchema.default({ mode: "internal" }),
   /** Optional per-app capability grant set at create time (architecture §6.3). */
   capabilities: CapabilitiesSchema.optional()
 });
-var SetManifestRequestSchema = z7.object({
+var UpdateAppRequestSchema = z11.object({
+  description: z11.string().max(APP_DESCRIPTION_MAX).nullable().optional()
+});
+var SetManifestRequestSchema = z11.object({
   capabilities: CapabilitiesSchema,
   /** Justification carried onto an approval request for any elevated deltas. */
-  reason: z7.string().max(2e3).optional()
+  reason: z11.string().max(2e3).optional()
 });
-var SetVisibilityRequestSchema = z7.object({
-  visibility: VisibilitySchema,
+var SetVisibilityRequestSchema = z11.object({
+  visibility: WritableVisibilitySchema,
   /** Justification carried onto the approval request when going public. */
-  reason: z7.string().max(2e3).optional()
+  reason: z11.string().max(2e3).optional()
 });
 var MIN_PASSWORD_LENGTH = 12;
-var SetPasswordRequestSchema = z7.object({
-  password: z7.string().min(MIN_PASSWORD_LENGTH).optional()
+var SetPasswordRequestSchema = z11.object({
+  password: z11.string().min(MIN_PASSWORD_LENGTH).optional()
 });
-var PasswordCredentialResponseSchema = z7.object({
+var PasswordCredentialResponseSchema = z11.object({
   /** The shared passphrase, in cleartext, for the owner to copy/share. */
-  password: z7.string().min(1),
+  password: z11.string().min(1),
   /** The app's public URL, prebuilt so the UI can offer a one-click copy. */
-  url: z7.url(),
+  url: z11.url(),
   /** When the current password was set (ISO 8601). */
-  setAt: z7.string()
-});
-var CspWarningSchema = z7.object({
-  file: z7.string(),
-  origin: z7.string(),
-  hint: z7.string()
-});
-var OriginGrantRequestSchema = z7.object({
-  origin: z7.url(),
-  reason: z7.string().max(2e3).optional()
-});
-var CspViolationSchema = z7.object({
-  appId: z7.string(),
-  appSlug: z7.string().nullable(),
-  directive: z7.string(),
-  blockedUri: z7.string(),
-  count: z7.number().int(),
-  lastSeen: z7.string(),
+  setAt: z11.string()
+});
+var CspWarningSchema = z11.object({
+  file: z11.string(),
+  origin: z11.string(),
+  hint: z11.string()
+});
+var OriginGrantRequestSchema = z11.object({
+  origin: z11.url(),
+  reason: z11.string().max(2e3).optional()
+});
+var CspViolationSchema = z11.object({
+  appId: z11.string(),
+  appSlug: z11.string().nullable(),
+  directive: z11.string(),
+  blockedUri: z11.string(),
+  count: z11.number().int(),
+  lastSeen: z11.string(),
   /**
    * The blocked origin is already permitted by the app's *current* manifest, so
    * this historical report is no longer actionable. Derived at read time
    * (directive-aware — only `connect-src`/`img-src` are widened by an
    * `externalOrigins` grant); the row itself is never deleted.
    */
-  resolved: z7.boolean()
+  resolved: z11.boolean()
 });
-var CspViolationsPageSchema = z7.object({
-  violations: z7.array(CspViolationSchema)
+var CspViolationsPageSchema = z11.object({
+  violations: z11.array(CspViolationSchema)
 });
-var UploadVersionResponseSchema = z7.object({
+var UploadVersionResponseSchema = z11.object({
   version: VersionSchema,
-  warnings: z7.array(CspWarningSchema)
+  warnings: z11.array(CspWarningSchema)
 });
-var RollbackRequestSchema = z7.object({
-  toNumber: z7.int().positive().optional()
+var RollbackRequestSchema = z11.object({
+  toNumber: z11.int().positive().optional()
 });
 var API_ERROR_CODES = [
   "validation_failed",
@@ -376,6 +1053,14 @@ var API_ERROR_CODES = [
   /** Authenticated but not allowed — reserved for v1 RBAC. */
   "forbidden",
   "conflict",
+  /**
+   * Portal: a sensitive provider edit (or a deletion) arrived without its
+   * invalidation acknowledgement. HTTP 409 like `conflict`, but
+   * distinguishable: the SPA's
+   * review panel opens on this code, and `details` carries the impact payload
+   * (`ConfirmationRequiredDetailsSchema` in providers.ts) it renders.
+   */
+  "confirmation_required",
   /** Gateway: requested model is not in the app's manifest allowlist (§6.3). */
   "model_not_allowed",
   /** Gateway: the app's daily token budget is exhausted (§6.1). */
@@ -387,48 +1072,141 @@ var API_ERROR_CODES = [
    * of its own budget. HTTP 429.
    */
   "rate_limited",
+  /**
+   * Gateway: a `shared` app-data write carried no concurrency precondition
+   * (`If-Match` / `If-None-Match`), which that scope requires (ADR-0041).
+   * Distinct from `conflict` (a precondition that was stated and lost) because
+   * the two demand opposite responses: `conflict` says re-read and retry,
+   * `precondition_required` says the app's code is wrong. HTTP 428.
+   */
+  "precondition_required",
   /** Gateway: a configured capability is not available on this edge. */
   "capability_unavailable",
   "internal"
 ];
-var ApiErrorCodeSchema = z7.enum(API_ERROR_CODES);
-var ApiErrorSchema = z7.object({
-  error: z7.object({
+var ApiErrorCodeSchema = z11.enum(API_ERROR_CODES);
+var ApiErrorSchema = z11.object({
+  error: z11.object({
     code: ApiErrorCodeSchema,
-    message: z7.string(),
-    details: z7.unknown().optional()
+    message: z11.string(),
+    details: z11.unknown().optional()
   })
 });
 
 // ../shared/src/auth.ts
-import { z as z8 } from "zod";
-var MeResponseSchema = z8.object({
-  user: z8.object({
-    /** IdP subject (Entra object id) — stable, safe to key app data on. */
-    id: z8.string(),
-    displayName: z8.string()
+import { z as z12 } from "zod";
+var MeResponseSchema = z12.object({
+  user: z12.object({
+    /**
+     * The principal id — Entra's `oid` claim (the directory object id), stable
+     * for the life of the user object and identical across every app
+     * registration in the tenant (ADR-0048): safe to key app data on, and the
+     * user scope partitions on exactly this value. Opaque by design — never
+     * render it; `displayName` and `email` are the half fit to display.
+     */
+    id: z12.string(),
+    displayName: z12.string(),
+    /**
+     * The captured address claim, or `null` when there isn't one — **nullable,
+     * not optional, and the difference is the contract**. A missing key would
+     * conflate "this platform doesn't send emails" with "we have no address for
+     * this person", and the second is routine: shared-password sessions are a
+     * `Guest` with no directory profile at all, and an issuer that sends no
+     * `email` and a non-addressable `preferred_username` yields null too
+     * (`captureEmail`). Apps must handle null; sending it explicitly is what
+     * makes them.
+     *
+     * Never a delivery target or an identity key — `id` is the only thing safe
+     * to join on. Entra addresses are reassignable and B2B guests carry their
+     * home-tenant address.
+     */
+    email: z12.string().nullable()
   })
 });
-var PortalMeResponseSchema = z8.object({
-  sub: z8.string(),
+var PortalMeResponseSchema = z12.object({
+  /**
+   * The canonical principal id — Entra's `oid` claim from the access token
+   * (ADR-0048). This is what `App.ownerId` stores and what ownership compares;
+   * `sub` below is the display/audit half, never a join key.
+   *
+   * **Optional, not required**, for the same cross-version reason as the
+   * defaulted fields below: this schema parses `PortalClient.me()` in the
+   * *published* CLI, which routinely talks to portals older than itself, and
+   * portals are customer-deployed and version independently (ADR-0028). An
+   * older portal has no `oid` to echo — pre-ADR-0048 it has no such concept —
+   * and nothing in the CLI keys on it. A current portal always sends it (the
+   * dev-token actor gets a fixed synthetic value).
+   */
+  oid: z12.string().optional(),
+  sub: z12.string(),
   /** How the actor was established: `oidc` or `dev-token`. */
-  via: z8.string(),
-  name: z8.string().optional(),
-  email: z8.string().optional(),
+  via: z12.string(),
+  name: z12.string().optional(),
+  email: z12.string().optional(),
   /**
    * Whether the actor holds the `platform-admin` role. Computed server-side from
    * the actor's group/role claim — the raw ids never cross to the browser. Drives
    * admin nav + route gating in the SPA (and `helix whoami`).
+   *
+   * **Defaulted, not required**, for the same reason as
+   * {@link canSearchDirectory} below: this schema parses `PortalClient.me()` in
+   * the *published* CLI, which routinely talks to portals older than itself. The
+   * polarity is the cautious one — a portal that never sent the field is not
+   * telling us the caller is an admin.
    */
-  isAdmin: z8.boolean()
+  isAdmin: z12.boolean().default(false),
+  /**
+   * Whether this caller may run a tenant-wide group search (ADR-0040 decision
+   * 11). Computed server-side from the deployment's `PORTAL_DIRECTORY_SEARCH`
+   * tier and the actor's admin-ness. A caller who *may* search learns nothing
+   * else; one who may not gets {@link searchRestriction} alongside.
+   *
+   * Sent so the group picker can **avoid issuing a search it is not allowed to
+   * make**, rather than firing one and interpreting the 403. That matters
+   * because a refused search is not a broken directory: the caller's own groups
+   * and their app's stored groups still resolve to names, so the picker stays
+   * useful and must not fall back to the "directory unavailable" banner. Server
+   * enforcement is independent of this hint (`GET /api/v1/directory/groups`
+   * refuses on its own).
+   *
+   * **Defaults to `true` when absent, and the polarity is the whole point.** The
+   * CLI bundles this schema (ADR-0032) and portals are customer-deployed and
+   * version independently (ADR-0028), so a new CLI against an older portal is
+   * routine — and it was a hard break while this was required: `helix whoami`
+   * failed outright, and `helix login` failed at its final "greet the actor"
+   * step, which runs *after* the tokens are written, so a login that genuinely
+   * succeeded reported an error. A portal old enough to omit this has no tier
+   * enforcement at all and therefore behaves exactly like `everyone`, so `true`
+   * describes the portal actually being talked to. Defaulting to `false` would
+   * instead tell a client that search is unavailable where it works.
+   */
+  canSearchDirectory: z12.boolean().default(true),
+  /**
+   * Why search was refused, when it was — **present only when
+   * {@link canSearchDirectory} is false**, and never `everyone`, which by
+   * construction refuses nobody.
+   *
+   * Exists because "restricted" and "restricted *to platform admins*" are
+   * different sentences and only one of them is true under the `none` tier. The
+   * picker has to be able to say which, and telling a platform admin that search
+   * is "limited to platform admins" while refusing them sends them off to audit
+   * a `PORTAL_ADMIN_GROUP_ID` that is perfectly correct.
+   *
+   * This is a deliberate, bounded narrowing of decision 11's "the browser learns
+   * the answer, never the tier": a *permitted* caller still learns nothing, and a
+   * refused one learns only which rule refused them — which they can already
+   * infer from the 403 they would get by asking. The admin group id still never
+   * crosses.
+   */
+  searchRestriction: z12.enum(["admins", "none"]).optional()
 });
-var AuthConfigResponseSchema = z8.object({
-  issuer: z8.url(),
-  cliClientId: z8.string().min(1),
+var AuthConfigResponseSchema = z12.object({
+  issuer: z12.url(),
+  cliClientId: z12.string().min(1),
   /** Public client the portal SPA uses for code+PKCE in the browser. */
-  webClientId: z8.string().min(1).optional(),
+  webClientId: z12.string().min(1).optional(),
   /** Expected token audience — part of what the CLI binds cached tokens to. */
-  audience: z8.string().min(1).optional(),
+  audience: z12.string().min(1).optional(),
   /**
    * Whether this deployment permits `public` (anonymous) apps. Drives the SPA's
    * visibility UI — it hides the public option when false. Absent = forbidden
@@ -436,9 +1214,9 @@ var AuthConfigResponseSchema = z8.object({
    * opt-in). Server-side enforcement is independent of this hint (portal routes
    * + edge serving).
    */
-  allowPublicApps: z8.boolean().optional(),
+  allowPublicApps: z12.boolean().optional(),
   /** Whether this deployment permits `password` (shared-passphrase) apps. Same shape as {@link allowPublicApps}. */
-  allowPasswordApps: z8.boolean().optional()
+  allowPasswordApps: z12.boolean().optional()
 });
 function portalApiScope(audience) {
   if (!audience || audience.startsWith("urn:")) return null;
@@ -447,27 +1225,27 @@ function portalApiScope(audience) {
 }
 
 // ../shared/src/deployment.ts
-import { z as z9 } from "zod";
-var DeploymentConfigResponseSchema = z9.object({
+import { z as z13 } from "zod";
+var DeploymentConfigResponseSchema = z13.object({
   /**
    * Scheme + host + (non-default) port where apps are served, as reachable by
    * this browser (architecture §4.1). The app slug is prepended as a subdomain:
    * `https://<slug>.<host>`.
    */
-  appPublicBase: z9.url(),
+  appPublicBase: z13.url(),
   /**
    * Base of the opt-in dev gateway (dev-mode design §3), absent when it is not
    * deployed. Unlike {@link appPublicBase} the slug goes in the *path*, not the
    * host. Absent ⇒ dev mode is unavailable here, so the UI says so instead of
    * printing an unreachable host.
    */
-  devApiBase: z9.url().optional(),
+  devApiBase: z13.url().optional(),
   /**
    * Month-to-date platform spend ceiling (USD) for the admin budget watch line.
    * Display-only — the gateway is the choke point, so the rollup is exact, but
    * nothing enforces this. Absent ⇒ no ceiling shown.
    */
-  platformMonthlyUsdCap: z9.number().positive().optional(),
+  platformMonthlyUsdCap: z13.number().positive().optional(),
   /**
    * Deploy bundle size caps in megabytes (`DEPLOY_MAX_FILE_MB` /
    * `DEPLOY_MAX_BUNDLE_MB` on the portal) — `deployMaxFileMb` is per file,
@@ -477,8 +1255,142 @@ var DeploymentConfigResponseSchema = z9.object({
    * substitute a default, because printing the wrong cap to an agent sends it
    * chasing a rejection it can't see the cause of.
    */
-  deployMaxFileMb: z9.number().positive().optional(),
-  deployMaxBundleMb: z9.number().positive().optional()
+  deployMaxFileMb: z13.number().positive().optional(),
+  deployMaxBundleMb: z13.number().positive().optional()
+});
+
+// ../shared/src/catalogue.ts
+import { z as z14 } from "zod";
+var CapabilityCatalogueSchema = z14.object({
+  /**
+   * Visibility modes an app may declare here. `internal` is always present
+   * (SSO, any directory principal — the baseline). `group` is present only when
+   * an IdP with group claims is configured: on a dev-token-only portal it is
+   * absent, matching `/api/v1/auth/config`'s 404. `password` / `public` are
+   * present only when the operator policy permits them
+   * (`PORTAL_ALLOW_*_APPS`). A mode absent from this list is not requestable.
+   */
+  visibility: z14.object({
+    modes: z14.array(VisibilityModeSchema).min(1)
+  }),
+  /**
+   * LLM: the **servable** model ids, not merely the curated catalog. The set is
+   * the operator's declaration when one exists (`PORTAL_LLM_MODEL_ALLOWLIST`,
+   * minus `PORTAL_LLM_MODEL_BLOCKLIST` — ADR-0047; on a `deployFoundry` install
+   * the Bicep derives it from `foundryModels`, so it reads exactly what was
+   * deployed), and otherwise the ADR-0036 v1 heuristic: a model is servable
+   * when its upstream family has a seeded `platform` secret, so a
+   * curated-but-unseeded model (e.g. a `gpt-*` model whose `openai` platform
+   * key was never added) is omitted and an agent that reads this list never
+   * designs an app that 502s at call time. Every id in this list is also
+   * curated, so requesting one is baseline (auto-approve).
+   *
+   * `baselineDollarsPerDay` is the spend cap at/under which an LLM grant
+   * auto-approves; above it queues. From `@azx-pbc/shared/approval.ts`, so the
+   * catalogue and the classifier cannot drift.
+   */
+  llm: z14.object({
+    models: z14.array(z14.string().min(1)),
+    baselineDollarsPerDay: z14.number().positive()
+  }),
+  /**
+   * App-data: whether the three scopes are provisioned here, and the daily
+   * budgets at/under which a data grant auto-approves. `provisioned` is `true`
+   * today (the storage tables exist unconditionally); the field is the seam for
+   * a future deployment-level toggle, present before it is needed. The
+   * baselines come from `@azx-pbc/shared/approval.ts`.
+   */
+  data: z14.object({
+    provisioned: z14.boolean(),
+    baselineWritesPerDay: z14.number().positive(),
+    baselineBytesPerDay: z14.number().positive()
+  }),
+  /**
+   * The fetch-proxy (`/_api/fetch`) and direct-CSP surfaces.
+   *
+   * `externalOriginsPermitted` is `true` when an app may request a direct-CSP
+   * origin grant at all (the surface exists; any entry still queues for
+   * approval). `connections` names the stored `global`-scope secrets an app may
+   * reference from `capabilities.fetch.origins[].connection` — names only, never
+   * values, and without the origin each one fronts: a global secret has no
+   * stored origin (the origin is declared per-app in each manifest), so listing
+   * one here would be a guess. An agent learns "this connection exists and is
+   * referenceable" and supplies the origin itself. `providers` is the configured
+   * OAuth connection providers an app may bind from
+   * `capabilities.fetch.origins[].provider` — metadata-only
+   * {@link CatalogueProviderSchema} entries (ref, kind, display name, API
+   * destinations, env), never a credential field, served to every
+   * authenticated principal exactly like `connections`. An origin bound to a
+   * provider must be one of that provider's `apiOrigins` in the applicable
+   * environment, so an app author picks both from this list.
+   * `baselineRequestsPerDay` is the proxied-request budget at/under which a
+   * fetch grant auto-approves.
+   */
+  fetch: z14.object({
+    externalOriginsPermitted: z14.boolean(),
+    connections: z14.array(z14.object({ name: z14.string().min(1) })),
+    providers: z14.array(CatalogueProviderSchema),
+    baselineRequestsPerDay: z14.number().positive()
+  }),
+  /**
+   * MCP is carried in the manifest but **not enforced** — no transport exists
+   * today. Surfaced as `false` so an agent does not assume a working `mcp`
+   * grant; declaring any server queues for approval regardless.
+   */
+  mcp: z14.object({
+    enforced: z14.boolean()
+  }),
+  /**
+   * Offline (ADR-0035): whether the platform service-worker grant is available,
+   * and the rule a `scope` must satisfy (not the domain root, not a `/_…`
+   * reserved path). Any grant or rescope queues for approval.
+   */
+  offline: z14.object({
+    available: z14.boolean(),
+    /** Human-facing summary of the scope rule; not machine-parsed. */
+    scopeRule: z14.string().min(1)
+  }),
+  /** Deploy bundle size caps in megabytes, as enforced on upload. */
+  deploy: z14.object({
+    maxFileMb: z14.number().positive(),
+    maxBundleMb: z14.number().positive()
+  }),
+  /**
+   * The opt-in dev-gateway base, absent when it is not deployed here (same
+   * convention as `DeploymentConfigResponseSchema.devApiBase`).
+   */
+  devApiBase: z14.url().optional(),
+  /**
+   * The approval half of the catalogue (decision 3). The four baselines mirror
+   * `@azx-pbc/shared/approval.ts` exactly, and `elevationTriggers` enumerates
+   * the requests that **queue for a human** rather than auto-applying — the
+   * thing an agent reads to design an app that ships immediately. A trigger
+   * absent from this list never queues.
+   */
+  approval: z14.object({
+    baselines: z14.object({
+      dollarsPerDay: z14.number().positive(),
+      writesPerDay: z14.number().positive(),
+      bytesPerDay: z14.number().positive(),
+      fetchRequestsPerDay: z14.number().positive()
+    }),
+    elevationTriggers: z14.array(
+      z14.enum([
+        /** Any `externalOrigins` entry — widens CSP for a direct browser call. */
+        "externalOrigins",
+        /** Any `fetch.origins` entry — a proxied outbound origin. */
+        "fetchOrigins",
+        /** Any `mcp` server — no transport is enforced today. */
+        "mcp",
+        /** `visibility: public` — crosses the tenant boundary. */
+        "publicVisibility",
+        /** Any budget above its baseline (LLM spend, data writes/bytes, fetch requests). */
+        "budgetAboveBaseline",
+        /** An LLM model not in this deployment's servable (curated) set. */
+        "uncuratedLlmModel"
+      ])
+    )
+  })
 });
 
 // ../shared/src/scrypt.ts
@@ -494,16 +1406,16 @@ var SCRYPT_PARAMS = {
 };
 
 // ../shared/src/llm.ts
-import { z as z10 } from "zod";
-var LlmMessageSchema = z10.object({
-  role: z10.enum(["user", "assistant"]),
-  content: z10.string().min(1)
+import { z as z15 } from "zod";
+var LlmMessageSchema = z15.object({
+  role: z15.enum(["user", "assistant"]),
+  content: z15.string().min(1)
 });
-var LlmUsageSchema = z10.object({
-  inputTokens: z10.int().nonnegative(),
-  outputTokens: z10.int().nonnegative(),
-  cacheReadInputTokens: z10.int().nonnegative().default(0),
-  cacheCreationInputTokens: z10.int().nonnegative().default(0)
+var LlmUsageSchema = z15.object({
+  inputTokens: z15.int().nonnegative(),
+  outputTokens: z15.int().nonnegative(),
+  cacheReadInputTokens: z15.int().nonnegative().default(0),
+  cacheCreationInputTokens: z15.int().nonnegative().default(0)
 });
 var MAX_SCHEMA_CHARS = 32768;
 var MAX_SCHEMA_DEPTH = 12;
@@ -526,11 +1438,11 @@ function withinSchemaBudget(schema) {
   }
   return serialized.length <= MAX_SCHEMA_CHARS && schemaDepth(schema) <= MAX_SCHEMA_DEPTH;
 }
-var LlmResponseFormatSchema = z10.object({
-  type: z10.literal("json_schema"),
+var LlmResponseFormatSchema = z15.object({
+  type: z15.literal("json_schema"),
   /** Schema name. OpenAI requires one; defaulted at translation when omitted. */
-  name: z10.string().regex(/^[A-Za-z0-9_-]{1,64}$/, "must be 1-64 chars of [A-Za-z0-9_-]").optional(),
-  schema: z10.record(z10.string(), z10.unknown()).refine((s) => s.type === "object", 'schema root must be `{"type":"object"}`').refine(
+  name: z15.string().regex(/^[A-Za-z0-9_-]{1,64}$/, "must be 1-64 chars of [A-Za-z0-9_-]").optional(),
+  schema: z15.record(z15.string(), z15.unknown()).refine((s) => s.type === "object", 'schema root must be `{"type":"object"}`').refine(
     withinSchemaBudget,
     `schema must serialize to <= ${MAX_SCHEMA_CHARS} characters and nest <= ${MAX_SCHEMA_DEPTH} levels`
   )
@@ -540,18 +1452,18 @@ var LlmResponseFormatSchema = z10.object({
   // on `gpt-*` but not `claude-*`, which is exactly the provider leak this seam
   // exists to prevent. The platform always enforces; see ADR-0034.
 });
-var LlmChatRequestSchema = z10.object({
-  model: z10.string().min(1),
-  messages: z10.array(LlmMessageSchema).min(1),
+var LlmChatRequestSchema = z15.object({
+  model: z15.string().min(1),
+  messages: z15.array(LlmMessageSchema).min(1),
   /** Optional system prompt; maps to the vendor's system channel. */
-  system: z10.string().optional(),
-  maxTokens: z10.int().positive().max(128e3).optional(),
+  system: z15.string().optional(),
+  maxTokens: z15.int().positive().max(128e3).optional(),
   /** Sampling temperature; forwarded as-is (the vendor validates its own range). */
-  temperature: z10.number().optional(),
+  temperature: z15.number().optional(),
   /** Nucleus sampling; forwarded as-is. */
-  topP: z10.number().optional(),
+  topP: z15.number().optional(),
   /** Stop sequences; normalized to a list at the boundary. */
-  stop: z10.array(z10.string()).optional(),
+  stop: z15.array(z15.string()).optional(),
   /**
    * Constrain the completion to a JSON schema (ADR-0034). Refused up front when
    * the requested model can't enforce it (`ModelPrice.structuredOutputs`). The
@@ -560,70 +1472,70 @@ var LlmChatRequestSchema = z10.object({
    */
   responseFormat: LlmResponseFormatSchema.optional(),
   /** SSE streaming (default) vs a single JSON body. */
-  stream: z10.boolean().default(true)
+  stream: z15.boolean().default(true)
 });
-var LlmChatResponseSchema = z10.object({
-  model: z10.string(),
-  content: z10.string(),
-  stopReason: z10.string(),
+var LlmChatResponseSchema = z15.object({
+  model: z15.string(),
+  content: z15.string(),
+  stopReason: z15.string(),
   usage: LlmUsageSchema
 });
-var LlmStreamDeltaSchema = z10.object({ text: z10.string() });
-var LlmStreamDoneSchema = z10.object({
-  stopReason: z10.string(),
+var LlmStreamDeltaSchema = z15.object({ text: z15.string() });
+var LlmStreamDoneSchema = z15.object({
+  stopReason: z15.string(),
   usage: LlmUsageSchema
 });
-var LlmStreamErrorSchema = z10.object({
-  code: z10.string(),
-  message: z10.string()
+var LlmStreamErrorSchema = z15.object({
+  code: z15.string(),
+  message: z15.string()
 });
 
 // ../shared/src/llmOpenai.ts
-import { z as z11 } from "zod";
-var OpenAiRoleSchema = z11.enum(["system", "developer", "user", "assistant", "tool"]);
-var OpenAiMessageSchema = z11.object({
+import { z as z16 } from "zod";
+var OpenAiRoleSchema = z16.enum(["system", "developer", "user", "assistant", "tool"]);
+var OpenAiMessageSchema = z16.object({
   role: OpenAiRoleSchema,
-  content: z11.union([z11.string(), z11.array(z11.unknown())]).nullish(),
+  content: z16.union([z16.string(), z16.array(z16.unknown())]).nullish(),
   /** Present only on assistant tool-call turns — parsed to reject, never honored. */
-  tool_calls: z11.array(z11.unknown()).optional(),
-  tool_call_id: z11.string().optional(),
-  name: z11.string().optional()
-});
-var OpenAiStreamOptionsSchema = z11.object({
-  include_usage: z11.boolean().optional()
-});
-var OpenAiResponseFormatSchema = z11.discriminatedUnion("type", [
-  z11.object({
-    type: z11.literal("json_schema"),
-    json_schema: z11.object({
-      name: z11.string().optional(),
-      schema: z11.record(z11.string(), z11.unknown()),
-      strict: z11.boolean().nullish(),
+  tool_calls: z16.array(z16.unknown()).optional(),
+  tool_call_id: z16.string().optional(),
+  name: z16.string().optional()
+});
+var OpenAiStreamOptionsSchema = z16.object({
+  include_usage: z16.boolean().optional()
+});
+var OpenAiResponseFormatSchema = z16.discriminatedUnion("type", [
+  z16.object({
+    type: z16.literal("json_schema"),
+    json_schema: z16.object({
+      name: z16.string().optional(),
+      schema: z16.record(z16.string(), z16.unknown()),
+      strict: z16.boolean().nullish(),
       /**
        * Declared so the codec can reject it rather than zod silently stripping it.
        * It is honorable on the OpenAI path but has no Anthropic equivalent, so
        * forwarding it would make behaviour depend on the backing vendor — the same
        * provider leak that got `json_object` rejected (ADR-0034).
        */
-      description: z11.string().optional()
+      description: z16.string().optional()
     })
   }),
-  z11.object({ type: z11.literal("json_object") }),
-  z11.object({ type: z11.literal("text") })
+  z16.object({ type: z16.literal("json_object") }),
+  z16.object({ type: z16.literal("text") })
 ]);
-var OpenAiChatCompletionRequestSchema = z11.object({
-  model: z11.string().min(1),
-  messages: z11.array(OpenAiMessageSchema).min(1),
-  max_tokens: z11.int().positive().max(128e3).optional(),
-  max_completion_tokens: z11.int().positive().max(128e3).optional(),
-  temperature: z11.number().optional(),
-  top_p: z11.number().optional(),
-  stop: z11.union([z11.string(), z11.array(z11.string())]).optional(),
-  stream: z11.boolean().optional(),
+var OpenAiChatCompletionRequestSchema = z16.object({
+  model: z16.string().min(1),
+  messages: z16.array(OpenAiMessageSchema).min(1),
+  max_tokens: z16.int().positive().max(128e3).optional(),
+  max_completion_tokens: z16.int().positive().max(128e3).optional(),
+  temperature: z16.number().optional(),
+  top_p: z16.number().optional(),
+  stop: z16.union([z16.string(), z16.array(z16.string())]).optional(),
+  stream: z16.boolean().optional(),
   stream_options: OpenAiStreamOptionsSchema.optional(),
   /** Declared so the codec can reject tool use in v1 (not supported). */
-  tools: z11.array(z11.unknown()).optional(),
-  tool_choice: z11.unknown().optional(),
+  tools: z16.array(z16.unknown()).optional(),
+  tool_choice: z16.unknown().optional(),
   /**
    * Structured output (ADR-0034). Parsed, not rejected — see the union above.
    * `.nullish()` because clients and proxies that serialize every field send
@@ -634,193 +1546,228 @@ var OpenAiChatCompletionRequestSchema = z11.object({
   // Behaviour-changing params the platform does not honor in v1. Declared (not
   // stripped) so the codec can reject them with a 400 rather than silently drop
   // them — the same "reject, never silently drop" contract as `tools`.
-  n: z11.unknown().optional(),
-  seed: z11.unknown().optional(),
-  logit_bias: z11.unknown().optional(),
-  presence_penalty: z11.unknown().optional(),
-  frequency_penalty: z11.unknown().optional(),
-  logprobs: z11.unknown().optional(),
-  top_logprobs: z11.unknown().optional()
-});
-var OpenAiUsageSchema = z11.object({
-  prompt_tokens: z11.int().nonnegative(),
-  completion_tokens: z11.int().nonnegative(),
-  total_tokens: z11.int().nonnegative()
-});
-var OpenAiChatCompletionResponseSchema = z11.object({
-  id: z11.string(),
-  object: z11.literal("chat.completion"),
-  created: z11.int(),
-  model: z11.string(),
-  choices: z11.array(
-    z11.object({
-      index: z11.int(),
-      message: z11.object({
-        role: z11.literal("assistant"),
-        content: z11.string()
+  n: z16.unknown().optional(),
+  seed: z16.unknown().optional(),
+  logit_bias: z16.unknown().optional(),
+  presence_penalty: z16.unknown().optional(),
+  frequency_penalty: z16.unknown().optional(),
+  logprobs: z16.unknown().optional(),
+  top_logprobs: z16.unknown().optional()
+});
+var OpenAiUsageSchema = z16.object({
+  prompt_tokens: z16.int().nonnegative(),
+  completion_tokens: z16.int().nonnegative(),
+  total_tokens: z16.int().nonnegative()
+});
+var OpenAiChatCompletionResponseSchema = z16.object({
+  id: z16.string(),
+  object: z16.literal("chat.completion"),
+  created: z16.int(),
+  model: z16.string(),
+  choices: z16.array(
+    z16.object({
+      index: z16.int(),
+      message: z16.object({
+        role: z16.literal("assistant"),
+        content: z16.string()
       }),
-      finish_reason: z11.string()
+      finish_reason: z16.string()
     })
   ),
   usage: OpenAiUsageSchema
 });
-var OpenAiChatCompletionChunkSchema = z11.object({
-  id: z11.string(),
-  object: z11.literal("chat.completion.chunk"),
-  created: z11.int(),
-  model: z11.string(),
-  choices: z11.array(
-    z11.object({
-      index: z11.int(),
-      delta: z11.object({
-        role: z11.literal("assistant").optional(),
-        content: z11.string().optional()
+var OpenAiChatCompletionChunkSchema = z16.object({
+  id: z16.string(),
+  object: z16.literal("chat.completion.chunk"),
+  created: z16.int(),
+  model: z16.string(),
+  choices: z16.array(
+    z16.object({
+      index: z16.int(),
+      delta: z16.object({
+        role: z16.literal("assistant").optional(),
+        content: z16.string().optional()
       }),
-      finish_reason: z11.string().nullable()
+      finish_reason: z16.string().nullable()
     })
   ),
   usage: OpenAiUsageSchema.nullish()
 });
-var OpenAiModelSchema = z11.object({
-  id: z11.string(),
-  object: z11.literal("model"),
-  created: z11.int(),
-  owned_by: z11.string()
+var OpenAiModelSchema = z16.object({
+  id: z16.string(),
+  object: z16.literal("model"),
+  created: z16.int(),
+  owned_by: z16.string()
 });
-var OpenAiModelListSchema = z11.object({
-  object: z11.literal("list"),
-  data: z11.array(OpenAiModelSchema)
+var OpenAiModelListSchema = z16.object({
+  object: z16.literal("list"),
+  data: z16.array(OpenAiModelSchema)
 });
 
 // ../shared/src/usage.ts
-import { z as z12 } from "zod";
-var GATEWAY_OUTCOMES = ["ok", "error", "refusal", "quota_blocked"];
-var GatewayOutcomeSchema = z12.enum(GATEWAY_OUTCOMES);
+import { z as z18 } from "zod";
+
+// ../shared/src/principal.ts
+import { z as z17 } from "zod";
+var PRINCIPAL_KINDS = ["user", "password", "anon", "dev"];
+var PrincipalKindSchema = z17.enum(PRINCIPAL_KINDS);
+
+// ../shared/src/usage.ts
+var GATEWAY_OUTCOMES = [
+  "ok",
+  "error",
+  "refusal",
+  "quota_blocked",
+  "conflict",
+  "forbidden",
+  "connection_required"
+];
+var GatewayOutcomeSchema = z18.enum(GATEWAY_OUTCOMES);
 var USAGE_RANGES = ["24h", "7d", "30d"];
-var UsageRangeSchema = z12.enum(USAGE_RANGES);
+var UsageRangeSchema = z18.enum(USAGE_RANGES);
 var PLATFORM_RANGES = ["7d", "30d", "90d"];
-var PlatformRangeSchema = z12.enum(PLATFORM_RANGES);
-var UsageSeriesPointSchema = z12.object({
-  bucket: z12.iso.datetime(),
-  costUsd: z12.number().nonnegative(),
-  tokens: z12.int().nonnegative(),
-  requests: z12.int().nonnegative()
-});
-var UsageSummarySchema = z12.object({
-  appId: z12.uuid(),
+var PlatformRangeSchema = z18.enum(PLATFORM_RANGES);
+var UsageSeriesPointSchema = z18.object({
+  bucket: z18.iso.datetime(),
+  costUsd: z18.number().nonnegative(),
+  tokens: z18.int().nonnegative(),
+  requests: z18.int().nonnegative()
+});
+var UsageSummarySchema = z18.object({
+  appId: z18.uuid(),
   /** The rolling range these figures cover. */
   range: UsageRangeSchema,
-  requests: z12.int().nonnegative(),
-  inputTokens: z12.int().nonnegative(),
-  outputTokens: z12.int().nonnegative(),
+  requests: z18.int().nonnegative(),
+  inputTokens: z18.int().nonnegative(),
+  outputTokens: z18.int().nonnegative(),
   /** Cache-aware input token totals (0 until prompt caching is enabled). */
-  cacheReadInputTokens: z12.int().nonnegative(),
-  cacheCreationInputTokens: z12.int().nonnegative(),
+  cacheReadInputTokens: z18.int().nonnegative(),
+  cacheCreationInputTokens: z18.int().nonnegative(),
   /** Estimated spend in USD over the window at current rates (./pricing.ts). */
-  costUsd: z12.number().nonnegative(),
+  costUsd: z18.number().nonnegative(),
   /** 95th-percentile upstream latency (ms) over the window; null when no timed calls. */
-  latencyP95Ms: z12.number().nonnegative().nullable(),
+  latencyP95Ms: z18.number().nonnegative().nullable(),
   /** Fraction of calls in the window whose outcome was not `ok` (0..1). */
-  errorRate: z12.number().min(0).max(1),
-  /** Count of calls keyed by outcome (`ok` / `error` / `refusal` / `quota_blocked`). */
-  byOutcome: z12.record(z12.string(), z12.int().nonnegative()),
-  byModel: z12.array(
-    z12.object({
-      model: z12.string(),
-      tokens: z12.int().nonnegative(),
-      requests: z12.int().nonnegative(),
+  errorRate: z18.number().min(0).max(1),
+  /** Count of calls keyed by outcome — see {@link GATEWAY_OUTCOMES}. */
+  byOutcome: z18.record(z18.string(), z18.int().nonnegative()),
+  byModel: z18.array(
+    z18.object({
+      model: z18.string(),
+      tokens: z18.int().nonnegative(),
+      requests: z18.int().nonnegative(),
       /** Estimated spend in USD for this model over the window. */
-      costUsd: z12.number().nonnegative()
+      costUsd: z18.number().nonnegative()
     })
   ),
   /** Dense, zero-filled buckets across the range, oldest-first, for the trend chart. */
-  series: z12.array(UsageSeriesPointSchema),
+  series: z18.array(UsageSeriesPointSchema),
   /**
    * Today-since-midnight totals, independent of `range` — backs the daily-cap
    * gauge (the budget the edge enforces is per calendar day).
    */
-  today: z12.object({
-    tokens: z12.int().nonnegative(),
-    costUsd: z12.number().nonnegative()
+  today: z18.object({
+    tokens: z18.int().nonnegative(),
+    costUsd: z18.number().nonnegative()
   })
 });
-var GatewayCallSchema = z12.object({
-  id: z12.uuid(),
-  appId: z12.uuid(),
+var GatewayCallSchema = z18.object({
+  id: z18.uuid(),
+  appId: z18.uuid(),
   /** App slug at read time; null when the app row no longer exists. */
-  slug: z12.string().nullable(),
-  userOid: z12.string(),
-  capability: z12.string(),
-  model: z12.string(),
-  inputTokens: z12.int().nonnegative(),
-  outputTokens: z12.int().nonnegative(),
-  cacheReadInputTokens: z12.int().nonnegative(),
-  cacheCreationInputTokens: z12.int().nonnegative(),
+  slug: z18.string().nullable(),
+  userOid: z18.string(),
+  /**
+   * The caller's claims as captured when the call was made — the **display half**
+   * (`App.ownerName`/`ownerEmail` applied to the ledger). Render these; never
+   * compare them, and never join on them. Null for anonymous, shared-password and
+   * dev-token callers, and for rows predating the columns, in which case the UI
+   * falls back to `userOid` — an opaque principal id the platform declines
+   * to resolve (no Graph `/users` grant by design, ADR-0040 decision 3; and
+   * pre-re-base rows hold a pairwise `sub`), so it is a last resort rather
+   * than a label.
+   */
+  userName: z18.string().nullable(),
+  userEmail: z18.string().nullable(),
+  /**
+   * Which kind of principal made the call. Read this instead of parsing
+   * `userOid` — see {@link PrincipalKindSchema} for why the obvious shape test is
+   * unsound. Null on rows written before the column, which render from `userOid`.
+   */
+  userKind: PrincipalKindSchema.nullable(),
+  capability: z18.string(),
+  model: z18.string(),
+  inputTokens: z18.int().nonnegative(),
+  outputTokens: z18.int().nonnegative(),
+  cacheReadInputTokens: z18.int().nonnegative(),
+  cacheCreationInputTokens: z18.int().nonnegative(),
   /** Estimated spend in USD for this single call at current rates. */
-  costUsd: z12.number().nonnegative(),
+  costUsd: z18.number().nonnegative(),
   /** Upstream round-trip latency in ms (0 when not measured). */
-  durationMs: z12.int().nonnegative(),
+  durationMs: z18.int().nonnegative(),
   /** Upstream/egress HTTP status — set for `fetch`; null for streamed `llm`. */
-  statusCode: z12.int().nullable(),
+  statusCode: z18.int().nullable(),
+  /**
+   * Request path of the proxied call — set for `fetch`; null otherwise. The
+   * target's query string is excluded (see `redactFetchTarget` in `./logging.ts`)
+   * because that is where credentials are conventionally placed — but a path can
+   * carry one too, and nothing here detects that. See ADR-0021.
+   */
+  path: z18.string().nullable(),
+  /** HTTP method of the proxied call — set for `fetch`; null otherwise. */
+  method: z18.string().nullable(),
   /** LLM stop reason; null for non-LLM calls. */
-  stopReason: z12.string().nullable(),
+  stopReason: z18.string().nullable(),
   /** Short upstream error string; null on success. */
-  errorDetail: z12.string().nullable(),
+  errorDetail: z18.string().nullable(),
   outcome: GatewayOutcomeSchema,
-  createdAt: z12.iso.datetime()
+  createdAt: z18.iso.datetime()
 });
-var GatewayAuditPageSchema = z12.object({
-  rows: z12.array(GatewayCallSchema),
+var GatewayAuditPageSchema = z18.object({
+  rows: z18.array(GatewayCallSchema),
   /** Pass as `?before=` to fetch the next (older) page; absent when exhausted. */
-  nextBefore: z12.iso.datetime().optional()
+  nextBefore: z18.iso.datetime().optional()
 });
-var PlatformUsageSchema = z12.object({
+var PlatformUsageSchema = z18.object({
   /** The rolling range the series + breakdowns cover. */
   range: PlatformRangeSchema,
   /** Dense, zero-filled daily buckets across the range, oldest-first. */
-  series: z12.array(UsageSeriesPointSchema),
+  series: z18.array(UsageSeriesPointSchema),
   /** Per-app rollup over the range, busiest-first. */
-  byApp: z12.array(
-    z12.object({
-      slug: z12.string().nullable(),
-      tokens: z12.int().nonnegative(),
-      requests: z12.int().nonnegative(),
+  byApp: z18.array(
+    z18.object({
+      slug: z18.string().nullable(),
+      tokens: z18.int().nonnegative(),
+      requests: z18.int().nonnegative(),
       /** Estimated spend in USD for this app over the range. */
-      costUsd: z12.number().nonnegative()
+      costUsd: z18.number().nonnegative()
     })
   ),
   /** Month-to-date headline KPIs (independent of `range`). */
-  totals: z12.object({
-    tokensMTD: z12.int().nonnegative(),
-    requestsMTD: z12.int().nonnegative(),
+  totals: z18.object({
+    tokensMTD: z18.int().nonnegative(),
+    requestsMTD: z18.int().nonnegative(),
     /** Estimated month-to-date spend in USD across all apps. */
-    costMTD: z12.number().nonnegative(),
+    costMTD: z18.number().nonnegative(),
     /** Distinct `userOid`s seen month-to-date. */
-    activeUsers: z12.int().nonnegative()
+    activeUsers: z18.int().nonnegative()
   }),
   /** Token + cost share by capability over the range (essentially all `llm` in M4). */
-  capabilityMix: z12.array(
-    z12.object({
-      capability: z12.string(),
-      tokens: z12.int().nonnegative(),
+  capabilityMix: z18.array(
+    z18.object({
+      capability: z18.string(),
+      tokens: z18.int().nonnegative(),
       /** Estimated spend in USD for this capability over the range. */
-      costUsd: z12.number().nonnegative()
+      costUsd: z18.number().nonnegative()
     })
   )
 });
 
 // ../shared/src/data.ts
-import { z as z14 } from "zod";
-
-// ../shared/src/env.ts
-import { z as z13 } from "zod";
-var ENVS = ["prod", "dev"];
-var EnvSchema = z13.enum(ENVS);
-
-// ../shared/src/data.ts
-var CollectionItemSchema = z14.object({
-  id: z14.uuid(),
-  collection: z14.string(),
+import { z as z19 } from "zod";
+var CollectionItemSchema = z19.object({
+  id: z19.uuid(),
+  collection: z19.string(),
   /**
    * Which tier collected the row (dev-mode §5). The runtime roles are RLS-pinned
    * to one tier each, but the portal reads across both, so the discriminator has
@@ -829,148 +1776,215 @@ var CollectionItemSchema = z14.object({
    */
   env: EnvSchema,
   /** The submitting user, if authenticated; null for anonymous/public visitors. */
-  userOid: z14.string().nullable(),
-  item: z14.unknown(),
+  userOid: z19.string().nullable(),
+  /**
+   * The submitter's captured claims — display half, rendered but never compared
+   * (see `GatewayCallSchema.userName`). Null whenever `userOid` is, and for
+   * password/dev-token principals.
+   */
+  userName: z19.string().nullable(),
+  userEmail: z19.string().nullable(),
+  /** The submitter's kind; null whenever `userOid` is, and on pre-column rows. */
+  userKind: PrincipalKindSchema.nullable(),
+  item: z19.unknown(),
   /** Hashed IP / truncated UA for abuse triage; null if not captured. */
-  meta: z14.unknown().nullable(),
-  createdAt: z14.iso.datetime()
+  meta: z19.unknown().nullable(),
+  createdAt: z19.iso.datetime()
 });
-var CollectionItemsPageSchema = z14.object({
-  rows: z14.array(CollectionItemSchema),
+var CollectionItemsPageSchema = z19.object({
+  rows: z19.array(CollectionItemSchema),
   /** Pass as `?before=` to fetch the next (older) page; absent when exhausted. */
-  nextBefore: z14.iso.datetime().optional()
+  nextBefore: z19.iso.datetime().optional()
 });
-var CollectionSummarySchema = z14.object({
-  name: z14.string(),
+var CollectionSummarySchema = z19.object({
+  name: z19.string(),
   env: EnvSchema,
-  count: z14.int().nonnegative(),
+  count: z19.int().nonnegative(),
   /** Newest row's timestamp; null only if the group is somehow empty. */
-  lastAt: z14.iso.datetime().nullable()
+  lastAt: z19.iso.datetime().nullable()
 });
 
 // ../shared/src/collectionTable.ts
 var BOM = String.fromCharCode(65279);
 
-// ../shared/src/secrets.ts
-import { z as z15 } from "zod";
-var FORBIDDEN_HEADER_NAMES = /* @__PURE__ */ new Set([
-  "host",
-  "content-length",
-  "transfer-encoding",
-  "connection",
-  "te",
-  "upgrade",
-  "expect",
-  "trailer"
+// ../shared/src/connections.ts
+import { z as z20 } from "zod";
+var CONNECTION_STATUSES = ["live", "reconnect-needed", "invalidated"];
+var ConnectionStatusSchema = z20.enum(CONNECTION_STATUSES);
+var ConnectionMaterialSchema = z20.strictObject({
+  access: z20.string().min(1),
+  refresh: z20.string().min(1)
+});
+var MAX_GRANTED_SCOPES = 64;
+var GrantedScopesSchema = z20.array(ScopeTokenSchema).max(MAX_GRANTED_SCOPES);
+var UserConnectionSchema = z20.strictObject({
+  id: z20.uuid(),
+  userOid: z20.string().min(1),
+  providerId: z20.uuid(),
+  providerRevision: z20.int().positive(),
+  env: EnvSchema,
+  status: ConnectionStatusSchema,
+  material: z20.string().min(1),
+  grantedScopes: GrantedScopesSchema,
+  grantedAt: z20.iso.datetime(),
+  expiresAt: z20.iso.datetime(),
+  renewBeforeNext: z20.boolean(),
+  pendingRetire: z20.string().min(1).nullable(),
+  lastRenewedAt: z20.iso.datetime().nullable(),
+  createdAt: z20.iso.datetime(),
+  updatedAt: z20.iso.datetime()
+});
+var MyConnectionSchema = z20.strictObject({
+  id: z20.uuid(),
+  providerRef: ProviderRefSchema,
+  providerDisplayName: z20.string().min(1).max(200),
+  env: EnvSchema,
+  status: ConnectionStatusSchema.exclude(["invalidated"]),
+  grantedScopes: GrantedScopesSchema,
+  grantedAt: z20.iso.datetime(),
+  sharedApps: z20.array(BoundAppSchema)
+});
+var MyConnectionsResponseSchema = z20.strictObject({
+  connections: z20.array(MyConnectionSchema)
+});
+var DisconnectResponseSchema = z20.strictObject({
+  outcome: z20.enum(["disconnected", "already_removed"])
+});
+
+// ../shared/src/consent.ts
+import { z as z21 } from "zod";
+var ConsentStateSchema = z21.string().min(43).max(128);
+var ConsentNonceSchema = z21.string().min(16).max(128);
+var ConsentAttemptTagSchema = z21.string().min(1).max(128).regex(/^[A-Za-z0-9._~-]+$/, "must be URL-safe punctuation, letters, or digits");
+var ConsentIdentitySchema = z21.discriminatedUnion("kind", [
+  z21.strictObject({ kind: z21.literal("user"), userOid: z21.string().min(1).max(128) }),
+  z21.strictObject({
+    kind: z21.literal("dev"),
+    developerOid: z21.string().min(1).max(128),
+    nonce: ConsentNonceSchema
+  })
 ]);
-var HEADER_TOKEN = /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/;
-var HEADER_VALUE_SAFE = /^[\t\x20-\x7e]*$/;
-var HEADER_VALUE_WIRE = /^[\t\x20-\x7e\x80-\xff]*$/;
-var headerName = (from) => {
-  const base = z15.string().min(1);
-  return (from === "request" ? base.max(64).regex(HEADER_TOKEN, "must be an RFC 7230 token") : base).transform((n) => n.trim().toLowerCase()).refine((n) => !FORBIDDEN_HEADER_NAMES.has(n), "reserved header name").refine((n) => !n.startsWith("x-helix-"), "reserved header prefix");
-};
-var headerTemplate = (from) => from === "request" ? z15.string().max(512).regex(HEADER_VALUE_SAFE) : z15.string().regex(HEADER_VALUE_WIRE);
-var injectionRecipe = (from) => z15.discriminatedUnion("kind", [
-  /** `Authorization: Bearer <secret>` — the common case. */
-  z15.object({ kind: z15.literal("header-bearer") }),
-  /** Arbitrary header; `{}` in `template` is replaced with the secret. */
-  z15.object({
-    kind: z15.literal("header"),
-    name: headerName(from),
-    template: headerTemplate(from).default("{}")
-  }),
-  /** Query parameter `?<param>=<secret>`. */
-  z15.object({ kind: z15.literal("query"), param: z15.string().min(1) }),
-  /**
-   * HMAC over a timestamp. The signed input is the timestamp string **alone** —
-   * not the method, path, query, or body — so injection is a pure function of
-   * (private key, now) and needs no request context.
-   *
-   * The canonical form lives in the KIND NAME, deliberately. A scheme that signs
-   * method+path+body is a *sibling kind* (`hmac-request`) — a code change with
-   * tests, reviewed — never an admin-editable canonical-string template.
-   * Canonicalization is where implementations of this family go wrong, and it
-   * does not belong in a text box.
-   *
-   * SHA-256, lowercase-hex, and ISO-8601-with-milliseconds are fixed rather than
-   * configurable. Each would carry a default, and `app_secrets.injection` is a
-   * schemaless JSON column, so adding a knob later is purely additive with no
-   * migration — while fixing them now removes the weak-algorithm and
-   * unencodable-digest failure classes outright.
-   *
-   * The stored value is a JSON blob carrying both halves of the key pair
-   * ({@link HmacCredentialSchema}): regenerating the pair changes both, and a
-   * blob rotates atomically through the existing rotate route.
-   */
-  z15.object({
-    kind: z15.literal("hmac-timestamp"),
-    /** Header carrying the timestamp that is also the entire signed input. */
-    timestampHeader: headerName(from),
-    /** Header carrying the rendered credential + signature. */
-    authHeader: headerName(from).default("authorization"),
-    /**
-     * Value written to `authHeader`. `{credential}` and `{signature}` are
-     * substituted. Named rather than the `header` kind's bare `{}` because there
-     * are two substitutions: the convention is one value ⇒ `{}`, more than one ⇒
-     * named placeholders. Positional `{}` here would let a swapped template
-     * produce a well-formed header that silently fails to authenticate.
-     *
-     * Both placeholders are required. This recipe writes exactly two headers,
-     * one of them the timestamp, so there is no configuration where the public
-     * credential id travels elsewhere — omitting `{credential}` means the
-     * upstream can never identify the key and every call 401s.
-     */
-    template: headerTemplate(from).refine((t) => t.includes("{signature}"), "template must contain {signature}").refine((t) => t.includes("{credential}"), "template must contain {credential}")
-  }).refine(
-    (r) => r.timestampHeader !== r.authHeader,
-    "timestampHeader and authHeader must differ \u2014 the second write overwrites the first"
-  )
+var HttpUrlNoUserinfoSchema = (() => {
+  const userinfo = /^https?:\/\/[/\\]*[^/?#\\]*@/i;
+  return z21.url({ protocol: /^https?$/ }).refine(
+    (value) => !userinfo.test(value.replace(/[\t\n\r]/g, "")),
+    "URL must not carry userinfo"
+  );
+})();
+var ConsultRequestSchema = z21.strictObject({
+  identity: ConsentIdentitySchema,
+  appSlug: z21.string().regex(SLUG_PATTERN, "must be a lowercase DNS label (a-z, 0-9, hyphen)"),
+  providerRef: ProviderRefSchema,
+  openerOrigin: HttpUrlNoUserinfoSchema.transform((value) => new URL(value).origin),
+  callbackUrl: HttpUrlNoUserinfoSchema
+});
+var ConsultResponseSchema = z21.discriminatedUnion("outcome", [
+  z21.strictObject({ outcome: z21.literal("already_connected") }),
+  z21.strictObject({ outcome: z21.literal("not_available") }),
+  z21.strictObject({ outcome: z21.literal("started"), authorizeUrl: z21.url() })
 ]);
-var InjectionRecipeSchema = injectionRecipe("request");
-var StoredInjectionRecipeSchema = injectionRecipe("stored");
-var HmacCredentialSchema = z15.object({
-  credential: z15.string().min(1),
-  key: z15.string().min(1)
+var CancelRequestSchema = z21.strictObject({
+  identity: ConsentIdentitySchema,
+  state: ConsentStateSchema
 });
-var SECRET_SCOPES = ["app", "global", "platform"];
-var SecretScopeSchema = z15.enum(SECRET_SCOPES);
-var SecretMetadataSchema = z15.object({
-  id: z15.string(),
-  name: z15.string().min(1),
-  scope: SecretScopeSchema,
-  /** Partition tier (dev-mode §6): a dev fetch injects only `dev` connection secrets. */
-  env: EnvSchema,
-  /**
-   * The **stored** parser, not the strict one — this field describes a row, and
-   * the SPA re-parses this schema on every response. Using the strict parser here
-   * would let the portal return a name the browser then refuses, moving the read
-   * failure from the server to the client, where it presents as a dead page.
-   *
-   * `null` = the stored recipe is unreadable (it names a reserved header, or is
-   * not a recipe at all). The credential still exists and is still deletable; it
-   * cannot be rotated, and egress fails its hop closed. Recipes are immutable by
-   * design, so recovery is delete-and-recreate.
-   */
-  injection: StoredInjectionRecipeSchema.nullable(),
-  createdBy: z15.string(),
-  createdAt: z15.string(),
-  rotatedAt: z15.string().nullable().optional(),
-  lastUsedAt: z15.string().nullable().optional(),
-  boundApps: z15.array(z15.string()).default([])
-});
-var SecretCreateRequestSchema = z15.object({
-  name: z15.string().min(1).max(64).regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase letters, digits, and hyphens"),
-  value: z15.string().min(1),
-  /** Target tier (dev-mode §6). Defaults `prod`; `dev` configures a dev-tier credential. */
-  env: EnvSchema.default("prod"),
-  injection: InjectionRecipeSchema.default({ kind: "header-bearer" })
+var CONSENT_CANCEL_OUTCOMES = ["cancelled", "not_cancellable"];
+var CancelResponseSchema = z21.strictObject({
+  outcome: z21.enum(CONSENT_CANCEL_OUTCOMES)
+});
+var ConnectionStatusIdentitySchema = z21.discriminatedUnion("kind", [
+  z21.strictObject({ kind: z21.literal("user"), userOid: z21.string().min(1).max(128) }),
+  z21.strictObject({ kind: z21.literal("dev"), developerOid: z21.string().min(1).max(128) })
+]);
+var ConnectionStatusRequestSchema = z21.strictObject({
+  identity: ConnectionStatusIdentitySchema,
+  appSlug: z21.string().regex(SLUG_PATTERN, "must be a lowercase DNS label (a-z, 0-9, hyphen)"),
+  providerRef: ProviderRefSchema
+});
+var ConnectionStatusResponseSchema = z21.strictObject({
+  status: z21.enum(["connected", "not_connected", "not_available"])
+});
+var AttemptCancelRequestSchema = z21.strictObject({
+  provider: ProviderRefSchema,
+  attempt: ConsentAttemptTagSchema
+});
+var DevConsentStartResponseSchema = z21.discriminatedUnion("outcome", [
+  z21.strictObject({ outcome: z21.literal("started"), popupUrl: z21.url() }),
+  z21.strictObject({ outcome: z21.literal("already_connected") }),
+  z21.strictObject({ outcome: z21.literal("not_available") })
+]);
+var HELIX_CONNECT_MESSAGE_SOURCE = "helix-connect";
+var CONNECT_MESSAGE_VERSION = 1;
+var CONSENT_MESSAGE_OUTCOMES = [
+  "connected",
+  "already_connected",
+  "denied",
+  "cancelled",
+  "timeout",
+  "blocked",
+  "signin_required",
+  "error"
+];
+var CONSENT_MESSAGE_REASONS = [
+  "conflict",
+  "provider_unavailable",
+  "provider_misconfigured",
+  "provider_incompatible",
+  "service_unavailable"
+];
+var ConnectOutcomeMessageSchema = z21.strictObject({
+  source: z21.literal(HELIX_CONNECT_MESSAGE_SOURCE),
+  version: z21.literal(CONNECT_MESSAGE_VERSION),
+  attempt: ConsentAttemptTagSchema.optional(),
+  provider: ProviderRefSchema,
+  outcome: z21.enum(CONSENT_MESSAGE_OUTCOMES),
+  reason: z21.enum(CONSENT_MESSAGE_REASONS).nullable()
+}).refine((message) => message.outcome === "error" || message.reason === null, {
+  error: "reason is only carried with the error outcome"
+});
+var ConnectResultSchema = z21.object({
+  outcome: z21.enum(CONSENT_MESSAGE_OUTCOMES),
+  provider: z21.string(),
+  attempt: ConsentAttemptTagSchema.optional(),
+  reason: z21.enum(CONSENT_MESSAGE_REASONS).optional()
+}).refine((result) => result.outcome === "error" || result.reason === void 0, {
+  error: "reason is only carried with the error outcome"
 });
-var SecretRotateRequestSchema = z15.object({ value: z15.string().min(1) });
-var SecretGrantRequestSchema = z15.object({ appSlug: z15.string().min(1) });
+
+// ../shared/src/exchange.ts
+import { z as z22 } from "zod";
+var ExchangeCodeSchema = z22.string().min(1).max(1024);
+var CodeVerifierSchema = z22.string().min(43).max(128).regex(/^[A-Za-z0-9\-._~]+$/, "must be an RFC 7636 code_verifier (43-128 unreserved characters)");
+var ExchangeRequestSchema = z22.strictObject({
+  providerId: z22.uuid(),
+  providerRevision: z22.int().positive(),
+  env: EnvSchema,
+  code: ExchangeCodeSchema,
+  codeVerifier: CodeVerifierSchema,
+  redirectUri: HttpUrlNoUserinfoSchema
+});
+var EXCHANGE_REJECTION_REASONS = [
+  "unusable_lifetime",
+  "missing_refresh_token",
+  "missing_permissions"
+];
+var ExchangeRejectionReasonSchema = z22.enum(EXCHANGE_REJECTION_REASONS);
+var MAX_EXCHANGED_SCOPES = 64;
+var ExchangedScopesSchema = z22.array(ScopeTokenSchema).max(MAX_EXCHANGED_SCOPES);
+var ExchangeResponseSchema = z22.discriminatedUnion("outcome", [
+  z22.strictObject({
+    outcome: z22.literal("exchanged"),
+    access: z22.string().min(1),
+    refresh: z22.string().min(1),
+    grantedScopes: ExchangedScopesSchema,
+    accessExpiresAt: z22.iso.datetime()
+  }),
+  z22.strictObject({ outcome: z22.literal("rejected"), reason: ExchangeRejectionReasonSchema }),
+  z22.strictObject({ outcome: z22.literal("provider_unavailable") }),
+  z22.strictObject({ outcome: z22.literal("exchange_failed") })
+]);
 
 // ../shared/src/devTokens.ts
-import { z as z16 } from "zod";
+import { z as z23 } from "zod";
 function isValidDevOrigin(input) {
   if (input.includes("*")) return false;
   let url;
@@ -984,47 +1998,69 @@ function isValidDevOrigin(input) {
   if (url.username !== "" || url.password !== "") return false;
   return input === url.origin || input === `${url.origin}/`;
 }
-var DevOriginSchema = z16.string().refine(
+var DevOriginSchema = z23.string().refine(
   isValidDevOrigin,
   "must be an exact origin (scheme://host[:port]) \u2014 no path, query, or wildcard"
 ).transform((o) => new URL(o).origin);
-var TtlDaysSchema = z16.number().int().min(1).max(365).optional();
-var DevTokenMintRequestSchema = z16.object({
-  origins: z16.array(DevOriginSchema).min(1).max(20),
+var TtlDaysSchema = z23.number().int().min(1).max(365).optional();
+var DevTokenMintRequestSchema = z23.object({
+  origins: z23.array(DevOriginSchema).min(1).max(20),
   ttlDays: TtlDaysSchema
 });
-var DevTokenRotateRequestSchema = z16.object({
+var DevTokenRotateRequestSchema = z23.object({
   ttlDays: TtlDaysSchema
 });
-var DevTokenMetadataSchema = z16.object({
-  id: z16.string(),
-  developerOid: z16.string(),
-  origins: z16.array(z16.string()),
-  expiresAt: z16.string(),
-  revokedAt: z16.string().nullable().optional(),
-  createdAt: z16.string()
-});
-var DevTokenMintResponseSchema = z16.object({
-  token: z16.string(),
+var DevTokenMetadataSchema = z23.object({
+  id: z23.string(),
+  developerOid: z23.string(),
+  origins: z23.array(z23.string()),
+  expiresAt: z23.string(),
+  revokedAt: z23.string().nullable().optional(),
+  createdAt: z23.string()
+});
+var DevTokenMintResponseSchema = z23.object({
+  token: z23.string(),
   metadata: DevTokenMetadataSchema
 });
 
 // ../shared/src/instruction.ts
-import { z as z17 } from "zod";
+import { z as z24 } from "zod";
 var INSTRUCTION_CAPABILITIES = ["fetch", "llm"];
-var InstructionCapabilitySchema = z17.enum(INSTRUCTION_CAPABILITIES);
-var AttestedInstructionSchema = z17.object({
+var InstructionCapabilitySchema = z24.enum(INSTRUCTION_CAPABILITIES);
+var AttestedInstructionSchema = z24.strictObject({
   /** App the call is attributed to (registry app id). */
-  appId: z17.string().min(1),
+  appId: z24.string().min(1),
   /** Authenticated user, or the anonymous sentinel on `public` apps. */
-  userOid: z17.string().min(1),
+  userOid: z24.string().min(1),
+  /**
+   * Which kind of principal `userOid` is (the `PrincipalKind` vocabulary the
+   * edge records at capture time — recorded, never inferred). The delegated
+   * resolution refuses `anon` and `password` callers — they can
+   * never hold a connection — and serving that refusal
+   * requires knowing the KIND: `userOid`'s shape proves nothing (a shared-
+   * password pseudonym and an Entra `sub` share the base64url alphabet, and
+   * the sentinel is only exact for `anon`). Optional on the payload as a
+   * whole so secret-backed and keyless instructions keep minting unchanged;
+   * mandatory on a delegated one — the refine below makes a provider-bearing
+   * instruction without it unrepresentable, so an old edge cannot mint a
+   * delegated call egress would have to guess about.
+   */
+  userKind: PrincipalKindSchema.optional(),
   capability: InstructionCapabilitySchema,
   /** The allowlisted origin the edge authorized (scheme + host + port). */
-  origin: z17.url(),
+  origin: z24.url(),
   /** Connection (secret) name to inject, if this is a secret-backed call. */
-  connection: z17.string().min(1).optional(),
+  connection: z24.string().min(1).optional(),
+  /**
+   * Provider reference for a delegated call — the user's connection to this
+   * provider is what egress injects. Exactly
+   * one credential source travels: this and `connection` are XOR-enforced
+   * below — a delegated instruction carries a provider ref or a
+   * secret name, never both.
+   */
+  provider: ProviderRefSchema.optional(),
   /** Correlates the edge audit row with the egress call. */
-  requestId: z17.string().min(1),
+  requestId: z24.string().min(1),
   /**
    * The HTTP method + URL pathname the edge authorized (ADR-0013 step 2, issue #6).
    * Egress refuses a mismatched verb/resource, so a captured instruction can't be
@@ -1039,8 +2075,8 @@ var AttestedInstructionSchema = z17.object({
    * means "old edge", not tampering — egress asserts ONLY when the claim is
    * present. Make required once a fleet is reliably past deploy.
    */
-  method: z17.string().min(1).optional(),
-  path: z17.string().optional(),
+  method: z24.string().min(1).optional(),
+  path: z24.string().optional(),
   /**
    * Environment tier this call is scoped to (dev-mode design §6). Egress resolves
    * the connection secret within this tier — a `dev` instruction can never reach a
@@ -1049,12 +2085,27 @@ var AttestedInstructionSchema = z17.object({
    * minted before this field existed verifies as production.
    */
   env: EnvSchema.default("prod")
+}).superRefine((i, ctx) => {
+  if (i.connection !== void 0 && i.provider !== void 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["provider"],
+      message: "an instruction carries exactly one credential source \u2014 a connection secret or a provider reference, never both."
+    });
+  }
+  if (i.provider !== void 0 && i.userKind === void 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["userKind"],
+      message: "a delegated instruction must carry the caller's principal kind \u2014 egress refuses anonymous and shared-password callers by kind, never by inferring it from userOid."
+    });
+  }
 });
 var INSTRUCTION_TTL_SECONDS = 30;
 var INSTRUCTION_BURN_RETENTION_SECONDS = INSTRUCTION_TTL_SECONDS + 15;
 
 // ../shared/src/fetch.ts
-import { z as z18 } from "zod";
+import { z as z25 } from "zod";
 var FETCH_ERROR_CODES = [
   "forbidden",
   "rate_limited",
@@ -1062,12 +2113,75 @@ var FETCH_ERROR_CODES = [
   "blocked",
   "too_large",
   "replay",
-  "upstream_error"
+  "upstream_error",
+  "connection_required",
+  "provider_unavailable",
+  "provider_misconfigured"
 ];
-var FetchErrorCodeSchema = z18.enum(FETCH_ERROR_CODES);
-var FetchProxyErrorSchema = z18.object({
+var FetchErrorCodeSchema = z25.enum(FETCH_ERROR_CODES);
+var FetchErrorProviderSchema = z25.strictObject({
+  ref: ProviderRefSchema,
+  displayName: z25.string().min(1).max(200).optional()
+});
+var FetchProxyErrorSchema = z25.object({
   code: FetchErrorCodeSchema,
-  message: z18.string()
+  message: z25.string(),
+  /** Present only on the delegated-call codes that carry it (`connection_required`, `provider_unavailable`). */
+  provider: FetchErrorProviderSchema.optional()
+});
+
+// ../shared/src/sessions.ts
+import { z as z26 } from "zod";
+var SessionPrincipalKindSchema = z26.enum(["user", "password"]);
+var SessionSummarySchema = z26.object({
+  id: z26.uuid(),
+  appId: z26.uuid(),
+  /** App slug at read time; the FK guarantees the app row exists. */
+  slug: z26.string(),
+  /**
+   * The identity half — Entra's `oid` claim since ADR-0048 (a pairwise `sub`
+   * on rows that predate the re-base; a `pw_*` pseudonym for shared-password
+   * visitors). Compared and joined on, never rendered except as a last
+   * resort: the platform deliberately holds no Graph `/users` grant, so no
+   * principal id it stores resolves to a name.
+   */
+  userOid: z26.string(),
+  /**
+   * The display half, captured at login. Render, never compare. Null for
+   * shared-password visitors (each login is a fresh pseudonym) and for rows
+   * predating the columns.
+   */
+  userName: z26.string().nullable(),
+  userEmail: z26.string().nullable(),
+  userKind: SessionPrincipalKindSchema.nullable(),
+  /** Group-id snapshot as of this session's login/refresh. */
+  groups: z26.array(z26.string()),
+  createdAt: z26.iso.datetime(),
+  /** Null while the handoff is un-redeemed — impossible here (live rows only). */
+  activatedAt: z26.iso.datetime().nullable(),
+  /** When silent re-auth (`prompt=none`) becomes due; past = overdue. */
+  refreshDueAt: z26.iso.datetime(),
+  /** Hard cap — the session is dead at this instant regardless of activity. */
+  expiresAt: z26.iso.datetime()
+});
+var SessionListResponseSchema = z26.object({
+  rows: z26.array(SessionSummarySchema),
+  groupNames: z26.record(z26.string(), z26.string().nullable()),
+  groupsResolved: z26.boolean()
+});
+var SessionRevokeRequestSchema = z26.object({
+  /**
+   * A session's principal id as seen in the list — the `oid` claim, a `pw_*`
+   * pseudonym, or a pre-re-base pairwise `sub`. Opaque to the admin; copied
+   * from the row they clicked, so its shape is whatever the session rows
+   * hold — bounded only against abuse, not parsed.
+   */
+  userOid: z26.string().min(1).max(200)
+});
+var SessionRevokeResultSchema = z26.object({
+  removed: z26.int().nonnegative(),
+  /** Slugs of the apps the removed sessions lived on; empty when none. */
+  apps: z26.array(z26.string())
 });
 
 // src/client.ts
@@ -1079,7 +2193,7 @@ var CliError = class extends Error {
     this.code = code;
   }
 };
-var VersionListSchema = z19.array(VersionSchema);
+var VersionListSchema = z27.array(VersionSchema);
 var PortalClient = class {
   #baseUrl;
   #tokenProvider;
@@ -1089,7 +2203,17 @@ var PortalClient = class {
     this.#tokenProvider = typeof token === "string" ? async () => token : token;
   }
   createApp(input) {
-    return this.#json(AppSchema, "POST", "/api/v1/apps", { auth: true, body: input });
+    return this.#json(AppSchema, "POST", "/api/v1/apps", {
+      auth: true,
+      body: {
+        slug: input.slug,
+        displayName: input.displayName,
+        // Sent only when set, so a description-free create posts exactly the
+        // body it always did — an older portal never sees a new key at all.
+        ...input.description !== void 0 ? { description: input.description } : {},
+        ...input.visibility !== void 0 ? { visibility: input.visibility } : {}
+      }
+    });
   }
   /** Public IdP discovery info — how `helix login` finds the issuer. */
   getAuthConfig() {
@@ -1099,6 +2223,15 @@ var PortalClient = class {
   me() {
     return this.#json(PortalMeResponseSchema, "GET", "/api/v1/me", { auth: true });
   }
+  /**
+   * The deployment-rendered agent skill (`GET /api/v1/skill`, ADR-0036) —
+   * `text/markdown`, already substituted with this deployment's hosts, servable
+   * models, and approval baselines. Authed like every other `/api/v1` read.
+   * Powers `helix skill`.
+   */
+  getSkill() {
+    return this.#text("/api/v1/skill", { auth: true });
+  }
   listVersions(slug) {
     return this.#json(VersionListSchema, "GET", `/api/v1/apps/${enc(slug)}/versions`, {
       auth: true
@@ -1156,23 +2289,47 @@ var PortalClient = class {
     }
     return schema.parse(data);
   }
+  /** A non-JSON GET (the markdown skill) — errors still typed via the envelope. */
+  async #text(path3, opts) {
+    const headers = await this.#authHeaders(opts.auth ?? false);
+    const res = await fetch(this.#url(path3), { method: "GET", headers });
+    const body = await res.text();
+    if (!res.ok) {
+      const data = body ? safeJsonParse(body) : void 0;
+      const parsed = ApiErrorSchema.safeParse(data);
+      if (parsed.success) throw new CliError(parsed.data.error.message, parsed.data.error.code);
+      throw new CliError(`request failed (HTTP ${res.status})`);
+    }
+    return body;
+  }
 };
 function enc(segment) {
   return encodeURIComponent(segment);
 }
+function safeJsonParse(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return void 0;
+  }
+}
 
 // src/commands.ts
-import { readFile as readFile2 } from "node:fs/promises";
+import { readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
+import { resolve } from "node:path";
+
+// ../deploy-skill/src/index.ts
+var SKILL_FILENAME = "SKILL.md";
 
 // src/zip.ts
 import { ZipArchive } from "archiver";
 function zipDirectory(dir) {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     const chunks = [];
     const archive = new ZipArchive({ zlib: { level: 9 } });
     archive.on("data", (c) => chunks.push(c));
     archive.on("error", reject);
-    archive.on("end", () => resolve(Buffer.concat(chunks)));
+    archive.on("end", () => resolve2(Buffer.concat(chunks)));
     archive.directory(dir, false);
     void archive.finalize();
   });
@@ -1297,9 +2454,16 @@ function requireSlug(config) {
 function parseVisibility(input) {
   if (!input) return void 0;
   if (input.startsWith("group:")) {
-    const groupId = input.slice("group:".length);
-    if (!groupId) throw new CliError("group visibility needs an id: group:<id>");
-    return { mode: "group", groupId };
+    const groupIds = input.slice("group:".length).split(",").map((id) => id.trim()).filter((id) => id.length > 0);
+    if (groupIds.length === 0) {
+      throw new CliError("group visibility needs at least one id: group:<id>[,<id>\u2026]");
+    }
+    if (groupIds.length > MAX_VISIBILITY_GROUPS) {
+      throw new CliError(
+        `group visibility takes at most ${MAX_VISIBILITY_GROUPS} ids (got ${groupIds.length})`
+      );
+    }
+    return { mode: "group", groupIds };
   }
   if (input === "internal" || input === "password" || input === "public") {
     return { mode: input };
@@ -1309,7 +2473,9 @@ function parseVisibility(input) {
       'visibility "private" was renamed to "internal" (the mode never checked which user signed in, only that someone had). Use --visibility internal; the name "private" is reserved for a future owner-only mode, so it is not accepted as an alias.'
     );
   }
-  throw new CliError(`invalid visibility "${input}" (internal | group:<id> | password | public)`);
+  throw new CliError(
+    `invalid visibility "${input}" (internal | group:<id>[,<id>\u2026] | password | public)`
+  );
 }
 function printVersion(v) {
   console.log(`  version ${v.number} (${v.status}) \u2014 ${v.id}`);
@@ -1317,12 +2483,16 @@ function printVersion(v) {
 }
 function printApp(app) {
   console.log(`  app ${app.slug} \u2014 live version: ${app.currentVersionId ?? "(none)"}`);
+  if (app.description) console.log(`  ${app.description}`);
 }
 async function createCommand(client, config, opts) {
   const slug = requireSlug(config);
   const app = await client.createApp({
     slug,
     displayName: opts.displayName ?? slug,
+    // Flag wins over helix.json, and an unset description is simply not sent —
+    // an older portal never sees a key it doesn't know.
+    description: opts.description ?? config.description,
     visibility: parseVisibility(opts.visibility)
   });
   console.log(`Created app "${app.slug}".`);
@@ -1385,7 +2555,8 @@ async function loginCommand(client, config) {
   await writeTokens({ portalUrl: config.portalUrl, issuer }, tokens, void 0, { audience });
   const authed = new PortalClient(config.portalUrl, tokens.accessToken);
   const me = await authed.me();
-  console.log(`Logged in as ${me.name ?? me.sub} (${me.sub}).`);
+  const oid = me.oid ? ` \u2014 oid ${me.oid}` : "";
+  console.log(`Logged in as ${me.name ?? me.sub} (${me.sub})${oid}.`);
 }
 async function logoutCommand(config) {
   const forgot = await deleteTokens(config.portalUrl);
@@ -1393,7 +2564,14 @@ async function logoutCommand(config) {
 }
 async function whoamiCommand(client) {
   const me = await client.me();
-  console.log(`${me.sub} (via ${me.via}${me.name ? `, ${me.name}` : ""})`);
+  const oid = me.oid ? `${me.oid} \u2014 ` : "";
+  console.log(`${oid}${me.sub} (via ${me.via}${me.name ? `, ${me.name}` : ""})`);
+}
+async function skillCommand(client, _config, opts) {
+  const skill = await client.getSkill();
+  const outPath = resolve(opts.path ?? SKILL_FILENAME);
+  await writeFile2(outPath, skill, "utf8");
+  console.log(`Wrote skill to ${outPath}`);
 }
 
 // src/auth/session.ts
@@ -1461,7 +2639,8 @@ async function resolveConfig(flags, env = process.env, cwd = process.cwd()) {
     token: flags.token ?? env.HELIX_TOKEN ?? env.AZX_TOKEN,
     slug: flags.slug ?? file.slug,
     dir: flags.dir ?? file.dir ?? DEFAULT_DIR,
-    bundle: flags.bundle
+    bundle: flags.bundle,
+    description: flags.description ?? file.description
   };
 }
 
@@ -1473,15 +2652,16 @@ Usage:
   helix logout
   helix whoami
   helix deploy   [--dir <dir>] [--bundle <zip>] [--promote]
-  helix create   [--display-name <name>] [--visibility <v>]
+  helix create   [--display-name <name>] [--description <text>] [--visibility <v>]
   helix versions
   helix promote  <number>
   helix rollback [number]
+  helix skill    [--path <file>]   # write this deployment's agent skill to disk
 
 Common flags: --slug <slug>  --portal-url <url>  --token <token>
 Env:  HELIX_PORTAL_URL, HELIX_TOKEN (static token \u2014 skips login; CI/scripts).
-Config file: helix.json { slug, portalUrl, dir }
-Visibility: internal | group:<id> | password | public
+Config file: helix.json { slug, portalUrl, dir, description }
+Visibility: internal | group:<id>[,<id>...] | password | public
 `;
 async function main() {
   const { values, positionals } = parseCliArgs(process.argv.slice(2));
@@ -1511,12 +2691,16 @@ async function main() {
     case "whoami":
       await whoamiCommand(client);
       break;
+    case "skill":
+      await skillCommand(client, config, { path: values.path });
+      break;
     case "deploy":
       await deployCommand(client, config, { promote: values.promote });
       break;
     case "create":
       await createCommand(client, config, {
         displayName: values["display-name"],
+        description: values.description ?? config.description,
         visibility: values.visibility
       });
       break;