@astrale-os/cli 1.0.0-beta.26 → 1.0.0-beta.28

package/studio/server/introspect/extractor.ts

@@ -1,9 +1,7 @@
 /** Bun subprocess that imports only the authored Schema entry and its installed SDK. */
-import {
-  admitCanonicalSchemaFromSdk,
-  findCanonicalDomainSchemaExport,
-  projectCanonicalSchema,
-} from './canonical-schema'
+import type { SchemaSdk } from './canonical-schema'
+
+import { extractCanonicalSchemaFromSdk, findCanonicalDomainSchemaExport } from './canonical-schema'
 
 const schemaPath = process.argv[2]
 const projectRoot = process.argv[3] ?? process.cwd()
@@ -15,19 +13,17 @@ async function main(): Promise<void> {
   if (candidate === null) {
     throw new Error('Schema entry exports no canonical V1 DomainSchema.')
   }
-  const sdk = (await import(Bun.resolveSync('@astrale-os/sdk/schema', projectRoot))) as Record<
-    string,
-    unknown
-  >
-  const admission = admitCanonicalSchemaFromSdk(sdk, candidate)
-  const projected = projectCanonicalSchema(admission.root, admission.closure)
+  const sdk = (await import(
+    Bun.resolveSync('@astrale-os/sdk/schema', projectRoot)
+  )) as unknown as SchemaSdk
+  const extraction = extractCanonicalSchemaFromSdk(sdk, candidate)
   process.stdout.write(
     JSON.stringify({
       ok: true,
-      ir: projected.ir,
-      root: admission.root,
-      schemaMode: admission.status === 'admitted' ? 'canonical-admitted' : 'canonical-preview',
-      revision: admission.revision,
+      ir: extraction.ir,
+      root: extraction.root,
+      schemaMode: extraction.status === 'admitted' ? 'canonical-admitted' : 'canonical-preview',
+      revision: extraction.revision,
     }),
   )
 }

package/studio/server/introspect/overlay-tsmorph.test.ts

@@ -5,7 +5,7 @@ import { join } from 'node:path'
 
 import type { SchemaIR } from '../../shared/types'
 
-import { buildHandlerLinks, buildSchemaAnnotations, buildSourceSpans } from './overlay-tsmorph'
+import { buildHandlerLinks, buildSourceSpans } from './overlay-tsmorph'
 
 const roots: string[] = []
 afterEach(() => {
@@ -139,8 +139,4 @@ describe('source overlay', () => {
     expect(spans['edge.assigned_to.property.note']?.file).toBe('schema/members.ts')
     expect(spans['function.createIssue']?.file).toBe('schema/members.ts')
   })
-
-  test('does not invent warnings for admitted enum values', () => {
-    expect(buildSchemaAnnotations({ ir })).toEqual([])
-  })
 })

package/studio/server/introspect/overlay-tsmorph.ts

@@ -4,6 +4,5 @@
  * Keep this path stable for the overlay composer and focused tests. The
  * implementation lives under source-overlay, split by responsibility.
  */
-export { buildSchemaAnnotations } from './source-overlay/annotations'
 export { buildHandlerLinks } from './source-overlay/handlers'
 export { buildSourceSpans } from './source-overlay/spans'

package/studio/server/introspect/overlay.ts

@@ -1,12 +1,9 @@
 /**
- * overlay.ts — the Studio overlay over the DSL IR. Computes what the IR cannot
- * carry. The import split and dependency list are computed here; handlerLinks,
- * static parse). handlerLinks, sourceSpans (+JSDoc) and annotations are filled
- * by a ts-morph pass over current Schema, Runtime, Action, and Workflow files.
+ * Source-only metadata that the admitted DSL Schema cannot carry.
  */
-import type { CrossDomainImport, SchemaIR, SchemaOverlay } from '../../shared/types'
+import type { SchemaIR, SchemaOverlay } from '../../shared/types'
 
