@wairon/cli 5.0.2-dev.1 → 5.0.2-dev.10

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.1";
+    WAIRON_VERSION = "5.0.2-dev.10";
     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, 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";
@@ -907,6 +907,28 @@ var init_specs = __esm({
       event: import_zod6.z.string().optional(),
       description: import_zod6.z.string().optional()
     });
+    ExternalLinkTypeSchema = import_zod6.z.enum(["implementation", "informative"]);
+    ExternalLinkSchema = import_zod6.z.object({
+      url: import_zod6.z.string(),
+      /** Defaults to 'informative' so an untyped link never silently satisfies the source requirement. */
+      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(),
@@ -920,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). */
@@ -932,6 +958,11 @@ var init_specs = __esm({
       patterns: import_zod6.z.array(PatternRefSchema).optional(),
       /** Optional component variant — a declared, base-anchored specialization of this component's stereotype (resolved against the variant registry; UNKNOWN_VARIANT / VARIANT_BASE_MISMATCH). */
       variant: import_zod6.z.string().optional(),
+      /** Opaque external references (see ExternalLinkSchema) — documented URLs wairon does
+       *  not fetch or validate. An `implementation` link is the external source-of-record and
+       *  satisfies the source requirement for a source-less implementation (suppresses
+       *  MISSING_SOURCE_PATH); `informative` links are context only. */
+      externalLinks: import_zod6.z.array(ExternalLinkSchema).optional(),
       /** Per-spec lint suppressions (see LintConfigSchema). */
       lint: LintConfigSchema.optional(),
       /** Opaque pack/tool extension data (see ExtDataSchema) — preserved verbatim. */
@@ -1064,6 +1095,18 @@ 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`). Two forms: an OPAQUE source
+       * (`env:API_KEY`, a config key, `vault:path`, a free note) — a design note
+       * wairon never resolves; or a MODELED reference `component:<id>` pointing at
+       * the Adapter/Store that provides the secret — validated to resolve, be an
+       * Adapter/Store, and be wired to the presenter (a checked graph edge). The
+       * actual secret is never stored here. 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>"
@@ -1280,7 +1323,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. */
@@ -1295,6 +1343,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,
@@ -2652,6 +2705,7 @@ function buildCanvasModel(issues = []) {
       ...ownerOf.has(comp.id) ? { owner: ownerOf.get(comp.id) } : {},
       owns: comp.owns.filter((o) => componentIds.has(o)),
       dependsOn: comp.dependsOn,
+      ...comp.externalLinks && comp.externalLinks.length ? { externalLinks: comp.externalLinks } : {},
       interfaces: compInterfaces.map((i) => ({
         id: i.id,
         name: i.name,
@@ -3304,12 +3358,21 @@ var MODEL = __MODEL_JSON__;
   var configuredLineStyle = ['bezier', 'straight', 'taxi'].indexOf(diagramConfig.lineStyle) >= 0 ? diagramConfig.lineStyle : 'bezier';
   var defaultViewKind = diagramConfig.defaultView === 'types' ? 'types' : (diagramConfig.defaultView === 'databases' && showDatabaseTab ? 'databases' : 'system');
 
+  // Stage J: a deep link (opts.initialRoute) seeds the initial view directly so a
+  // refresh / shared URL renders the right scope with NO root-first flash. Parsed
+  // by the same resolver as openRoute (hoisted below). No onViewChange fires for
+  // this initial seed.
+  var initialView = { kind: defaultViewKind, id: null };
+  if (typeof opts !== 'undefined' && opts && typeof opts.initialRoute === 'string' && opts.initialRoute.length) {
+    initialView = resolveRoute(opts.initialRoute);
+  }
+
   var state = {
-    view: { kind: defaultViewKind, id: null },
-    internals: false,
-    externals: true,
-    dataCoupling: false,
-    showIssues: false,
+    view: initialView,
+    internals: typeof saved.internals === 'boolean' ? saved.internals : false,
+    externals: typeof saved.externals === 'boolean' ? saved.externals : true,
+    dataCoupling: typeof saved.dataCoupling === 'boolean' ? saved.dataCoupling : false,
+    showIssues: typeof saved.showIssues === 'boolean' ? saved.showIssues : false,
     query: '',
     selected: null,
     selectedKind: null,
@@ -3324,6 +3387,9 @@ var MODEL = __MODEL_JSON__;
   // Set by buildTypeElements when the ERD is degraded for performance (huge
   // scopes); consumed by renderTypesNotice to explain the level-of-detail.
   var typesNotice = '';
+  // Stage J: true while openRoute is applying a URL-driven view change, so the
+  // onViewChange callback is suppressed and we do not loop URL -> engine -> URL.
+  var applyingRoute = false;
 
   function viewKey() {
     // 'types2' + detail level: table sizes differ per detail, and the prefix
@@ -3343,6 +3409,10 @@ var MODEL = __MODEL_JSON__;
         lineStyle: state.lineStyle,
         panelOpen: state.panelOpen,
         panelWidth: state.panelWidth,
+        internals: state.internals,
+        externals: state.externals,
+        dataCoupling: state.dataCoupling,
+        showIssues: state.showIssues,
       }));
     } catch (e) { /* non-fatal */ }
   }
@@ -4749,6 +4819,78 @@ var MODEL = __MODEL_JSON__;
     state.typesRenderAll = false; // a fresh scope re-evaluates the LOD budget
     rebuild(true);
     renderPanel();
+    notifyViewChange();
+  }
+
+  // ---- Stage J: URL <-> view routing ----------------------------------------
+  // The canvas navigation lives in the URL path (refresh-safe + shareable). A
+  // route is the string AFTER /canvas/<project>: '' = system root; a '/'-joined
+  // NAMESPACE (e.g. 'a/b') that resolves against the model to a subsystem or a
+  // component; or the 'types'/'databases' view modes with an optional scope.
+  // A segment is the '::' namespace with '/' as separator, each part encoded.
+  function encSeg(s) { return encodeURIComponent(String(s)); }
+  function routeOf(view) {
+    if (!view) return '';
+    var k = view.kind;
+    if (k === 'system') return '';
+    if (k === 'types' || k === 'databases') {
+      return view.id ? k + '/' + view.id.split('::').map(encSeg).join('/') : k;
+    }
+    if (k === 'subsystem') {
+      return view.id ? view.id.split('::').map(encSeg).join('/') : '';
+    }
+    if (k === 'component') {
+      // A component's full namespace path IS its id: a chained subproject carries
+      // the subsystem prefix in the id (a::b::comp), a flat project uses the bare
+      // id (comp). Serializing comp.id split on '::' round-trips exactly via the
+      // compById lookup in resolveRoute. Owner-pattern nesting is deliberately NOT
+      // encoded (ownership is a separate axis; comp.id does not embed the owner).
+      var c = compById[view.id];
+      var full = c ? c.id : view.id;
+      return full.split('::').map(encSeg).join('/');
+    }
+    return '';
+  }
+  function resolveRoute(routeStr) {
+    var parts = String(routeStr || '').split('/').filter(function (s) { return s.length > 0; }).map(decodeURIComponent);
+    if (!parts.length) return { kind: 'system', id: null };
+    // NOTE: a subsystem literally named 'types'/'databases' is SHADOWED by these
+    // view-mode routes (acceptable \u2014 the modes own those first segments).
+    if (parts[0] === 'types') {
+      return { kind: 'types', id: parts.length > 1 ? parts.slice(1).join('::') : null };
+    }
+    if (parts[0] === 'databases') {
+      if (!showDatabaseTab) return { kind: 'system', id: null };
+      return { kind: 'databases', id: parts.length > 1 ? parts.slice(1).join('::') : null };
+    }
+    var joined = parts.join('::');
+    if (subById[joined]) return { kind: 'subsystem', id: joined };
+    if (compById[joined]) return { kind: 'component', id: joined };
+    return { kind: 'system', id: null }; // unknown id -> fall back to the root
+  }
+  // Apply a route (URL -> engine) WITHOUT echoing back through onViewChange.
+  function openRoute(routeStr) {
+    var v = resolveRoute(routeStr);
+    if (state.view.kind === v.kind && state.view.id === v.id) return;
+    applyingRoute = true;
+    try {
+      state.view = { kind: v.kind, id: v.id };
+      state.selected = null;
+      state.selectedKind = null;
+      state.typesRenderAll = false;
+      rebuild(true);
+      renderPanel();
+    } finally {
+      applyingRoute = false;
+    }
+  }
+  // Notify the embedder (engine -> URL) of the current view; suppressed while a
+  // route is being applied so the URL is not driven in a loop.
+  function notifyViewChange() {
+    if (applyingRoute) return;
+    if (typeof opts !== 'undefined' && opts && typeof opts.onViewChange === 'function') {
+      try { opts.onViewChange(routeOf(state.view)); } catch (e) { /* ignore */ }
+    }
   }
   // Explain (and offer to override) a performance-degraded ERD.
   function renderTypesNotice() {
@@ -4899,6 +5041,7 @@ var MODEL = __MODEL_JSON__;
     if (t.ghost) {
       state.view = parentViewOf(t.kind, t.id);
       rebuild(true);
+      notifyViewChange();
       select(t.kind, t.id, true);
       return;
     }
@@ -4920,10 +5063,16 @@ var MODEL = __MODEL_JSON__;
   }
 
   document.getElementById('search').addEventListener('input', function (ev) { state.query = ev.target.value.trim(); rebuild(false); });
-  document.getElementById('internalsToggle').addEventListener('change', function (ev) { state.internals = ev.target.checked; rebuild(true); });
-  document.getElementById('externalsToggle').addEventListener('change', function (ev) { state.externals = ev.target.checked; rebuild(true); });
-  document.getElementById('dataCouplingToggle').addEventListener('change', function (ev) { state.dataCoupling = ev.target.checked; renderLegend(); rebuild(true); });
-  document.getElementById('issuesToggle').addEventListener('change', function (ev) { state.showIssues = ev.target.checked; rebuild(false); renderPanel(); });
+  // Sync each View toggle's checkbox from the (possibly persisted) state, then
+  // persist on change so the choices survive a refresh (see persist()/saved).
+  document.getElementById('internalsToggle').checked = state.internals;
+  document.getElementById('internalsToggle').addEventListener('change', function (ev) { state.internals = ev.target.checked; persist(); rebuild(true); });
+  document.getElementById('externalsToggle').checked = state.externals;
+  document.getElementById('externalsToggle').addEventListener('change', function (ev) { state.externals = ev.target.checked; persist(); rebuild(true); });
+  document.getElementById('dataCouplingToggle').checked = state.dataCoupling;
+  document.getElementById('dataCouplingToggle').addEventListener('change', function (ev) { state.dataCoupling = ev.target.checked; persist(); renderLegend(); rebuild(true); });
+  document.getElementById('issuesToggle').checked = state.showIssues;
+  document.getElementById('issuesToggle').addEventListener('change', function (ev) { state.showIssues = ev.target.checked; persist(); rebuild(false); renderPanel(); });
   document.getElementById('dragToggle').addEventListener('change', function (ev) { cy.autolock(!ev.target.checked); });
   // Mode seg: Components \u21C4 Types. Entering Types keeps the current subsystem
   // scope, so a subsystem's own types (plus shared ones) show scoped.
@@ -5913,10 +6062,12 @@ var MODEL = __MODEL_JSON__;
     if (kind === 'type' && state.view.kind !== 'types' && state.view.kind !== 'databases') {
       state.view = { kind: 'types', id: typesScopeFromView() };
       rebuild(true);
+      notifyViewChange();
     } else if (kind === 'component' && (state.view.kind === 'types' || state.view.kind === 'databases')) {
       var c = compById[id];
       state.view = { kind: 'subsystem', id: c ? c.subsystem : null };
       rebuild(true);
+      notifyViewChange();
     }
     state.selectedKind = kind;
     state.selected = id;
@@ -5975,6 +6126,14 @@ var MODEL = __MODEL_JSON__;
     if (!exposes || !openApiAllowed()) return '';
     return '<div class="openbtn"><button class="tbtn" data-openapi-tag="' + esc(tag || '') + '">\\u25A4 View OpenAPI \\u2197</button></div>';
   }
+  // "Open in Specs" \u2014 deep-links the focused spec into the hosted Specs value
+  // editor via a host hook (opts.onOpenSpec). Hidden when no host provides it
+  // (standalone file, shared page): those have no editor to open. kind is the
+  // spec layer, id its qualified spec id.
+  function openSpecButton(kind, id) {
+    if (typeof opts === 'undefined' || !opts || typeof opts.onOpenSpec !== 'function') return '';
+    return '<div class="openbtn"><button class="tbtn" data-openspec-kind="' + kind + '" data-openspec-id="' + esc(id) + '">\\u270E Open in Specs \\u2197</button></div>';
+  }
 
   function renderPanel() {
     var head = '', body = '';
@@ -5997,7 +6156,8 @@ 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; });
       if (linkedTypes.length) {
@@ -6007,6 +6167,14 @@ var MODEL = __MODEL_JSON__;
       }
       body += '<p class="desc">' + esc(c.description) + '</p>';
 
+      if (c.externalLinks && c.externalLinks.length) {
+        body += section('External links', c.externalLinks.length, c.externalLinks.map(function (l) {
+          var label = l.label || l.url;
+          var tag = l.type === 'implementation' ? staticChip('source') : '';
+          return '<div class="method">' + tag + '<a href="' + esc(l.url) + '" target="_blank" rel="noopener" style="color:var(--accent);word-break:break-all">' + esc(label) + ' \\u2197</a></div>';
+        }).join(''), true);
+      }
+
       var depInner = (c.dependsOn.length ? c.dependsOn.map(function (d) { return chip(d, 'component', d); }).join('') : '<span class="desc">none</span>')
         + (c.owns.length ? '<div style="margin-top:8px"><b style="font-size:11px">Owns:</b><br>' + c.owns.map(function (d) { return chip(d, 'component', d); }).join('') + '</div>' : '');
       body += section('Dependencies', c.dependsOn.length + c.owns.length, depInner, true);
@@ -6081,7 +6249,8 @@ var MODEL = __MODEL_JSON__;
       MODEL.types.forEach(function (t2) { if (t2.id === focusId) ty = t2; });
       if (ty) {
         head = '<h2>' + esc(ty.name) + '</h2>' + staticChip('\\u00AB' + ty.kind + '\\u00BB')
-          + (ty.subsystem ? chip(ty.subsystem, 'subsystem', ty.subsystem) : staticChip('system-level shared'));
+          + (ty.subsystem ? chip(ty.subsystem, 'subsystem', ty.subsystem) : staticChip('system-level shared'))
+          + openSpecButton('type', ty.id);
         
         if (ty.componentClass) {
           head += '<div style="margin-top:6px"><b style="font-size:11px">Class Component:</b> ' + chip(ty.componentClass, 'component', ty.componentClass) + '</div>';
@@ -6157,7 +6326,8 @@ var MODEL = __MODEL_JSON__;
         + (s.status ? staticChip(s.status) : '')
         + (scopeFocus ? staticChip('current view') : '')
         + (scopeFocus ? '' : openViewButton('subsystem', s.id, subKids > 0))
-        + openApiButton(subsystemExposesApi(s.id), '');
+        + openApiButton(subsystemExposesApi(s.id), '')
+        + openSpecButton('subsystem', s.id);
       body += '<p class="desc">' + esc(s.description) + '</p>';
       if (s.trustedLinks.length) {
         body += section('Trusted links (fast lanes)', s.trustedLinks.length, s.trustedLinks.map(function (t2) {
@@ -6215,6 +6385,16 @@ var MODEL = __MODEL_JSON__;
         });
       })(oapis[oi]);
     }
+    var ospecs = panel.querySelectorAll('[data-openspec-kind]');
+    for (var si = 0; si < ospecs.length; si++) {
+      (function (b) {
+        b.addEventListener('click', function () {
+          if (typeof opts !== 'undefined' && opts && typeof opts.onOpenSpec === 'function') {
+            opts.onOpenSpec(b.getAttribute('data-openspec-kind'), b.getAttribute('data-openspec-id') || '');
+          }
+        });
+      })(ospecs[si]);
+    }
     var flows = panel.querySelectorAll('[data-flow-comp]');
     for (var j = 0; j < flows.length; j++) {
       (function (b) {
@@ -6227,6 +6407,23 @@ var MODEL = __MODEL_JSON__;
   }
 
   renderPanel();
+  // Stage G: a deep link may focus a component and/or open a method's narrative
+  // modal once the seeded view + DOM + cy graph exist. The host parses the URL hash
+  // into opts.initialSelect / opts.initialFlow \u2014 both carry the component id, so this
+  // works whether the seeded view is the component itself or its parent subsystem
+  // (a leaf component has no meaningful "inside", so Specs deep-links open the parent
+  // and focus the component here).
+  (function () {
+    if (typeof opts === 'undefined' || !opts) return;
+    var f = opts.initialFlow, s = opts.initialSelect;
+    var focusComp = (f && f.comp) || (s && s.comp);
+    if (focusComp && compById[focusComp]) {
+      try { select('component', focusComp, true); } catch (e) { /* ignore */ }
+    }
+    if (f && f.comp && f.method && compById[f.comp]) {
+      try { openFlow(f.comp, f.method, f.mode === 'steps' ? 'steps' : 'flow'); } catch (e) { /* ignore */ }
+    }
+  })();
 })();
 </script>
 </body>
@@ -6764,11 +6961,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;
@@ -6776,7 +7025,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] } : {}
       };
     }
   }
@@ -6789,19 +7039,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 {
@@ -6823,6 +7095,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 {
@@ -6900,6 +7205,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,
@@ -6908,7 +7216,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,
@@ -7023,6 +7332,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 } : {}
@@ -7066,20 +7379,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);
@@ -8339,13 +8660,16 @@ var init_conformance = __esm({
           if (isInChainedSubproject(component.subsystem, ctx)) continue;
           const draft = ctx.isImplementationDraft(impl);
           if (!impl.sourcePath) {
-            ctx.addIssue(
-              "warning",
-              "MISSING_SOURCE_PATH",
-              `Implementation "${impl.id}" declares no sourcePath \u2014 its contract "${impl.contract}" cannot be structurally checked against code.`,
-              impl.id,
-              draft
-            );
+            const hasExternalSource = (component.externalLinks ?? []).some((l) => l.type === "implementation");
+            if (!hasExternalSource) {
+              ctx.addIssue(
+                "warning",
+                "MISSING_SOURCE_PATH",
+                `Implementation "${impl.id}" declares no sourcePath \u2014 its contract "${impl.contract}" cannot be structurally checked against code.`,
+                impl.id,
+                draft
+              );
+            }
             continue;
           }
           const lookup = lookups.get(normalizeSourcePath(impl.sourcePath));
@@ -8734,13 +9058,14 @@ var init_portals = __esm({
     };
     portalsRule = {
       name: "portal-endpoints",
-      description: "A Portal declares its portalType and binds every interface method to a concrete endpoint of the matching transport. Non-Portal components carry no portalType, basePath, or endpoints.",
+      description: "A Portal declares its portalType and binds every interface method to a concrete endpoint of the matching transport. Non-Portal components carry no portalType, basePath, endpoints, or auth (auth is inbound transport auth \u2014 a Gateway carries it on the Portal it owns).",
       codes: [
         { code: "MISSING_PORTAL_TYPE", defaultSeverity: "error", summary: "Portal without a portalType" },
         { code: "MISSING_ENDPOINT", defaultSeverity: "error", summary: "Portal method without a wire endpoint binding" },
         { code: "ENDPOINT_TRANSPORT_MISMATCH", defaultSeverity: "error", summary: "Endpoint transport does not match the Portal portalType" },
         { code: "UNEXPECTED_PORTAL_FIELD", defaultSeverity: "error", summary: "Non-Portal component with portalType/basePath" },
-        { code: "ARCHITECTURE_VIOLATION_NON_PORTAL_ENDPOINT", defaultSeverity: "error", summary: "Non-Portal component method declaring an endpoint" }
+        { code: "ARCHITECTURE_VIOLATION_NON_PORTAL_ENDPOINT", defaultSeverity: "error", summary: "Non-Portal component method declaring an endpoint" },
+        { code: "AUTH_ON_NON_PORTAL", defaultSeverity: "warning", summary: "Non-Portal component declaring auth (auth is inbound transport auth, only meaningful on a Portal)" }
       ],
       check(ctx) {
         for (const comp of ctx.components) {
@@ -8792,6 +9117,15 @@ var init_portals = __esm({
                 isDraftCtx
               );
             }
+            if (comp.auth !== void 0) {
+              ctx.addIssue(
+                "warning",
+                "AUTH_ON_NON_PORTAL",
+                `Component "${comp.id}" is a ${comp.componentType}, not a Portal, but declares "auth". Auth is inbound transport auth and is only meaningful on a Portal (a Gateway carries it on the Portal it owns). Move it to the exposed Portal, or remove it.`,
+                comp.id,
+                isDraftCtx
+              );
+            }
             const compInterfaces = ctx.interfaces.filter((i) => i.component === comp.id);
             for (const intf of compInterfaces) {
               for (const m of intf.methods) {
@@ -11875,6 +12209,95 @@ var init_lint_allows = __esm({
   }
 });
 
+// src/core/rules/portal-call-auth.ts
+var COMPONENT_REF_PREFIX, portalCallAuthRule;
+var init_portal_call_auth = __esm({
+  "src/core/rules/portal-call-auth.ts"() {
+    "use strict";
+    COMPONENT_REF_PREFIX = "component:";
+    portalCallAuthRule = {
+      name: "portal-call-auth",
+      description: "Hardens authenticated cross-service calls. An OUTBOUND narrative `call` into ANOTHER component's Portal whose auth is not `none` must (a) be made by an Adapter \u2014 the only block that does external I/O \u2014 and (b) declare the credential source it presents via the step's `auth.from`. Absence of a source warns PORTAL_AUTH_UNMET; a non-Adapter presenter warns AUTH_PRESENTER_NOT_ADAPTER. When `auth.from` is a modeled reference (`component:<id>`) it must resolve to an Adapter/Store the presenter is wired to (UNKNOWN_AUTH_SOURCE / AUTH_SOURCE_NOT_PROVIDER / AUTH_SOURCE_UNWIRED). 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" },
+        { code: "AUTH_PRESENTER_NOT_ADAPTER", defaultSeverity: "warning", summary: "A non-Adapter component authenticates an outbound call to a portal (external I/O must go through an Adapter)" },
+        { code: "UNKNOWN_AUTH_SOURCE", defaultSeverity: "warning", summary: "auth.from references a component: source that does not exist" },
+        { code: "AUTH_SOURCE_NOT_PROVIDER", defaultSeverity: "warning", summary: "auth.from references a component that is not an Adapter or Store" },
+        { code: "AUTH_SOURCE_UNWIRED", defaultSeverity: "warning", summary: "The presenter declares a component: credential source it does not depend on or own" }
+      ],
+      check(ctx) {
+        for (const impl of ctx.implementations) {
+          const ownComponent = ctx.interfaceMap.get(impl.contract)?.component;
+          const presenter = ownComponent ? ctx.componentMap.get(ownComponent) : void 0;
+          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 (presenter && presenter.componentType !== "Adapter") {
+                ctx.addIssue(
+                  "warning",
+                  "AUTH_PRESENTER_NOT_ADAPTER",
+                  `Narrative step ${step.stepNumber} of "${method2.name}" in "${impl.id}": "${presenter.id}" (${presenter.componentType}) authenticates an outbound call to portal "${target.id}". An authenticated cross-service call is external I/O and must be made by an Adapter (the only block that does external I/O) \u2014 route it through a client Adapter.`,
+                  impl.id,
+                  draft
+                );
+              }
+              const from = step.auth?.from;
+              if (!from) {
+                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
+                );
+                continue;
+              }
+              if (from.startsWith(COMPONENT_REF_PREFIX)) {
+                const srcId = from.slice(COMPONENT_REF_PREFIX.length);
+                const src = ctx.componentMap.get(srcId);
+                if (!src) {
+                  ctx.addIssue(
+                    "warning",
+                    "UNKNOWN_AUTH_SOURCE",
+                    `Narrative step ${step.stepNumber} of "${method2.name}" in "${impl.id}": auth.from references component "${srcId}", which does not exist.`,
+                    impl.id,
+                    draft
+                  );
+                } else {
+                  if (src.componentType !== "Adapter" && src.componentType !== "Store") {
+                    ctx.addIssue(
+                      "warning",
+                      "AUTH_SOURCE_NOT_PROVIDER",
+                      `Narrative step ${step.stepNumber} of "${method2.name}" in "${impl.id}": auth.from references "${srcId}" (${src.componentType}); a credential source must be an Adapter (loads the secret via external I/O) or a Store (holds it).`,
+                      impl.id,
+                      draft
+                    );
+                  }
+                  const wired = (presenter?.dependsOn ?? []).includes(srcId) || (presenter?.owns ?? []).includes(srcId);
+                  if (presenter && !wired) {
+                    ctx.addIssue(
+                      "warning",
+                      "AUTH_SOURCE_UNWIRED",
+                      `Narrative step ${step.stepNumber} of "${method2.name}" in "${impl.id}": "${presenter.id}" loads its credential from "${srcId}" but neither depends on nor owns it \u2014 declare the dependsOn edge so the credential wiring is real.`,
+                      impl.id,
+                      draft
+                    );
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    };
+  }
+});
+
 // src/core/rules/index.ts
 function makeScopeFilter(opts) {
   const { components, interfaces, implementations, types, scopeSubsystem } = opts;
@@ -12120,6 +12543,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();
@@ -12141,6 +12565,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.
@@ -12203,6 +12630,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",
@@ -12608,6 +13036,28 @@ function buildGraphModel(level) {
       ...t.subsystem ? { parentId: t.subsystem } : {}
     });
   }
+  const componentByInterface = /* @__PURE__ */ new Map();
+  for (const c of model.components) {
+    for (const intf of c.interfaces) componentByInterface.set(intf.id, c.id);
+  }
+  for (const impl of loadImplementationSpecs()) {
+    const componentId = componentByInterface.get(impl.contract);
+    if (!componentId) continue;
+    nodes.push({
+      id: impl.id,
+      label: impl.name,
+      kind: "implementation",
+      level: 4,
+      parentId: componentId,
+      ...impl.status ? { status: impl.status } : {}
+    });
+    candidates.push({ from: componentId, to: impl.id, edgeKind: "owns" });
+  }
+  for (const c of model.components) {
+    for (const memberId of c.owns) {
+      candidates.push({ from: c.id, to: memberId, edgeKind: "owns" });
+    }
+  }
   for (const e of model.edges) {
     candidates.push({ from: e.from, to: e.to, edgeKind: "depends_on" });
   }
@@ -16744,6 +17194,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`). Opaque form (env:API_KEY, a config key, vault:path) = a design note wairon never resolves; modeled form `component:<id>` references the Adapter/Store that provides the secret and is validated (must resolve, be an Adapter/Store, and be wired to the presenter). Absence on a call into a Portal whose auth \u2260 none warns (PORTAL_AUTH_UNMET). The authenticated call itself should be made by an Adapter (AUTH_PRESENTER_NOT_ADAPTER)."),
     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)"),
@@ -25456,6 +25907,7 @@ init_validation();
 init_diagram();
 init_loader();
 init_extensions();
+init_types();
 init_server();
 
 // src/git/config.ts
@@ -25976,7 +26428,11 @@ var hostCore = {
   checkDeclarativePack: (raw) => {
     const result = DeclarativePackSchema.safeParse(raw);
     return result.success ? null : result.error.issues[0]?.message ?? "shape mismatch";
-  }
+  },
+  /** The ids of wairon's built-in architectural profiles, read from the core rules
+   *  registry's built-in profile set (BUILTIN_PROFILES) — a pure, side-effect-free
+   *  read of a bundled constant. */
+  builtinProfileIds: () => [...BUILTIN_PROFILES]
 };
 function validateProjectAsComplete() {
   const config = loadProjectConfig();
@@ -26385,7 +26841,12 @@ function probe(loadRef, baseRoot, scope, displayRef) {
     ref: displayRef,
     profiles: Object.keys(loaded.profiles).length,
     languages: Object.keys(loaded.languages).length,
-    rules: loaded.rules.length
+    rules: loaded.rules.length,
+    // Structured id lists paralleling the counts above — a UI can present a
+    // pack's profiles/languages/rules as choices instead of a bare number.
+    profileIds: Object.keys(loaded.profiles),
+    languageIds: Object.keys(loaded.languages),
+    ruleIds: loaded.rules.map((r) => r.name)
   };
 }
 function writeFileAtomic(file, content) {
@@ -26415,6 +26876,31 @@ function storeListGlobalPacks() {
   );
   return [...instance, ...image];
 }
