@gaia-ai/ui 0.6.0 → 0.6.2

package/README.md

@@ -1,5 +1,5 @@
 # @gaia-ai/ui
 
-GAIA home-rooted cockpit: the `gaia ui` command plugin (renderer resolved dynamically).
+GAIA project-first cockpit: the `gaia ui` command plugin (renderer resolved dynamically).
 
-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/index.d.ts

@@ -1,2 +1,3 @@
+export { type HereContext, isTicketIdentifier, isUuid, normalizeRepoUrl, type ParsedTarget, parseTarget, parseTicketIdentifierFromBranch, resolveHere, type TargetInputs, UI_VIEW_MODES, type UiInitialRoute, type UiViewMode, } from './route.js';
 export { cmdUi, default, type RunGaiaUiOptions, type UiDeps } from './ui.js';
-export { buildHomeConnection, type HomeConnection, resolveAgentCommand, resolveDefaultProject, resolveUiConfigPath, } from './ui-home.js';
+export { type HomeConnection, type ProjectRooting, resolveAgentCommand, resolveDefaultProject, resolveProjectRooting, } from './ui-home.js';

package/dist/src/index.js

@@ -1,5 +1,10 @@
-// GAIA-201: `@gaia-ai/ui` — the home-rooted `gaia ui` command plugin. The
-// default export is the `GaiaCommandPlugin` the host mounts; `cmdUi` + the
-// home-connection builders are exported for tests.
+// GAIA-201 / GAIA-219: `@gaia-ai/ui` — the `gaia ui` command plugin. Its
+// connection is resolved by core's `loadGaiaConfig` (explicit → project
+// walk-up → home → shipped fallback), so running it inside a project uses that
+// project's control plane; this package owns no precedence rule of its own.
+// The default export is the `GaiaCommandPlugin` the host mounts; `cmdUi` + the
+// bootstrap helpers are exported for tests.
+// GAIA-223: the deep-link grammar (the pure CLI seam).
+export { isTicketIdentifier, isUuid, normalizeRepoUrl, parseTarget, parseTicketIdentifierFromBranch, resolveHere, UI_VIEW_MODES, } from './route.js';
 export { cmdUi, default } from './ui.js';
-export { buildHomeConnection, resolveAgentCommand, resolveDefaultProject, resolveUiConfigPath, } from './ui-home.js';
+export { resolveAgentCommand, resolveDefaultProject, resolveProjectRooting, } from './ui-home.js';

package/dist/src/route.d.ts

@@ -0,0 +1,115 @@
+/** How a ticket target is rendered. Mirrors the Drupal `gaia_ticket` view modes. */
+export type UiViewMode = 'full' | 'teaser' | 'board_card';
+/** The known `--view` modes, in the order error messages list them. */
+export declare const UI_VIEW_MODES: readonly UiViewMode[];
+/**
+ * A deep-link target as the CLI understands it — *unresolved*: it says what to
+ * look up and how, never what screen results. Crosses both package boundaries
+ * (`RunGaiaUiOptions` → `GaiaUiLauncherOptions` → `TuiOptions`) and is mirrored
+ * structurally in the renderer, per the `HomeConnection` precedent (Finding 6).
+ */
+export interface UiInitialRoute {
+    kind: 'ticket' | 'project' | 'run';
+    /**
+     * How `value` must be looked up. `'repo'` is the `--here` project rung: the
+     * value is a NORMALISED remote URL (`host/path`), matched client-side against
+     * every `gaia_project.repos[].url` (spec Decision 3).
+     */
+    by: 'uuid' | 'identifier' | 'name' | 'repo';
+    value: string;
+    /** Drupal view mode for a ticket target; default 'full'. */
+    view?: UiViewMode | undefined;
+    /** Set when the target came from `--here`; error messages only. */
+    fromBranch?: string | undefined;
+}
+/** The raw argv inputs `parseTarget` reads (commander's parsed options). */
+export interface TargetInputs {
+    target?: string | undefined;
+    ticket?: string | undefined;
+    project?: string | undefined;
+    run?: string | undefined;
+    here?: boolean | undefined;
+    view?: string | undefined;
+}
+/**
+ * What the grammar made of the argv: nothing (the dashboard), a `--here`
+ * request that still needs the ladder walked, or a finished route.
+ */
+export type ParsedTarget = {
+    kind: 'here';
+    view?: UiViewMode | undefined;
+} | {
+    kind: 'route';
+    route: UiInitialRoute;
+};
+/** True for an `8-4-4-4-12` hex UUID (case-insensitive). */
+export declare function isUuid(value: string): boolean;
+/** True for a `KEY-123` ticket identifier (case-insensitive). */
+export declare function isTicketIdentifier(value: string): boolean;
+/**
+ * The ticket identifier a branch name carries, uppercased, or `null`.
+ * Pure and offline — the `--here` ticket rung never needs the network.
+ */
+export declare function parseTicketIdentifierFromBranch(branch: string): string | null;
+/**
+ * The grammar: at most ONE target source (the positional, `--ticket`,
+ * `--project`, `--run`, `--here`) plus the orthogonal `--view` modifier.
+ *
+ * Returns `undefined` for no target at all (the dashboard, AC-4), `{kind:'here'}`
+ * when the ladder still has to be walked, else the finished route. Throws — with
+ * a message naming exactly what went wrong — on a conflict or an unparseable
+ * form; the caller turns that into a stderr line and exit 1 before any network
+ * work happens.
+ */
+export declare function parseTarget(inputs: TargetInputs): ParsedTarget | undefined;
+/**
+ * A git remote URL reduced to a comparable `host/path` identity: scheme,
+ * userinfo, port and a trailing `.git` (and trailing slashes) dropped, the whole
+ * thing lowercased. Returns `undefined` for anything that carries no host+path.
+ *
+ * This is REQUIRED, not cosmetic (spec Decision 3): git and the control plane
+ * disagree on form. Measured in this repo — `git remote get-url origin` yields
+ * `git@git.key-tec.de:keytec/gaia.git` while `gaia_project.repos[].url` holds
+ * `ssh://git@git.key-tec.de/keytec/gaia.git`. Both must reduce to
+ * `git.key-tec.de/keytec/gaia` or the `--here` project rung never matches.
+ *
+ * | raw                                     | normalised          |
+ * |-----------------------------------------|---------------------|
+ * | `git@host:keytec/gaia.git`              | `host/keytec/gaia`  |
+ * | `ssh://git@host/keytec/gaia.git`        | `host/keytec/gaia`  |
+ * | `ssh://git@host:2222/keytec/gaia.git`   | `host/keytec/gaia`  |
+ * | `https://host/keytec/gaia.git`          | `host/keytec/gaia`  |
+ */
+export declare function normalizeRepoUrl(raw: string | undefined): string | undefined;
+/** Everything `resolveHere` needs, all injected — two git reads, nothing else. */
+export interface HereContext {
+    cwd: string;
+    view?: UiViewMode | undefined;
+    /** The current branch of `cwd` (git resolves it per worktree). May reject. */
+    readBranch: (cwd: string) => Promise<string>;
+    /**
+     * The cwd's `origin` remote URL, raw. Git resolves it per worktree too, and a
+     * worktree shares its main clone's remote — which is exactly the right answer
+     * (spec Decision 3). May reject (not a repo, no `origin`).
+     */
+    readRemoteUrl: (cwd: string) => Promise<string>;
+}
+/**
+ * `--here`: derive the target from the cwd (spec Decision 3).
+ *
+ * ```
+ * branch carries a ticket identifier?  → that TICKET   (feat/gaia-223-… → GAIA-223)
+ * else: the cwd's git remote           → the PROJECT(s) whose repos[] claim it
+ * else                                 → a named error
+ * ```
+ *
+ * The BRANCH decides the first rung, not git mechanics: a worktree on a
+ * non-ticket branch and the main clone on a ticket branch both come out right.
+ *
+ * The project rung stops HERE at a normalised repo identity — matching it
+ * against `gaia_project.repos[]` needs a JSON:API client, which the entry does
+ * not have (Finding 1), so `by: 'repo'` travels to the renderer's `resolveRoute`
+ * and the ambiguity ruling (one match / a picker / an error) is made there
+ * (Decisions 5 + 14).
+ */
+export declare function resolveHere(ctx: HereContext): Promise<UiInitialRoute>;