-import { buildHandlerLinks, buildSchemaAnnotations, buildSourceSpans } from './overlay-tsmorph'
+import { buildHandlerLinks, buildSourceSpans } from './overlay-tsmorph'
 
 export interface OverlayArgs {
   ir: SchemaIR | null
@@ -15,26 +12,8 @@ export interface OverlayArgs {
 }
 
 export function buildOverlay({ ir, domainRoot, schemaDir }: OverlayArgs): SchemaOverlay {
-  const origin = ir?.domain ?? ''
-  const mixins: CrossDomainImport[] = []
-  const crossDomainImports: CrossDomainImport[] = []
-  for (const descriptor of Object.values(ir?.importsByKey ?? {})) {
-    const entry: CrossDomainImport = {
-      name: descriptor.ref.name,
-      origin: descriptor.origin,
-      ref: descriptor.ref,
-    }
-    if (descriptor.origin === 'kernel.astrale.ai') mixins.push(entry)
-    else crossDomainImports.push(entry)
-  }
-
   return {
-    origin,
-    requires: (ir?.dependencies ?? []).map(({ origin }) => origin),
-    crossDomainImports,
-    mixins,
     handlerLinks: buildHandlerLinks({ ir, domainRoot }),
     sourceSpans: buildSourceSpans({ ir, schemaDir }),
-    annotations: buildSchemaAnnotations({ ir }),
   }
 }

package/studio/server/introspect/revision.test.ts

@@ -1,53 +1,49 @@
+import * as sdk from '@astrale-os/sdk/schema'
+import { defineSchema } from '@astrale-os/sdk/schema'
 import { describe, expect, test } from 'bun:test'
 
 import { admittedBundleRevisionFromSdk } from './revision'
 
-const REVISION = `sha256:${'a'.repeat(64)}` as const
+const schema = defineSchema('notes.example.dev', {})
+const wire = JSON.parse(JSON.stringify(sdk.bundle.create(schema)))
 
 describe('installed Bundle revision', () => {
-  test('uses bundle admission before asking the installed schema owner for its revision', () => {
+  test('uses Bundle admission and the resolved Domain identity', () => {
     const calls: string[] = []
-    const root = { format: 'astrale.dsl', version: 'v1', origin: 'notes.example.dev' }
-    const input = { wire: true }
-    const sdk = {
+    const wrapped = {
+      ...sdk,
       bundle: {
+        ...sdk.bundle,
         accept(value: unknown) {
           calls.push('bundle.accept')
-          expect(value).toBe(input)
-          return { root, closure: [] }
+          return sdk.bundle.accept(value)
         },
       },
       schema: {
-        revision(value: unknown) {
-          calls.push('schema.revision')
-          expect(value).toBe(root)
-          return REVISION
+        ...sdk.schema,
+        resolve(value: typeof schema) {
+          calls.push('schema.resolve')
+          return sdk.schema.resolve(value)
         },
       },
-    }
+    } as unknown as typeof sdk
 
-    expect(admittedBundleRevisionFromSdk(sdk, input)).toBe(REVISION)
-    expect(calls).toEqual(['bundle.accept', 'schema.revision'])
+    expect(admittedBundleRevisionFromSdk(wrapped, wire)).toBe(sdk.schema.revision(schema))
+    expect(calls).toEqual(['bundle.accept', 'schema.resolve'])
   })
 
-  test('fails closed when bundle admission or the returned revision is invalid', () => {
-    expect(
-      admittedBundleRevisionFromSdk(
-        { bundle: { accept: () => ({ root: {} }) }, schema: { revision: () => 'sha-short' } },
-        {},
-      ),
-    ).toBeNull()
+  test('fails closed when Bundle admission or the resolved identity is invalid', () => {
+    expect(admittedBundleRevisionFromSdk({} as typeof sdk, {})).toBeNull()
     expect(
       admittedBundleRevisionFromSdk(
         {
-          bundle: {
-            accept: () => {
-              throw new Error('invalid bundle')
-            },
+          ...sdk,
+          schema: {
+            ...sdk.schema,
+            resolve: () => ({ source: schema, revision: 'sha-short' }),
           },
-          schema: { revision: () => REVISION },
-        },
-        {},
+        } as unknown as typeof sdk,
+        wire,
       ),
     ).toBeNull()
   })

package/studio/server/introspect/revision.ts

@@ -1,28 +1,23 @@
 import type { SchemaRevision } from '../../shared/types'
+import type { SchemaAdmissionSdk } from './canonical-schema'
 
 import { isSchemaRevision } from '../../shared/types'
 
-type AnyRecord = Record<string, unknown>
-
 /**
  * Cross the installed-bundle JSON boundary through the Domain's installed SDK, then
  * ask the DSL owner for the root revision. Invalid/unavailable bundles return
  * null so Studio reports unknown drift instead of inventing an identity.
  */
 export function admittedBundleRevisionFromSdk(
-  sdkModule: Record<string, unknown>,
+  sdk: SchemaAdmissionSdk,
   input: unknown,
 ): SchemaRevision | null {
-  const bundleApi = asRecord(sdkModule.bundle)
-  const schemaApi = asRecord(sdkModule.schema)
-  if (typeof bundleApi?.accept !== 'function' || typeof schemaApi?.revision !== 'function') {
-    return null
-  }
   try {
-    const accepted = asRecord(Reflect.apply(bundleApi.accept, bundleApi, [input]))
-    if (!accepted || !Object.prototype.hasOwnProperty.call(accepted, 'root')) return null
-    const revision = Reflect.apply(schemaApi.revision, schemaApi, [accepted.root])
-    return isSchemaRevision(revision) ? revision : null
+    const accepted = sdk.bundle.accept(input)
+    const domain = sdk.schema.resolve(accepted.root)
+    return domain.source === accepted.root && isSchemaRevision(domain.revision)
+      ? domain.revision
+      : null
   } catch {
     return null
   }
@@ -33,17 +28,11 @@ export async function admittedBundleRevision(
   input: unknown,
 ): Promise<SchemaRevision | null> {
   try {
-    const sdkModule: Record<string, unknown> = await import(
+    const sdk = (await import(
       Bun.resolveSync('@astrale-os/sdk/schema', domainRoot)
-    )
-    return admittedBundleRevisionFromSdk(sdkModule, input)
+    )) as unknown as SchemaAdmissionSdk
+    return admittedBundleRevisionFromSdk(sdk, input)
   } catch {
     return null
   }
 }
-
-function asRecord(value: unknown): AnyRecord | null {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
-    ? (value as AnyRecord)
-    : null
-}

package/studio/server/introspect/runtime.test.ts

@@ -6,9 +6,10 @@ import { join } from 'node:path'
 import type { DomainHandle } from '../domain'
 
 import { buildBundle } from './bundle'
+import { buildCore } from './core'
 import { renderFingerprintOf } from './hash'
 import { admittedBundleRevision } from './revision'
-import { coreExtract, runtimeExtract } from './runtime'
+import { runtimeExtract } from './runtime'
 
 const roots: string[] = []
 afterEach(() => {
@@ -128,19 +129,18 @@ describe('SDK V1 schema extractor', () => {
 
   test('extracts Core through the pure Schema entry without importing Application', async () => {
     const handle = currentFixture()
-    expect(await coreExtract(handle.schemaIndex, handle.root)).toEqual({
-      ok: true,
-      core: {
-        domain: 'documents.runtime.test',
-        nodes: [
-          {
-            path: '/:documents.runtime.test:core.welcome',
-            className: 'Document',
-            data: {},
-          },
-        ],
-        edges: [],
-      },
+    const bundle = await buildBundle(handle)
+    expect(buildCore(handle, bundle)).toMatchObject({
+      domain: 'documents.runtime.test',
+      nodes: [
+        {
+          path: '/:documents.runtime.test:core.welcome',
+          className: 'Document',
+          data: {},
+        },
+      ],
+      edges: [],
+      error: null,
     })
   })
 })

package/studio/server/introspect/runtime.ts

@@ -5,12 +5,11 @@
  * render IR plus the raw canonical root (when present), or an error render-state
  * — never throws.
  */
-import type { SchemaIR, SchemaRevision, StudioCore, StudioSchemaBundle } from '../../shared/types'
+import type { SchemaIR, SchemaRevision, StudioSchemaBundle } from '../../shared/types'
 
 import { isSchemaRevision } from '../../shared/types'
 
 const EXTRACTOR = new URL('./extractor.ts', import.meta.url).pathname
-const CORE_EXTRACTOR = new URL('./core-extractor.ts', import.meta.url).pathname
 
 export interface RuntimeExtractResult {
   ok: boolean
@@ -94,47 +93,3 @@ export async function runtimeExtract(
     }
   }
 }
-
-export interface CoreExtractResult {
-  ok: boolean
-  /** the resolved core graph, or null when the domain defines no core */
-  core: Pick<StudioCore, 'domain' | 'nodes' | 'edges'> | null
-  error?: { message: string }
-}
-
-/**
- * Spawn the Core extractor over the pure Schema entry. Returns the projected
- * graph or an error and never imports Application or Runtime modules.
- */
-export async function coreExtract(
-  schemaIndexPath: string,
-  domainDir: string,
-  timeoutMs = 20000,
-): Promise<CoreExtractResult> {
-  try {
-    const proc = Bun.spawn(['bun', 'run', CORE_EXTRACTOR, schemaIndexPath, domainDir], {
-      cwd: domainDir,
-      stdout: 'pipe',
-      stderr: 'pipe',
-    })
-    const timer = setTimeout(() => proc.kill(9), timeoutMs)
-    const out = await new Response(proc.stdout).text()
-    await proc.exited
-    clearTimeout(timer)
-
-    if (!out.trim()) {
-      const err = await new Response(proc.stderr).text()
-      return {
-        ok: false,
-        core: null,
-        error: { message: err.trim() || 'core extractor produced no output' },
-      }
-    }
-    const parsed = JSON.parse(out)
-    if (!parsed.ok)
-      return { ok: false, core: null, error: parsed.error ?? { message: 'core extraction failed' } }
-    return { ok: true, core: (parsed.core ?? null) as CoreExtractResult['core'] }
-  } catch (e: any) {
-    return { ok: false, core: null, error: { message: String(e?.message ?? e) } }
-  }
-}

package/studio/server/lifecycle.ts

@@ -9,6 +9,7 @@ import type { DomainHandle } from './domain'
  */
 import { getBundle } from './cache'
 import { captureBaseline, hashAnatomyFiles, loadBaseline } from './state/baseline'
+import { migrateDocuments } from './state/documents'
 import { initDotDir } from './state/store'
 import { watchDomain } from './watch'
 
@@ -22,6 +23,8 @@ export interface BootedDomain {
 /** Initialize + start watching one domain. Returns its origin + a stop handle. */
 export async function bootDomain(handle: DomainHandle): Promise<BootedDomain> {
   initDotDir(handle.root)
+  // one-shot: uuid-named documents become readable file names under context/docs
+  migrateDocuments(handle.root)
   const bundle = await getBundle(handle.id)
   if (!loadBaseline(handle.root))
     captureBaseline(
@@ -35,7 +38,7 @@ export async function bootDomain(handle: DomainHandle): Promise<BootedDomain> {
     )
   const stop = watchDomain(handle)
   return {
-    origin: bundle?.overlay.origin ?? handle.id,
+    origin: bundle?.ir?.domain ?? handle.origin ?? handle.id,
     depsInstalled: !!bundle?.depsInstalled,
     stop,
   }

package/studio/server/state/documents.test.ts

@@ -0,0 +1,69 @@
+import { afterEach, expect, test } from 'bun:test'
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { addDocument, listDocuments, migrateDocuments, readDocument } from './documents'
+import { statePath, writeJson, writeStateBuffer } from './store'
+
+const roots: string[] = []
+
+function root(): string {
+  const created = mkdtempSync(join(tmpdir(), 'studio-documents-'))
+  roots.push(created)
+  return created
+}
+
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+const bytes = (text: string) => new TextEncoder().encode(text)
+
+test('a document is stored under a readable name, not its id', () => {
+  const domain = root()
+  const meta = addDocument(domain, 'Pricing Decisions.MD', 'text/markdown', bytes('# pricing'))
+
+  expect(meta.stored).toBe('context/docs/pricing-decisions.md')
+  expect(readFileSync(statePath(domain, meta.stored), 'utf8')).toBe('# pricing')
+  expect(readDocument(domain, meta.id)?.meta.name).toBe('Pricing Decisions.MD')
+})
+
+test('same-named documents never overwrite each other', () => {
+  const domain = root()
+  const first = addDocument(domain, 'notes.md', 'text/markdown', bytes('first'))
+  const second = addDocument(domain, 'notes.md', 'text/markdown', bytes('second'))
+
+  expect([first.stored, second.stored]).toEqual([
+    'context/docs/notes.md',
+    'context/docs/notes-2.md',
+  ])
+  expect(readFileSync(statePath(domain, first.stored), 'utf8')).toBe('first')
+})
+
+test('uuid-named documents are migrated in place, once', () => {
+  const domain = root()
+  const legacy = 'context/documents/2b0d9d7e-1f2a-4a10-9f0c-1a2b3c4d5e6f.md'
+  writeStateBuffer(domain, legacy, bytes('legacy body'))
+  writeJson(domain, 'context/documents/index.json', [
+    {
+      id: '2b0d9d7e-1f2a-4a10-9f0c-1a2b3c4d5e6f',
+      name: 'Meeting notes.md',
+      type: 'text/markdown',
+      size: 11,
+      addedAt: new Date(0).toISOString(),
+      stored: legacy,
+    },
+  ])
+
+  migrateDocuments(domain)
+  const [migrated] = listDocuments(domain)
+
+  expect(migrated?.stored).toBe('context/docs/meeting-notes.md')
+  expect(readFileSync(statePath(domain, migrated!.stored), 'utf8')).toBe('legacy body')
+  expect(existsSync(statePath(domain, legacy))).toBe(false)
+
+  // idempotent: a second boot leaves the already-migrated store alone
+  migrateDocuments(domain)
+  expect(listDocuments(domain)[0]?.stored).toBe('context/docs/meeting-notes.md')
+})

package/studio/server/state/documents.ts

@@ -1,10 +1,11 @@
 /**
- * documents.ts — context DOCUMENTS the user drops in for the AI agent. Files are
- * stored under `.domain-studio/context/documents/` (allow-listed) and tracked in
- * an index. They travel with the domain and are part of the agent handoff context.
+ * documents.ts — context DOCUMENTS the user drops in for the AI agent. Files live
+ * under `.domain-studio/context/docs/`, named after the document (not its id), so
+ * the folder is readable by a human and by the agent that is handed its path.
+ * They travel with the domain and are part of the agent handoff context.
  */
 import { randomUUID } from 'node:crypto'
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { extname } from 'node:path'
 
 import type { DocMeta } from '../../shared/types'
@@ -13,7 +14,54 @@ import { asFiniteNumber, asJsonRecord, asString } from '../json'
 import { readJson, removeState, statePath, writeJson, writeStateBuffer } from './store'
 
 const INDEX = 'context/documents/index.json'
-const storedPath = (id: string, name: string) => `context/documents/${id}${extname(name)}`
+const DIR = 'context/docs'
+/** Where documents lived before they were named: `context/documents/<uuid>.<ext>`. */
+const LEGACY_DIR = 'context/documents'
+
+/** `Pricing decisions.md` → `pricing-decisions` — a file name you can read. */
+function slugify(name: string): string {
+  const base = name.replace(/\.[^.]+$/, '')
+  const slug = base
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60)
+  return slug || 'document'
+}
+
+/** A stored path no other document (and no file on disk) already claims. */
+function uniqueStoredPath(root: string, docs: DocMeta[], name: string): string {
+  const extension = extname(name).toLowerCase()
+  const slug = slugify(name)
+  const taken = new Set(docs.map((doc) => doc.stored))
+  for (let attempt = 0; ; attempt++) {
+    const candidate = `${DIR}/${slug}${attempt === 0 ? '' : `-${attempt + 1}`}${extension}`
+    if (!taken.has(candidate) && !existsSync(statePath(root, candidate))) return candidate
+  }
+}
+
+/**
+ * Move documents written under the old uuid-named layout into `context/docs/`.
+ * Idempotent and only ever renames inside the studio's own state directory.
+ */
+export function migrateDocuments(root: string): void {
+  const docs = listDocuments(root)
+  if (!docs.some((doc) => doc.stored.startsWith(`${LEGACY_DIR}/`))) return
+  let moved = false
+  for (const doc of docs) {
+    if (!doc.stored.startsWith(`${LEGACY_DIR}/`)) continue
+    const from = statePath(root, doc.stored)
+    if (!existsSync(from)) continue
+    const next = uniqueStoredPath(root, docs, doc.name)
+    writeStateBuffer(root, next, readFileSync(from))
+    removeState(root, doc.stored)
+    doc.stored = next
+    moved = true
+  }
+  if (moved) writeJson(root, INDEX, docs)
+}
 
 function decodeDocument(value: unknown): DocMeta | undefined {
   const record = asJsonRecord(value)
@@ -30,7 +78,7 @@ function decodeDocument(value: unknown): DocMeta | undefined {
     size === undefined ||
     size < 0 ||
     !addedAt ||
-    !stored?.startsWith('context/documents/') ||
+    !(stored?.startsWith(`${DIR}/`) || stored?.startsWith(`${LEGACY_DIR}/`)) ||
     stored.split('/').includes('..')
   ) {
     return undefined
@@ -60,18 +108,17 @@ export function listDocuments(root: string): DocMeta[] {
 }
 
 export function addDocument(root: string, name: string, type: string, data: Uint8Array): DocMeta {
-  const id = randomUUID()
-  const stored = storedPath(id, name)
+  const docs = listDocuments(root)
+  const stored = uniqueStoredPath(root, docs, name || 'untitled')
   writeStateBuffer(root, stored, data)
   const meta: DocMeta = {
-    id,
+    id: randomUUID(),
     name: name || 'untitled',
     type: type || 'application/octet-stream',
     size: data.byteLength,
     addedAt: new Date().toISOString(),
     stored,
   }
-  const docs = listDocuments(root)
   docs.unshift(meta)
   writeJson(root, INDEX, docs)
   return meta

package/studio/server/workspace/updates.ts

@@ -3,7 +3,7 @@
  *
  * We don't reimplement staleness: the `astrale` CLI owns it. `astrale update
  * --check --json`, run in the DOMAIN ROOT (so its @astrale-os/* SDK-dep axis sees
- * THIS project), emits a unified `{ stale, cli, sdk }` report. We run it with
+ * THIS project), emits a unified `{ stale, cli, skills, sdk }` report. We run it with
  * stdout piped and read it regardless of exit code — a stale result exits 10 by
  * design, which is not an error here. Best-effort: anything unexpected (no
  * bad output) collapses to "nothing stale" so the badge stays
@@ -16,6 +16,7 @@ import { decodeJsonObject, runStudioCliJson, runStudioCliText } from '../cli'
 const NOT_STALE: StaleReport = {
   stale: false,
   cli: { stale: false, managed: true },
+  skills: { status: 'current' },
   sdk: { stale: false, inProject: false, outdated: [] },
 }
 
@@ -30,6 +31,7 @@ export async function getUpdates(root: string): Promise<StaleReport> {
 function decodeStaleReport(value: unknown): StaleReport | null {
   const report = decodeJsonObject(value)
   const cli = decodeJsonObject(report?.cli)
+  const skills = decodeJsonObject(report?.skills)
   const sdk = decodeJsonObject(report?.sdk)
   if (
     typeof report?.stale !== 'boolean' ||
@@ -50,6 +52,22 @@ function decodeStaleReport(value: unknown): StaleReport | null {
       : []
   })
   if (outdated.length !== sdk.outdated.length) return null
+  const skillStatuses = new Set([
+    'current',
+    'update-available',
+    'repair-needed',
+    'unavailable',
+    'skipped',
+  ])
+  // Additive compatibility: Studio can briefly run a newer server against an
+  // older CLI report while a binary update is being applied.
+  const skillStatus =
+    skills === null || skills === undefined
+      ? 'current'
+      : typeof skills.status === 'string' && skillStatuses.has(skills.status)
+        ? (skills.status as StaleReport['skills']['status'])
+        : null
+  if (skillStatus === null) return null
   return {
     stale: report.stale,
     cli: {
@@ -59,6 +77,10 @@ function decodeStaleReport(value: unknown): StaleReport | null {
       ...(typeof cli.latest === 'string' ? { latest: cli.latest } : {}),
       ...(typeof cli.channel === 'string' ? { channel: cli.channel } : {}),
     },
+    skills: {
+      status: skillStatus,
+      ...(typeof skills?.error === 'string' ? { error: skills.error } : {}),
+    },
     sdk: { stale: sdk.stale, inProject: sdk.inProject, outdated },
   }
 }

package/studio/shared/contracts/runtime.ts

@@ -42,6 +42,10 @@ export interface StudioSettings {
 export interface StaleReport {
   stale: boolean
   cli: { stale: boolean; managed: boolean; current?: string; latest?: string; channel?: string }
+  skills: {
+    status: 'current' | 'update-available' | 'repair-needed' | 'unavailable' | 'skipped'
+    error?: string
+  }
   sdk: {
     stale: boolean
     inProject: boolean