+function storeListAvailableProfiles() {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const emit = (id, source, family) => {
+    const key = JSON.stringify([id, source]);
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push(family ? { id, source, family } : { id, source });
+  };
+  for (const id of hostCore.builtinProfileIds()) emit(id, "builtin");
+  const scanTier = (dir) => {
+    for (const full of hostCore.discoverPacks(dir)) {
+      try {
+        const loaded = hostCore.loadExtensionPacks([{ ref: full, scope: "global" }], path45.dirname(full));
+        if (loaded.errors.length) continue;
+        const source = loaded.packNames[0] ?? path45.basename(full);
+        for (const [id, def] of Object.entries(loaded.profiles)) emit(id, source, def.family);
+      } catch {
+      }
+    }
+  };
+  scanTier(hostCore.globalPacksDir());
+  scanTier(imagePacksDir());
+  return out;
+}
 function readPackContent(full) {
   const st = fs36.statSync(full);
   if (st.isFile()) return fs36.readFileSync(full, "utf8");
@@ -26601,6 +27087,23 @@ function installProjectPack(cfg, credential, project2, name, content) {
   requireCap(cfg, credential, "project:admin", "project", project2, "Forbidden \u2014 installing a project pack requires project:admin over the project");
   return executeApprovedInstallProjectPack(cfg, project2, name, content);
 }
+function listAvailableProfiles(cfg, credential) {
+  requirePrincipal2(cfg, credential);
+  return storeListAvailableProfiles();
+}
+function listAdoptableProjectPacks(cfg, credential, project2) {
+  requireCap(cfg, credential, "project:read", "project", project2, "Forbidden \u2014 listing adoptable packs requires project:read over the project");
+  return storeListGlobalPacks();
+}
+function adoptProjectPack(cfg, credential, project2, name) {
+  requireCap(cfg, credential, "project:admin", "project", project2, "Forbidden \u2014 adopting a project pack requires project:admin over the project");
+  const resolution = executeApprovedResolveGlobalPacks([name]);
+  if (resolution.resolved.length === 0) {
+    throw new Error(`no such server-global pack "${name}" \u2014 cannot adopt a pack the instance does not carry`);
+  }
+  const resolved = resolution.resolved[0];
+  return executeApprovedInstallProjectPack(cfg, project2, resolved.name, resolved.content);
+}
 function executeApprovedListProjectPacks(cfg, project2) {
   return runWithProjectRoot(boundProject2(cfg, project2), () => storeListProjectPacks());
 }
@@ -27521,6 +28024,7 @@ function removeIdentityProviderRecord(dataDir, id) {
 }
 var PROJECT_CREATE_CAPABILITY = "project:create";
 var PROJECT_WRITE_CAPABILITY = "project:write";
+var PROJECT_READ_CAPABILITY = "project:read";
 var POLICY_MANAGE_CAPABILITY = "project:admin";
 function carriesInstancePermission(cfg, principal, capability) {
   return authorize(cfg.dataDir, principal, capability, "instance", "").value === "yes";
@@ -27585,6 +28089,19 @@ function recordProjectProfileSelection(root, selection) {
     writeYamlFile(AI_PATHS.projectConfig(), raw);
   });
 }
