@gaia-ai/conductor 0.5.5 → 0.6.1

package/README.md

@@ -2,4 +2,4 @@
 
 GAIA conductor engine + CLI: registers, claims tickets via JSON:API, dispatches agents.
 
-Part of the GAIA conductor. Install the meta package `@gaia-ai/gaia` to get the `gaia` CLI with all plugins. Source: https://git.key-tec.de/keytec/gaia (conductor/).
+Part of the GAIA CLI. Install the meta package `@gaia-ai/gaia` to get the `gaia` CLI with all addons. Source: https://git.key-tec.de/keytec/gaia (gaia-cli/).

package/dist/src/cli/config-schema.d.ts

@@ -0,0 +1,89 @@
+/**
+ * A single, discrete, testable upgrade method `vN → vN+1`, registered in order —
+ * exactly like a Drupal `hook_update_N` chain. `gaia upgrade` resolves a config's
+ * current version and applies each method in sequence up to CURRENT (it does not
+ * blindly overwrite), so a method can PRESERVE operator-set fields across a bump.
+ */
+export interface ConnectionConfigMigration {
+    /** The schema version this method upgrades FROM. */
+    from: number;
+    /** The schema version this method upgrades TO (=== from + 1). */
+    to: number;
+    /** What shape change this method performs (human-readable). */
+    description: string;
+    /**
+     * Upgrade the config text from `from` to `to`, returning the new file text
+     * WITHOUT the version header — the runner re-stamps `@gaia-schema-version to`.
+     */
+    apply(currentText: string): string;
+}
+/**
+ * GAIA-226: the package name whose `plugins[]` entry contributes the `md`
+ * renderer (plus the authoritative JSON:API schema) to a connection config. The
+ * AGGREGATOR is named, not `@dropsh/plugin-markdown` directly: a direct
+ * `@dropsh/*` descriptor is unresolvable from `loadGaiaConfig`'s bases
+ * (config dir / host module / cwd), whereas `@gaia-ai/addon-essentials` is a
+ * real dependency of both the host and the engine and therefore resolves in the
+ * monorepo AND from a global `@gaia-ai/gaia` install. No `export:` is needed —
+ * the package default-exports its factory.
+ */
+export declare const RENDERER_PLUGIN_PACKAGE = "@gaia-ai/addon-essentials";
+/** The exact `plugins[]` element text the v1→v2 migration and the scaffold emit. */
+export declare const RENDERER_PLUGIN_ENTRY = "{ plugin: '@gaia-ai/addon-essentials' },";
+/**
+ * GAIA-226 (v1 → v2): insert the renderer aggregator as the FIRST `plugins[]`
+ * element, so `gaia dropsh --format md` works instead of failing with
+ * `E_CONFIG: Unknown format 'md'. Available: json`.
+ *
+ * A pure TEXT transform — the upgrade runner must never execute a possibly
+ * side-effecting config module. Idempotent: text that already names the package
+ * in CODE is returned unchanged (whole-line `//` comments are stripped for that
+ * probe, so the template's own explanatory header does not read as a hit), and a
+ * config with no `plugins: [` array literal (an `addons: []`-shaped or
+ * hand-reshaped file) is left alone rather than guessed at.
+ */
+export declare function addRendererPluginEntry(text: string): string;
+/**
+ * The ordered, contiguous migration chain. v1 was the pre-GAIA-226 shape (auth
+ * plugins only); v2 adds the markdown renderer entry. Nothing below v1 is a
+ * versioned config (v0 = seed / hand-authored / untouched). `GAIA_CONFIG_SCHEMA_VERSION`
+ * derives from the chain's last `to` — never hardcode it.
+ */
+export declare const CONNECTION_MIGRATIONS: ConnectionConfigMigration[];
+/** The current connection-config schema version — single source of truth. */
+export declare const GAIA_CONFIG_SCHEMA_VERSION: number;
+/** Parse the `@gaia-schema-version` marker from config text; `0` when absent. */
+export declare function schemaVersionOf(text: string): number;
+/**
+ * Read the schema version from a connection config FILE by regex (sync, never
+ * executes the module). `0` when the file is absent, unreadable, or carries no
+ * marker (legacy / hand-authored).
+ */
+export declare function readConfigSchemaVersion(path: string): number;
+/** Strip a leading `// @gaia-schema-version <N>` header line, if present. */
+export declare function stripVersionHeader(text: string): string;
+/** Prepend (replacing any existing) a `// @gaia-schema-version <N>` header. */
+export declare function stampVersion(text: string, version: number): string;
+/**
+ * Re-stamp the in-body `schema_version: <N>` field, which the generated config
+ * carries alongside the header marker for programmatic reads. The header is the
+ * upgrade decision's source of truth and is stamped by the runner; this keeps the
+ * FIELD from going stale when a migration bumps the version (GAIA-226 — the first
+ * migration is where the two could first disagree). No-op when the field is
+ * absent (a hand-authored config need not carry it).
+ */
+export declare function stampSchemaVersionField(text: string, version: number): string;
+/**
+ * Validate a migration chain is contiguous: each `to === from + 1`, the first
+ * migrates from v1, no gaps, and the chain ends at `current` (default CURRENT).
+ * An empty chain is valid iff `current === 1`. Throws with an actionable message.
+ */
+export declare function assertContiguous(chain: ConnectionConfigMigration[], current?: number): void;
+/**
+ * Walk the migration chain from `from` up to `to`, applying each method's
+ * `apply` in sequence. Input/output text is WITHOUT the version header — the
+ * caller stamps CURRENT after. After each step the in-body `schema_version:`
+ * field is re-stamped to that step's `to`, so no individual method has to know
+ * (or hardcode) its own number twice. `chain` is injectable for tests.
+ */
+export declare function applyMigrations(text: string, from: number, to: number, chain?: ConnectionConfigMigration[]): string;

