@wairon/cli 5.0.2-dev.7 → 5.0.2-dev.9

package/dist/cli/index.js

@@ -65,7 +65,7 @@ var init_defaults = __esm({
       copilot: ".github/prompts",
       codex: ".codex/agents"
     };
-    WAIRON_VERSION = "5.0.2-dev.7";
+    WAIRON_VERSION = "5.0.2-dev.9";
     GITHUB_REPO = "SYW-Apps/Waffle-AIron";
     ARCHITECT_AGENT_ID = "agent-architect";
     ARCHITECT_TEMPLATE_ID = "architect";
@@ -703,7 +703,7 @@ var init_template = __esm({
 });
 
 // src/models/specs.ts
-var import_zod6, SpecIdSchema, SpecStatusSchema, BoundaryItemSchema, RequirementItemSchema, DatabaseSpecSchema, DiagramConfigSchema, SURFACE_AUDIENCES, SurfaceAudienceSchema, SystemPublicInterfaceSchema, SystemSpecSchema, PublicInterfaceTypeSchema, PublicInterfaceSchema, TrustedLinkSchema, LintAllowSchema, LintConfigSchema, ExtDataSchema, LifecycleEntrypointSchema, SubsystemSpecSchema, ComponentTypeSchema, PATTERN_TYPES, PortalTypeSchema, DispatchBindingSchema, DurabilitySchema, PatternRefSchema, EventBindingSchema, ExternalLinkTypeSchema, ExternalLinkSchema, ComponentSpecSchema, HttpMethodSchema, TransportSchema, EndpointSchema, SEMANTIC_GUARANTEES, GuaranteeSchema, MethodParamSchema, MethodSignatureSchema, InterfaceSpecSchema, NarrativeStepTypeSchema, LoopKindSchema, SwitchCaseSchema, CatchClauseSchema, ParallelBranchSchema, NarrativeStepSchema, NarrativeDetailSchema, ConformanceTierSchema, MethodImplementationSchema, ImplementationSpecSchema, TypeKindSchema, TypeFieldSchema, TypeMethodSchema, InvariantSchema, TypeSpecSchema, SurfaceOriginSchema, SurfaceTypeDefSchema, SurfaceContractEntrySchema, SurfaceSnapshotSchema, GroupSpecSchema;
+var import_zod6, SpecIdSchema, SpecStatusSchema, BoundaryItemSchema, RequirementItemSchema, DatabaseSpecSchema, DiagramConfigSchema, SURFACE_AUDIENCES, SurfaceAudienceSchema, SystemPublicInterfaceSchema, SystemSpecSchema, PublicInterfaceTypeSchema, PublicInterfaceSchema, TrustedLinkSchema, LintAllowSchema, LintConfigSchema, ExtDataSchema, LifecycleEntrypointSchema, SubsystemSpecSchema, ComponentTypeSchema, PATTERN_TYPES, PortalTypeSchema, DispatchBindingSchema, DurabilitySchema, PatternRefSchema, EventBindingSchema, ExternalLinkTypeSchema, ExternalLinkSchema, PortalAuthSchemeSchema, PortalAuthSchema, ComponentSpecSchema, HttpMethodSchema, TransportSchema, EndpointSchema, SEMANTIC_GUARANTEES, GuaranteeSchema, MethodParamSchema, MethodSignatureSchema, InterfaceSpecSchema, NarrativeStepTypeSchema, LoopKindSchema, SwitchCaseSchema, CatchClauseSchema, ParallelBranchSchema, NarrativeStepSchema, NarrativeDetailSchema, ConformanceTierSchema, MethodImplementationSchema, ImplementationSpecSchema, TypeKindSchema, TypeFieldSchema, TypeMethodSchema, InvariantSchema, TypeSpecSchema, SurfaceOriginSchema, SurfaceTypeDefSchema, SurfaceContractEntrySchema, SurfaceSnapshotSchema, NamedOpenApiSpecSchema, GroupSpecSchema;
 var init_specs = __esm({
   "src/models/specs.ts"() {
     "use strict";
@@ -914,6 +914,21 @@ var init_specs = __esm({
       type: ExternalLinkTypeSchema.default("informative"),
       label: import_zod6.z.string().optional()
     });
+    PortalAuthSchemeSchema = import_zod6.z.enum(["none", "apiKey", "bearer", "basic", "oauth2", "openIdConnect", "custom"]);
+    PortalAuthSchema = import_zod6.z.object({
+      scheme: PortalAuthSchemeSchema,
+      in: import_zod6.z.enum(["header", "query", "cookie"]).optional(),
+      name: import_zod6.z.string().optional(),
+      bearerFormat: import_zod6.z.string().optional(),
+      authorizationUrl: import_zod6.z.string().optional(),
+      tokenUrl: import_zod6.z.string().optional(),
+      refreshUrl: import_zod6.z.string().optional(),
+      scopes: import_zod6.z.array(import_zod6.z.object({ name: import_zod6.z.string(), description: import_zod6.z.string() })).optional(),
+      flow: import_zod6.z.enum(["authorizationCode", "clientCredentials", "implicit", "password"]).optional(),
+      openIdConnectUrl: import_zod6.z.string().optional(),
+      description: import_zod6.z.string().optional(),
+      example: import_zod6.z.string().optional()
+    });
     ComponentSpecSchema = import_zod6.z.object({
       id: SpecIdSchema,
       name: import_zod6.z.string(),
@@ -927,6 +942,10 @@ var init_specs = __esm({
       dependsOn: import_zod6.z.array(import_zod6.z.string()).default([]),
       portalType: PortalTypeSchema.optional(),
       basePath: import_zod6.z.string().optional(),
+      /** Portal-only: the API's authentication scheme (see PortalAuthSchema) — projected
+       *  into the generated OpenAPI's securitySchemes/security. Portals with different auth
+       *  must be separate components (one auth per portal ⇒ one OpenAPI spec per portal). */
+      auth: PortalAuthSchema.optional(),
       /** Portal-only: capability → component.method dispatch table (see DispatchBindingSchema). */
       dispatch: import_zod6.z.array(DispatchBindingSchema).optional(),
       /** Store-only: whether held state survives restart (see DurabilitySchema). */
@@ -1076,6 +1095,14 @@ var init_specs = __esm({
       // Required if type is 'call', references Method name on target interface
       capability: import_zod6.z.string().optional(),
       // Required if type is 'dispatch': the capability routed through the target Portal's dispatch table
+      /**
+       * call/dispatch only: the credential this step presents to an authed callee
+       * Portal, and WHERE it is loaded from (`from` — a secret-store component id,
+       * `env:API_KEY`, a config key, a vault ref, …). A declared DESIGN NOTE — wairon
+       * never fetches it — but its absence on a call into a Portal whose `auth ≠ none`
+       * warns (PORTAL_AUTH_UNMET), so credential loading is never overlooked.
+       */
+      auth: import_zod6.z.object({ from: import_zod6.z.string(), note: import_zod6.z.string().optional() }).optional(),
       assertsGuarantees: import_zod6.z.array(GuaranteeSchema).optional(),
       /**
        * Declared entity invariants this step upholds, as "<type-id>.<invariant-id>"
@@ -1292,7 +1319,12 @@ var init_specs = __esm({
       dispatch: import_zod6.z.array(DispatchBindingSchema).optional(),
       details: import_zod6.z.string().default(""),
       version: import_zod6.z.string().optional(),
-      stability: import_zod6.z.string().optional()
+      stability: import_zod6.z.string().optional(),
+      /** Projected copy of the backing Portal's auth (see PortalAuthSchema) — the codec
+       *  emits it as OpenAPI securitySchemes/security. */
+      auth: PortalAuthSchema.optional(),
+      /** The backing Portal's basePath — becomes the per-portal OpenAPI `servers` url. */
+      basePath: import_zod6.z.string().optional()
     });
     SurfaceSnapshotSchema = import_zod6.z.object({
       /** Producing project/system name — the snapshot's resolution identity. */
@@ -1307,6 +1339,11 @@ var init_specs = __esm({
       /** Transitive type closure of every exported signature — self-contained. */
       types: import_zod6.z.array(SurfaceTypeDefSchema).default([])
     });
+    NamedOpenApiSpecSchema = import_zod6.z.object({
+      portalId: import_zod6.z.string(),
+      name: import_zod6.z.string(),
+      document: import_zod6.z.string()
+    });
     GroupSpecSchema = import_zod6.z.object({
       kind: import_zod6.z.literal("group"),
       id: SpecIdSchema,
@@ -6115,7 +6152,7 @@ var MODEL = __MODEL_JSON__;
         + (scopeFocus ? staticChip('current view') : '')
         + chip(c.subsystem, 'subsystem', c.subsystem)
         + (scopeFocus ? '' : openViewButton('component', c.id, c.owns.length > 0))
-        + openApiButton(componentExposesApi(c), c.apiTag)
+        + openApiButton(componentExposesApi(c), c.id)
         + openSpecButton('component', c.id);
       
       var linkedTypes = MODEL.types.filter(function (t) { return t.componentClass === c.id; });
@@ -6920,11 +6957,63 @@ function operationFor(method2, closureIds) {
   }
   return op;
 }
-function toOpenApi(snapshot) {
-  const closureIds = new Set(snapshot.types.map((t) => t.id));
-  const httpEntries = snapshot.interfaces.filter((e) => e.type === "REST" || e.methods.some((m) => m.endpoint?.transport === "HTTP"));
+function securitySchemeObject(auth) {
+  if (auth.scheme === "none") return null;
+  const desc = auth.description ? { description: auth.description } : {};
+  switch (auth.scheme) {
+    case "apiKey":
+      return { type: "apiKey", in: auth.in ?? "header", name: auth.name ?? "X-API-Key", ...desc };
+    case "bearer":
+      return { type: "http", scheme: "bearer", ...auth.bearerFormat ? { bearerFormat: auth.bearerFormat } : {}, ...desc };
+    case "basic":
+      return { type: "http", scheme: "basic", ...desc };
+    case "oauth2": {
+      const flow = { scopes: Object.fromEntries((auth.scopes ?? []).map((s) => [s.name, s.description])) };
+      if (auth.authorizationUrl) flow.authorizationUrl = auth.authorizationUrl;
+      if (auth.tokenUrl) flow.tokenUrl = auth.tokenUrl;
+      if (auth.refreshUrl) flow.refreshUrl = auth.refreshUrl;
+      return { type: "oauth2", flows: { [auth.flow ?? "authorizationCode"]: flow }, ...desc };
+    }
+    case "openIdConnect":
+      return { type: "openIdConnect", openIdConnectUrl: auth.openIdConnectUrl ?? "", ...desc };
+    case "custom":
+      return { type: "apiKey", in: auth.in ?? "header", name: auth.name ?? "Authorization", description: auth.description ?? auth.example ?? "Custom authentication scheme." };
+    default:
+      return null;
+  }
+}
+function schemeBaseName(scheme) {
+  return { apiKey: "ApiKeyAuth", bearer: "BearerAuth", basic: "BasicAuth", oauth2: "OAuth2", openIdConnect: "OpenIdConnect", custom: "CustomAuth" }[scheme] ?? "Auth";
+}
+function buildSecurity(entries) {
+  const schemes = {};
+  const nameByContent = /* @__PURE__ */ new Map();
+  const securityByEntry = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    if (!entry.auth) continue;
+    const obj = securitySchemeObject(entry.auth);
+    if (!obj) continue;
+    const content = JSON.stringify(obj);
+    let name = nameByContent.get(content);
+    if (!name) {
+      name = schemeBaseName(entry.auth.scheme);
+      for (let n = 2; schemes[name]; n++) name = schemeBaseName(entry.auth.scheme) + n;
+      schemes[name] = obj;
+      nameByContent.set(content, name);
+    }
+    const scopeNames = entry.auth.scheme === "oauth2" ? (entry.auth.scopes ?? []).map((s) => s.name) : [];
+    securityByEntry.set(entry.id, { [name]: scopeNames });
+  }
+  return { schemes, securityByEntry };
+}
+function httpEntriesOf(snapshot) {
+  return snapshot.interfaces.filter((e) => e.type === "REST" || e.methods.some((m) => m.endpoint?.transport === "HTTP"));
+}
+function renderDoc(snapshot, entries, closureIds, opts = {}) {
+  const { schemes, securityByEntry } = buildSecurity(entries);
   const paths = {};
-  for (const entry of httpEntries) {
+  for (const entry of entries) {
+    const security = securityByEntry.get(entry.id);
     for (const method2 of entry.methods) {
       const endpoint = method2.endpoint;
       if (!endpoint || endpoint.transport !== "HTTP") continue;
@@ -6932,7 +7021,8 @@ function toOpenApi(snapshot) {
       paths[p] = paths[p] ?? {};
       paths[p][endpoint.method.toLowerCase()] = {
         tags: [entry.id],
-        ...operationFor(method2, closureIds)
+        ...operationFor(method2, closureIds),
+        ...security ? { security: [security] } : {}
       };
     }
   }
@@ -6945,19 +7035,41 @@ function toOpenApi(snapshot) {
       required: t.fields.filter((f) => !f.optional).map((f) => f.name)
     };
   }
-  const doc = {
+  const components = {};
+  if (Object.keys(schemas).length) components.schemas = schemas;
+  if (Object.keys(schemes).length) components.securitySchemes = schemes;
+  const basePaths = [...new Set(entries.map((e) => e.basePath).filter((b) => !!b))];
+  const servers = opts.servers && basePaths.length === 1 ? [{ url: basePaths[0] }] : void 0;
+  return {
     openapi: "3.1.0",
     info: {
-      title: snapshot.projectName,
+      title: opts.title ?? snapshot.projectName,
       version: snapshot.version ?? "0.0.0",
       ...snapshot.stateId ? { "x-wairon-state-id": snapshot.stateId } : {},
       "x-wairon-origin": snapshot.origin,
       "x-wairon-generated-at": snapshot.generatedAt
     },
+    ...servers ? { servers } : {},
     paths,
-    ...Object.keys(schemas).length ? { components: { schemas } } : {}
+    ...Object.keys(components).length ? { components } : {}
   };
-  return JSON.stringify(doc, null, 2);
+}
+function toOpenApiSet(snapshot) {
+  const closureIds = new Set(snapshot.types.map((t) => t.id));
+  const byPortal = /* @__PURE__ */ new Map();
+  const order = [];
+  for (const entry of httpEntriesOf(snapshot)) {
+    if (!byPortal.has(entry.component)) {
+      byPortal.set(entry.component, []);
+      order.push(entry.component);
+    }
+    byPortal.get(entry.component).push(entry);
+  }
+  return order.map((portalId) => {
+    const entries = byPortal.get(portalId);
+    const name = entries[0]?.name ?? portalId;
+    return { portalId, name, document: JSON.stringify(renderDoc(snapshot, entries, closureIds, { title: name, servers: true }), null, 2) };
+  });
 }
 function isOpenApiDocument(body) {
   try {
@@ -6979,6 +7091,39 @@ function typeRefFromSchema(schema) {
   if (typeof t === "string" && t !== "object") return t;
   return "json";
 }
+function authFromSecurityScheme(scheme) {
+  const desc = typeof scheme.description === "string" ? { description: scheme.description } : {};
+  if (scheme.type === "apiKey") {
+    return {
+      scheme: "apiKey",
+      ...scheme.in === "header" || scheme.in === "query" || scheme.in === "cookie" ? { in: scheme.in } : {},
+      ...typeof scheme.name === "string" ? { name: scheme.name } : {},
+      ...desc
+    };
+  }
+  if (scheme.type === "http") {
+    if (scheme.scheme === "bearer") return { scheme: "bearer", ...typeof scheme.bearerFormat === "string" ? { bearerFormat: scheme.bearerFormat } : {}, ...desc };
+    if (scheme.scheme === "basic") return { scheme: "basic", ...desc };
+  }
+  if (scheme.type === "oauth2") {
+    const flows = scheme.flows ?? {};
+    const flowKey = Object.keys(flows)[0];
+    const f = flows[flowKey] ?? {};
+    return {
+      scheme: "oauth2",
+      ...flowKey === "authorizationCode" || flowKey === "clientCredentials" || flowKey === "implicit" || flowKey === "password" ? { flow: flowKey } : {},
+      ...typeof f.authorizationUrl === "string" ? { authorizationUrl: f.authorizationUrl } : {},
+      ...typeof f.tokenUrl === "string" ? { tokenUrl: f.tokenUrl } : {},
+      ...typeof f.refreshUrl === "string" ? { refreshUrl: f.refreshUrl } : {},
+      scopes: Object.entries(f.scopes ?? {}).map(([name, description]) => ({ name, description })),
+      ...desc
+    };
+  }
+  if (scheme.type === "openIdConnect") {
+    return { scheme: "openIdConnect", openIdConnectUrl: typeof scheme.openIdConnectUrl === "string" ? scheme.openIdConnectUrl : "", ...desc };
+  }
+  return void 0;
+}
 function fromOpenApi(document, projectName) {
   let parsed;
   try {
@@ -7056,6 +7201,9 @@ function fromOpenApi(document, projectName) {
       }))
     });
   }
+  const securitySchemes = parsed.components?.securitySchemes ?? {};
+  const firstScheme = Object.values(securitySchemes)[0];
+  const importedAuth = firstScheme ? authFromSecurityScheme(firstScheme) : void 0;
   const entry = {
     id: `${projectName}-api`,
     name: typeof info.title === "string" ? info.title : projectName,
@@ -7064,7 +7212,8 @@ function fromOpenApi(document, projectName) {
     component: `${projectName}-api`,
     methods,
     details: typeof info.description === "string" ? info.description : `Imported OpenAPI surface of ${projectName}.`,
-    ...typeof info.version === "string" ? { version: info.version } : {}
+    ...typeof info.version === "string" ? { version: info.version } : {},
+    ...importedAuth ? { auth: importedAuth } : {}
   };
   return SurfaceSnapshotSchema.parse({
     projectName,
@@ -7179,6 +7328,10 @@ function projectOwnSurface(maxAudience) {
       component: comp.id,
       methods,
       ...comp.dispatch && comp.dispatch.length ? { dispatch: comp.dispatch } : {},
+      // Project the backing Portal's auth + basePath so the codec can emit
+      // OpenAPI security + per-portal servers self-contained from the snapshot.
+      ...comp.auth && comp.auth.scheme !== "none" ? { auth: comp.auth } : {},
+      ...comp.basePath ? { basePath: comp.basePath } : {},
       details: raw.details ?? "",
       ...raw.version ? { version: raw.version } : {},
       ...raw.stability ? { stability: raw.stability } : {}
@@ -7222,20 +7375,28 @@ function saveSnapshot(snapshot, rootDir = getProjectRoot()) {
 function loadSurfaceSnapshots() {
   return listSnapshots();
 }
+function renderOpenApiForms(snapshot) {
+  const renderedSet = toOpenApiSet(snapshot);
+  return { renderedSet, ...renderedSet.length === 1 ? { rendered: renderedSet[0].document } : {} };
+}
+function writeSurfaceFile(outPath, body, snapshot) {
+  const resolved = path10.resolve(outPath);
+  fs9.mkdirSync(path10.dirname(resolved), { recursive: true });
+  if (body !== void 0) fs9.writeFileSync(resolved, body);
+  else writeYamlFile(resolved, snapshot);
+  return resolved;
+}
 function exportSurface(maxAudience, format, outPath) {
   const snapshot = projectOwnSurface(maxAudience);
-  const rendered = format === "openapi" ? toOpenApi(snapshot) : void 0;
-  let writtenTo;
-  if (outPath) {
-    fs9.mkdirSync(path10.dirname(path10.resolve(outPath)), { recursive: true });
-    if (rendered !== void 0) {
-      fs9.writeFileSync(path10.resolve(outPath), rendered);
-    } else {
-      writeYamlFile(path10.resolve(outPath), snapshot);
-    }
-    writtenTo = path10.resolve(outPath);
-  }
-  return { snapshot, ...rendered !== void 0 ? { rendered } : {}, ...writtenTo ? { writtenTo } : {} };
+  const openapi = format === "openapi" ? renderOpenApiForms(snapshot) : void 0;
+  const body = openapi?.rendered ?? openapi?.renderedSet[0]?.document;
+  const writtenTo = outPath ? writeSurfaceFile(outPath, body, snapshot) : void 0;
+  return {
+    snapshot,
+    ...openapi?.rendered !== void 0 ? { rendered: openapi.rendered } : {},
+    ...openapi ? { renderedSet: openapi.renderedSet } : {},
+    ...writtenTo ? { writtenTo } : {}
+  };
 }
 function importSurface(sourcePath, origin) {
   const resolved = path10.resolve(sourcePath);
@@ -12034,6 +12195,44 @@ var init_lint_allows = __esm({
   }
 });
 
+// src/core/rules/portal-call-auth.ts
+var portalCallAuthRule;
+var init_portal_call_auth = __esm({
+  "src/core/rules/portal-call-auth.ts"() {
+    "use strict";
+    portalCallAuthRule = {
+      name: "portal-call-auth",
+      description: "An OUTBOUND narrative `call` into ANOTHER component's Portal whose auth is not `none` must declare the credential source it presents \u2014 the step's `auth.from`, a design note naming where the secret loads from (a secret-store component, env var, config key, vault ref). Its absence warns (PORTAL_AUTH_UNMET) so credential loading is never overlooked; the actual secret is never stored in the spec. Dispatch steps (a portal's OWN inbound routing) and self-calls are not cross-service calls and are excluded.",
+      codes: [
+        { code: "PORTAL_AUTH_UNMET", defaultSeverity: "warning", summary: "A narrative call into another component's authed Portal does not declare where its credential loads from" }
+      ],
+      check(ctx) {
+        for (const impl of ctx.implementations) {
+          const ownComponent = ctx.interfaceMap.get(impl.contract)?.component;
+          const draft = ctx.isImplementationDraft(impl);
+          for (const method2 of impl.methods ?? []) {
+            for (const step of method2.narrative ?? []) {
+              if (step.type !== "call") continue;
+              if (!step.targetComponent || step.targetComponent === ownComponent) continue;
+              const target = ctx.componentMap.get(step.targetComponent);
+              if (!target || target.componentType !== "Portal") continue;
+              if (!target.auth || target.auth.scheme === "none") continue;
+              if (step.auth?.from) continue;
+              ctx.addIssue(
+                "warning",
+                "PORTAL_AUTH_UNMET",
+                `Narrative step ${step.stepNumber} of "${method2.name}" in "${impl.id}" calls the authenticated portal "${target.id}" (auth scheme: ${target.auth.scheme}) but does not declare where its credential is loaded from. Add the credential source (the step's auth.from \u2014 a secret-store component, env var, config key, or vault ref), or drop the portal's auth if it needs none.`,
+                impl.id,
+                draft
+              );
+            }
+          }
+        }
+      }
+    };
+  }
+});
+
 // src/core/rules/index.ts
 function makeScopeFilter(opts) {
   const { components, interfaces, implementations, types, scopeSubsystem } = opts;
@@ -12279,6 +12478,7 @@ var init_rules = __esm({
     init_hidden_state();
     init_dependency_conformance();
     init_lint_allows();
+    init_portal_call_auth();
     init_source_analysis();
     init_types();
     init_type_analysis();
@@ -12300,6 +12500,9 @@ var init_rules = __esm({
       narrativeAntipatternsRule,
       narrativeDetailRule,
       portalsRule,
+      // Cross-call auth: a narrative call into an authed Portal must name its
+      // credential source (rides with the portal family).
+      portalCallAuthRule,
       stereotypeDepsRule,
       patternsRule,
       // Facade shape rides with pattern ownership: same §7 doctrine, narrative side.
@@ -12362,6 +12565,7 @@ var init_rules = __esm({
       // L4 expectations: implementations and their code linkage.
       MISSING_IMPLEMENTATION_METHOD: "implementations",
       MISSING_SOURCE_PATH: "implementations",
+      PORTAL_AUTH_UNMET: "implementations",
       MISSING_SOURCE_FILE: "implementations",
       SOURCE_PATH_ESCAPES_ROOT: "implementations",
       UNREALIZED_METHOD: "implementations",
@@ -16925,6 +17129,7 @@ NOTICE:
     type: import_zod9.z.enum(["local", "call", "dispatch", "branch", "switch", "loop", "try", "parallel", "jump", "return", "throw"]),
     targetComponent: import_zod9.z.string().optional().describe("call/dispatch: L2 component id (for dispatch, the Portal routed through)"),
     targetMethod: import_zod9.z.string().optional().describe("call: method name on the target"),
+    auth: import_zod9.z.object({ from: import_zod9.z.string(), note: import_zod9.z.string().optional() }).optional().describe("call/dispatch: the credential this step presents to an AUTHED callee Portal and WHERE it loads from (`from` = a secret-store component id, env:API_KEY, a config key, a vault ref). A design note \u2014 wairon never fetches it. Its absence on a call into a Portal whose auth \u2260 none warns (PORTAL_AUTH_UNMET), so credential loading is never overlooked."),
     detach: import_zod9.z.boolean().optional().describe("call/dispatch: fire-and-forget \u2014 issue the call and continue without awaiting the result (no later step consumes it)"),
     capability: import_zod9.z.string().optional().describe("dispatch: the capability routed through the target Portal's dispatch table (validated against it \u2014 UNSERVED_CAPABILITY)"),
     assertsGuarantees: import_zod9.z.array(import_zod9.z.string().min(1)).optional().describe("Semantic guarantees this step relies on \u2014 each must be declared in the called method's L3 guarantees (NARRATIVE_SEMANTIC_UNBACKED otherwise). Builtin tokens: idempotent | atomic | transactional | exactly-once; extension packs may declare more (any other token is UNKNOWN_GUARANTEE)"),
@@ -32127,7 +32332,7 @@ function getWebProjectCanvasModel(cfg, sessionId, projectId) {
   }
   return runWithProjectRoot(root, () => hostCore.buildCanvasDataModel());
 }
-function getWebProjectOpenApi(cfg, sessionId, projectId) {
+function getWebProjectOpenApi(cfg, sessionId, projectId, portalId) {
   const principal = authenticateSession(cfg.dataDir, sessionId);
   if (!principal.authenticated) throw new UnauthenticatedError();
   if (!listProjects2(cfg, sessionId).some((r) => r.id === projectId)) {
@@ -32136,7 +32341,19 @@ function getWebProjectOpenApi(cfg, sessionId, projectId) {
   const root = resolveProjectRoot(cfg.dataDir, principal, projectId);
   if (!root) throw new ForbiddenError("project not authorized or unknown");
   const result = runWithProjectRoot(root, () => hostSurfaces.exportBoundSurface("project", "openapi"));
-  return swaggerUiPage(result.rendered ?? "{}", projectId);
+  const specs = result.renderedSet ?? (result.rendered ? [{ portalId: "", name: projectId, document: result.rendered }] : []);
+  if (specs.length === 0) return swaggerUiPage("{}", projectId);
+  if (portalId) {
+    const sel = specs.find((s) => s.portalId === portalId) ?? specs[0];
+    return swaggerUiPage(sel.document, sel.name);
+  }
+  if (specs.length === 1) return swaggerUiPage(specs[0].document, specs[0].name);
+  return openApiIndexPage(projectId, specs);
+}
+function openApiIndexPage(projectId, specs) {
+  const esc2 = (s) => s.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+  const items = specs.map((s) => `<li><a href="/web/openapi?projectId=${encodeURIComponent(projectId)}&spec=${encodeURIComponent(s.portalId)}">${esc2(s.name)}</a> <code>${esc2(s.portalId)}</code></li>`).join("");
+  return `<!doctype html><html><head><meta charset="utf-8"><title>${esc2(projectId)} \u2014 API specs</title><style>body{font-family:system-ui,sans-serif;max-width:680px;margin:48px auto;padding:0 20px;color:#e6e6e6;background:#161616}h1{font-size:20px}a{color:#6ea8fe;text-decoration:none}a:hover{text-decoration:underline}li{margin:10px 0}code{color:#8a94a6;font-size:12px;margin-left:8px}</style></head><body><h1>${esc2(projectId)} \u2014 API specs</h1><p>This project exposes ${specs.length} separate public APIs, each with its own OpenAPI document and auth:</p><ul>${items}</ul></body></html>`;
 }
 function reshapeLandscapeGraph(model, level) {
   const unitNodeIds = new Set(model.nodes.filter((n) => n.nodeKind === "orgUnit").map((n) => n.id));
@@ -34498,7 +34715,8 @@ async function handleWebRequest(cfg, req, res, body, url, ctx) {
     }
     if (req.method === "GET" && parts.length === 2 && parts[1] === "openapi") {
       const projectId = url.searchParams.get("projectId") ?? "";
-      const html = getWebProjectOpenApi(cfg, sessionId, projectId);
+      const spec = url.searchParams.get("spec") ?? void 0;
+      const html = getWebProjectOpenApi(cfg, sessionId, projectId, spec);
       res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
       res.end(html);
       return;