package/dist/src/route.js

@@ -0,0 +1,264 @@
+// GAIA-223: the pure CLI seam of `gaia ui` deep links.
+//
+// This module owns the *grammar* — argv in, an unresolved `UiInitialRoute` out —
+// and the `--here` ladder. It performs no I/O of its own: git, the filesystem
+// and the conductor registry all enter through injected seams, so the whole
+// grammar is testable offline and a conflict/parse failure costs no network
+// round-trip (spec Decisions 1, 3, 4, 6, 13).
+//
+// Resolving a route against the control plane is deliberately NOT here: the
+// entry has no JSON:API client (spec Finding 1). That happens in the renderer,
+// in `@gaia-ai/addon-gaia-ui`'s `resolveRoute`, still before the TUI takes the
+// terminal (spec Decision 5).
+/** The known `--view` modes, in the order error messages list them. */
+export const UI_VIEW_MODES = [
+    'full',
+    'teaser',
+    'board_card',
+];
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** `<project-key>-<number>`, case-insensitive (Decision 4). One dash only, so a
+ *  UUID can never match it. */
+const IDENTIFIER_RE = /^[A-Za-z][A-Za-z0-9]*-\d+$/;
+/**
+ * The ticket identifier carried by a branch name, first match wins. Every
+ * convention places the identifier before the title slug and `capBranchName()`
+ * never truncates it (Finding 3), so the first match is the right one.
+ */
+const BRANCH_IDENTIFIER_RE = /(?:^|[/_-])([A-Za-z][A-Za-z0-9]*-\d+)(?=$|[/_-])/;
+const ACCEPTED_FORMS = "accepted forms: GAIA-221 (a ticket identifier), 'ticket:<id|uuid>', " +
+    "'project:<name|uuid>', 'run:<uuid>'";
+/** True for an `8-4-4-4-12` hex UUID (case-insensitive). */
+export function isUuid(value) {
+    return UUID_RE.test(value);
+}
+/** True for a `KEY-123` ticket identifier (case-insensitive). */
+export function isTicketIdentifier(value) {
+    return IDENTIFIER_RE.test(value);
+}
+/**
+ * The ticket identifier a branch name carries, uppercased, or `null`.
+ * Pure and offline — the `--here` ticket rung never needs the network.
+ */
+export function parseTicketIdentifierFromBranch(branch) {
+    const match = BRANCH_IDENTIFIER_RE.exec(branch);
+    return match?.[1] ? match[1].toUpperCase() : null;
+}
+/** Validate a raw `--view` value against the known modes. */
+function parseViewMode(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (UI_VIEW_MODES.includes(raw)) {
+        return raw;
+    }
+    throw new Error(`gaia ui: unknown --view mode '${raw}'. Known modes: ${UI_VIEW_MODES.join(', ')}.`);
+}
+/** A ticket target from a raw value: a UUID by id, else an identifier by name. */
+function ticketTarget(value) {
+    if (isUuid(value))
+        return { kind: 'ticket', by: 'uuid', value };
+    if (isTicketIdentifier(value)) {
+        return { kind: 'ticket', by: 'identifier', value: value.toUpperCase() };
+    }
+    throw new Error(`gaia ui: '${value}' is not a ticket identifier or UUID — ${ACCEPTED_FORMS}.`);
+}
+/** A project target: a UUID by id, else the label verbatim (labels are
+ *  case-sensitive Drupal entity labels — Decision 4). */
+function projectTarget(value) {
+    return isUuid(value)
+        ? { kind: 'project', by: 'uuid', value }
+        : { kind: 'project', by: 'name', value };
+}
+/** A run target — UUIDs only; there is no human-readable run handle. */
+function runTarget(value) {
+    if (!isUuid(value)) {
+        throw new Error(`gaia ui: a run target must be a UUID, got '${value}'.`);
+    }
+    return { kind: 'run', by: 'uuid', value };
+}
+/** Parse the positional form: an optional `kind:` prefix, else a bare identifier. */
+function parsePositional(raw) {
+    const colon = raw.indexOf(':');
+    if (colon >= 0) {
+        const prefix = raw.slice(0, colon);
+        const value = raw.slice(colon + 1);
+        if (prefix !== 'ticket' && prefix !== 'project' && prefix !== 'run') {
+            throw new Error(`gaia ui: unknown target kind '${prefix}'. ` +
+                "Known kinds: 'ticket:', 'project:', 'run:'.");
+        }
+        if (value === '') {
+            throw new Error(`gaia ui: '${raw}' has an empty value — ${ACCEPTED_FORMS}.`);
+        }
+        if (prefix === 'ticket')
+            return ticketTarget(value);
+        if (prefix === 'project')
+            return projectTarget(value);
+        return runTarget(value);
+    }
+    // Bare: strictly a ticket identifier. A UUID is ambiguous by construction —
+    // it does not say which kind — and never guessed (Decision 1).
+    if (isUuid(raw)) {
+        throw new Error(`gaia ui: '${raw}' is ambiguous — a bare UUID does not say which kind. ` +
+            "Use 'ticket:<uuid>', 'project:<uuid>' or 'run:<uuid>'.");
+    }
+    return ticketTarget(raw);
+}
+/**
+ * The grammar: at most ONE target source (the positional, `--ticket`,
+ * `--project`, `--run`, `--here`) plus the orthogonal `--view` modifier.
+ *
+ * Returns `undefined` for no target at all (the dashboard, AC-4), `{kind:'here'}`
+ * when the ladder still has to be walked, else the finished route. Throws — with
+ * a message naming exactly what went wrong — on a conflict or an unparseable
+ * form; the caller turns that into a stderr line and exit 1 before any network
+ * work happens.
+ */
+export function parseTarget(inputs) {
+    const supplied = [];
+    if (inputs.target !== undefined && inputs.target !== '') {
+        supplied.push(`the positional target '${inputs.target}'`);
+    }
+    if (inputs.ticket !== undefined)
+        supplied.push('--ticket');
+    if (inputs.project !== undefined)
+        supplied.push('--project');
+    if (inputs.run !== undefined)
+        supplied.push('--run');
+    if (inputs.here === true)
+        supplied.push('--here');
+    if (supplied.length > 1) {
+        throw new Error(`gaia ui: conflicting targets — ${supplied.join(', ')} were all supplied. ` +
+            'Give at most one of: a positional target, --ticket, --project, --run, --here.');
+    }
+    const view = parseViewMode(inputs.view);
+    if (supplied.length === 0)
+        return undefined;
+    if (inputs.here === true) {
+        return { kind: 'here', view: view ?? 'full' };
+    }
+    const target = inputs.target !== undefined && inputs.target !== ''
+        ? parsePositional(inputs.target)
+        : inputs.ticket !== undefined
+            ? ticketTarget(inputs.ticket)
+            : inputs.project !== undefined
+                ? projectTarget(inputs.project)
+                : runTarget(inputs.run);
+    // `--view` describes how a TICKET renders. A project screen has no view mode,
+    // and `run:` already means "the ticket's Runs tab", so pairing it with a
+    // compact block is contradictory rather than resolvable (Decision 13).
+    if (view !== undefined && target.kind === 'project') {
+        throw new Error('gaia ui: --view applies to ticket targets only, but the target is a project. ' +
+            'Drop --view, or name a ticket.');
+    }
+    if (view !== undefined && target.kind === 'run') {
+        throw new Error("gaia ui: --view cannot be combined with a 'run:' target — 'run:' already " +
+            "means the owning ticket's Runs tab. Use 'ticket:<id> --view <mode>' instead.");
+    }
+    return {
+        kind: 'route',
+        route: target.kind === 'project' ? target : { ...target, view: view ?? 'full' },
+    };
+}
+/**
+ * A git remote URL reduced to a comparable `host/path` identity: scheme,
+ * userinfo, port and a trailing `.git` (and trailing slashes) dropped, the whole
+ * thing lowercased. Returns `undefined` for anything that carries no host+path.
+ *
+ * This is REQUIRED, not cosmetic (spec Decision 3): git and the control plane
+ * disagree on form. Measured in this repo — `git remote get-url origin` yields
+ * `git@git.key-tec.de:keytec/gaia.git` while `gaia_project.repos[].url` holds
+ * `ssh://git@git.key-tec.de/keytec/gaia.git`. Both must reduce to
+ * `git.key-tec.de/keytec/gaia` or the `--here` project rung never matches.
+ *
+ * | raw                                     | normalised          |
+ * |-----------------------------------------|---------------------|
+ * | `git@host:keytec/gaia.git`              | `host/keytec/gaia`  |
+ * | `ssh://git@host/keytec/gaia.git`        | `host/keytec/gaia`  |
+ * | `ssh://git@host:2222/keytec/gaia.git`   | `host/keytec/gaia`  |
+ * | `https://host/keytec/gaia.git`          | `host/keytec/gaia`  |
+ */
+export function normalizeRepoUrl(raw) {
+    const trimmed = (raw ?? '').trim();
+    if (trimmed === '')
+        return undefined;
+    let host;
+    let path;
+    // `scheme://[user@]host[:port]/path` — checked FIRST, so an `ssh://…:2222/…`
+    // port is never mistaken for the scp form's `host:path` colon.
+    const withScheme = /^[A-Za-z][A-Za-z0-9+.-]*:\/\/(.+)$/.exec(trimmed);
+    if (withScheme?.[1] !== undefined) {
+        const rest = withScheme[1];
+        const slash = rest.indexOf('/');
+        if (slash < 0)
+            return undefined;
+        host = rest.slice(0, slash);
+        path = rest.slice(slash + 1);
+    }
+    else {
+        // The scp-like form `[user@]host:path` — what `git remote get-url` emits
+        // for an ssh clone. A bare local path has no colon and falls out here.
+        const scp = /^(?:[^/@]+@)?([^/:]+):(.+)$/.exec(trimmed);
+        if (scp?.[1] === undefined || scp[2] === undefined)
+            return undefined;
+        host = scp[1];
+        path = scp[2];
+    }
+    host = host
+        .replace(/^[^@]*@/, '')
+        .replace(/:\d+$/, '')
+        .toLowerCase();
+    path = path
+        .replace(/^\/+/, '')
+        .replace(/\/+$/, '')
+        .replace(/\.git$/i, '')
+        .replace(/\/+$/, '')
+        .toLowerCase();
+    if (host === '' || path === '')
+        return undefined;
+    return `${host}/${path}`;
+}
+/**
+ * `--here`: derive the target from the cwd (spec Decision 3).
+ *
+ * ```
+ * branch carries a ticket identifier?  → that TICKET   (feat/gaia-223-… → GAIA-223)
+ * else: the cwd's git remote           → the PROJECT(s) whose repos[] claim it
+ * else                                 → a named error
+ * ```
+ *
+ * The BRANCH decides the first rung, not git mechanics: a worktree on a
+ * non-ticket branch and the main clone on a ticket branch both come out right.
+ *
+ * The project rung stops HERE at a normalised repo identity — matching it
+ * against `gaia_project.repos[]` needs a JSON:API client, which the entry does
+ * not have (Finding 1), so `by: 'repo'` travels to the renderer's `resolveRoute`
+ * and the ambiguity ruling (one match / a picker / an error) is made there
+ * (Decisions 5 + 14).
+ */
+export async function resolveHere(ctx) {
+    const branch = await ctx.readBranch(ctx.cwd).then((b) => b.trim(), () => '');
+    const identifier = branch === '' ? null : parseTicketIdentifierFromBranch(branch);
+    if (identifier !== null) {
+        return {
+            kind: 'ticket',
+            by: 'identifier',
+            value: identifier,
+            view: ctx.view ?? 'full',
+            fromBranch: branch,
+        };
+    }
+    const remote = await ctx.readRemoteUrl(ctx.cwd).then((r) => r.trim(), () => '');
+    const repo = normalizeRepoUrl(remote);
+    if (repo === undefined) {
+        const got = remote === '' ? '' : `, got '${remote}'`;
+        throw new Error(`gaia ui --here: could not derive a project from '${ctx.cwd}' — ` +
+            `no usable git remote (looked at 'origin'${got}).\n` +
+            "  Run 'gaia ui' for the dashboard, or 'gaia ui project:<name>' to open one directly.");
+    }
+    return {
+        kind: 'project',
+        by: 'repo',
+        value: repo,
+        ...(branch !== '' ? { fromBranch: branch } : {}),
+    };
+}

