@@ -0,0 +1,15 @@
+---
+'@objectstack/cli': patch
+---
+
+fix(cli): `os build` carries the OpenAPI document a `provider: 'openapi'` connector names by package-relative file into the artifact, so the app works once installed into another runtime
+
+Clause-②: no
+Metadata-protocol: none
+
+A declarative OpenAPI connector may name its document by file, relative to the directory holding `objectstack.config.ts` (`providerConfig.spec: './openapi/stripe.openapi.json'`). The build used to write that path into `dist/objectstack.json` unchanged and carry no document. The runtime the artifact is installed into (`os package install ./dist/objectstack.json`, or a marketplace install) keeps the artifact JSON and nothing else, so the path resolved against that runtime's own root, named no file, and the connector never came up: the install answered success, and the instance was missing from `GET /api/v1/automation/connectors`.
+
+- **What the build now writes.** For each `provider: 'openapi'` entry whose `providerConfig.spec` is a string that is not an http(s) URL, the file is read and its JSON written in place of the path, as the inline document the provider already accepts. Every other key of `providerConfig`, an inline document, an http(s) URL and every other provider are written as before. The entries of `packages[i].manifest` bodies are read too.
+- **What the build now refuses.** A spec path that is absolute, climbs out of the directory holding the config, names no file, or names a file that is not a JSON object fails the build, located at the entry (`connectors[0].providerConfig.spec`) — it would fail the instance after install otherwise.
+- **What changes for readers of the artifact.** An artifact built this way carries the document (its size grows by the document's), and `providerConfig.spec` there is an object rather than a path. Whether the document is OpenAPI 3.x is still judged by the provider when the instance materializes.
+- **Your fix, if you ship such an app:** rebuild it with this CLI and publish or install the new artifact. Nothing in the source changes.
@@ -131,6 +131,10 @@ only the listed operations become actions). The `spec` takes any of three forms:
 - a **package-relative file path** like `'./specs/billing-openapi.json'`,
   resolved against the directory containing `objectstack.config.ts` and
   **confined to it** — absolute and `..`-escaping paths are rejected.
