@aperant/framework 0.8.1 → 0.8.6

package/src/cli/install/runtime-migrate.mjs

@@ -2,15 +2,14 @@
  * install/runtime-migrate.mjs — at-install cleanup of legacy install
  * trees the framework no longer owns (FRAMEWORK-BUG-021).
  *
- * Codex was originally installed into `.agents/skills/` (commit 1a8dd8a8)
- * and later moved to `.codex/`. Projects that upgraded across that move
- * end up with a stale `.agents/skills/` tree that:
- *
- *   - keeps `.apt-version` on disk → the legacy fallback in
- *     `readSkillInstallState` reports a stale codex install.
- *   - shows up in `health-check` as `stale-skills`.
- *   - leaves dozens of orphaned SKILL.md files the runtime no longer
- *     reads.
+ * Codex shuffled install roots twice:
+ *   - Pre-0.7: installed at `.agents/skills/` (commit 1a8dd8a8).
+ *   - v0.7/v0.8: moved to `.codex/agents/` + `.codex/commands/` — a
+ *     misdirect, since Codex CLI 0.132.0 doesn't discover skills there.
+ *   - v0.8.2 (this fix): moved back to `.agents/skills/<folder>/SKILL.md`
+ *     (Codex's documented surface). The v0.7/v0.8 `.codex/` markdown
+ *     tree is now the legacy target — `LEGACY_INSTALL_PATHS.codex` was
+ *     re-pointed accordingly.
  *
  * `runLegacyCleanup` runs once per `apt-tools init` when codex is in the
  * requested runtime set. It is conservative by default:
@@ -20,8 +19,11 @@
  *     preserved. If anything beyond the known framework set remains,
  *     `retained[]` lists those paths.
  *   - A present-and-current `apt-file-manifest.json` is treated as the
- *     authoritative "this is a managed install, leave it alone" signal:
- *     the function no-ops with `reason: 'managed'`.
+ *     authoritative "this is a managed install, leave it alone" signal
+ *     — but ONLY when the legacy entry has `honor_manifest: true` (the
+ *     default). When `honor_manifest: false` (the current codex entry,
+ *     because `.codex/` is known-dead), the manifest is removed alongside
+ *     framework files.
  *   - The caller can suppress cleanup entirely via `--keep-legacy` at the
  *     init.mjs site; the function itself is dumb about flags.
  */
@@ -33,7 +35,8 @@ import { MANIFEST_FILENAME } from './manifest.mjs'
 
 /**
  * @typedef {Object} LegacyCodexDetection
- * @property {boolean} present              True when `.agents/skills/` exists.
+ * @property {boolean} present              True when the legacy install_root
+ *                                          (currently `.codex/`) exists.
  * @property {string[]} frameworkFiles      Subset of `framework_files` that
  *                                          actually exist on disk (relative
  *                                          to install_root).
@@ -46,9 +49,15 @@ import { MANIFEST_FILENAME } from './manifest.mjs'
  *                                          stamp is present.
  * @property {boolean} hasManifest          Whether an
  *                                          `apt-file-manifest.json` is
- *                                          present at install_root (signals
- *                                          a managed install — cleanup
- *                                          should no-op).
+ *                                          present at install_root. When the
+ *                                          legacy entry has
+ *                                          `honor_manifest: true` (default)
+ *                                          this signals a managed install
+ *                                          and cleanup no-ops; when
+ *                                          `honor_manifest: false` the
+ *                                          manifest is treated as orphan
+ *                                          and removed alongside framework
+ *                                          files.
  */
 
 const LEGACY = LEGACY_INSTALL_PATHS.codex
@@ -93,7 +102,9 @@ function walkRelative(dir) {
 }
 
 /**
- * Probe the codex legacy install tree at `<targetDir>/.agents/skills/`.
+ * Probe the codex legacy install tree at `<targetDir>/<LEGACY.install_root>`
+ * (currently `.codex/` after the v0.8.2 registry inversion — the v0.7/v0.8
+ * misdirect topology).
  *
  * @param {string} targetDir
  * @returns {LegacyCodexDetection}
@@ -142,25 +153,36 @@ function rmEmptyDir(dir) {
 }
 
 /**
- * Clean up the legacy `.agents/skills/` tree if it looks orphaned.
+ * Clean up the legacy install tree at `<targetDir>/<LEGACY.install_root>`
+ * if it looks orphaned. Post v0.8.2 the codex legacy root is `.codex/`
+ * with framework files at `agents/<file>.md` + `commands/<file>.md` +
+ * `apt-file-manifest.json`.
  *
  * Branches:
  *   1. `present: false` OR `frameworkFiles.length === 0` → no-op,
  *      `{ ran: false, reason: 'no-legacy' }`.
- *   2. `hasManifest: true` → managed install, no-op,
- *      `{ ran: false, reason: 'managed' }`.
+ *   2. `hasManifest: true` AND `LEGACY.honor_manifest !== false`
+ *      (default true) → managed install, no-op,
+ *      `{ ran: false, reason: 'managed' }`. When `honor_manifest: false`
+ *      (known-dead surface like the v0.7/v0.8 codex misdirect) the
+ *      manifest is treated as orphan and removed alongside framework
+ *      files.
  *   3. Otherwise: per-file `unlinkSync` each framework-owned file;
- *      `rmdirSync` any now-empty `apt-*` subdirectory; sweep
- *      `.agents/skills/` only if it is empty; sweep `.agents/` only if
- *      its `skills/` got removed and `.agents/` is empty.
+ *      `rmdirSync` any subdirectory left empty after the unlinks (e.g.
+ *      `.codex/agents/`, `.codex/commands/`); sweep the install_root
+ *      itself only if it is fully empty after the per-file pass; sweep
+ *      the install_root's parent only if it too became empty (relevant
+ *      for legacy topologies two levels deep, e.g. the pre-0.7
+ *      `.agents/skills/` codex layout).
  *
  * Returns `{ ran: true, removed, retained, rmdirs }` on the cleanup
  * branch:
  *   - `removed`  — relative paths under `install_root` that were unlinked.
  *   - `retained` — relative paths under `install_root` that were NOT
- *     removed (user-added skills / files not in the legacy set).
- *   - `rmdirs`   — absolute paths of directories that were removed
- *     (apt-* subdirs, the install_root itself, .agents/), in removal order.
+ *     removed (user-added skills / files not in the legacy set, e.g.
+ *     `.codex/config.toml`).
+ *   - `rmdirs`   — absolute paths of directories that were removed,
+ *     in removal order.
  *
  * Atomicity: per-file unlink is non-atomic. A partial-failure scenario
  * (process killed mid-loop) is tolerable — the next `init` run will
@@ -178,7 +200,14 @@ export function runLegacyCleanup({ targetDir, dryRun = false }) {
 	if (!detection.present || detection.frameworkFiles.length === 0) {
 		return { ran: false, reason: 'no-legacy' }
 	}
-	if (detection.hasManifest) {
+	// `honor_manifest: false` means the legacy install_root is a known-dead
+	// surface (the v0.7/v0.8 codex misdirect). A manifest sitting there is
+	// by definition stale — fall through and remove it alongside framework
+	// files. `honor_manifest: true` (default) preserves the managed-install
+	// safety for legacy roots that could legitimately re-host a managed
+	// install.
+	const honorManifest = LEGACY.honor_manifest !== false
+	if (detection.hasManifest && honorManifest) {
 		return { ran: false, reason: 'managed' }
 	}
 
@@ -233,12 +262,16 @@ export function runLegacyCleanup({ targetDir, dryRun = false }) {
 		if (rmEmptyDir(abs)) rmdirs.push(abs)
 	}
 
-	// Sweep `.agents/skills/` only if fully empty after the per-file
-	// pass — preserves any user-added skill dirs.
+	// Sweep the legacy install_root only if fully empty after the per-file
+	// pass — preserves any user-added content under it (e.g. `.codex/config.toml`
+	// when LEGACY.install_root is `.codex/`).
 	if (rmEmptyDir(installRoot)) {
 		rmdirs.push(installRoot)
-		// Sweep `.agents/` only if it became empty too (i.e. no other
-		// `.agents/<sibling>` content the user keeps there).
+		// Sweep the install_root's parent only if it became empty too
+		// (relevant for legacy topologies whose install_root sits two
+		// levels deep, e.g. the pre-0.7 `.agents/skills/` codex layout).
+		// No-op when install_root is a top-level dir like `.codex/` —
+		// rmEmptyDir refuses to remove a non-empty project root.
 		const agentsRoot = dirname(installRoot)
 		if (rmEmptyDir(agentsRoot)) rmdirs.push(agentsRoot)
 	}

package/src/cli/install/transforms/codex.mjs

@@ -2,13 +2,18 @@
  * install/transforms/codex.mjs — Codex transform.
  *
  * Codex quirks:
- *   - frontmatter strips `tools` and `color` (Codex validates strictly and
- *     rejects unknown/style-only keys).
+ *   - frontmatter is whitelisted to `KEEP = {name, description}` (Codex
+ *     validates strictly against its `allowed_properties` set and rejects
+ *     unknown keys; the whitelist is drift-proof against new framework
+ *     frontmatter keys).
  *   - body is wrapped in <codex_agent_role>…</codex_agent_role>.
  *   - slash-command refs `/apt:foo` rewritten to `/apt-foo` (Codex command
  *     names disallow `:`).
- *   - output: .codex/agents/<name>.md AND .codex/commands/<name>.md (some
- *     skills register both as agent + invocable command).
+ *   - output: skills/<folder>/SKILL.md (the documented Codex discovery
+ *     surface per https://developers.openai.com/codex/skills — resolved
+ *     against installRoot `.agents` to land at `.agents/skills/<folder>/SKILL.md`).
+ *     Markdown agents are NOT a Codex surface (custom-agents are TOML
+ *     under `.codex/agents/`); only skills are emitted.
  */
 
 import { basename, dirname } from 'node:path'
@@ -16,11 +21,16 @@ import {
 	parseFrontmatter,
 	rewriteCommandRefs,
 	serializeFrontmatter,
-	stripFields,
 	substituteVersion,
 } from './_shared.mjs'
 
-const STRIP = ['tools', 'color']
+// Codex's `allowed_properties` set (see
+// ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py:40):
+// {"name", "description", "license", "allowed-tools", "metadata"}.
+// We use the minimum viable whitelist {name, description} so adding new
+// framework frontmatter keys (a routine occurrence) doesn't break Codex
+// validation — only the 2 keys Codex actually consumes are emitted.
+const KEEP = ['name', 'description']
 
 /**
  * @param {import('../pipeline.mjs').TransformInput} input
@@ -31,7 +41,10 @@ export function transform({ canonicalContent, canonicalRelPath, version, fileTyp
 	const parsed = parseFrontmatter(subbed)
 	let payload
 	if (parsed.hasFrontmatter && parsed.fm) {
-		stripFields(parsed.fm, STRIP)
+		// Whitelist filter: drop every frontmatter key NOT in KEEP.
+		for (const k of Object.keys(parsed.fm)) {
+			if (!KEEP.includes(k)) delete parsed.fm[k]
+		}
 		const wrappedBody = `<codex_agent_role>\n${parsed.body}\n</codex_agent_role>\n`
 		payload = serializeFrontmatter({ ...parsed, body: wrappedBody })
 	} else {
@@ -41,16 +54,12 @@ export function transform({ canonicalContent, canonicalRelPath, version, fileTyp
 
 	if (fileType === 'skill') {
 		const folder = basename(dirname(canonicalRelPath))
-		// Skills emit BOTH an agent definition (for invocation context) and a
-		// command (so the user can type `/apt-foo` directly in Codex).
-		return [
-			{ outputPath: `agents/${folder}.md`, content: payload },
-			{ outputPath: `commands/${folder}.md`, content: payload },
-		]
-	}
-	if (fileType === 'agent') {
-		const file = basename(canonicalRelPath, '.md')
-		return [{ outputPath: `agents/${file}.md`, content: payload }]
+		// Codex's documented skill discovery surface is `.agents/skills/<folder>/SKILL.md`
+		// (one folder per skill, canonical SKILL.md filename).
+		return [{ outputPath: `skills/${folder}/SKILL.md`, content: payload }]
 	}
+	// Markdown agents are not a Codex surface. Codex custom-agents are TOML
+	// under `.codex/agents/`; emitting markdown there would just create
+	// another dead surface. Drop the agent branch entirely.
 	return []
 }

package/src/cli/skill-author/contract.mjs

@@ -164,9 +164,9 @@ export const SkillFrontmatterSchema = z
 		// don't immediately break skills that carry them.
 		triggers: z.array(z.string()).optional(),
 		color: z.string().optional(),
-		// Pocock adoption ST-13 (AC12): optional `produces:` field enumerates
+		// ST-13 (AC12): optional `produces:` field enumerates
 		// the content-formats a skill emits (e.g. "PRD-shaped spec.md",
-		// "vertical-slice subtasks", "Pocock-format CONTEXT.md term-block").
+		// "vertical-slice subtasks", "Aperant CONTEXT.md term-block").
 		// Consumed by `apt-tools modes list` to surface what each skill ships.
 		// Additive and backward-compatible — skills without the field default
 		// to [] in modes list output.

package/src/cli/verify-proof/audit.mjs

@@ -0,0 +1,55 @@
+/**
+ * audit.mjs — append-only JSONL audit log for driver invocations.
+ *
+ * ID-05: one file per day at .aperant/events/{YYYY-MM-DD}.jsonl.
+ * One line per driver invocation:
+ *   {ts, driver_id, version, manifest_sha256, trust_tier, sandbox_profile,
+ *    decision: "allow|deny|requires_approval",
+ *    result: "success|fail|skip"}
+ *
+ * Append-only — no rewrites. Each appendDriverEvent() opens the file in
+ * 'a' mode and writes a single line; concurrent agents may interleave
+ * lines but no line is ever overwritten.
+ */
+
+import { appendFileSync, mkdirSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+/**
+ * Compute today's events filename relative to projectDir.
+ * @param {string} projectDir
+ * @param {Date} [now]
+ * @returns {string}
+ */
+export function dailyEventsPath(projectDir, now = new Date()) {
+	const yyyy = now.getUTCFullYear()
+	const mm = String(now.getUTCMonth() + 1).padStart(2, '0')
+	const dd = String(now.getUTCDate()).padStart(2, '0')
+	return join(resolve(projectDir), '.aperant/events', `${yyyy}-${mm}-${dd}.jsonl`)
+}
+
+/**
+ * Append a driver-invocation audit line.
+ *
+ * @param {string} projectDir
+ * @param {Object} entry
+ * @param {string} entry.driver_id
+ * @param {string} entry.version
+ * @param {string} entry.manifest_sha256
+ * @param {string} entry.trust_tier
+ * @param {string} entry.sandbox_profile
+ * @param {'allow' | 'deny' | 'requires_approval'} entry.decision
+ * @param {'success' | 'fail' | 'skip'} entry.result
+ * @param {string} [entry.verb] — IDL verb invoked (optional metadata)
+ * @param {string} [entry.reason] — decision-rationale string (optional)
+ */
+export function appendDriverEvent(projectDir, entry) {
+	const path = dailyEventsPath(projectDir)
+	mkdirSync(dirname(path), { recursive: true })
+	const line = JSON.stringify({
+		ts: new Date().toISOString(),
+		kind: 'driver_invocation',
+		...entry,
+	})
+	appendFileSync(path, line + '\n', 'utf-8')
+}

package/src/cli/verify-proof/exec.mjs

@@ -0,0 +1,74 @@
+/**
+ * exec.mjs — execFile-only execution layer for local_command transports.
+ *
+ * ID-03 security invariant: drivers with `transport: { local_command }`
+ * MUST be invoked through execFile (NO shell, NO pipes, NO redirects).
+ *
+ * This module exposes ONE function — execLocalCommand — which:
+ *   1. Asserts the transport is { local_command: { binary, args[] } }
+ *      (the manifest validator already structurally enforces this; this
+ *      is defense-in-depth at runtime).
+ *   2. Rejects any args entry that is not a plain string.
+ *   3. Invokes node:child_process.execFile (NOT child_process.exec, NOT
+ *      spawn with shell:true).
+ *
+ * Grep guard (TD-05): the test verify-proof-local-command-security.test.ts
+ * statically asserts that exec.mjs imports execFile from
+ * 'node:child_process' and never references child_process.exec / spawn
+ * with shell:true.
+ */
+
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+/**
+ * Type-check that a transport is the structured local_command variant.
+ * @param {unknown} transport
+ * @returns {transport is {local_command: {binary: string, args: string[]}}}
+ */
+function isStructuredLocalCommand(transport) {
+	if (transport === null || typeof transport !== 'object' || Array.isArray(transport)) return false
+	const obj = /** @type {Record<string, unknown>} */ (transport)
+	if (obj.local_command === null || typeof obj.local_command !== 'object') return false
+	const lc = /** @type {Record<string, unknown>} */ (obj.local_command)
+	if (typeof lc.binary !== 'string') return false
+	if (!Array.isArray(lc.args)) return false
+	for (const a of lc.args) {
+		if (typeof a !== 'string') return false
+	}
+	return true
+}
+
+/**
+ * Execute a manifest's local_command transport via execFile (no shell).
+ * Throws if the transport is not the structured variant.
+ *
+ * @param {{transport: unknown}} manifest
+ * @param {string[]} [extraArgs] — appended to manifest.transport.local_command.args.
+ * @param {{cwd?: string, env?: Record<string,string>, timeout?: number}} [options]
+ * @returns {Promise<{stdout: string, stderr: string}>}
+ */
+export async function execLocalCommand(manifest, extraArgs = [], options = {}) {
+	const transport = manifest.transport
+	if (!isStructuredLocalCommand(transport)) {
+		throw new Error(
+			`execLocalCommand: transport is not a structured local_command — refusing to invoke. Got: ${JSON.stringify(transport)}`,
+		)
+	}
+	const { binary, args } = transport.local_command
+	for (const arg of extraArgs) {
+		if (typeof arg !== 'string') {
+			throw new Error(`execLocalCommand: extraArgs must be strings, got ${typeof arg}`)
+		}
+	}
+	return execFileAsync(binary, [...args, ...extraArgs], {
+		cwd: options.cwd,
+		env: options.env,
+		timeout: options.timeout,
+		// Explicit — never pass shell:true. execFile defaults to no shell, but
+		// we surface the invariant in code for grep-guard purposes.
+		shell: false,
+	})
+}

package/src/cli/verify-proof/idl/index.mjs

@@ -0,0 +1,23 @@
+/**
+ * idl/index.mjs — framework-side re-export of the IDL v1 runtime registry.
+ *
+ * Single source of truth lives at packages/framework/src/driver-sdk/idl.ts
+ * (inlined in 0.8.5 — originally `@aperant/driver-sdk`). This file
+ * re-exports those runtime values so existing callers (bundled drivers,
+ * resolver, driver-doctor, conformance kit) keep working without a
+ * refactor of every callsite.
+ *
+ * If you add a verb, edit packages/framework/src/driver-sdk/idl.ts.
+ */
+
+export {
+	ASSERTION_VERBS,
+	ASYNC_VERBS,
+	EVIDENCE_VERBS,
+	IDL_VERB_ARGS,
+	IDL_VERB_NAMES,
+	INTERACTION_VERBS,
+	isVerbResult,
+	LIFECYCLE_VERBS,
+	validateVerbArgs,
+} from '@aperant/framework/driver-sdk'

package/src/cli/verify-proof/idl/types.ts

@@ -0,0 +1,42 @@
+/**
+ * idl/types.ts — re-export the SDK's IDL types for framework-internal use.
+ *
+ * Single source of truth lives at packages/framework/src/driver-sdk/idl.ts
+ * (inlined in 0.8.5). Framework code imports from here so future moves
+ * (e.g. an internal-only IDL extension or re-extraction) only touch this
+ * re-export, not every call site.
+ */
+
+export type {
+	AssertNetworkArgs,
+	AssertOutputArgs,
+	AssertTextArgs,
+	AssertVisibleArgs,
+	AwaitSignalArgs,
+	CaptureLogsArgs,
+	ClickArgs,
+	DomDumpArgs,
+	DragDropArgs,
+	DriverModule,
+	DumpStateArgs,
+	ExecuteJsArgs,
+	Handle,
+	IdlVerbName,
+	KeyArgs,
+	LaunchArgs,
+	NavigateArgs,
+	RecordVideoArgs,
+	ScreenshotArgs,
+	SelectArgs,
+	SwipeArgs,
+	SwitchContextArgs,
+	Target,
+	TargetKind,
+	TeardownArgs,
+	TriggerArgs,
+	TypeArgs,
+	UploadFileArgs,
+	VerbResult,
+	WaitForEventArgs,
+	WaitForIdleArgs,
+} from '@aperant/framework/driver-sdk'

package/src/cli/verify-proof/manifest-schema.json

@@ -0,0 +1,212 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://aperant.dev/schemas/driver-manifest-v1.json",
+	"title": "Aperant Driver Manifest v1",
+	"description": "Structural contract for a verify-proof driver manifest. Validates at publish-time (apt-tools driver doctor) and at load-time (resolver). The transport oneOf rejects free-form shell strings — local_command MUST be a structured {binary, args[]} object per ID-03.",
+	"type": "object",
+	"required": [
+		"driverId",
+		"version",
+		"targets",
+		"capabilities",
+		"frameworkApiRange",
+		"priority",
+		"stability",
+		"trust",
+		"security",
+		"transport"
+	],
+	"properties": {
+		"driverId": {
+			"type": "string",
+			"pattern": "^[a-z][a-z0-9_-]*$"
+		},
+		"version": {
+			"type": "string"
+		},
+		"targets": {
+			"type": "array",
+			"items": { "type": "string" }
+		},
+		"capabilities": {
+			"type": "array",
+			"items": { "type": "string" }
+		},
+		"evidence_capabilities": {
+			"type": "array",
+			"items": { "type": "string" }
+		},
+		"frameworkApiRange": {
+			"type": "string"
+		},
+		"requires": {
+			"type": "object",
+			"properties": {
+				"allOf": { "type": "array", "items": { "type": "string" } },
+				"anyOf": { "type": "array", "items": { "type": "string" } }
+			}
+		},
+		"os": {
+			"type": "array",
+			"items": { "type": "string" }
+		},
+		"arch": {
+			"type": "array",
+			"items": { "type": "string" }
+		},
+		"container_support": { "type": "boolean" },
+		"conflicts_with": {
+			"type": "array",
+			"items": { "type": "string" }
+		},
+		"priority": { "type": "number" },
+		"stability": {
+			"type": "string",
+			"enum": ["experimental", "beta", "ga"]
+		},
+		"trust": {
+			"type": "object",
+			"required": ["tier"],
+			"properties": {
+				"tier": {
+					"type": "string",
+					"enum": [
+						"first_party_signed",
+						"community_verified",
+						"community_unverified",
+						"local_unverified"
+					]
+				},
+				"publisher": {
+					"type": "object",
+					"required": ["name"],
+					"properties": {
+						"name": { "type": "string" },
+						"npm_scope": { "type": "string" },
+						"github_org": { "type": "string" },
+						"verified": { "type": "boolean" }
+					}
+				},
+				"provenance": {
+					"type": "object",
+					"properties": {
+						"scheme": {
+							"type": "string",
+							"enum": ["sigstore", "npm-provenance", "gpg", "none"]
+						},
+						"identity": { "type": "string" },
+						"signature": { "type": "string" },
+						"certificate": { "type": "string" }
+					}
+				},
+				"integrity": {
+					"type": "object",
+					"properties": {
+						"manifest_sha256": { "type": "string" },
+						"artifact_digest": { "type": "string" }
+					}
+				}
+			}
+		},
+		"security": {
+			"type": "object",
+			"required": ["sandbox_profile", "network"],
+			"properties": {
+				"sandbox_profile": {
+					"type": "string",
+					"enum": ["read_only", "workspace_write", "system_write"]
+				},
+				"network": {
+					"type": "string",
+					"enum": ["deny", "allowlist", "allow"]
+				},
+				"allowed_executables": {
+					"type": "array",
+					"items": { "type": "string" }
+				},
+				"allow_shell": { "type": "boolean" },
+				"requires_user_approval": { "type": "boolean" }
+			}
+		},
+		"audit": {
+			"type": "object",
+			"required": ["log_invocations", "log_manifest_hash"],
+			"properties": {
+				"log_invocations": { "type": "boolean" },
+				"log_manifest_hash": { "type": "boolean" }
+			}
+		},
+		"preflight": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["name", "required"],
+				"properties": {
+					"name": { "type": "string" },
+					"command": {
+						"type": "object",
+						"required": ["binary", "args"],
+						"properties": {
+							"binary": { "type": "string" },
+							"args": {
+								"type": "array",
+								"items": { "type": "string" }
+							}
+						}
+					},
+					"required": { "type": "boolean" }
+				}
+			}
+		},
+		"transport": {
+			"oneOf": [
+				{
+					"type": "object",
+					"required": ["mcp_server_id"],
+					"properties": {
+						"mcp_server_id": { "type": "string" },
+						"skill_id": { "type": "string" }
+					}
+				},
+				{
+					"type": "object",
+					"required": ["local_command"],
+					"properties": {
+						"local_command": {
+							"type": "object",
+							"required": ["binary", "args"],
+							"properties": {
+								"binary": { "type": "string" },
+								"args": {
+									"type": "array",
+									"items": { "type": "string" }
+								}
+							}
+						}
+					}
+				},
+				{
+					"type": "object",
+					"required": ["http_endpoint"],
+					"properties": {
+						"http_endpoint": { "type": "string" }
+					}
+				},
+				{
+					"type": "object",
+					"required": ["npm_package"],
+					"properties": {
+						"npm_package": { "type": "string" }
+					}
+				},
+				{
+					"type": "object",
+					"required": ["builtin"],
+					"properties": {
+						"builtin": { "const": true }
+					}
+				}
+			]
+		}
+	}
+}