package/dist/src/ui-home.d.ts

@@ -1,7 +1,7 @@
 import { type ConductorRegistryEntry, type MachineContext } from '@gaia-ai/core';
 /**
- * The resolved home control-plane connection passed to the renderer launcher.
- * A structural mirror of `@gaia-ai/plugin-gaia-ui`'s `HomeConnection` — kept
+ * The resolved control-plane connection passed to the renderer launcher.
+ * A structural mirror of `@gaia-ai/addon-gaia-ui`'s `HomeConnection` — kept
  * local so this package needs NO compile-time dependency on the renderer (it
  * resolves the renderer dynamically, ESLint-style, at runtime).
  */
@@ -12,30 +12,6 @@ export interface HomeConnection {
     configPath?: string | undefined;
     authProfile?: string | undefined;
 }
-/** The `session` oauth2 client-credentials descriptor, matching the connection
- *  config template shape exactly so home reads authenticate identically to a
- *  project-rooted `gaia dropsh`. */
-export interface SessionAuthDescriptor {
-    plugin: '@dropsh/plugin-oauth2';
-    export: 'oauth2Plugin';
-    with: {
-        id: 'session';
-        default: true;
-        type: 'oauth2_client_credentials';
-        client_id: string;
-        client_secret: string;
-        token_url: string;
-        scope: 'gaia:session';
-    };
-}
-/**
- * Build the home control-plane connection from the machine context. Throws an
- * actionable error when the context is missing `base_url` / `client_id` /
- * `client_secret` (there is no project config to fall back to). The returned
- * `authPlugins` carries a single `session` oauth2 descriptor; `configPath` is
- * filled in by the entry once it has resolved the connection config file.
- */
-export declare function buildHomeConnection(machine: Partial<MachineContext>): HomeConnection;
 /**
  * Resolve the default project (opaque group) from the conductor registry: the
  * `preferred` project when it is registered, else the first entry's project.
@@ -51,15 +27,38 @@ export declare function resolveDefaultProject(entries: ConductorRegistryEntry[],
 export declare function resolveAgentCommand(machine: Partial<MachineContext> & {
     agent_command?: string;
 }): (prompt: string) => string;
+/** Where `gaia ui` roots the agents it launches, and which project they belong to. */
+export interface ProjectRooting {
+    cwd: string;
+    project?: string | undefined;
+    ownConductorMachineId?: string | undefined;
+}
 /**
- * Resolve which connection config `gaia ui` reads. A user-authored home
- * `~/.gaia/gaia.config.js` (`userConfigPath`) wins — a real home-level cockpit
- * connection — used verbatim (`fallback: false`). Otherwise the shipped
- * machine-context fallback (`fallbackPath`) is used (`fallback: true`), which
- * requires a complete machine context. Pure: the caller does the
- * `$DROPSH_CONFIG` / `$GAIA_MACHINE_CONTEXT` wiring.
+ * Decide the agents' working directory + project (GAIA-219 AC-9).
+ *
+ * The trigger is the **cwd**, deliberately not the winning connection config:
+ * "which connection did we resolve" and "which project am I standing in" are
+ * different questions, and binding them would let an explicit `--config`
+ * silently relocate the agents' working directory.
+ *
+ * Standing **in** a project (core's walk-up finds a `.gaia/` project dir that
+ * is not the user's own `~/.gaia`), the cwd is that repo's **root** and the
+ * matching registry entry supplies the project + machine id; a project with no
+ * registry entry still roots at its repo root. Otherwise the registry default
+ * applies verbatim, exactly as before this ticket.
+ *
+ * The marker is core's `findProjectGaiaDir` — "is there a `.gaia/` here" —
+ * NOT the connection walk-up `findGaiaConfig`. Since GAIA-230 the latter skips
+ * an engine-only `conductor.config.js`, which GAIA-218 makes the canonical repo
+ * shape, so keying on it would leave the most common project rooted in the
+ * registry default. Which connection won and which project we stand in stay two
+ * separate questions, as this function's whole point requires.
+ *
+ * `~/.gaia` is excluded for the same reason core labels it `home`: the walk-up
+ * reaches it from every directory under `$HOME`, so counting it would make
+ * every such directory look like "a project rooted at `$HOME`".
+ *
+ * Pure with respect to precedence — the walk-up is core's; this helper owns no
+ * filesystem probe of its own.
  */
