@aperant/framework 0.10.0 → 0.12.0

package/src/cli/coordination/catch-up.mjs

@@ -0,0 +1,231 @@
+/**
+ * @internal
+ * coordination/catch-up.mjs — composes the combined catch-up panel: the
+ * Welcome-Back Summary (your own half-finished work, local-only) and the
+ * gated Team-Change Digest (what teammates merged while you were away).
+ *
+ * Composition order is fixed: welcome_back first, then team_digest (LD-10).
+ * The renderer (apt/SKILL.md) enforces display order; this module only sets
+ * the field order on the returned object.
+ *
+ * Both halves diff against one Last-Seen Marker:
+ *   - Welcome-Back fires on a staleness threshold (now - last_run_at), reads
+ *     only local state.active_tasks, and is ALWAYS-ON regardless of visibility
+ *     (LD-08/09).
+ *   - Team-Change Digest fires only when share.visibility is team/oss AND the
+ *     local default-branch sha has moved since last_main_sha (LD-04/06/07).
+ *
+ * Returns null when neither half fires. This module is `@internal` — reached
+ * via the route.mjs lazy-compute path and the apt-tools catch-up command, not
+ * from bin/apt-tools.mjs directly.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { resolveSharePolicy } from '../config/share-policy.mjs'
+import { listMergedPullRequests } from '../git/default-branch.mjs'
+import { getGitIdentity } from '../git/identity.mjs'
+import { resolveSharedRoot } from './agent-identity.mjs'
+
+const HOUR_MS = 60 * 60 * 1000
+
+/**
+ * Best-available per-task activity timestamp (ms). Prefers an explicit
+ * updated_at, then the most recent history entry, then created_at.
+ *
+ * @param {object} task
+ * @returns {number} epoch ms, or 0 when no timestamp is parseable.
+ */
+function taskActivityMs(task) {
+	const candidates = []
+	if (task?.updated_at) candidates.push(Date.parse(task.updated_at))
+	if (Array.isArray(task?.history)) {
+		for (const h of task.history) {
+			if (h?.at) candidates.push(Date.parse(h.at))
+		}
+	}
+	if (task?.created_at) candidates.push(Date.parse(task.created_at))
+	const valid = candidates.filter((n) => Number.isFinite(n))
+	return valid.length ? Math.max(...valid) : 0
+}
+
+/**
+ * A coarse "x ago" relative-time string. Kept dependency-free and stable for
+ * tests — granularity is minutes/hours/days.
+ *
+ * @param {number} deltaMs
+ * @returns {string}
+ */
+function relativeTime(deltaMs) {
+	if (!Number.isFinite(deltaMs) || deltaMs < 0) return 'just now'
+	const mins = Math.floor(deltaMs / 60000)
+	if (mins < 1) return 'just now'
+	if (mins < 60) return `${mins}m ago`
+	const hours = Math.floor(mins / 60)
+	if (hours < 24) return `${hours}h ago`
+	const days = Math.floor(hours / 24)
+	return `${days}d ago`
+}
+
+/**
+ * Read the first actionable next-step line from a task's CONTINUE note, if one
+ * exists at `.aperant/tasks/{taskId}/CONTINUE.md`. Parses the first non-empty
+ * item under the `## Next Steps` heading (the pause-note format).
+ *
+ * @param {string} sharedRoot
+ * @param {string} taskId
+ * @returns {string|null}
+ */
+function readNextStepLine(sharedRoot, taskId) {
+	if (!taskId) return null
+	const notePath = join(sharedRoot, '.aperant', 'tasks', taskId, 'CONTINUE.md')
+	if (!existsSync(notePath)) return null
+	let text
+	try {
+		text = readFileSync(notePath, 'utf-8')
+	} catch {
+		return null
+	}
+	const lines = text.split('\n')
+	const headingIdx = lines.findIndex((l) => /^##\s+Next Steps\s*$/i.test(l.trim()))
+	if (headingIdx === -1) return null
+	for (let i = headingIdx + 1; i < lines.length; i++) {
+		const raw = lines[i].trim()
+		if (raw.startsWith('##')) break // next section
+		if (raw.length === 0) continue
+		// Strip a leading list marker: "1. ", "- ", "* ".
+		const cleaned = raw.replace(/^(\d+\.|[-*])\s+/, '').trim()
+		if (cleaned.length > 0) return cleaned
+	}
+	return null
+}
+
+/**
+ * Build the Welcome-Back half from local state (LD-08/09). Returns null when
+ * the threshold has not elapsed or there is no active task.
+ *
+ * @param {object} params
+ * @param {object} params.config
+ * @param {number} params.now           epoch ms
+ * @param {object|null} params.marker
+ * @param {object|null} params.state    raw state.json (for active_tasks)
+ * @param {string} params.sharedRoot
+ * @returns {object|null}
+ */
+function buildWelcomeBack({ config, now, marker, state, sharedRoot }) {
+	const wb = config?.collaboration?.welcome_back
+	if (wb?.enabled === false) return null
+
+	const lastRunAt = marker?.last_run_at ? Date.parse(marker.last_run_at) : NaN
+	const thresholdHours = Number.isFinite(wb?.threshold_hours) ? wb.threshold_hours : 16
+	// Only fire when we have a baseline AND the gap strictly exceeds the threshold.
+	if (!Number.isFinite(lastRunAt)) return null
+	if (now - lastRunAt <= thresholdHours * HOUR_MS) return null
+
+	const activeTasks =
+		state?.active_tasks && typeof state.active_tasks === 'object' ? state.active_tasks : {}
+	const ids = Object.keys(activeTasks)
+	if (ids.length === 0) return null
+
+	// Pick the single most-recently-active task.
+	let bestId = null
+	let bestMs = -1
+	for (const id of ids) {
+		const ms = taskActivityMs(activeTasks[id])
+		if (ms > bestMs) {
+			bestMs = ms
+			bestId = id
+		}
+	}
+	if (!bestId) return null
+
+	const task = activeTasks[bestId]
+	const currentSubtask = task?.progress?.current_subtask ?? task?.current_subtask ?? null
+
+	return {
+		task_id: bestId,
+		description: task?.description ?? bestId,
+		lifecycle_phase: task?.lifecycle_phase ?? null,
+		current_subtask: currentSubtask,
+		progress: task?.progress ?? null,
+		relative_time: bestMs > 0 ? relativeTime(now - bestMs) : null,
+		next_step: readNextStepLine(sharedRoot, bestId),
+		others_count: Math.max(0, ids.length - 1),
+	}
+}
+
+/**
+ * Build the Team-Change Digest half (LD-04/06/07). Returns null when the
+ * visibility gate is closed (solo), the digest is disabled, or the
+ * default-branch sha has not moved since the marker.
+ *
+ * @param {object} params
+ * @param {string} params.projectRoot
+ * @param {object} params.config
+ * @param {object|null} params.marker
+ * @param {{ branch: string, sha: string }|null} params.defaultBranch
+ * @returns {object|null}
+ */
+function buildTeamDigest({ projectRoot, config, marker, defaultBranch }) {
+	const td = config?.collaboration?.team_digest
+	if (td?.enabled === false) return null
+
+	const visibility = resolveSharePolicy(config).visibility
+	if (visibility !== 'team' && visibility !== 'oss') return null
+
+	if (!defaultBranch?.sha) return null
+	// Only fire when main has actually moved since the recorded baseline.
+	if (marker?.last_main_sha && marker.last_main_sha === defaultBranch.sha) return null
+
+	const maxEntries = Number.isInteger(td?.max_entries) && td.max_entries > 0 ? td.max_entries : 7
+	const identity = (() => {
+		try {
+			return getGitIdentity(projectRoot)
+		} catch {
+			return null
+		}
+	})()
+
+	const { entries, more_count } = listMergedPullRequests(projectRoot, {
+		sinceSha: marker?.last_main_sha || null,
+		defaultBranch: defaultBranch.branch,
+		currentUserEmail: identity?.email || '',
+		maxEntries,
+	})
+
+	if (entries.length === 0 && more_count === 0) return null
+	return { entries, more_count }
+}
+
+/**
+ * Compose the combined catch-up panel. Returns null when neither half fires.
+ *
+ * @param {string} projectRoot
+ * @param {object} params
+ * @param {object} params.config
+ * @param {number} params.now                       epoch ms
+ * @param {object|null} params.marker               Last-Seen Marker
+ * @param {{ branch: string, sha: string }|null} params.defaultBranch
+ * @returns {{ welcome_back: object|null, team_digest: object|null }|null}
+ *
+ * @internal
+ */
+export function computeCatchUpPanel(projectRoot, { config, now, marker, defaultBranch } = {}) {
+	const sharedRoot = resolveSharedRoot(projectRoot)
+	const state = (() => {
+		const statePath = join(sharedRoot, '.aperant', 'state.json')
+		if (!existsSync(statePath)) return null
+		try {
+			return JSON.parse(readFileSync(statePath, 'utf-8'))
+		} catch {
+			return null
+		}
+	})()
+
+	const welcome_back = buildWelcomeBack({ config, now, marker, state, sharedRoot })
+	const team_digest = buildTeamDigest({ projectRoot, config, marker, defaultBranch })
+
+	if (!welcome_back && !team_digest) return null
+	// Fixed field order: welcome_back first (LD-10).
+	return { welcome_back, team_digest }
+}

package/src/cli/coordination/last-seen.mjs

@@ -0,0 +1,131 @@
+/**
+ * @internal
+ * last-seen.mjs — per-machine, per-git-identity Last-Seen Marker (LD-01).
+ *
+ * The collaboration catch-up surfaces (Welcome-Back Summary + Team-Change
+ * Digest) both diff against one baseline record per human/machine:
+ *
+ *   .aperant/last-seen/{email-slug}.json  →  { last_run_at, last_main_sha, last_active_task }
+ *
+ * The slug is derived from the git `user.email` (stable per human/machine),
+ * lowercased with every non-[a-z0-9] run collapsed to '-'. The directory is
+ * gitignored in the same per-machine ephemeral class as `team-status/` and
+ * `events/` (see upgrade-gitignore.mjs / share-policy.mjs).
+ *
+ * Modeled on team-status.mjs: resolveSharedRoot-based path so the marker lives
+ * in the main repo even when called from a worktree; atomicWriteJson +
+ * mkdirSync(recursive) for durable writes.
+ *
+ * This module is `@internal` — consumed only through the CoordinationStore
+ * seam (store.readLastSeen / store.advanceLastSeen). Do NOT import it from
+ * bin/apt-tools.mjs.
+ */
+
+import { existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { getGitIdentity } from '../git/identity.mjs'
+import { atomicWriteJson } from '../util/io.mjs'
+import { resolveSharedRoot } from './agent-identity.mjs'
+
+function lastSeenDir(projectRoot) {
+	return join(resolveSharedRoot(projectRoot), '.aperant', 'last-seen')
+}
+
+/**
+ * Slug a git email into a filesystem-safe key: lowercase, every run of
+ * non-[a-z0-9] characters collapsed to a single '-'.
+ *
+ * @param {string} email
+ * @returns {string}
+ */
+export function slugFromEmail(email) {
+	return String(email)
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, '-')
+		.replace(/^-+|-+$/g, '')
+}
+
+function markerPath(projectRoot) {
+	const identity = (() => {
+		try {
+			return getGitIdentity(projectRoot)
+		} catch {
+			return null
+		}
+	})()
+	if (!identity?.email) return null
+	const slug = slugFromEmail(identity.email)
+	if (!slug) return null
+	return join(lastSeenDir(projectRoot), `${slug}.json`)
+}
+
+/**
+ * Read the current user's Last-Seen Marker. Returns null when the git email is
+ * absent (no identity → no key) or the file does not yet exist / is malformed.
+ *
+ * @param {string} projectRoot
+ * @returns {{ last_run_at: string|null, last_main_sha: string|null, last_active_task: string|null }|null}
+ *
+ * @internal
+ */
+export function readLastSeen(projectRoot) {
+	const path = markerPath(projectRoot)
+	if (!path || !existsSync(path)) return null
+	try {
+		const record = JSON.parse(readFileSync(path, 'utf-8'))
+		if (!record || typeof record !== 'object') return null
+		return {
+			last_run_at: record.last_run_at ?? null,
+			last_main_sha: record.last_main_sha ?? null,
+			last_active_task: record.last_active_task ?? null,
+		}
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Advance the marker, merging partial fields onto any existing record.
+ *
+ * Marker-advance semantics (LD-02):
+ *   - last_run_at is always settable (it measures engagement).
+ *   - last_main_sha is optional — the caller passes it only AFTER the digest
+ *     was computed (even when empty). When undefined, the existing sha is kept.
+ *   - last_active_task is optional — the welcome-back task id, kept otherwise.
+ *
+ * No-op (returns null) when the git email is absent — there is no key to write.
+ *
+ * @param {string} projectRoot
+ * @param {{ last_run_at?: string, last_main_sha?: string|null, last_active_task?: string|null }} fields
+ * @returns {object|null} the written record, or null when there is no identity key.
+ *
+ * @internal
+ */
+export function advanceLastSeen(projectRoot, fields = {}) {
+	const path = markerPath(projectRoot)
+	if (!path) return null
+
+	let existing = {}
+	if (existsSync(path)) {
+		try {
+			existing = JSON.parse(readFileSync(path, 'utf-8')) || {}
+		} catch {
+			existing = {}
+		}
+	}
+
+	const record = {
+		last_run_at:
+			fields.last_run_at !== undefined ? fields.last_run_at : (existing.last_run_at ?? null),
+		last_main_sha:
+			fields.last_main_sha !== undefined ? fields.last_main_sha : (existing.last_main_sha ?? null),
+		last_active_task:
+			fields.last_active_task !== undefined
+				? fields.last_active_task
+				: (existing.last_active_task ?? null),
+	}
+
+	mkdirSync(lastSeenDir(projectRoot), { recursive: true })
+	atomicWriteJson(path, record)
+	return record
+}

package/src/cli/coordination/store.mjs

@@ -33,6 +33,7 @@ import { atomicWriteJson } from '../util/io.mjs'
 import { getAgentIdentity, resolveSharedRoot } from './agent-identity.mjs'
 import { appendLifecycleEvent } from './event-log.mjs'
 import { validateConductorEvent } from './event-schema.mjs'
+import { advanceLastSeen as lastSeenAdvance, readLastSeen as lastSeenRead } from './last-seen.mjs'
 import {
 	listActive as teamStatusListActive,
 	removeSelf as teamStatusRemoveSelf,
@@ -152,6 +153,23 @@ export function createCoordinationStore(projectRoot) {
 			}
 		},
 
+		/**
+		 * @internal — LD-01: read the per-machine Last-Seen Marker. Returns
+		 * null when the git email is absent or the marker has not been written.
+		 */
+		readLastSeen() {
+			return lastSeenRead(projectRoot)
+		},
+
+		/**
+		 * @internal — LD-02: advance the Last-Seen Marker. `last_run_at` is
+		 * always settable; `last_main_sha` / `last_active_task` are optional
+		 * partial fields merged onto the existing record.
+		 */
+		advanceLastSeen(fields = {}) {
+			return lastSeenAdvance(projectRoot, fields)
+		},
+
 		/** @internal */
 		getIdentity() {
 			return getAgentIdentity(projectRoot)

package/src/cli/coverage-check/user-outcomes.mjs

@@ -33,20 +33,21 @@
  * authoring contract.
  */
 
-const VALID_SURFACES = new Set(['electron', 'web', 'cli', 'api', 'electron+web'])
+const VALID_SURFACES = new Set(['electron', 'web', 'cli', 'api', 'mobile', 'electron+web'])
 
 const HEADING_RE = /^(#{1,6})\s+(.*)$/
 const USER_OUTCOMES_HEADING_RE = /^user\s+outcomes\s*$/i
 const EPIC_RE = /^\*\*Epic:\*\*\s+(.+)$/
 const EMPTY_WITH_NOTE_RE = /^_No user-observable changes — pure refactor\._\s*$/
 const OUTCOME_RE =
-	/^-\s+\*\*ON\*\*\s+\[(electron|web|cli|api|electron\+web)\]:\s+(.+?)(\s+\*\(requires\s+ON\s+(\d+)\)\*)?\s*$/
+	/^-\s+\*\*ON\*\*\s+\[(electron|web|cli|api|mobile|electron\+web)\]:\s+(.+?)(\s+\*\(requires\s+ON\s+(\d+)\)\*)?\s*$/
 
 /**
  * @typedef {Object} UserOutcome
  * @property {string} id                — synthesized positional ID (O1, O2, ...)
- * @property {('electron'|'web'|'cli'|'api'|'electron+web')} surface
+ * @property {('electron'|'web'|'cli'|'api'|'mobile'|'electron+web')} surface
  * @property {string} text              — outcome prose (sans the surface tag and requires suffix)
+ * @property {string[]} inferred        — v0.9.0 — indented child bullets under the parent outcome (raw prose, no further parsing). Defaults to [] when no children are present.
  * @property {number} [requires]        — the digit captured from `*(requires ON N)*`, when present and valid
  */
 
@@ -165,24 +166,58 @@ export function parseUserOutcomes(specContent) {
 		return result
 	}
 
-	// Parse outcome rows in document order. Skip non-matching lines (e.g.
-	// stray prose between outcomes) — they don't count as outcomes.
+	// Parse outcome rows in document order. v0.9.0 — walk the raw body lines
+	// (not the trimmed `outcomeLines`) so we preserve indentation of child
+	// bullets. A `**ON**` parent row is followed by zero or more indented
+	// child bullets (lines starting with at least 2 spaces + `- `); those
+	// children attach to the parent as `inferred: string[]` (raw prose, no
+	// further parsing). The children block ends at the next `**ON**` row,
+	// a non-indented line, or a section terminator (blank line followed by
+	// another non-bullet non-blank line is fine; the next `**ON**` always
+	// resets ownership).
 	/** @type {UserOutcome[]} */
 	const outcomes = []
 	const rawRequires = []
-	for (const line of outcomeLines) {
-		const m = line.match(OUTCOME_RE)
-		if (!m) continue
-		const surface = /** @type {UserOutcome['surface']} */ (m[1])
-		if (!VALID_SURFACES.has(surface)) continue
-		const text = m[2].trim()
-		const id = 'O' + (outcomes.length + 1)
-		const outcome = /** @type {UserOutcome} */ ({ id, surface, text })
-		if (m[4]) {
-			const n = Number.parseInt(m[4], 10)
-			rawRequires.push({ outcomeIndex: outcomes.length, requires: n })
+	const CHILD_RE = /^(?: {2}|\t)+- (.+)$/
+	let currentOutcomeIndex = -1
+	for (let i = 0; i < bodyLines.length; i++) {
+		const rawLine = bodyLines[i]
+		const trimmed = rawLine.trim()
+		if (trimmed.length === 0) {
+			// Blank lines don't close the parent — children may resume after
+			// a blank line (loose-list markdown). The next non-blank line
+			// decides ownership.
+			continue
+		}
+		const onMatch = trimmed.match(OUTCOME_RE)
+		if (onMatch) {
+			const surface = /** @type {UserOutcome['surface']} */ (onMatch[1])
+			if (!VALID_SURFACES.has(surface)) {
+				currentOutcomeIndex = -1
+				continue
+			}
+			const text = onMatch[2].trim()
+			const id = 'O' + (outcomes.length + 1)
+			const outcome = /** @type {UserOutcome} */ ({ id, surface, text, inferred: [] })
+			if (onMatch[4]) {
+				const n = Number.parseInt(onMatch[4], 10)
+				rawRequires.push({ outcomeIndex: outcomes.length, requires: n })
+			}
+			outcomes.push(outcome)
+			currentOutcomeIndex = outcomes.length - 1
+			continue
+		}
+		// Non-`**ON**` non-blank line. If it's an indented child bullet AND
+		// we have a current outcome, attach it. Otherwise (e.g. Epic line,
+		// sentinel, stray prose), drop ownership.
+		const childMatch = rawLine.match(CHILD_RE)
+		if (childMatch && currentOutcomeIndex >= 0) {
+			outcomes[currentOutcomeIndex].inferred.push(childMatch[1].trim())
+			continue
 		}
-		outcomes.push(outcome)
+		// Non-indented, non-`**ON**` line — closes the current outcome's
+		// child block. (The next `**ON**` will start a new block.)
+		currentOutcomeIndex = -1
 	}
 
 	if (outcomes.length === 0) {

package/src/cli/dispatch.mjs

@@ -36,9 +36,11 @@
 
 import { cmdActive } from './commands/active.mjs'
 import { cmdAdr } from './commands/adr.mjs'
+// cmdApplyRecipe — loaded lazily in the dispatch handler (Fast Path PRF-001)
 import { cmdAudit } from './commands/audit.mjs'
 import { cmdAuthorSkill } from './commands/author-skill.mjs'
 import { cmdBootstrap } from './commands/bootstrap.mjs'
+import { cmdCatchUp } from './commands/catch-up.mjs'
 import { cmdCheck } from './commands/check.mjs'
 import { cmdCheckVersion } from './commands/check-version.mjs'
 import { cmdCiWatch, cmdCiWatchSweep } from './commands/ci-watch.mjs'
@@ -69,12 +71,14 @@ import { cmdInitState } from './commands/init-state.mjs'
 import { cmdInstallFromSource } from './commands/install-from-source.mjs'
 import { cmdLock } from './commands/lock.mjs'
 import { cmdMigratePrReviews } from './commands/migrate-pr-reviews.mjs'
+import { cmdMobilePrepare } from './commands/mobile-prepare.mjs'
 import { cmdPersonas } from './commands/personas.mjs'
 import { cmdPlanApproval } from './commands/plan-approval.mjs'
 import { cmdPrReview } from './commands/pr-review.mjs'
 import { cmdPrecompactHook } from './commands/precompact-hook.mjs'
 import { cmdProductContext } from './commands/product-context.mjs'
 import { cmdProfile } from './commands/profile.mjs'
+// cmdRecipeDiff — loaded lazily in the dispatch handler (Fast Path PRF-001)
 import { cmdReleaseNotes } from './commands/release-notes.mjs'
 import { cmdRiskCheck } from './commands/risk-check.mjs'
 import { cmdRoadmap } from './commands/roadmap.mjs'
@@ -97,6 +101,7 @@ import { cmdValidateEvidence } from './commands/validate-evidence.mjs'
 import { cmdVariantGallery } from './commands/variant-gallery.mjs'
 import { cmdVariantPick } from './commands/variant-pick.mjs'
 import { cmdVariantPool } from './commands/variant-pool.mjs'
+// cmdVerifySandbox — loaded lazily in the dispatch handler (Fast Path PRF-001)
 import { cmdVitestDoctor } from './commands/vitest-doctor.mjs'
 import { cmdWave } from './commands/wave.mjs'
 import { cmdWfrun } from './commands/wfrun.mjs'
@@ -212,11 +217,24 @@ export const DISPATCH = {
 
 	// ---- (positional dir, slice(2)) shape ----
 	state: (args) => wrap(cmdState)(args[1]),
+	'catch-up': (args) => wrap(cmdCatchUp)(args[1]),
 	config: (args) => wrap(cmdConfig)(args[1], args.slice(2)),
 	'state-update': (args) => wrap(cmdStateUpdate)(args[1], args.slice(2)),
 	'state-artifacts': (args) => wrap(cmdStateArtifacts)(args[1], args.slice(2)),
 	'detect-project': (args) => wrap(cmdDetectProject)(args[1]),
 	'detect-runtime': (args) => wrap(cmdDetectRuntime)(args[1], args.slice(2)),
+	'recipe-diff': async (args) => {
+		const { cmdRecipeDiff } = await import('./commands/recipe-diff.mjs')
+		return wrap(cmdRecipeDiff)(args[1], args.slice(2))
+	},
+	'apply-recipe': async (args) => {
+		const { cmdApplyRecipe } = await import('./commands/apply-recipe.mjs')
+		return wrap(cmdApplyRecipe)(args[1], args.slice(2))
+	},
+	'verify-sandbox': async (args) => {
+		const { cmdVerifySandbox } = await import('./commands/verify-sandbox.mjs')
+		return wrap(cmdVerifySandbox)(args[1], args.slice(2))
+	},
 	driver: (args) => {
 		// `apt-tools driver doctor <project-dir>` — only subcommand for now.
 		if (args[1] === 'doctor') return wrap(cmdDriverDoctor)(args[2], args.slice(3))
@@ -228,6 +246,17 @@ export const DISPATCH = {
 			exitCode: 1,
 		}))()
 	},
+	mobile: (args) => {
+		// `apt-tools mobile prepare <project-dir> --platform <ios|android> [--mode <expo|native>] [--device <id>]`
+		if (args[1] === 'prepare') return wrap(cmdMobilePrepare)(args[2], args.slice(3))
+		return wrap(() => ({
+			envelope: {
+				status: 'error',
+				error: `Usage: apt-tools mobile prepare <project-dir> --platform <ios|android>. Unknown subcommand: ${args[1] ?? '(none)'}`,
+			},
+			exitCode: 1,
+		}))()
+	},
 	'features-audit': (args) => wrap(cmdFeaturesAudit)(args[1], args.slice(2)),
 	'init-state': (args) => wrap(cmdInitState)(args[1], args.slice(2)),
 	'risk-check': (args) => wrap(cmdRiskCheck)(args[1], args.slice(2)),