From 876ce8ee525be2c5f371c0d8fb16b85d42f84dd1 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 3 Sep 2026 02:33:56 +0000
Subject: [PATCH] docs(cli): stop naming the out-of-repo `apps/objectos` as
 serve.ts's in-repo host-config example
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`packages/cli/src/commands/serve.ts` named `apps/objectos` at three sites as if
it were a path in this repo. It is not: `apps/` holds exactly one entry,
`apps/docs`. The app is real but lives in the sibling `objectstack-ai/cloud`
repo, split out of this one (CHANGELOG.md, "deleted from this repo ... now
lives in `objectstack-ai/cloud/apps/objectos`"; ROADMAP.md says the same).

The three sites are not one defect repeated, so they do not take one fix:

- `:1921` is a provenance note about where the artifact-first fallback came
  from. The referent is genuinely out of this repo, so it is marked as such
  rather than renamed — a reader who wants it can still find it.
- `:2791` and `:2965` were worked examples of live branches. Both branches key
  on a SHAPE (`plugins[]` already holding an `AppPlugin` instance; a config
  composing several `new AppPlugin(...)` entries), never on an app name, so the
  shape is stated and no app is named. `examples/app-showcase` is named once,
  at the one claim that is true of it and checkable: a host config whose
  `plugins[]` holds instantiated plugins while the stack still carries
  top-level metadata.

Comments only; no behaviour, no exported surface, no authored metadata changes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza
---
 packages/cli/src/commands/serve.ts | 26 +++++++++++++++++---------
 1 file changed, 17 insertions(+), 9 deletions(-)

diff --git a/packages/cli/src/commands/serve.ts b/packages/cli/src/commands/serve.ts
index 86b5052c35..bd070ffeab 100644
--- a/packages/cli/src/commands/serve.ts
+++ b/packages/cli/src/commands/serve.ts
@@ -1917,10 +1917,11 @@ export default class Serve extends Command {
     // compiled artifact is reachable (explicit OS_ARTIFACT_PATH —
     // including http(s):// URLs — or the canonical
     // `<cwd>/dist/objectstack.json`), boot from that artifact alone.
-    // This is the same capability previously hard-coded in
-    // `apps/objectos/objectstack.config.ts`, lifted into the framework
-    // so any project can `objectstack start` against just a
-    // `dist/objectstack.json`.
+    // This is the same capability previously hard-coded in the tenant
+    // runtime's own `objectstack.config.ts` — that app is `apps/objectos` in
+    // the separate `objectstack-ai/cloud` repo, NOT a path in this one — and
+    // lifted into the framework so any project can `objectstack start`
+    // against just a `dist/objectstack.json`.
     const configMissing = !configExists;
     let useArtifactFallback = false;
     let useEmptyBoot = false;
@@ -2786,10 +2787,17 @@ export default class Serve extends Command {
       // need this wrap when they ALSO carry top-level metadata — otherwise
       // top-level `flows`, `objects`, etc. never reach the ObjectQL registry
       // and downstream services like AutomationServicePlugin start with 0 flows.
+      // `examples/app-showcase` is the in-repo worked example of exactly that
+      // shape: its `plugins[]` holds instantiated connector plugins while the
+      // stack still declares top-level `objects` / `apps` / `flows` / `apis`
+      // (`serve-host-config-security-registrar.pin.test.ts` records an `os dev`
+      // boot of it).
       //
       // To avoid double-registration when the host already wraps itself with
-      // an AppPlugin (e.g. apps/objectos's dev-workspace stack), we skip if
-      // any plugin in `plugins[]` is already an AppPlugin instance.
+      // an AppPlugin, we skip if any plugin in `plugins[]` is already an
+      // AppPlugin instance. That branch keys on the SHAPE — a `plugins[]` that
+      // already holds an AppPlugin instance — and never on a named app, so it
+      // is checked structurally below.
       const hasAppPluginAlready = plugins.some(isAppPluginLike);
       const configHasMetadata = !!(
         config.objects || config.manifest || config.apps || config.flows || config.apis
@@ -2962,9 +2970,9 @@ export default class Serve extends Command {
             || p.constructor?.name === 'I18nServicePlugin'
       );
       // Check the top-level config AND any nested AppPlugin bundles in the
-      // `plugins` array — host/aggregator configs (e.g. apps/objectos) don't
-      // define translations themselves but compose multiple `new AppPlugin(...)`
-      // entries, each carrying its own translations.
+      // `plugins` array — a host/aggregator config may define no translations
+      // of its own and instead compose several `new AppPlugin(...)` entries,
+      // each carrying its own. Keyed on that shape, not on a named app.
       const pluginBundleHasTranslations = (bundle: any): boolean => {
         if (!bundle || typeof bundle !== 'object') return false;
         if (Array.isArray(bundle.translations) && bundle.translations.length > 0) return true;