-export declare function resolveUiConfigPath(userConfigPath: string, fallbackPath: string): {
-    path: string;
-    fallback: boolean;
-};
+export declare function resolveProjectRooting(cwd: string, entries: ConductorRegistryEntry[], homeDir: string): ProjectRooting;

package/dist/src/ui-home.js

@@ -1,51 +1,10 @@
-// GAIA-201 (was GAIA-194): home-rooted bootstrap builders for `gaia ui`. Pure
-// functions that turn the user-global machine context (identity + connection) +
-// the conductor registry into everything `runGaiaUi` needs — WITHOUT a project
-// engine `conductor.config.js`. The `gaia ui` entry (`ui.ts`) wires them.
-import { existsSync } from 'node:fs';
-import { shellQuote, } from '@gaia-ai/core';
-/**
- * Build the home control-plane connection from the machine context. Throws an
- * actionable error when the context is missing `base_url` / `client_id` /
- * `client_secret` (there is no project config to fall back to). The returned
- * `authPlugins` carries a single `session` oauth2 descriptor; `configPath` is
- * filled in by the entry once it has resolved the connection config file.
- */
-export function buildHomeConnection(machine) {
-    const baseUrl = (machine.base_url ?? '').trim();
-    const clientId = (machine.client_id ?? '').trim();
-    const clientSecret = (machine.client_secret ?? '').trim();
-    const missing = [];
-    if (baseUrl === '')
-        missing.push('base_url');
-    if (clientId === '')
-        missing.push('client_id');
-    if (clientSecret === '')
-        missing.push('client_secret');
-    if (missing.length > 0) {
-        throw new Error(`gaia ui: the machine context is missing ${missing.join(', ')} — ` +
-            `run 'gaia conductor init --base-url <url>' to onboard this machine.`);
-    }
-    const descriptor = {
-        plugin: '@dropsh/plugin-oauth2',
-        export: 'oauth2Plugin',
-        with: {
-            id: 'session',
-            default: true,
-            type: 'oauth2_client_credentials',
-            client_id: clientId,
-            client_secret: clientSecret,
-            token_url: `${baseUrl}/oauth/token`,
-            scope: 'gaia:session',
-        },
-    };
-    return {
-        baseUrl,
-        jsonapiPrefix: '/jsonapi',
-        authPlugins: [descriptor],
-        authProfile: 'session',
-    };
-}
+// GAIA-201 (was GAIA-194), GAIA-219: bootstrap builders for `gaia ui`. Pure
+// functions that turn the machine context (identity), the conductor registry
+// and the cwd into everything `runGaiaUi` needs. The CONNECTION itself is not
+// built here — `ui.ts` asks core's `loadGaiaConfig` for it, so this package
+// holds no connection-precedence rule of its own (AC-6).
+import { dirname, resolve } from 'node:path';
+import { findProjectGaiaDir, homeGaiaDir, shellQuote, } from '@gaia-ai/core';
 /**
  * Resolve the default project (opaque group) from the conductor registry: the
  * `preferred` project when it is registered, else the first entry's project.
@@ -68,15 +27,52 @@ export function resolveAgentCommand(machine) {
     return (prompt) => prompt.trim() === '' ? bin : `${bin} ${shellQuote(prompt)}`;
 }
 /**
- * Resolve which connection config `gaia ui` reads. A user-authored home
- * `~/.gaia/gaia.config.js` (`userConfigPath`) wins — a real home-level cockpit
- * connection — used verbatim (`fallback: false`). Otherwise the shipped
- * machine-context fallback (`fallbackPath`) is used (`fallback: true`), which
- * requires a complete machine context. Pure: the caller does the
- * `$DROPSH_CONFIG` / `$GAIA_MACHINE_CONTEXT` wiring.
+ * Decide the agents' working directory + project (GAIA-219 AC-9).
+ *
+ * The trigger is the **cwd**, deliberately not the winning connection config:
+ * "which connection did we resolve" and "which project am I standing in" are
+ * different questions, and binding them would let an explicit `--config`
+ * silently relocate the agents' working directory.
+ *
+ * Standing **in** a project (core's walk-up finds a `.gaia/` project dir that
+ * is not the user's own `~/.gaia`), the cwd is that repo's **root** and the
+ * matching registry entry supplies the project + machine id; a project with no
+ * registry entry still roots at its repo root. Otherwise the registry default
+ * applies verbatim, exactly as before this ticket.
+ *
+ * The marker is core's `findProjectGaiaDir` — "is there a `.gaia/` here" —
+ * NOT the connection walk-up `findGaiaConfig`. Since GAIA-230 the latter skips
+ * an engine-only `conductor.config.js`, which GAIA-218 makes the canonical repo
+ * shape, so keying on it would leave the most common project rooted in the
+ * registry default. Which connection won and which project we stand in stay two
+ * separate questions, as this function's whole point requires.
+ *
+ * `~/.gaia` is excluded for the same reason core labels it `home`: the walk-up
+ * reaches it from every directory under `$HOME`, so counting it would make
+ * every such directory look like "a project rooted at `$HOME`".
+ *
+ * Pure with respect to precedence — the walk-up is core's; this helper owns no
+ * filesystem probe of its own.
  */
