@astrale-os/cli 1.0.0-beta.2 → 1.0.0-beta.20

package/src/lib/view/host-capabilities.ts

@@ -0,0 +1,17 @@
+import type { HostCapabilities } from '@astrale-os/shell'
+
+import { admitHostCapabilities } from '@astrale-os/shell'
+
+/** Build the exact host grant handed to a CLI-hosted View session. */
+export function viewHostCapabilities(externalOrigins: readonly string[]): HostCapabilities {
+  return admitHostCapabilities({
+    version: 1,
+    navigation: {
+      openView: {},
+      ...(externalOrigins.length === 0 ? {} : { external: { origins: externalOrigins } }),
+    },
+    actions: {},
+    browser: {},
+    access: {},
+  })
+}

package/src/lib/view/resolve.ts

@@ -1,4 +1,4 @@
-import type { ResolvedView as SessionResolvedView } from '@astrale-os/kernel-client/session'
+import type { ResolvedView as SessionResolvedView } from '@astrale-os/sdk/client/session'
 import type { ResolvedView } from '@astrale-os/shell'
 
 import { Path } from '@astrale-os/sdk/graph/path'

package/src/lib/view/server.ts

@@ -1,3 +1,5 @@
+import type { AuthApi } from '@astrale-os/sdk/auth'
+import type { IssuerId } from '@astrale-os/sdk/auth'
 import type { ReadableStream as WebReadableStream } from 'node:stream/web'
 
 import { readFile } from 'node:fs/promises'
@@ -23,8 +25,9 @@ export { ensureViewerAssets, viewerDistDir } from './assets'
  * heartbeat keeps a live session alive.
  */
 
-const TOKEN_REFRESH_MARGIN_MS = 5 * 60_000
-const FALLBACK_TOKEN_TTL_MS = 3600_000
+const VIEW_TOKEN_TTL_SECONDS = 4 * 60
+const TOKEN_REFRESH_MARGIN_MS = 60_000
+const FALLBACK_TOKEN_TTL_MS = VIEW_TOKEN_TTL_SECONDS * 1_000
 const IDLE_SWEEP_MS = 60_000
 
 export type PageStatus = { state: string; error?: string; at: string }