+  `os build` reads the file and writes its JSON into
+  `dist/objectstack.json` in place of the path, so an artifact installed into
+  another runtime carries the document; a path that names no file, or no JSON
+  object, fails the build.
 
 {/* os:check */}
 ```typescript
 
@@ -16,6 +16,7 @@ import {
 } from '@objectstack/spec';
 import { loadConfig, namedExportRejectionHints } from '../utils/config.js';
 import { collectSeedFiles, placeSeedFiles } from '../utils/bundle-seed-files.js';
+import { collectConnectorSpecFiles, placeConnectorSpecFiles } from '../utils/bundle-connector-spec-files.js';
 import { judgeSeedRecordValues } from '../utils/seed-record-values.js';
 import { refuseUnbuiltStack } from '../utils/stack-provenance-refusal.js';
 import { isExtractionRefusal, lowerCallables } from '../utils/lower-callables.js';
@@ -1122,6 +1123,30 @@ export default class Compile extends Command {
         printStep(`Bundling seed files... ${seedFiles.files} file${seedFiles.files === 1 ? '' : 's'} (${(seedFiles.bytes / 1024).toFixed(1)} KB)`);
       }
 
+      // 4a-bis. The OpenAPI document a `provider: 'openapi'` connector names
+      //     by package-relative file (ADR-0097), read relative to the
+      //     directory holding the config and carried in the artifact as the
+      //     inline document. An installed artifact has no package directory —
+      //     the runtime it is installed into caches the JSON alone — so a
+      //     reference left as a path resolves against that runtime's own root
+      //     and names nothing. A path that names no file fails the build here
+      //     rather than the instance after install.
+      const connectorSpecs = collectConnectorSpecFiles(absolutePath, finalBundle);
+      if (connectorSpecs.issues.length > 0) {
+        if (flags.json) {
+          await emitJson({ success: false, error: 'connector spec file bundling failed', issues: connectorSpecs.issues, warnings: warningsSoFar(), conversions: conversionNotices }, 0, { compact: true });
+          this.exit(1);
+        }
+        console.log('');
+        printError(`Connector spec file bundling failed (${connectorSpecs.issues.length} issue${connectorSpecs.issues.length > 1 ? 's' : ''})`);
+        for (const issue of connectorSpecs.issues) console.log(chalk.red(`  ✗ ${issue.location}: ${issue.message}`));
+        this.exit(1);
+      }
+      placeConnectorSpecFiles(connectorSpecs);
+      if (connectorSpecs.files > 0 && !flags.json) {
+        printStep(`Bundling connector spec files... ${connectorSpecs.files} document${connectorSpecs.files === 1 ? '' : 's'} (${(connectorSpecs.bytes / 1024).toFixed(1)} KB)`);
+      }
+
       // 4b. Bundle handler functions into `<artifactDir>/objectstack-runtime.{hash}.mjs`
       //     and stamp the relative path into the JSON so the runtime can
       //     dynamic-import it at boot. `runtimeModule` is part of the
 
@@ -26,6 +26,7 @@ import { resolveJsxGateManifest, printJsxGateNotices } from '../utils/sdui-manif
 import { preflightDeclaredCapabilities, renderCapabilityMessage } from '../utils/capability-preflight.js';
 import { collectAndLintDocs, type DocIssue } from '../utils/collect-docs.js';
 import { collectSeedFiles } from '../utils/bundle-seed-files.js';
+import { collectConnectorSpecFiles } from '../utils/bundle-connector-spec-files.js';
 import { judgeSeedRecordValues } from '../utils/seed-record-values.js';
 import {
   printHeader,
@@ -804,6 +805,29 @@ export default class Validate extends Command {
         this.exit(1);
       }
 
+      // 3d-ter. Connector spec files — the OpenAPI document a
+      //     `provider: 'openapi'` connector names by package-relative file must
+      //     name a JSON object under the directory holding the config. `os build`
+      //     refuses the same references before it carries the documents into the
+      //     artifact, where an installed copy has no package directory to read.
+      const connectorSpecs = collectConnectorSpecFiles(absolutePath, result.data as Record<string, unknown>);
+      if (connectorSpecs.issues.length > 0) {
+        if (flags.json) {
+          await emitJson({
+            valid: false,
+            errors: connectorSpecs.issues,
+            warnings: warningsSoFar(),
+            conversions: conversionNotices,
+            duration: timer.elapsed(),
+          });
+          this.exit(1);
+        }
+        console.log('');
+        printError(`Connector spec file validation failed (${connectorSpecs.issues.length} issue${connectorSpecs.issues.length > 1 ? 's' : ''})`);
+        for (const issue of connectorSpecs.issues) console.log(chalk.red(`  ✗ ${issue.location}: ${issue.message}`));
+        this.exit(1);
+      }
+
       // 3d-bis. [#27259] Seed record VALUES — each value a seed record writes,
       //     judged by the insert write's own value verdict
       //     (`validateInsertValues`, `@objectstack/objectql`), so a value the
 
@@ -0,0 +1,103 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { collectConnectorSpecFiles, placeConnectorSpecFiles } from './bundle-connector-spec-files.js';
+
+/**
+ * `os build` reads the OpenAPI document a `provider: 'openapi'` connector names
+ * by package-relative file, relative to the directory holding the config
+ * (`collectConnectorSpecFiles`), and writes it into the entry's
+ * `providerConfig.spec` as the inline document (`placeConnectorSpecFiles`), so
+ * an artifact installed into another runtime carries it. A reference that is
+ * absolute, climbs out of the root, names no file or names no JSON object is
+ * refused; every other provider, key and form is left as written.
+ */
+
+const DOC = { openapi: '3.0.3', info: { title: 'Fixture', version: '1.0.0' }, paths: {} };
+
+const roots: string[] = [];
+afterEach(() => {
+  for (const root of roots.splice(0)) fs.rmSync(root, { recursive: true, force: true });
+});
+
+/** A package root holding `files`; answers the path of its (unread) config. */
+function packageRoot(files: Record<string, string>): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'os-connector-spec-'));
+  roots.push(root);
+  for (const [rel, content] of Object.entries(files)) {
+    fs.mkdirSync(path.dirname(path.join(root, rel)), { recursive: true });
+    fs.writeFileSync(path.join(root, rel), content);
+  }
+  return path.join(root, 'objectstack.config.ts');
+}
+
+/** Both halves, as `os build` runs them. */
+function bundle(stack: Record<string, unknown>, config: string) {
+  const collected = collectConnectorSpecFiles(config, stack);
+  if (collected.issues.length === 0) placeConnectorSpecFiles(collected);
+  return collected;
+}
+
+const openapi = (spec: unknown, name = 'billing') => ({
+  name,
+  provider: 'openapi',
+  providerConfig: { spec, include: ['GetThings'] },
+});
+
+describe('os build — connector spec files', () => {
+  it('carries a package-relative spec into the entry as the inline document, keeping its other keys', () => {
+    const config = packageRoot({ 'openapi/billing.json': JSON.stringify(DOC) });
+    const stack = { connectors: [openapi('./openapi/billing.json')] };
+    const collected = bundle(stack, config);
+    expect(collected.issues).toEqual([]);
+    expect(collected.files).toBe(1);
+    expect(stack.connectors[0].providerConfig).toEqual({ spec: DOC, include: ['GetThings'] });
+  });
+
+  it('reads the entries of every package body and the manifest, by where each sits', () => {
+    const config = packageRoot({ 'a.json': JSON.stringify(DOC), 'b.json': JSON.stringify({ ...DOC, x: 1 }) });
+    const stack = {
+      manifest: { connectors: [openapi('a.json', 'a')] },
+      packages: [{ manifest: { connectors: [openapi('b.json', 'b')] } }],
+    };
+    const collected = bundle(stack, config);
+    expect(collected.issues).toEqual([]);
+    expect(stack.manifest.connectors[0].providerConfig.spec).toEqual(DOC);
+    expect(stack.packages[0].manifest.connectors[0].providerConfig.spec).toEqual({ ...DOC, x: 1 });
+  });
+
+  it('leaves an inline document, an http(s) URL and every other provider as written', () => {
+    const config = packageRoot({ 'x.json': JSON.stringify(DOC) });
+    const stack = {
+      connectors: [
+        openapi(DOC, 'inline'),
+        openapi('https://example.com/openapi.json', 'remote'),
+        { name: 'rest', provider: 'rest', providerConfig: { spec: 'x.json', baseUrl: 'https://example.com' } },
+        { name: 'descriptor', type: 'api' },
+      ],
+    };
+    const before = JSON.parse(JSON.stringify(stack));
+    const collected = bundle(stack, config);
+    expect(collected).toMatchObject({ issues: [], files: 0 });
+    expect(stack).toEqual(before);
+  });
+
+  it.each([
+    ['names no file', './openapi/absent.json'],
+    ['climbs out of the root', '../outside.json'],
+    ['is absolute', '/etc/openapi.json'],
+    ['is not JSON', 'bad.json'],
+    ['is not a JSON object', 'list.json'],
+  ])('refuses a reference that %s, located and naming it, and changes nothing', (_label, ref) => {
+    const config = packageRoot({ 'bad.json': 'openapi: 3.0.3', 'list.json': '[]' });
+    const stack = { connectors: [openapi(ref)] };
+    const collected = collectConnectorSpecFiles(config, stack);
+    expect(collected.issues).toHaveLength(1);
+    expect(collected.issues[0].location).toBe('connectors[0].providerConfig.spec');
+    expect(collected.issues[0].message).toContain(`connector 'billing' providerConfig.spec '${ref}'`);
+    expect(stack.connectors[0].providerConfig.spec).toBe(ref);
+  });
+});