-export function resolveUiConfigPath(userConfigPath, fallbackPath) {
-    return existsSync(userConfigPath)
-        ? { path: userConfigPath, fallback: false }
-        : { path: fallbackPath, fallback: true };
+export function resolveProjectRooting(cwd, entries, homeDir) {
+    const gaiaDir = findProjectGaiaDir(cwd);
+    // Core owns where `.gaia` lives; the ui never spells the path itself.
+    const homeDotGaia = resolve(homeGaiaDir(homeDir));
+    if (gaiaDir !== undefined && resolve(gaiaDir) !== homeDotGaia) {
+        // Registry entries store the `.gaia` dir (the conductor's checkoutRoot),
+        // so that — not the repo root — is what an entry is matched on.
+        const entry = entries.find((e) => resolve(e.path) === resolve(gaiaDir));
+        return {
+            cwd: dirname(gaiaDir),
+            project: entry?.project,
+            ownConductorMachineId: entry?.id,
+        };
+    }
+    const project = resolveDefaultProject(entries);
+    const projectEntry = entries.find((e) => e.project === project);
+    return {
+        cwd: projectEntry?.path ?? homeDir,
+        project,
+        ownConductorMachineId: projectEntry?.id,
+    };
 }

package/dist/src/ui.d.ts

@@ -1,5 +1,6 @@
-import { type ConductorRegistryEntry, type GaiaCommandHost, type GaiaCommandPlugin, type MachineContext } from '@gaia-ai/core';
-import { type AgentLaunchHost } from '@gaia-ai/plugin-herdr';
+import { type AgentLaunchHost } from '@gaia-ai/addon-herdr';
+import { type ConductorRegistryEntry, type GaiaCommandHost, type GaiaCommandPlugin, type GaiaConnectionConfig, type MachineContext } from '@gaia-ai/core';
+import { type UiInitialRoute } from './route.js';
 import { type HomeConnection } from './ui-home.js';
 /** Prompt-level agent service the renderer consumes (mirror of gaia-ui's `TuiAgentService`). */
 interface TuiAgentService {
@@ -43,6 +44,9 @@ export interface RunGaiaUiOptions {
         plugins: unknown[];
     }) => DropshProgram;
     renderer?: ((opts: unknown) => unknown) | undefined;
+    /** GAIA-223: the deep-link target, still UNRESOLVED (the entry has no JSON:API
+     *  client — Finding 1). Absent ⇒ the renderer boots its dashboard (AC-4). */
+    initialRoute?: UiInitialRoute | undefined;
 }
 /** Test/composition seams for `gaia ui`. */
 export interface UiDeps {
@@ -54,18 +58,49 @@ export interface UiDeps {
     agentHost?: AgentLaunchHost;
     /** The renderer launcher; default: the dynamically-resolved `runGaiaUi`. */
     runUi?: (opts: RunGaiaUiOptions) => Promise<void>;
-    /** Pre-resolved home connection config path; default: resolved from ~/.gaia or the shipped fallback. */
-    homeConfigPath?: string;
     /** Host contract (resolveBases) for renderer resolution; default: cwd + this install. */
     host?: GaiaCommandHost;
+    /** Explicit connection config (`--config`); beats project + home (AC-4). */
+    explicitConfig?: string;
+    /** Where the resolution + the rooting start; default: `process.cwd()`. */
+    cwd?: string;
+    /** Connection loader; default: core's `loadGaiaConfig` (the ONE rule). */
+    loadConnection?: (host: GaiaCommandHost, opts: {
+        cwd?: string;
+        explicit?: string | undefined;
+    }) => Promise<GaiaConnectionConfig>;
+    /** Print the resolved connection and exit without launching the TUI (AC-7). */
+    printConfig?: boolean;
+    /** Sink for `--print-config`; default: `process.stdout.write`. */
+    stdout?: (s: string) => void;
+    /** Positional `[target]` (`GAIA-221`, `ticket:…`, `project:…`, `run:…`). */
+    target?: string | undefined;
+    /** `--ticket <id>`. */
+    ticket?: string | undefined;
+    /** `--project <id>`. */
+    project?: string | undefined;
+    /** `--run <uuid>`. */
+    run?: string | undefined;
+    /** `--here` — derive the target from the cwd (Decision 3). */
+    here?: boolean | undefined;
+    /** `--view <mode>` — how a ticket target renders (Decision 13). */
+    view?: string | undefined;
+    /** Current git branch of a dir; default `git branch --show-current`. */
+    readBranch?: (cwd: string) => Promise<string>;
+    /** The dir's `origin` remote URL; default `git remote get-url origin`. */
+    readRemoteUrl?: (cwd: string) => Promise<string>;
+    /** Where user-facing grammar errors go; default `process.stderr`. */
+    stderr?: (line: string) => void;
 }
 /**
- * `gaia ui` — launch the home-rooted interactive terminal UI. Reads the
- * user-global machine context + the conductor registry (NOT a project engine
- * config), resolves the connection from the home `gaia.config.js` scope, adapts
- * a herdr-backed agent host to the renderer's prompt-level service, and
- * delegates to `@gaia-ai/plugin-gaia-ui`'s `runGaiaUi`. `$GAIA_UI_PLUGIN`
- * overrides the renderer module (dev).
+ * `gaia ui` — launch the interactive terminal UI. Resolves the connection
+ * through core's `loadGaiaConfig` (explicit → project walk-up → home → shipped
+ * fallback), roots the agents in the project it was started in, reads the
+ * machine context for identity + the agent binary, adapts a herdr-backed agent
+ * host to the renderer's prompt-level service, and delegates to
+ * `@gaia-ai/addon-gaia-ui`'s `runGaiaUi`. `--print-config` reports the
+ * resolution and exits without launching. `$GAIA_UI_PLUGIN` overrides the
+ * renderer module (dev).
  */
 export declare function cmdUi(deps?: UiDeps): Promise<void>;
 /** The `ui` command plugin the host mounts (`gaia ui`). */

package/dist/src/ui.js

@@ -1,18 +1,87 @@
 import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { CommandRunner, createLogger, exec, homeFallbackGaiaConfigPath, listRegisteredConductors, machineContextPath, readMachineContext, setDefaultCommandRunner, } from '@gaia-ai/core';
-import { herdrAgentHost } from '@gaia-ai/plugin-herdr';
+import { herdrAgentHost } from '@gaia-ai/addon-herdr';
+import { CommandRunner, createLogger, exec, listRegisteredConductors, loadGaiaConfig, machineContextPath, readMachineContext, setDefaultCommandRunner, } from '@gaia-ai/core';
 import { buildProgram as buildDropshProgram } from 'dropsh';
-import { buildHomeConnection, resolveAgentCommand, resolveDefaultProject, resolveUiConfigPath, } from './ui-home.js';
+import { parseTarget, resolveHere, UI_VIEW_MODES, } from './route.js';
+import { resolveAgentCommand, resolveProjectRooting, } from './ui-home.js';
+/**
+ * The current branch of `cwd`. Git resolves this PER WORKTREE, so
+ * worktree-awareness for `--here` costs nothing (Decision 3). Never throws:
+ * outside a repo, or on a detached HEAD, it yields '' and the ladder falls
+ * through to its project rung.
+ */
+async function readCurrentBranch(cwd) {
+    try {
+        const out = await exec('git', ['branch', '--show-current'], { cwd });
+        return typeof out === 'string' ? out.trim() : String(out ?? '').trim();
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * The cwd's `origin` remote URL, raw. Git resolves it per worktree, and a
+ * worktree shares its main clone's remote — exactly the right answer for
+ * "which repo am I standing in" (Decision 3). Never throws: outside a repo, or
+ * with no `origin`, it yields '' and the ladder produces its named error.
+ *
+ * Revision 4 replaced the previous rung (an `import()` of the repo's engine
+ * `conductor.config.js` plus a conductor-registry longest-prefix fallback) with
+ * this one read: the registry cannot answer inside a worktree (its paths point
+ * at `.gaia` DIRS, and a worktree has its own unregistered one), the config read
+ * needed a dynamic import of a possibly secret-bearing module, and the remote
+ * works in a fresh clone that has no `.gaia/` at all.
+ */
+async function readOriginRemoteUrl(cwd) {
+    try {
+        const out = await exec('git', ['remote', 'get-url', 'origin'], { cwd });
+        return typeof out === 'string' ? out.trim() : String(out ?? '').trim();
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * The explicit connection leg (AC-4, D2): `--config` → `$GAIA_CONFIG` →
+ * `$DROPSH_CONFIG`, first non-empty wins. The two env vars are read because
+ * core's resolver already names all three as the explicit leg and the renderer's
+ * launcher already honours a pre-set `$DROPSH_CONFIG` — so the path `gaia ui`
+ * reports and the file dropsh loads can never disagree.
+ */
+function resolveExplicitConfig(flag) {
+    for (const candidate of [
+        flag,
+        process.env.GAIA_CONFIG,
+        process.env.DROPSH_CONFIG,
+    ]) {
+        if (candidate !== undefined && candidate.trim() !== '')
+            return candidate;
+    }
+    return undefined;
+}
+/** The `--print-config` block (AC-7): which file won, and what it points at. */
+function formatConnectionReport(connection, rooting) {
+    const yesNo = (b) => (b ? 'yes' : 'no');
+    const lines = [
+        ['connection', connection.config_path],
+        ['source', connection.source],
+        ['fallback', yesNo(connection.fallback)],
+        ['legacy', yesNo(connection.legacy)],
+        ['base_url', connection.site.base_url],
+        ['cwd', rooting.cwd],
+        ['project', rooting.project ?? '(none)'],
+    ];
+    return `${lines.map(([k, v]) => `${`${k}:`.padEnd(12)}${v}`).join('\n')}\n`;
+}
 function loggerFor(checkoutRoot) {
     const logger = createLogger({ checkoutRoot });
     setDefaultCommandRunner(new CommandRunner(logger));
     return logger;
 }
 /**
- * Resolve + dynamically import `@gaia-ai/plugin-gaia-ui` (the renderer launcher),
+ * Resolve + dynamically import `@gaia-ai/addon-gaia-ui` (the renderer launcher),
  * ESLint-style over the host bases. This package never statically imports the
  * renderer — it is a swappable plugin. Returns undefined (and logs) when the
  * package is not installed.
@@ -21,7 +90,7 @@ async function loadGaiaUiModule(logger, bases) {
     let resolved;
     for (const base of bases) {
         try {
-            resolved = createRequire(base).resolve('@gaia-ai/plugin-gaia-ui');
+            resolved = createRequire(base).resolve('@gaia-ai/addon-gaia-ui');
             break;
         }
         catch {
@@ -29,57 +98,116 @@ async function loadGaiaUiModule(logger, bases) {
         }
     }
     if (resolved === undefined) {
-        logger.error({}, 'gaia ui: could not resolve @gaia-ai/plugin-gaia-ui. ' +
+        logger.error({}, 'gaia ui: could not resolve @gaia-ai/addon-gaia-ui. ' +
             'Install it, or set $GAIA_UI_PLUGIN to a renderer plugin path.');
         return undefined;
     }
     return (await import(pathToFileURL(resolved).href));
 }
 /**
- * `gaia ui` — launch the home-rooted interactive terminal UI. Reads the
- * user-global machine context + the conductor registry (NOT a project engine
- * config), resolves the connection from the home `gaia.config.js` scope, adapts
- * a herdr-backed agent host to the renderer's prompt-level service, and
- * delegates to `@gaia-ai/plugin-gaia-ui`'s `runGaiaUi`. `$GAIA_UI_PLUGIN`
- * overrides the renderer module (dev).
+ * `gaia ui` — launch the interactive terminal UI. Resolves the connection
+ * through core's `loadGaiaConfig` (explicit → project walk-up → home → shipped
+ * fallback), roots the agents in the project it was started in, reads the
+ * machine context for identity + the agent binary, adapts a herdr-backed agent
+ * host to the renderer's prompt-level service, and delegates to
+ * `@gaia-ai/addon-gaia-ui`'s `runGaiaUi`. `--print-config` reports the
+ * resolution and exits without launching. `$GAIA_UI_PLUGIN` overrides the
+ * renderer module (dev).
  */
 export async function cmdUi(deps = {}) {
     const logger = loggerFor(homedir());
     const host = deps.host ?? {
         resolveBases: [`${process.cwd()}/`, import.meta.url],
     };
-    const mcPath = machineContextPath();
-    const machine = deps.machine ?? (await readMachineContext(mcPath).catch(() => ({})));
-    // Which connection config `gaia ui` reads: a user-authored
-    // `~/.gaia/gaia.config.js` wins; otherwise the shipped machine-context
-    // fallback. The test seam `homeConfigPath` forces a path (fallback branch).
-    const userHomeConfig = join(homedir(), '.gaia', 'gaia.config.js');
-    const resolved = deps.homeConfigPath
-        ? { path: deps.homeConfigPath, fallback: true }
-        : resolveUiConfigPath(userHomeConfig, homeFallbackGaiaConfigPath());
-    let connection;
-    if (resolved.fallback) {
-        try {
-            connection = buildHomeConnection(machine);
-        }
-        catch (err) {
-            logger.error({}, err instanceof Error ? err.message : String(err));
-            process.exitCode = 1;
-            return;
+    const cwd = deps.cwd ?? process.cwd();
+    // User-facing CLI errors go to stderr, not the log sink: `createLogger` writes
+    // to `$HOME/log.txt` whenever stdout is not a TTY, and `gaia ui GAIA-1 | cat`
+    // must still SAY why it failed. Spec Decision 5: "a stderr line and exit 1".
+    const fail = (message) => {
+        (deps.stderr ?? ((line) => process.stderr.write(line)))(`${message}\n`);
+        process.exitCode = 1;
+    };
+    // GAIA-223: build the deep-link route FIRST — argv parsing, the conflict rule
+    // and the whole `--here` ladder are offline, so every one of their failures
+    // costs no config load and no network round-trip, and never reaches the
+    // launcher (AC-1/AC-2).
+    let initialRoute;
+    try {
+        const parsed = parseTarget({
+            target: deps.target,
+            ticket: deps.ticket,
+            project: deps.project,
+            run: deps.run,
+            here: deps.here,
+            view: deps.view,
+        });
+        if (parsed?.kind === 'route') {
+            initialRoute = parsed.route;
         }
-        if (!process.env.GAIA_MACHINE_CONTEXT) {
-            process.env.GAIA_MACHINE_CONTEXT = mcPath;
+        else if (parsed?.kind === 'here') {
+            initialRoute = await resolveHere({
+                cwd,
+                ...(parsed.view !== undefined ? { view: parsed.view } : {}),
+                readBranch: deps.readBranch ?? readCurrentBranch,
+                readRemoteUrl: deps.readRemoteUrl ?? readOriginRemoteUrl,
+            });
         }
     }
-    else {
-        connection = { baseUrl: '', authProfile: 'session', authPlugins: [] };
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+        return;
     }
-    connection.configPath = resolved.path;
+    // Read only AFTER the route: the whole grammar + ladder is offline, so a
+    // parse/conflict/no-remote failure must not even touch the registry file.
     const entries = deps.registryEntries ?? (await listRegisteredConductors());
-    const project = resolveDefaultProject(entries);
-    const projectEntry = entries.find((e) => e.project === project);
-    const cwd = projectEntry?.path ?? homedir();
-    const ownConductorMachineId = projectEntry?.id;
+    const mcPath = machineContextPath();
+    // The machine context still supplies identity (`user_id`) + the agent binary;
+    // it is NOT the connection any more — core resolves that.
+    const machine = deps.machine ?? (await readMachineContext(mcPath).catch(() => ({})));
+    // The ONE precedence rule, core's, the same one `gaia dropsh` uses (AC-1/2/3/
+    // 4/5/6). A legacy `conductor.config.js` carrying site/plugins is accepted on
+    // exactly core's terms — there is no back-compat branch here.
+    const load = deps.loadConnection ?? loadGaiaConfig;
+    let resolved;
+    try {
+        resolved = await load(host, {
+            cwd,
+            explicit: resolveExplicitConfig(deps.explicitConfig),
+        });
+    }
+    catch (err) {
+        logger.error({}, err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+        return;
+    }
+    const connection = {
+        baseUrl: resolved.site.base_url,
+        jsonapiPrefix: resolved.site.jsonapi_prefix,
+        authPlugins: resolved.plugins,
+        configPath: resolved.config_path,
+        authProfile: 'session',
+    };
+    const rooting = resolveProjectRooting(cwd, entries, homedir());
+    const ownConductorMachineId = rooting.ownConductorMachineId;
+    const project = rooting.project;
+    // AC-7, always on: the resolution lands in the log even when the TUI takes
+    // over the screen a moment later.
+    logger.info({
+        config_path: resolved.config_path,
+        source: resolved.source,
+        fallback: resolved.fallback,
+        legacy: resolved.legacy,
+        base_url: resolved.site.base_url,
+        cwd: rooting.cwd,
+        project,
+    }, 'gaia ui: resolved connection');
+    // AC-7, the human surface: print and exit 0 WITHOUT booting the TUI, so a
+    // wrong-control-plane situation is diagnosable at a prompt.
+    if (deps.printConfig) {
+        const write = deps.stdout ?? ((s) => process.stdout.write(s));
+        write(formatConnectionReport(resolved, rooting));
+        return;
+    }
     const agentCommand = resolveAgentCommand(machine);
     const agentHost = deps.agentHost ?? herdrAgentHost((args) => exec('herdr', args));
     const agents = {
@@ -122,18 +250,38 @@ export async function cmdUi(deps = {}) {
         }
         run = uiMod.runGaiaUi;
     }
-    await run({
-        connection,
-        cwd,
-        ...(project !== undefined ? { project } : {}),
-        agents,
-        ...(machine.user_id ? { currentUser: machine.user_id } : {}),
-        ...(ownConductorMachineId ? { ownConductorMachineId } : {}),
-        buildProgram: (o) => buildDropshProgram({
-            plugins: o.plugins,
-        }),
-        ...(renderer ? { renderer } : {}),
-    });
+    // The launcher (and, through it, the renderer's route resolution — Decision 5)
+    // may reject BEFORE the TUI takes the terminal; `await run(...)` was unguarded,
+    // so that surfaced as an unhandled rejection. Catch it into exit 1 + a line.
+    try {
+        await run({
+            connection,
+            cwd: rooting.cwd,
+            ...(project !== undefined ? { project } : {}),
+            agents,
+            ...(machine.user_id ? { currentUser: machine.user_id } : {}),
+            ...(ownConductorMachineId ? { ownConductorMachineId } : {}),
+            // The plugins are real constructed `DropSHPlugin[]` now (core built them),
+            // matching dropsh's declared contract — F3's substance, a descriptor handed
+            // to an API expecting instances, is gone. The two casts that remain are
+            // structural, not unsound: `RunGaiaUiOptions` is a local MIRROR of the
+            // dynamically-resolved renderer's type (this package must not compile
+            // against it), so its `plugins` is `unknown[]` and its program type is the
+            // narrow `DropshProgram` above. Both casts only re-tell TypeScript what the
+            // mirror deliberately forgot.
+            // dropsh uses the plugins for renderers + `registerCommands` only; auth
+            // still comes from its own `$DROPSH_CONFIG` reload of the very file we
+            // resolved, so nothing is registered twice.
+            buildProgram: (o) => buildDropshProgram({
+                plugins: o.plugins,
+            }),
+            ...(renderer ? { renderer } : {}),
+            ...(initialRoute ? { initialRoute } : {}),
+        });
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+    }
 }
 /** The `ui` command plugin the host mounts (`gaia ui`). */
 const uiCommandPlugin = {
@@ -144,8 +292,46 @@ const uiCommandPlugin = {
         program
             .command('ui')
             .description('interactive terminal UI: project dashboard, ticket list, ticket detail')
-            .action(async () => {
-            await cmdUi({ host });
+            .argument('[target]', 'deep-link target: GAIA-221 · ticket:<id|uuid> · project:<name|uuid> · run:<uuid>')
+            .option('--ticket <id>', 'open a ticket by identifier or uuid')
+            .option('--project <id>', 'open a project by name or uuid')
+            .option('--run <uuid>', "open a run's owning ticket, on its Runs tab")
+            .option('--here', "derive the target from the cwd: the branch's ticket, else this repo's project")
+            .option('--view <mode>', `how a ticket renders: ${UI_VIEW_MODES.join(' | ')}`)
+            .option('--config <path>', 'connection config path; wins over the project and home configs')
+            .option('--print-config', 'print the resolved connection config and exit, without launching the UI')
+            .addHelpText('after', `
+Targets (at most ONE of the positional, --ticket, --project, --run, --here):
+  gaia ui                                the project dashboard
+  gaia ui GAIA-221                       a ticket by identifier (case-insensitive)
+  gaia ui ticket:GAIA-221                the same, said explicitly
+  gaia ui ticket:<uuid>                  a ticket by uuid
+  gaia ui project:gaia                   a project by name (case-sensitive label)
+  gaia ui run:<uuid>                     that run's owning ticket, Runs tab active
+  gaia ui --ticket GAIA-221              the script-friendly flag form
+  gaia ui --here                         this branch's ticket (feat/gaia-223-… → GAIA-223),
+                                         else this repo's project
+
+Modifier (orthogonal — never conflicts with a target):
+  gaia ui GAIA-221 --view teaser         a compact block instead of the tabbed detail
+  gaia ui GAIA-221 --view board_card     the board-card field set
+
+Two target sources at once exit non-zero naming both. A bare uuid is ambiguous
+(prefix it); a bare number is not an identifier. --view applies to ticket
+targets only. Full reference: gaia-cli/ui/README.md
+`)
+            .action(async (target, o) => {
+            await cmdUi({
+                host,
+                ...(target !== undefined ? { target } : {}),
+                ...(o.ticket !== undefined ? { ticket: o.ticket } : {}),
+                ...(o.project !== undefined ? { project: o.project } : {}),
+                ...(o.run !== undefined ? { run: o.run } : {}),
+                ...(o.here !== undefined ? { here: o.here } : {}),
+                ...(o.view !== undefined ? { view: o.view } : {}),
+                ...(o.config !== undefined ? { explicitConfig: o.config } : {}),
+                ...(o.printConfig ? { printConfig: true } : {}),
+            });
         });
     },
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gaia-ai/ui",
-  "version": "0.6.0",
-  "description": "GAIA home-rooted cockpit: the `gaia ui` command plugin (renderer resolved dynamically).",
+  "version": "0.6.2",
+  "description": "GAIA project-first cockpit: the `gaia ui` command plugin (renderer resolved dynamically).",
   "type": "module",
   "license": "MIT",
   "engines": {
@@ -23,11 +23,11 @@
   "repository": {
     "type": "git",
     "url": "git+https://git.key-tec.de/keytec/gaia.git",
-    "directory": "conductor/ui"
+    "directory": "gaia-cli/ui"
   },
   "dependencies": {
-    "@gaia-ai/core": "^0.6.0",
-    "@gaia-ai/plugin-herdr": "^0.6.0",
+    "@gaia-ai/core": "^0.6.2",
+    "@gaia-ai/addon-herdr": "^0.6.2",
     "commander": "^12.1.0",
     "dropsh": "^0.5.8"
   }