+function readProjectType(root) {
+  return runWithProjectRoot(root, () => {
+    const raw = readYamlFile(AI_PATHS.projectConfig());
+    return raw?.projectType ?? "backend";
+  });
+}
+function writeProjectType(root, projectType) {
+  runWithProjectRoot(root, () => {
+    const raw = readYamlFile(AI_PATHS.projectConfig()) ?? {};
+    raw["projectType"] = projectType;
+    writeYamlFile(AI_PATHS.projectConfig(), raw);
+  });
+}
 function requestPackNames(request) {
   const sel = request.profileSelection;
   if (!sel) return [];
@@ -27779,6 +28296,32 @@ function reconcileProjectPolicy(cfg, credential, projectId) {
   );
   return result;
 }
+function getProjectConfig(cfg, credential, projectId) {
+  const principal = requirePrincipal4(cfg, credential);
+  if (authorize(cfg.dataDir, principal, PROJECT_READ_CAPABILITY, "project", projectId).value !== "yes") {
+    throw new ForbiddenError(
+      "reading a project's configuration requires project:read over the project"
+    );
+  }
+  const root = resolveProjectRoot(cfg.dataDir, principal, projectId);
+  if (!root) throw new Error(`Unknown project "${projectId}".`);
+  const projectType = readProjectType(root);
+  const locked = runWithProjectRoot(root, () => hostCore.readLockRecord() !== null);
+  return { projectType, locked };
+}
+function setProjectType(cfg, credential, projectId, projectType) {
+  const principal = requirePrincipal4(cfg, credential);
+  if (authorize(cfg.dataDir, principal, PROJECT_WRITE_CAPABILITY, "project", projectId).value !== "yes") {
+    throw new ForbiddenError(
+      "changing a project's configuration requires project:write over the project"
+    );
+  }
+  const root = resolveProjectRoot(cfg.dataDir, principal, projectId);
+  if (!root) throw new Error(`Unknown project "${projectId}".`);
+  writeProjectType(root, projectType);
+  const locked = runWithProjectRoot(root, () => hostCore.readLockRecord() !== null);
+  return { projectType, locked };
+}
 function getPackPolicy(cfg, credential) {
   requirePrincipal4(cfg, credential);
   return getPackPolicyRecord(cfg.dataDir) ?? PERMISSIVE_DEFAULT_POLICY;
@@ -27842,7 +28385,7 @@ function handlePolicyRequest(cfg, credential, req, res, body, url) {
 
 // src/server/identity.ts
 var PROJECT_ADMIN_CAPABILITY2 = "project:admin";
-var PROJECT_READ_CAPABILITY = "project:read";
+var PROJECT_READ_CAPABILITY2 = "project:read";
 var PROJECT_WRITE_CAPABILITY2 = "project:write";
 function requireInstanceProjectAdmin(cfg, principal, what) {
   if (authorize(cfg.dataDir, principal, PROJECT_ADMIN_CAPABILITY2, "instance", "").value !== "yes") {
@@ -27988,7 +28531,7 @@ function revokeToken(cfg, credential, tokenId) {
 }
 function mintSelfToken(cfg, credential, projectId, write) {
   const principal = requirePrincipal5(cfg, credential);
-  if (authorize(cfg.dataDir, principal, PROJECT_READ_CAPABILITY, "project", projectId).value !== "yes") {
+  if (authorize(cfg.dataDir, principal, PROJECT_READ_CAPABILITY2, "project", projectId).value !== "yes") {
     throw new ForbiddenError("caller lacks project:read on the requested project");
   }
   if (write && authorize(cfg.dataDir, principal, PROJECT_WRITE_CAPABILITY2, "project", projectId).value !== "yes") {
@@ -28634,7 +29177,7 @@ function audienceDistance(resolution, targetProjectId) {
 // src/server/landscape.ts
 var yamlLib = __toESM(require("js-yaml"));
 var PROJECT_ADMIN_CAPABILITY3 = "project:admin";
-var PROJECT_READ_CAPABILITY2 = "project:read";
+var PROJECT_READ_CAPABILITY3 = "project:read";
 var PROJECT_WRITE_CAPABILITY3 = "project:write";
 function requirePrincipal6(cfg, credential) {
   const principal = authenticateCredential(cfg.dataDir, credential);
@@ -28648,7 +29191,7 @@ function readView(cfg, principal) {
   if (isInstanceAdmin(principal)) {
     return { all: true, projectIds: /* @__PURE__ */ new Set(), unitIds: /* @__PURE__ */ new Set(), contextUnitIds: /* @__PURE__ */ new Set() };
   }
-  const read = visibleScopes(cfg.dataDir, principal, PROJECT_READ_CAPABILITY2);
+  const read = visibleScopes(cfg.dataDir, principal, PROJECT_READ_CAPABILITY3);
   const admin = visibleScopes(cfg.dataDir, principal, PROJECT_ADMIN_CAPABILITY3);
   const unitIds = /* @__PURE__ */ new Set([...actionableUnitIds(read), ...actionableUnitIds(admin)]);
   const contextUnitIds = new Set(
@@ -28663,13 +29206,13 @@ function readView(cfg, principal) {
 }
 function requireLandscapeReach(cfg, principal, view, what) {
   if (view.all || view.projectIds.size > 0 || view.unitIds.size > 0) return;
-  if (permitsCap(cfg, principal, PROJECT_READ_CAPABILITY2, "instance", "") || permitsCap(cfg, principal, PROJECT_ADMIN_CAPABILITY3, "instance", "")) {
+  if (permitsCap(cfg, principal, PROJECT_READ_CAPABILITY3, "instance", "") || permitsCap(cfg, principal, PROJECT_ADMIN_CAPABILITY3, "instance", "")) {
     return;
   }
   throw new ForbiddenError(`${what} requires project:read reach`);
 }
 function requireObserverScope(cfg, principal, observerProjectId) {
-  const covered = permitsCap(cfg, principal, PROJECT_READ_CAPABILITY2, "project", observerProjectId) || permitsCap(cfg, principal, PROJECT_WRITE_CAPABILITY3, "project", observerProjectId);
+  const covered = permitsCap(cfg, principal, PROJECT_READ_CAPABILITY3, "project", observerProjectId) || permitsCap(cfg, principal, PROJECT_WRITE_CAPABILITY3, "project", observerProjectId);
   if (!covered) {
     throw new ForbiddenError("caller lacks scope over the current project");
   }
@@ -30706,6 +31249,15 @@ function installGlobalPackArchive2(cfg, credential, archive, name) {
 function installProjectPackArchive2(cfg, credential, project2, archive, name) {
   return installProjectPackArchive(cfg, credential, project2, archive, name);
 }
+function listAvailableProfiles2(cfg, credential) {
+  return listAvailableProfiles(cfg, credential);
+}
+function listAdoptableProjectPacks2(cfg, credential, project2) {
+  return listAdoptableProjectPacks(cfg, credential, project2);
+}
+function adoptProjectPack2(cfg, credential, project2, name) {
+  return adoptProjectPack(cfg, credential, project2, name);
+}
 function getPackPolicy2(cfg, credential) {
   return getPackPolicy(cfg, credential);
 }
@@ -30718,6 +31270,12 @@ function evaluateProjectPolicy2(cfg, credential, projectId) {
 function reconcileProjectPolicy2(cfg, credential, projectId) {
   return reconcileProjectPolicy(cfg, credential, projectId);
 }
+function getProjectConfig2(cfg, credential, projectId) {
+  return getProjectConfig(cfg, credential, projectId);
+}
+function setProjectType2(cfg, credential, projectId, projectType) {
+  return setProjectType(cfg, credential, projectId, projectType);
+}
 function listProducers2(cfg, credential, project2) {
   return listProducers(cfg, credential, project2);
 }
@@ -31839,7 +32397,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)) {
@@ -31848,7 +32406,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));
@@ -33999,6 +34569,15 @@ function opsInstallGlobalPackArchive(cfg, sessionId, req, body, res) {
 function opsInstallProjectPackArchive(cfg, sessionId, req, url, body, res) {
   sendJson(res, 200, installProjectPackArchive2(cfg, sessionId, q(url, "projectId") ?? "", archiveBody(body), packNameOverride(req)));
 }
+function opsListAvailableProfiles(cfg, sessionId, res) {
+  sendJson(res, 200, { profiles: listAvailableProfiles2(cfg, sessionId) });
+}
+function opsListAdoptableProjectPacks(cfg, sessionId, url, res) {
+  sendJson(res, 200, { packs: listAdoptableProjectPacks2(cfg, sessionId, q(url, "projectId") ?? "") });
+}
+function opsAdoptProjectPack(cfg, sessionId, body, res) {
+  sendJson(res, 200, adoptProjectPack2(cfg, sessionId, String(body?.projectId ?? ""), String(body?.name ?? "")));
+}
 function opsGetPackPolicy(cfg, sessionId, res) {
   sendJson(res, 200, getPackPolicy2(cfg, sessionId));
 }
@@ -34011,6 +34590,12 @@ function opsPolicyEvaluate(cfg, sessionId, url, res) {
 function opsPolicyReconcile(cfg, sessionId, body, res) {
   sendJson(res, 200, reconcileProjectPolicy2(cfg, sessionId, String(body?.projectId ?? "")));
 }
+function opsGetProjectConfig(cfg, sessionId, url, res) {
+  sendJson(res, 200, getProjectConfig2(cfg, sessionId, q(url, "projectId") ?? ""));
+}
+function opsSetProjectConfig(cfg, sessionId, body, res) {
+  sendJson(res, 200, setProjectType2(cfg, sessionId, String(body?.projectId ?? ""), String(body?.projectType ?? "")));
+}
 function opsListProducers(cfg, sessionId, url, res) {
   sendJson(res, 200, { producers: listProducers2(cfg, sessionId, q(url, "projectId") ?? "") });
 }
@@ -34195,7 +34780,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;
@@ -34237,6 +34823,18 @@ async function handleWebRequest(cfg, req, res, body, url, ctx) {
       if (req.method === "POST" && parts.length === 4 && parts[2] === "packs" && parts[3] === "remove") {
         return opsRemoveProjectPack(cfg, sessionId, body, res);
       }
+      if (req.method === "GET" && parts.length === 4 && parts[2] === "packs" && parts[3] === "adoptable") {
+        return opsListAdoptableProjectPacks(cfg, sessionId, url, res);
+      }
+      if (req.method === "POST" && parts.length === 4 && parts[2] === "packs" && parts[3] === "adopt") {
+        return opsAdoptProjectPack(cfg, sessionId, body, res);
+      }
+      if (req.method === "GET" && parts.length === 3 && parts[2] === "config") {
+        return opsGetProjectConfig(cfg, sessionId, url, res);
+      }
+      if (req.method === "POST" && parts.length === 3 && parts[2] === "config") {
+        return opsSetProjectConfig(cfg, sessionId, body, res);
+      }
       if (req.method === "GET" && parts.length === 3 && parts[2] === "policy") {
         return opsPolicyEvaluate(cfg, sessionId, url, res);
       }
@@ -34350,6 +34948,9 @@ async function handleWebRequest(cfg, req, res, body, url, ctx) {
       if (req.method === "POST" && parts.length === 4 && parts[2] === "packs" && parts[3] === "remove") {
         return opsRemoveGlobalPack(cfg, sessionId, body, res);
       }
+      if (req.method === "GET" && parts.length === 3 && parts[2] === "profiles") {
+        return opsListAvailableProfiles(cfg, sessionId, res);
+      }
       if (req.method === "GET" && parts.length === 3 && parts[2] === "policy") {
         return opsGetPackPolicy(cfg, sessionId, res);
       }
@@ -35151,6 +35752,7 @@ var WEB_MUTATION_PATHS = /* @__PURE__ */ new Set([
   "/web/projects/packs",
   "/web/projects/packs/upload",
   "/web/projects/packs/remove",
+  "/web/projects/packs/adopt",
   "/web/projects/policy/reconcile",
   "/web/projects/producers",
   "/web/projects/producers/remove",