package/dist/src/cli/config-schema.js

@@ -0,0 +1,146 @@
+import { readFileSync } from 'node:fs';
+// GAIA-216: schema versioning for the generated CONNECTION config
+// (`gaia.config.js`, project + home). Decoupled from the npm package semver —
+// the schema version bumps only when the config SHAPE changes, not every
+// release. Every generated connection config carries a machine-readable header
+// comment `// @gaia-schema-version <N>` (the source of truth for the upgrade
+// decision, read by regex so `gaia upgrade` NEVER executes a possibly
+// side-effecting config module) and a `schema_version: <N>` field for
+// programmatic reads.
+/** The header marker prepended to every generated connection config. */
+const MARKER_RE = /@gaia-schema-version\s+(\d+)/;
+const HEADER_LINE_RE = /^\/\/ @gaia-schema-version \d+\n/;
+/**
+ * GAIA-226: the package name whose `plugins[]` entry contributes the `md`
+ * renderer (plus the authoritative JSON:API schema) to a connection config. The
+ * AGGREGATOR is named, not `@dropsh/plugin-markdown` directly: a direct
+ * `@dropsh/*` descriptor is unresolvable from `loadGaiaConfig`'s bases
+ * (config dir / host module / cwd), whereas `@gaia-ai/addon-essentials` is a
+ * real dependency of both the host and the engine and therefore resolves in the
+ * monorepo AND from a global `@gaia-ai/gaia` install. No `export:` is needed —
+ * the package default-exports its factory.
+ */
+export const RENDERER_PLUGIN_PACKAGE = '@gaia-ai/addon-essentials';
+/** The exact `plugins[]` element text the v1→v2 migration and the scaffold emit. */
+export const RENDERER_PLUGIN_ENTRY = `{ plugin: '${RENDERER_PLUGIN_PACKAGE}' },`;
+/** `plugins: [` — captures its own indentation so the inserted element aligns. */
+const PLUGINS_ARRAY_OPEN_RE = /^([ \t]*)plugins:\s*\[[ \t]*$/m;
+/** Whole-line `//` comments — stripped before the presence probe (see below). */
+const LINE_COMMENT_RE = /^[ \t]*\/\/.*$/gm;
+/**
+ * GAIA-226 (v1 → v2): insert the renderer aggregator as the FIRST `plugins[]`
+ * element, so `gaia dropsh --format md` works instead of failing with
+ * `E_CONFIG: Unknown format 'md'. Available: json`.
+ *
+ * A pure TEXT transform — the upgrade runner must never execute a possibly
+ * side-effecting config module. Idempotent: text that already names the package
+ * in CODE is returned unchanged (whole-line `//` comments are stripped for that
+ * probe, so the template's own explanatory header does not read as a hit), and a
+ * config with no `plugins: [` array literal (an `addons: []`-shaped or
+ * hand-reshaped file) is left alone rather than guessed at.
+ */
+export function addRendererPluginEntry(text) {
+    if (text.replace(LINE_COMMENT_RE, '').includes(RENDERER_PLUGIN_PACKAGE)) {
+        return text;
+    }
+    const m = PLUGINS_ARRAY_OPEN_RE.exec(text);
+    if (m === null)
+        return text;
+    const indent = `${m[1]}  `;
+    return text.replace(PLUGINS_ARRAY_OPEN_RE, (line) => `${line}\n${indent}${RENDERER_PLUGIN_ENTRY}`);
+}
+/**
+ * The ordered, contiguous migration chain. v1 was the pre-GAIA-226 shape (auth
+ * plugins only); v2 adds the markdown renderer entry. Nothing below v1 is a
+ * versioned config (v0 = seed / hand-authored / untouched). `GAIA_CONFIG_SCHEMA_VERSION`
+ * derives from the chain's last `to` — never hardcode it.
+ */
+export const CONNECTION_MIGRATIONS = [
+    {
+        from: 1,
+        to: 2,
+        description: `add the ${RENDERER_PLUGIN_PACKAGE} renderer entry to plugins[]`,
+        apply: addRendererPluginEntry,
+    },
+];
+/** The current connection-config schema version — single source of truth. */
+export const GAIA_CONFIG_SCHEMA_VERSION = CONNECTION_MIGRATIONS.at(-1)?.to ?? 1;
+/** Parse the `@gaia-schema-version` marker from config text; `0` when absent. */
+export function schemaVersionOf(text) {
+    const m = MARKER_RE.exec(text);
+    return m ? Number.parseInt(m[1], 10) : 0;
+}
+/**
+ * Read the schema version from a connection config FILE by regex (sync, never
+ * executes the module). `0` when the file is absent, unreadable, or carries no
+ * marker (legacy / hand-authored).
+ */
+export function readConfigSchemaVersion(path) {
+    try {
+        return schemaVersionOf(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return 0;
+    }
+}
+/** Strip a leading `// @gaia-schema-version <N>` header line, if present. */
+export function stripVersionHeader(text) {
+    return text.replace(HEADER_LINE_RE, '');
+}
+/** Prepend (replacing any existing) a `// @gaia-schema-version <N>` header. */
+export function stampVersion(text, version) {
+    return `// @gaia-schema-version ${version}\n${stripVersionHeader(text)}`;
+}
+/**
+ * Re-stamp the in-body `schema_version: <N>` field, which the generated config
+ * carries alongside the header marker for programmatic reads. The header is the
+ * upgrade decision's source of truth and is stamped by the runner; this keeps the
+ * FIELD from going stale when a migration bumps the version (GAIA-226 — the first
+ * migration is where the two could first disagree). No-op when the field is
+ * absent (a hand-authored config need not carry it).
+ */
+export function stampSchemaVersionField(text, version) {
+    return text.replace(/^([ \t]*)schema_version:\s*\d+\s*,/m, `$1schema_version: ${version},`);
+}
+/**
+ * Validate a migration chain is contiguous: each `to === from + 1`, the first
+ * migrates from v1, no gaps, and the chain ends at `current` (default CURRENT).
+ * An empty chain is valid iff `current === 1`. Throws with an actionable message.
+ */
+export function assertContiguous(chain, current = GAIA_CONFIG_SCHEMA_VERSION) {
+    let prev = 1;
+    chain.forEach((m, i) => {
+        if (m.to !== m.from + 1) {
+            throw new Error(`migration[${i}]: to (${m.to}) must equal from+1 (${m.from + 1})`);
+        }
+        const expectedFrom = i === 0 ? 1 : prev;
+        if (m.from !== expectedFrom) {
+            throw new Error(`migration[${i}]: from (${m.from}) must equal ${expectedFrom} (no gaps; chain starts at v1)`);
+        }
+        prev = m.to;
+    });
+    const end = chain.at(-1)?.to ?? 1;
+    if (end !== current) {
+        throw new Error(`migration chain ends at v${end}, expected CURRENT v${current}`);
+    }
+}
+/**
+ * Walk the migration chain from `from` up to `to`, applying each method's
+ * `apply` in sequence. Input/output text is WITHOUT the version header — the
+ * caller stamps CURRENT after. After each step the in-body `schema_version:`
+ * field is re-stamped to that step's `to`, so no individual method has to know
+ * (or hardcode) its own number twice. `chain` is injectable for tests.
+ */
+export function applyMigrations(text, from, to, chain = CONNECTION_MIGRATIONS) {
+    let cur = from;
+    let out = text;
+    while (cur < to) {
+        const step = chain.find((m) => m.from === cur);
+        if (step === undefined) {
+            throw new Error(`no migration from v${cur} (chain incomplete)`);
+        }
+        out = stampSchemaVersionField(step.apply(out), step.to);
+        cur = step.to;
+    }
+    return out;
+}

package/dist/src/cli/init.d.ts

@@ -1,3 +1,6 @@
+import { type MachineContext, machineContextPath, readMachineContext } from '@gaia-ai/core';
+export type { MachineContext };
+export { machineContextPath, readMachineContext };
 export interface InitInputs {
     baseUrl: string;
     project: string;
@@ -21,19 +24,6 @@ export interface ScaffoldResult {
     wroteCommitted: boolean;
     machine: MachineContextResult;
 }
-/**
- * The user-global machine context: a plain importable module carrying the
- * developer's machine identity and connection (incl. the OAuth client secret).
- * Committed configs import it to compose machine_id and read
- * base_url / client_id / client_secret. Gitignored, user-only (chmod 0600).
- */
-export interface MachineContext {
-    machine_id: string;
-    user_id: string;
-    base_url: string;
-    client_id: string;
-    client_secret: string;
-}
 export interface MachineContextOptions {
     path: string;
     userId: string;
@@ -48,35 +38,43 @@ export interface MachineContextResult {
     filledKeys: string[];
 }
 /**
- * The committed, structural conductor config. `project` is the only per-repo
- * value and is baked in here; connection + identity (incl. the secret) come from
- * the user-global machine context (~/.config/conductor/conductor.config.machine.js),
- * and machine_id is composed as `${user_id}-${machine_id}-${project}`. An
- * optional, gitignored conductor.config.local.js beside this file may override
- * any field — it is loaded if present but never created by `gaia conductor init`.
+ * The committed, structural ENGINE conductor config (GAIA-201). It carries the
+ * engine wiring only — remote/executor/agent/workspace + `machine_id`
+ * composition — and NO `site`/`plugins`, which now live in the sibling
+ * connection config `gaia.config.js`. Connection + identity (incl. the secret)
+ * come from the user-global machine context (`~/.gaia/machine.config.js`);
+ * `machine_id` is composed as `${user_id}-${machine_id}-${project}`.
  */
 export declare function renderCommittedConfig(inputs: Pick<InitInputs, 'project'>): string;
+/**
+ * The committed CONNECTION config `./.gaia/gaia.config.js` (GAIA-201). A
+ * dropsh-shaped `{ site, plugins }` read by `gaia ui`, `gaia dropsh`, and the
+ * conductor's auth. Reads base_url + client credentials from the user-global
+ * machine context (`~/.gaia/machine.config.js`) and declares the session
+ * (default) + pm oauth2 profiles.
+ */
+export declare function renderGaiaConfig(): string;
 /** The user-global machine context module: identity + connection (incl. secret). */
 export declare function renderMachineContext(ctx: MachineContext): string;
-/** The user-global machine context path: ~/.config/conductor/conductor.config.machine.js */
-export declare function machineContextPath(): string;
-/** Import an existing context module's default export, or {} if absent/broken. */
-export declare function readMachineContext(path: string): Promise<Partial<MachineContext>>;
 /**
  * Create-if-missing / fill-only-missing the user-global machine context.
  * Existing values always win; only absent/blank keys are filled. machine_id
- * defaults to hostname(). A no-op (no rewrite) when the file is already complete.
- * The file is written user-only (chmod 0600) since it holds the client secret.
+ * defaults to hostname(). Written user-only (chmod 0600) since it holds the
+ * client secret.
  */
 export declare function scaffoldMachineContext(opts: MachineContextOptions): Promise<MachineContextResult>;
+/** Write the sibling connection config `gaia.config.js` next to the engine
+ *  config. Created only if missing (unless `force`). Returns its path + whether
+ *  it was written. */
+export declare function scaffoldGaiaConfig(engineConfigPath: string, force: boolean): {
+    path: string;
+    wrote: boolean;
+};
 /**
- * Scaffold the two conductor config files: the committed conductor.config.js
- * (created only if missing — never overwritten unless `force`) and the
- * user-global machine context (create-if-missing / fill-only-missing). The
- * optional per-project conductor.config.local.js is NOT generated.
- *
- * `skipMachine` writes the committed config only (project-only setup); its
- * mirror `skipCommitted` writes the machine context only (machine-only
- * onboarding, no repo). Setting both is a no-op.
+ * Scaffold the committed ENGINE conductor.config.js (created only if missing —
+ * never overwritten unless `force`) and the user-global machine context
+ * (create-if-missing / fill-only-missing). The connection config is scaffolded
+ * separately by `scaffoldGaiaConfig`. `skipMachine` writes the committed config
+ * only; `skipCommitted` writes the machine context only.
  */
 export declare function scaffold(inputs: InitInputs, opts: ScaffoldOptions): Promise<ScaffoldResult>;

package/dist/src/cli/init.js

@@ -1,50 +1,53 @@
 import { chmodSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { dirname, join } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { machineContextPath, readMachineContext, } from '@gaia-ai/core';
+import { GAIA_CONFIG_SCHEMA_VERSION, RENDERER_PLUGIN_ENTRY, } from './config-schema.js';
+export { machineContextPath, readMachineContext };
 /** JS single-quoted string literal for a trusted, simple value. */
 function q(value) {
     return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
 }
 /**
- * The committed, structural conductor config. `project` is the only per-repo
- * value and is baked in here; connection + identity (incl. the secret) come from
- * the user-global machine context (~/.config/conductor/conductor.config.machine.js),
- * and machine_id is composed as `${user_id}-${machine_id}-${project}`. An
- * optional, gitignored conductor.config.local.js beside this file may override
- * any field — it is loaded if present but never created by `gaia conductor init`.
+ * The committed, structural ENGINE conductor config (GAIA-201). It carries the
+ * engine wiring only — remote/executor/agent/workspace + `machine_id`
+ * composition — and NO `site`/`plugins`, which now live in the sibling
+ * connection config `gaia.config.js`. Connection + identity (incl. the secret)
+ * come from the user-global machine context (`~/.gaia/machine.config.js`);
+ * `machine_id` is composed as `${user_id}-${machine_id}-${project}`.
  */
 export function renderCommittedConfig(inputs) {
-    return `// Canonical GAIA conductor config — committed. Connection + identity come from
-// your user-global machine context (~/.config/conductor/conductor.config.machine.js:
+    return `// Canonical GAIA conductor ENGINE config — committed. Connection + identity
+// come from your user-global machine context (~/.gaia/machine.config.js:
 // { machine_id, user_id, base_url, client_id, client_secret }); machine_id is
 // composed here as \`\${user_id}-\${machine_id}-\${project}\`. \`project\` is the only
-// per-repo value and is baked in below. The client_secret is read from the
-// machine context (gitignored, user-only) — never committed here.
+// per-repo value and is baked in below. This file is ENGINE-ONLY (GAIA-201):
+// it has NO \`site\` and NO auth \`plugins\` — those live in the sibling
+// ./.gaia/gaia.config.js (the connection config that ui + dropsh + this
+// conductor's auth all read).
 //
-// IMPORT-FREE (GAIA-78): the plugin slots + plugins[] are \`{ plugin, with }\`
-// descriptors naming the REAL published package (\`@gaia-ai/plugin-*\`,
-// \`@dropsh/plugin-*\`), not \`import\`ed constructors. loadConductorConfig
-// resolves each name ESLint-style (config dir → cwd → conductor install), so
-// config load never depends on a \`node_modules/@gaia-ai\` symlink beside this
-// file. Each plugin package default-exports its factory, so the resolver's
-// auto-pick needs no \`export:\` here — EXCEPT the \`@gaia-ai/gaia/plugins\` host
-// barrel (many exports → \`export: 'drupalRemote'\`) and the merged herdr
-// workspace slot (\`@gaia-ai/plugin-herdr\` default-exports the executor, so the
-// workspace names \`export: 'herdrWorkspace'\` — GAIA-139).
+// IMPORT-FREE (GAIA-78): the plugin slots are \`{ plugin, with }\` descriptors
+// naming the REAL published package, not \`import\`ed constructors.
+// loadConductorConfig resolves each name ESLint-style (config dir → cwd →
+// conductor install). Every addon package default-exports its single factory, so
+// no slot needs an \`export:\` — EXCEPT the merged herdr workspace
+// (\`@gaia-ai/addon-herdr\` default-exports the executor, so the workspace names
+// \`export: 'herdrWorkspace'\` — GAIA-139). GAIA-224 replaced the old
+// \`{ plugin: '@gaia-ai/gaia/plugins', export: 'drupalRemote' }\` host-barrel
+// descriptor with the real addon package \`@gaia-ai/addon-remote-drupal\`.
 
 // The user-global machine context: identity + connection (incl. secret), shared
 // by every project on this machine. Never committed.
 async function loadMachine() {
   try {
-    return (await import(\`\${process.env.HOME}/.config/conductor/conductor.config.machine.js\`)).default ?? {};
+    return (await import(\`\${process.env.HOME}/.gaia/machine.config.js\`)).default ?? {};
   } catch {}
   return {};
 }
 
 // OPTIONAL per-project override — create conductor.config.local.js beside this
-// file to override any field (machine_id, base_url, model, …). It is loaded only
-// if present and is NOT created by \`gaia conductor init\`.
+// file to override any field (machine_id, model, …). Loaded only if present and
+// NOT created by \`gaia conductor init\`.
 async function loadLocal() {
   try { return (await import('./conductor.config.local.js')).default ?? {}; } catch {}
   return {};
@@ -53,48 +56,79 @@ async function loadLocal() {
 const machine = await loadMachine();
 const local = await loadLocal();
 const project = local.project ?? ${q(inputs.project)};
-const baseUrl = local.base_url ?? machine.base_url;
-const clientId = local.oauth?.client_id ?? machine.client_id ?? 'gaia-agent';
-const clientSecret = local.oauth?.client_secret ?? machine.client_secret;
 const composedMachineId =
   machine.user_id && machine.machine_id
     ? \`\${machine.user_id}-\${machine.machine_id}-\${project}\`
     : undefined;
 
 export default {
-  site: { base_url: baseUrl, jsonapi_prefix: local.jsonapi_prefix ?? '/jsonapi' },
   project,
   machine_id: local.machine_id ?? composedMachineId,
   states: ['spec', 'diagnose', 'coding', 'review'],
   max_parallel: 5,
-  // Lifecycle hooks are executor-owned (GAIA-84): the executor invokes each
-  // best-effort (logs loudly + continues, never aborts a run), so they live at
-  // the config top level — NOT on a plugin descriptor's \`with.hooks\`.
+  // Lifecycle hooks are executor-owned (GAIA-84): they live at the config top
+  // level — NOT on a plugin descriptor's \`with.hooks\`.
   hooks: { after_create: 'ddev init-worktree', after_done: 'ddev delete -Oy' },
-  remote: { plugin: '@gaia-ai/gaia/plugins', export: 'drupalRemote' },
-  // No hard-wired diff pane for review: the review diff surface is hunk
-  // (GAIA-55) — agent-driven + opt-in in the human's interactive pane, not an
-  // executor-forced git-diff pane. Clicking a changed file in that hunk pane
-  // opens it editable in a spiceedit overlay (see conductor/README.md).
-  executor: { plugin: '@gaia-ai/plugin-herdr' },
+  remote: { plugin: '@gaia-ai/addon-remote-drupal' },
+  executor: { plugin: '@gaia-ai/addon-herdr' },
   agent: {
-    plugin: '@gaia-ai/plugin-claude',
+    plugin: '@gaia-ai/addon-claude',
     with: { model: local.model ?? 'claude-opus-4-8' },
   },
-  // GAIA-139: the herdr workspace ships in @gaia-ai/plugin-herdr now (the
-  // separate plugin-herdr-workspace was merged in). That package default-exports
-  // the EXECUTOR, so the workspace slot must name export: 'herdrWorkspace'.
+  // GAIA-139: the herdr workspace ships in @gaia-ai/addon-herdr, which
+  // default-exports the EXECUTOR — so the workspace slot names export: 'herdrWorkspace'.
   workspace: {
-    plugin: '@gaia-ai/plugin-herdr',
+    plugin: '@gaia-ai/addon-herdr',
     export: 'herdrWorkspace',
   },
-  // oauth2 is a real dep of the host (npm installs it alongside @gaia-ai/gaia).
-  // NOTE: plugins[] is consumed by DROPSH, which reloads this config with its OWN
-  // resolver (\`export ?? 'default'\`, no sole-function auto-pick) on every
-  // \`gaia dropsh …\` command. @dropsh/plugin-oauth2 has no default export, so
-  // these entries MUST name \`export: 'oauth2Plugin'\` — unlike the four conductor
-  // slots above, which the conductor resolves and auto-picks.
+};
+`;
+}
+/**
+ * The committed CONNECTION config `./.gaia/gaia.config.js` (GAIA-201). A
+ * dropsh-shaped `{ site, plugins }` read by `gaia ui`, `gaia dropsh`, and the
+ * conductor's auth. Reads base_url + client credentials from the user-global
+ * machine context (`~/.gaia/machine.config.js`) and declares the session
+ * (default) + pm oauth2 profiles.
+ */
+export function renderGaiaConfig() {
+    return `// @gaia-schema-version ${GAIA_CONFIG_SCHEMA_VERSION}
+// Canonical GAIA CONNECTION config — committed (GAIA-201). A dropsh-shaped
+// { site, plugins } read by 'gaia ui', 'gaia dropsh', and this conductor's auth.
+// Connection + credentials come from your user-global machine context
+// (~/.gaia/machine.config.js). The engine wiring lives in the sibling
+// conductor.config.js (engine-only).
+//
+// plugins[] is consumed by DROPSH, whose resolver has no sole-function
+// auto-pick, so @dropsh/plugin-oauth2 entries MUST name export: 'oauth2Plugin'.
+// The '@gaia-ai/addon-essentials' entry (GAIA-226) needs NO export: — that
+// package default-exports its factory. It contributes the markdown renderer
+// ('gaia dropsh --format md') plus the authoritative JSON:API schema.
+async function loadMachine() {
+  try {
+    return (await import(\`\${process.env.HOME}/.gaia/machine.config.js\`)).default ?? {};
+  } catch {}
+  return {};
+}
+
+async function loadLocal() {
+  try { return (await import('./conductor.config.local.js')).default ?? {}; } catch {}
+  return {};
+}
+
+const machine = await loadMachine();
+const local = await loadLocal();
+const baseUrl = local.base_url ?? machine.base_url;
+const clientId = local.oauth?.client_id ?? machine.client_id ?? 'gaia-agent';
+const clientSecret = local.oauth?.client_secret ?? machine.client_secret;
+
+export default {
+  // GAIA-216: the connection-config schema version — kept in sync with the
+  // header marker above so \`gaia upgrade\` can migrate a stale-shape config.
+  schema_version: ${GAIA_CONFIG_SCHEMA_VERSION},
+  site: { base_url: baseUrl, jsonapi_prefix: local.jsonapi_prefix ?? '/jsonapi' },
   plugins: [
+    ${RENDERER_PLUGIN_ENTRY}
     {
       plugin: '@dropsh/plugin-oauth2',
       export: 'oauth2Plugin',
@@ -126,12 +160,12 @@ export default {
 }
 /** The user-global machine context module: identity + connection (incl. secret). */
 export function renderMachineContext(ctx) {
-    return `// User-global conductor context — gitignored, user-only (chmod 0600), never
+    return `// User-global GAIA machine context — gitignored, user-only (chmod 0600), never
 // committed. A plain importable module holding your machine identity +
-// connection, incl. the OAuth client secret. Committed conductor.config.js files
-// import this to compose machine_id (\`\${user_id}-\${machine_id}-\${project}\`) and
-// read base_url / client_id / client_secret. Created and gap-filled by
-// \`gaia conductor init\`; existing values are never overwritten.
+// connection, incl. the OAuth client secret. The engine conductor.config.js
+// composes machine_id (\`\${user_id}-\${machine_id}-\${project}\`) from it; the
+// connection gaia.config.js reads base_url / client_id / client_secret. Created
+// and gap-filled by \`gaia conductor init\`; existing values are never overwritten.
 export default {
   machine_id: ${q(ctx.machine_id)},
   user_id: ${q(ctx.user_id)},
@@ -141,31 +175,11 @@ export default {
 };
 `;
 }
-/** The user-global machine context path: ~/.config/conductor/conductor.config.machine.js */
-export function machineContextPath() {
-    return join(process.env.HOME ?? '', '.config', 'conductor', 'conductor.config.machine.js');
-}
-/** Import an existing context module's default export, or {} if absent/broken. */
-export async function readMachineContext(path) {
-    if (!existsSync(path))
-        return {};
-    try {
-        // Cache-bust so a re-render within one process re-reads fresh.
-        const mod = await import(`${pathToFileURL(path).href}?t=${Date.now()}`);
-        const raw = mod.default;
-        return raw && typeof raw === 'object'
-            ? raw
-            : {};
-    }
-    catch {
-        return {};
-    }
-}
 /**
  * Create-if-missing / fill-only-missing the user-global machine context.
  * Existing values always win; only absent/blank keys are filled. machine_id
- * defaults to hostname(). A no-op (no rewrite) when the file is already complete.
- * The file is written user-only (chmod 0600) since it holds the client secret.
+ * defaults to hostname(). Written user-only (chmod 0600) since it holds the
+ * client secret.
  */
 export async function scaffoldMachineContext(opts) {
     const existing = await readMachineContext(opts.path);
@@ -196,20 +210,28 @@ export async function scaffoldMachineContext(opts) {
         mkdirSync(dirname(opts.path), { recursive: true });
         writeFileSync(opts.path, renderMachineContext(merged), 'utf8');
     }
-    // Always tighten perms — the file holds a secret.
     if (existsSync(opts.path))
         chmodSync(opts.path, 0o600);
     return { path: opts.path, created, filledKeys };
 }
+/** Write the sibling connection config `gaia.config.js` next to the engine
+ *  config. Created only if missing (unless `force`). Returns its path + whether
+ *  it was written. */
+export function scaffoldGaiaConfig(engineConfigPath, force) {
+    const path = join(dirname(engineConfigPath), 'gaia.config.js');
+    mkdirSync(dirname(path), { recursive: true });
+    if (!existsSync(path) || force) {
+        writeFileSync(path, renderGaiaConfig(), 'utf8');
+        return { path, wrote: true };
+    }
+    return { path, wrote: false };
+}
 /**
- * Scaffold the two conductor config files: the committed conductor.config.js
- * (created only if missing — never overwritten unless `force`) and the
- * user-global machine context (create-if-missing / fill-only-missing). The
- * optional per-project conductor.config.local.js is NOT generated.
- *
- * `skipMachine` writes the committed config only (project-only setup); its
- * mirror `skipCommitted` writes the machine context only (machine-only
- * onboarding, no repo). Setting both is a no-op.
+ * Scaffold the committed ENGINE conductor.config.js (created only if missing —
+ * never overwritten unless `force`) and the user-global machine context
+ * (create-if-missing / fill-only-missing). The connection config is scaffolded
+ * separately by `scaffoldGaiaConfig`. `skipMachine` writes the committed config
+ * only; `skipCommitted` writes the machine context only.
  */
 export async function scaffold(inputs, opts) {
     const committedPath = opts.configPath;