@@ -44,7 +47,7 @@ export function startViewServer(config: ViewServeConfig): Server {
   async function freshGrant(): Promise<TokenGrant> {
     if (grant && grant.expiresAt - Date.now() > TOKEN_REFRESH_MARGIN_MS) return grant
     grant = await withClientSession(config.kernel, async ({ auth, target }) => {
-      const token = await auth.mint({ audience: target.kernelIssuer, ttlSeconds: 3_600 })
+      const token = await mintViewCredential(auth, target.kernelIssuer)
       return {
         token,
         expiresAt: jwtExpiry(token) ?? Date.now() + FALLBACK_TOKEN_TTL_MS,
@@ -98,6 +101,7 @@ export function startViewServer(config: ViewServeConfig): Server {
         identity: session.identity ?? null,
         instance: session.instance ?? null,
         sessionId: session.id,
+        externalOrigins: config.externalOrigins,
       })
       return
     }
@@ -182,6 +186,17 @@ export function startViewServer(config: ViewServeConfig): Server {
   return server
 }
 
+/** Mint a short-lived credential from the selected CLI identity proof. */
+export async function mintViewCredential(
+  auth: Pick<AuthApi, 'mint'>,
+  audience: IssuerId,
+): Promise<string> {
+  return auth.mint({
+    audience,
+    ttlSeconds: VIEW_TOKEN_TTL_SECONDS,
+  })
+}
+
 function jwtExpiry(token: string): number | null {
   try {
     const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64url').toString('utf8')) as {

package/src/lib/view/session.ts

@@ -41,6 +41,8 @@ export type ViewServeConfig = {
    * handles CORS and self-signed local CAs.
    */
   proxy: { kernelUrl: string; issuer: string; caFile?: string; direct: boolean }
+  /** Exact HTTPS origins the operator consented to open from this View session. */
+  externalOrigins: readonly string[]
   idleMs: number
 }
 

package/src/program/.spec/api.d.ts

@@ -5,6 +5,7 @@ export interface CommandArgument {
   readonly name: string
   readonly description: string
   readonly required?: boolean
+  readonly variadic?: boolean
 }
 
 /** One Commander-compatible option in a CLI command definition. */

package/src/program/__tests__/program.test.ts

@@ -5,7 +5,7 @@ import { createHash } from 'node:crypto'
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 
-import { buildProgram } from '../index'
+import { buildProgram, normalizeRootVersionArgv } from '../index'
 
 // Help output is the public CLI contract: version, spec anchors, and skill mirror stay in sync.
 
@@ -181,13 +181,21 @@ describe('program composition', () => {
       'status',
       'studio',
       'token',
+      'ui',
+      'ui add',
+      'ui doctor',
+      'ui init',
+      'ui list',
+      'ui preset',
+      'ui preset apply',
+      'ui preset list',
       'update',
       'use',
       'view',
       'whoami',
     ])
     expect(createHash('sha256').update(JSON.stringify(surface)).digest('hex')).toBe(
-      '44f78959867171661197043f5b47eb6d6890274090370e071d10f11b4204850d',
+      '51546dd7ea5cbf25efbd41f0cd09ceb480abad5be489fc16743500a18e3a02c6',
     )
   })
 
@@ -213,6 +221,19 @@ describe('help contract — no internal SPEC anchors leak to users', () => {
 
     expect(offenders).toEqual([])
   })
+
+  test('Kernel and Instance vocabulary does not expose retired Host or Interface concepts', async () => {
+    const program = await buildProgram()
+    const help = allCommands(program)
+      .map((command) => command.helpInformation())
+      .join('\n')
+
+    expect(help).not.toContain('host.astrale.ai')
+    expect(help).not.toContain(':interface.')
+    expect(help).not.toContain('Class or Interface')
+    expect(help).not.toContain('emulated host')
+    expect(help).not.toContain('Host shell')
+  })
 })
 
 describe('help contract — IdP/auth surface is registered', () => {
@@ -251,21 +272,24 @@ describe('help contract — admin target surface is registered', () => {
     expect(adminUse?.helpInformation()).not.toContain('--issuer <url>')
   })
 
-  test('instance create is the alphaCreate flow, not legacy Instance.init DX', async () => {
+  test('instance create delegates infrastructure placement to Admin', async () => {
     const program = await buildProgram()
     const instanceCreate = allCommands(program).find((command) => command.name() === 'create')
     const help = instanceCreate?.helpInformation() ?? ''
 
-    expect(help).toContain('Instance.alphaCreate')
+    expect(help).toContain('Provision an instance through the Admin control plane')
+    expect(help).not.toContain('Host')
+    expect(help).not.toContain('Fleet')
+    expect(help).not.toContain('--host-id')
     expect(help).not.toContain('--no-use')
-    expect(help).not.toContain('Instance.init requires --host-id')
+    expect(help).not.toContain('Instance.init')
   })
 })
 
 describe('help contract — connect-only command surface', () => {
   test('runtime management commands are not registered', async () => {
     const program = await buildProgram()
-    const names = allCommands(program).map((command) => command.name())
+    const names = program.commands.map((command) => command.name())
 
     // `logs` and `domain` have managed/admin meanings, so only retired verbs are absent.
     for (const removed of [
@@ -287,6 +311,139 @@ describe('help contract — connect-only command surface', () => {
   })
 })
 
+describe('help contract — UI is project tooling', () => {
+  test('add recovery guidance uses only registered UI commands', async () => {
+    const program = await buildProgram()
+    const uiAdd = program.commands
+      .find((command) => command.name() === 'ui')
+      ?.commands.find((command) => command.name() === 'add')
+    let help = ''
+    uiAdd?.configureOutput({
+      writeOut: (chunk) => {
+        help += chunk ?? ''
+      },
+    })
+    uiAdd?.outputHelp()
+
+    expect(help).toContain('astrale ui doctor')
+    expect(help).toContain('--overwrite --yes')
+    expect(help).not.toMatch(/\b(?:astrale ui )?diff\b/u)
+  })
+
+  test('keeps the documented root version alias operational', async () => {
+    const program = await buildProgram()
+    let stdout = ''
+    program.exitOverride().configureOutput({
+      writeOut: (chunk) => {
+        stdout += chunk ?? ''
+      },
+    })
+
+    await expect(
+      program.parseAsync(normalizeRootVersionArgv(['node', 'astrale', '--version'])),
+    ).rejects.toMatchObject({ code: 'commander.version' })
+    expect(stdout.trim()).toBe(program.version() ?? '')
+    expect(program.helpInformation()).toMatch(/root alias:\s+--version/u)
+  })
+
+  test('routes root and subcommand version flags to their exact owners', async () => {
+    const program = await buildProgram()
+    const uiList = program.commands
+      .find((command) => command.name() === 'ui')
+      ?.commands.find((command) => command.name() === 'list')
+    let observedVersion: unknown
+    uiList?.action((_query, options) => {
+      observedVersion = options.version
+    })
+
+    const uiArgv = ['node', 'astrale', 'ui', 'list', 'chart', '--version', '0.3.0-beta.1']
+    expect(normalizeRootVersionArgv(uiArgv)).toEqual(uiArgv)
+    expect(normalizeRootVersionArgv(['node', 'astrale', '--version'])).toEqual([
+      'node',
+      'astrale',
+      '--cli-version',
+    ])
+    expect(normalizeRootVersionArgv(['node', 'astrale', '--ci', '--version'])).toEqual([
+      'node',
+      'astrale',
+      '--ci',
+      '--cli-version',
+    ])
+
+    await program.parseAsync(uiArgv)
+
+    expect(observedVersion).toBe('0.3.0-beta.1')
+  })
+
+  test('routes explicit versions with positional inputs for UI init and update', async () => {
+    const program = await buildProgram()
+    const uiInit = program.commands
+      .find((command) => command.name() === 'ui')
+      ?.commands.find((command) => command.name() === 'init')
+    const update = program.commands.find((command) => command.name() === 'update')
+    let initializedPath: unknown
+    let initializedVersion: unknown
+    let updateVersion: unknown
+    uiInit?.action((projectPath, options) => {
+      initializedPath = projectPath
+      initializedVersion = options.version
+    })
+    update?.action((options) => {
+      updateVersion = options.version
+    })
+
+    await program.parseAsync([
+      'node',
+      'astrale',
+      'ui',
+      'init',
+      './app',
+      '--version',
+      '0.3.0-beta.1',
+    ])
+    expect(initializedPath).toBe('./app')
+    expect(initializedVersion).toBe('0.3.0-beta.1')
+
+    await program.parseAsync(['node', 'astrale', 'update', '--version', '1.0.0-beta.13'])
+    expect(updateVersion).toBe('1.0.0-beta.13')
+  })
+
+  test('continues to admit global machine flags after a subcommand', async () => {
+    const program = await buildProgram()
+    const uiList = program.commands
+      .find((command) => command.name() === 'ui')
+      ?.commands.find((command) => command.name() === 'list')
+    let invoked = false
+    uiList?.action(() => {
+      invoked = true
+    })
+
+    await program.parseAsync(['node', 'astrale', 'ui', 'list', '--ci', '--no-prompt'])
+
+    expect(invoked).toBe(true)
+  })
+
+  test('UI commands are local-only and add accepts zero or more canonical addresses', async () => {
+    const program = await buildProgram()
+    const ui = program.commands.find((command) => command.name() === 'ui')
+    const add = ui?.commands.find((command) => command.name() === 'add')
+
+    expect(ui?.commands.map((command) => command.name())).toEqual([
+      'init',
+      'list',
+      'add',
+      'doctor',
+      'preset',
+    ])
+    expect(add?.helpInformation()).toContain('[items...]')
+    for (const command of ui?.commands ?? []) {
+      const help = command.helpInformation()
+      expect(help).not.toContain('--url <url>')
+      expect(help).not.toContain('--anonymous')
+    }
+  })
+})
+
 describe('help contract — read command split', () => {
   test('get is point-read only and query owns structured read flags', async () => {
     const program = await buildProgram()

package/src/program/argv.ts

@@ -0,0 +1,14 @@
+/**
+ * Keep `astrale --version` as the familiar root spelling without claiming the
+ * same flag after a subcommand. Commands such as `ui list` and `update` own
+ * their release `--version` value.
+ */
+export function normalizeRootVersionArgv(argv: readonly string[]): string[] {
+  const normalized = [...argv]
+  const commandIndex = normalized.findIndex((token, index) => index >= 2 && !token.startsWith('-'))
+  const versionIndex = normalized.indexOf('--version', 2)
+  if (versionIndex !== -1 && (commandIndex === -1 || versionIndex < commandIndex)) {
+    normalized[versionIndex] = '--cli-version'
+  }
+  return normalized
+}

package/src/program/build.ts

@@ -19,7 +19,7 @@ export async function buildProgram(): Promise<Command> {
     .description('Astrale CLI — connect to existing Astrale kernels')
     // Single source of truth = package.json (bumped by release-please together
     // with .release-please-manifest.json). Never hand-write a version literal.
-    .version(pkg.version)
+    .version(pkg.version, '-V, --cli-version', 'output the CLI version (root alias: --version)')
     .showSuggestionAfterError(true)
     .addOption(new Option('--ci', 'Machine mode: no prompts, structured errors on stderr'))
     .addOption(new Option('--no-prompt', 'Disable interactive prompts'))
@@ -63,6 +63,27 @@ export async function buildProgram(): Promise<Command> {
   registerCommand(program, (await import('../commands/view-serve')).default)
   registerCommand(program, (await import('../commands/studio')).default)
 
+  registerGroup(program, {
+    name: 'ui',
+    description: 'Initialize and install Astrale UI in local applications',
+    commands: [
+      (await import('../commands/ui/init')).default,
+      (await import('../commands/ui/list')).default,
+      (await import('../commands/ui/add')).default,
+      (await import('../commands/ui/doctor')).default,
+    ],
+    subgroups: [
+      {
+        name: 'preset',
+        description: 'List and apply qualified Astrale UI presets',
+        commands: [
+          (await import('../commands/ui/preset-list')).default,
+          (await import('../commands/ui/preset-apply')).default,
+        ],
+      },
+    ],
+  })
+
   registerGroup(program, {
     name: 'instance',
     description: 'Manage admin-provisioned instances and local bookmarks',
@@ -154,12 +175,13 @@ Command groups:
   Getting started  setup     (sign in, pick an instance, equip your workspace)
   Kernel        get, mutate, call, query, introspect, logs, view, token
   Management    admin, instance, domain, identity, auth, idp, update
+  Application   ui        (initialize, inspect, and install Astrale UI source)
   Agent         browser   (drive the GUI via agent-browser)
   Studio        studio    (launch the local Domain Studio GUI for a workspace)
 
 Path syntax:
   /:origin                       Domain root
-  /:origin:class.Name            Class node     (or /:origin:interface.Name)
+  /:origin:class.Name            Class node
   /:origin:class.Name:method     Static callable
   <nodePath>::method             Instance method dispatch — double colon ::
   @nodeId                        Reference a node by its UID
@@ -172,9 +194,9 @@ Examples:
   $ astrale instance bookmark staging --url https://kernel.example.com
   $ astrale instance create my-app
   $ astrale instance status staging
-  $ astrale token --audience shell.astrale.ai --ttl 3600
+  $ astrale token --audience shell.astrale.ai
   $ astrale query /:notes.example.dev:class.Note --limit 50
-  $ astrale introspect /:host.astrale.ai:class.Manager:createInstance
+  $ astrale introspect /:kernel.astrale.ai:class.Identity:whois
   $ astrale query --file query.v6.json --cursor "$CURSOR"
 `,
   )

package/src/program/command.ts

@@ -2,6 +2,7 @@ export interface CommandArgument {
   readonly name: string
   readonly description: string
   readonly required?: boolean
+  readonly variadic?: boolean
 }
 
 export interface CommandOption {

package/src/program/index.ts

@@ -1,2 +1,3 @@
 export { buildProgram } from './build.js'
+export { normalizeRootVersionArgv } from './argv.js'
 export type { CommandArgument, CommandDefinition, CommandGroup, CommandOption } from './command.js'

package/src/program/registry.ts

@@ -18,7 +18,8 @@ export function registerCommand(parent: Command, def: CommandDefinition): void {
 
   if (def.arguments) {
     for (const arg of def.arguments) {
-      const bracket = arg.required !== false ? `<${arg.name}>` : `[${arg.name}]`
+      const name = arg.variadic ? `${arg.name}...` : arg.name
+      const bracket = arg.required !== false ? `<${name}>` : `[${name}]`
       cmd.argument(bracket, arg.description)
     }
   }

package/src/setup/__tests__/instance-step.test.ts

@@ -27,11 +27,15 @@ function instance(slug: string, state: OwnedInstanceInfo['state'] = 'ready'): Ow
   }
 }
 
+function inventory(instances: OwnedInstanceInfo[], identity?: string) {
+  return { instances, ...(identity ? { identity } : {}) }
+}
+
 function dependencies(
   overrides: Partial<InstanceSetupDependencies> = {},
 ): InstanceSetupDependencies {
   return {
-    fetchOwned: mock(async () => []),
+    fetchOwned: mock(async () => inventory([])),
     adopt: mock(async () => {}),
     selectReady: mock(async (instances) => instances[0] ?? null),
     confirmCreate: mock(async () => true),
@@ -48,12 +52,14 @@ describe('setup owned-instance reconciliation', () => {
   test('silently adopts the sole owned ready instance', async () => {
     const ready = instance('only')
     const failed = instance('old-attempt', 'failed')
-    const deps = dependencies({ fetchOwned: mock(async () => [failed, ready]) })
+    const deps = dependencies({
+      fetchOwned: mock(async () => inventory([failed, ready], 'manager')),
+    })
 
     await expect(ensureOwnedInstance(ctx, deps)).resolves.toBe('fixed')
 
     expect(deps.adopt).toHaveBeenCalledTimes(1)
-    expect(deps.adopt).toHaveBeenCalledWith(ready)
+    expect(deps.adopt).toHaveBeenCalledWith(ready, 'manager')
     expect(deps.selectReady).not.toHaveBeenCalled()
     expect(deps.confirmCreate).not.toHaveBeenCalled()
     expect(deps.provision).not.toHaveBeenCalled()
@@ -64,14 +70,14 @@ describe('setup owned-instance reconciliation', () => {
     const second = instance('second')
     const pending = instance('pending', 'provisioning')
     const deps = dependencies({
-      fetchOwned: mock(async () => [first, pending, second]),
+      fetchOwned: mock(async () => inventory([first, pending, second], 'manager')),
       selectReady: mock(async (instances) => instances[1] ?? null),
     })
 
     await expect(ensureOwnedInstance(ctx, deps)).resolves.toBe('fixed')
 
     expect(deps.selectReady).toHaveBeenCalledWith([first, second])
-    expect(deps.adopt).toHaveBeenCalledWith(second)
+    expect(deps.adopt).toHaveBeenCalledWith(second, 'manager')
     expect(deps.confirmCreate).not.toHaveBeenCalled()
     expect(deps.provision).not.toHaveBeenCalled()
   })
@@ -80,7 +86,7 @@ describe('setup owned-instance reconciliation', () => {
     const first = instance('first')
     const second = instance('second')
     const deps = dependencies({
-      fetchOwned: mock(async () => [first, second]),
+      fetchOwned: mock(async () => inventory([first, second])),
       selectReady: mock(async () => null),
     })
 
@@ -165,7 +171,9 @@ describe('setup owned-instance reconciliation', () => {
       phase: 'installing:default-domains',
     }
     const failed = { ...instance('broken', 'failed'), error: 'postInstall failed' }
-    const deps = dependencies({ fetchOwned: mock(async () => [provisioning, failed]) })
+    const deps = dependencies({
+      fetchOwned: mock(async () => inventory([provisioning, failed])),
+    })
     const logged: string[] = []
     const original = console.log
     console.log = mock((...args: unknown[]) => {
@@ -218,10 +226,10 @@ describe('owned-instance adoption', () => {
     console.log = mock(() => {})
 
     try {
-      await adoptOwnedInstance(owned, {
+      await adoptOwnedInstance(owned, 'manager', {
         upsert: mock(async (...args) => {
           calls.push(['upsert', ...args])
-          return {}
+          return { entry: {} }
         }),
         activate: mock(async (...args) => {
           calls.push(['activate', ...args])
@@ -232,7 +240,16 @@ describe('owned-instance adoption', () => {
     }
 
     expect(calls).toEqual([
-      ['upsert', 'existing', 'existing', 'https://existing.eu.astrale.ai', 'org_existing'],
+      [
+        'upsert',
+        {
+          key: 'existing',
+          slug: 'existing',
+          url: 'https://existing.eu.astrale.ai',
+          organizationId: 'org_existing',
+          defaultIdentity: 'manager',
+        },
+      ],
       ['activate', 'existing'],
     ])
   })

package/src/setup/steps/instance.ts

@@ -4,7 +4,7 @@ import type { OwnedInstanceInfo } from '../../lib/admin-instance'
 import type { SetupContext, SetupStep } from '../types'
 
 import { AstraleError } from '../../errors'
-import { listOwnedInstances } from '../../lib/admin-instance'
+import { listOwnedInstancesWithIdentity } from '../../lib/admin-instance'
 import { normalizeInstanceKernelUrl, setActive, upsertManagedBookmark } from '../../lib/instance'
 import { readLocalStatus } from '../../lib/local-status'
 import { log, withSpinner } from '../../lib/log'
@@ -14,8 +14,11 @@ import { provisionInstance, type ProvisionResult } from '../../lib/provision-ins
 import { guiOrigin, slugError } from '../util'
 
 export type InstanceSetupDependencies = {
-  fetchOwned: (ctx: SetupContext) => Promise<OwnedInstanceInfo[]>
-  adopt: (info: OwnedInstanceInfo) => Promise<void>
+  fetchOwned: (ctx: SetupContext) => Promise<{
+    readonly instances: OwnedInstanceInfo[]
+    readonly identity?: string
+  }>
+  adopt: (info: OwnedInstanceInfo, identity?: string) => Promise<void>
   selectReady: (instances: OwnedInstanceInfo[]) => Promise<OwnedInstanceInfo | null>
   confirmCreate: () => Promise<boolean>
   promptSlug: () => Promise<string | undefined>
@@ -23,12 +26,7 @@ export type InstanceSetupDependencies = {
 }
 
 export type OwnedInstanceAdoptionDependencies = {
-  upsert: (
-    key: string,
-    slug: string,
-    url: string,
-    organizationId?: string,
-  ) => Promise<{ repointedFrom?: string }>
+  upsert: typeof upsertManagedBookmark
   activate: (slug: string) => Promise<unknown>
 }
 
@@ -41,12 +39,19 @@ function hero(slug: string, kernelUrl: string): void {
 
 export async function adoptOwnedInstance(
   info: OwnedInstanceInfo,
+  defaultIdentity?: string,
   deps: OwnedInstanceAdoptionDependencies = {
     upsert: upsertManagedBookmark,
     activate: setActive,
   },
 ): Promise<void> {
-  const { repointedFrom } = await deps.upsert(info.slug, info.slug, info.url, info.organizationId)
+  const { repointedFrom } = await deps.upsert({
+    key: info.slug,
+    slug: info.slug,
+    url: info.url,
+    ...(info.organizationId ? { organizationId: info.organizationId } : {}),
+    ...(defaultIdentity ? { defaultIdentity } : {}),
+  })
   await deps.activate(info.slug)
   if (repointedFrom) {
     log.warn(
@@ -61,7 +66,7 @@ function defaultDependencies(ctx: SetupContext): InstanceSetupDependencies {
   return {
     fetchOwned: (setupCtx) =>
       withSpinner('Checking for existing instances', !setupCtx.machine, () =>
-        listOwnedInstances(setupCtx.opts),
+        listOwnedInstancesWithIdentity(setupCtx.opts),
       ),
     adopt: adoptOwnedInstance,
     selectReady: (instances) =>
@@ -90,9 +95,9 @@ export async function ensureOwnedInstance(
   ctx: SetupContext,
   deps: InstanceSetupDependencies = defaultDependencies(ctx),
 ): Promise<'fixed' | 'skipped'> {
-  let owned: OwnedInstanceInfo[]
+  let inventory: Awaited<ReturnType<InstanceSetupDependencies['fetchOwned']>>
   try {
-    owned = await deps.fetchOwned(ctx)
+    inventory = await deps.fetchOwned(ctx)
   } catch (cause) {
     const detail = cause instanceof Error ? cause.message : String(cause)
     throw new AstraleError(
@@ -102,9 +107,11 @@ export async function ensureOwnedInstance(
     )
   }
 
+  const owned = inventory.instances
+
   const ready = owned.filter((info) => info.state === 'ready')
   if (ready.length === 1) {
-    await deps.adopt(ready[0]!)
+    await deps.adopt(ready[0]!, inventory.identity)
     return 'fixed'
   }
 
@@ -114,7 +121,7 @@ export async function ensureOwnedInstance(
       log.dim('  Skipped — no active instance set.')
       return 'skipped'
     }
-    await deps.adopt(choice)
+    await deps.adopt(choice, inventory.identity)
     return 'fixed'
   }
 

package/src/telemetry/__tests__/recorder.test.ts

@@ -91,6 +91,7 @@ describe('beginInvocation', () => {
   test('writes nothing for help/version-only invocations', () => {
     beginInvocation(['node', 'astrale', '--help'])(0)
     beginInvocation(['node', 'astrale', '--version'])(0)
+    beginInvocation(['node', 'astrale', '--cli-version'])(0)
     beginInvocation(['node', 'astrale'])(0)
     expect(listSessions()).toHaveLength(0)
   })

package/src/telemetry/recorder.ts

@@ -17,7 +17,15 @@ import { eventsPath } from './store'
 export type Finalizer = (exitCode: number, errorName?: string) => void
 
 const NOOP: Finalizer = () => {}
-const HELP_VERSION = new Set(['-h', '--help', '-V', '--version', 'help', 'version'])
+const HELP_VERSION = new Set([
+  '-h',
+  '--help',
+  '-V',
+  '--version',
+  '--cli-version',
+  'help',
+  'version',
+])
 
 /** Bare invocation (every() is true for []) or only help/version tokens — skip. */
 function isHelpOrVersion(args: string[]): boolean {

package/src/ui/.spec/api.d.ts

@@ -0,0 +1,14 @@
+export {
+  addUi,
+  applyPreset,
+  diffUi,
+  doctorUi,
+  initUi,
+  listUi,
+  viewUi,
+  type InitUiOptions,
+} from '../operations.js'
+export { UI_PRESETS, UiError, type UiLock, type UiPreset } from '../model.js'
+export { discoverUiProject, type UiProject } from '../project.js'
+export { resolveUiRelease } from '../release.js'
+export { shadcnInvocation, type UiRunner } from '../runner.js'