@sayknow-cli/coding-agent 0.5.11 → 0.5.14

package/src/cli/skills-cli.ts

@@ -1,11 +1,13 @@
 /**
- * Handles `skc skills` for inspecting bundled workflow skill definitions.
+ * Handles `skc skills` for inspecting bundled workflow and UI skill definitions.
  */
 import {
 	DEFAULT_SKC_DEFINITION_NAMES,
 	type EmbeddedDefaultSkcSkill,
 	getEmbeddedDefaultSkcSkills,
 } from "../defaults/skc-defaults";
+import { getEmbeddedSkcUiSkills } from "../defaults/skc-ui-skills";
+import type { Skill } from "../extensibility/skills";
 
 export type SkillsAction = "list" | "read";
 
@@ -28,17 +30,21 @@ interface SkillsReadEntry extends SkillsListEntry {
 	content: string;
 }
 
-function getEmbeddedSkill(name: string): EmbeddedDefaultSkcSkill | undefined {
-	return getEmbeddedDefaultSkcSkills().find(skill => skill.name === name);
+function getEmbeddedSkill(name: string): EmbeddedDefaultSkcSkill | Skill | undefined {
+	return (
+		getEmbeddedDefaultSkcSkills().find(skill => skill.name === name) ??
+		getEmbeddedSkcUiSkills().find(skill => skill.name === name)
+	);
 }
 
 function listEmbeddedSkills(): SkillsListEntry[] {
-	return getEmbeddedDefaultSkcSkills().map(skill => ({
+	const toEntry = (skill: EmbeddedDefaultSkcSkill | Skill): SkillsListEntry => ({
 		name: skill.name,
 		description: skill.description,
 		path: skill.filePath,
 		source: skill.source,
-	}));
+	});
+	return [...getEmbeddedDefaultSkcSkills().map(toEntry), ...getEmbeddedSkcUiSkills().map(toEntry)];
 }
 
 function writeJson(value: unknown): void {
@@ -60,14 +66,27 @@ export async function runSkillsCommand(cmd: SkillsCommandArgs): Promise<void> {
 
 	const name = cmd.name?.trim();
 	if (!name) {
-		process.stderr.write(`error: skill name is required for read (${DEFAULT_SKC_DEFINITION_NAMES.join(", ")})\n`);
+		process.stderr.write(
+			`error: skill name is required for read (${DEFAULT_SKC_DEFINITION_NAMES.join(", ")}, or a bundled UI skill such as emil-design-eng)\n`,
+		);
 		process.exitCode = 1;
 		return;
 	}
 
 	const skill = getEmbeddedSkill(name);
 	if (!skill) {
-		process.stderr.write(`error: unknown embedded skill "${name}" (${DEFAULT_SKC_DEFINITION_NAMES.join(", ")})\n`);
+		process.stderr.write(
+			`error: unknown embedded skill "${name}" (${DEFAULT_SKC_DEFINITION_NAMES.join(", ")}, or a bundled UI skill such as emil-design-eng)\n`,
+		);
+		process.exitCode = 1;
+		return;
+	}
+
+	// Every embedded skill carries inline content; a missing body means the
+	// bundle was built wrong, so fail loudly instead of printing "undefined".
+	const content = skill.content;
+	if (typeof content !== "string" || content.length === 0) {
+		process.stderr.write(`error: embedded skill "${name}" has no bundled content\n`);
 		process.exitCode = 1;
 		return;
 	}
@@ -77,12 +96,12 @@ export async function runSkillsCommand(cmd: SkillsCommandArgs): Promise<void> {
 		description: skill.description,
 		path: skill.filePath,
 		source: skill.source,
-		content: skill.content,
+		content,
 	};
 	if (cmd.flags?.json) {
 		writeJson(entry);
 		return;
 	}
-	process.stdout.write(skill.content);
-	if (!skill.content.endsWith("\n")) process.stdout.write("\n");
+	process.stdout.write(content);
+	if (!content.endsWith("\n")) process.stdout.write("\n");
 }

package/src/commands/setup.ts

@@ -15,6 +15,7 @@ const COMPONENTS: SetupComponent[] = [
 	"provider",
 	"python",
 	"stt",
+	"ui-skills",
 ];
 
 export default class Setup extends Command {

package/src/config/file-lock-gc.ts

@@ -58,9 +58,33 @@ function keptMalformedRecord(lockDir: string): GcRecord {
 	};
 }
 
+function emptyLockDirRecord(lockDir: string): GcRecord {
+	return {
+		store: "file_locks",
+		id: lockDir,
+		path: lockDir,
+		pid_status: "none",
+		status: "stale",
+		stale: true,
+		removable: true,
+		action: "none",
+		reason: "empty_file_lock_dir",
+	};
+}
+
 async function collectLockRecord(lockDir: string, ctx: GcContext): Promise<GcRecord> {
 	const info = await readFileLockInfoForGc(lockDir);
-	if (!info) return keptMalformedRecord(lockDir);
+	if (!info) {
+		// mkdir-before-info crash leftover: an empty `.lock` dir has no owner token
+		// and is safe to reclaim. Any other info-less shape stays fail-closed.
+		try {
+			const entries = await fs.readdir(lockDir);
+			if (entries.length === 0) return emptyLockDirRecord(lockDir);
+		} catch (error) {
+			if (!isEnoent(error)) throw error;
+		}
+		return keptMalformedRecord(lockDir);
+	}
 
 	const probeResult = ctx.probe(info.pid);
 	const pidStatus = gcPidStatusLabel(probeResult);
@@ -165,7 +189,20 @@ export const fileLocksGcAdapter: GcStoreAdapter = {
 	async prune(record: GcRecord, ctx: GcContext): Promise<GcPruneOutcome> {
 		const lockDir = record.path ?? record.id;
 		const info = await readFileLockInfoForGc(lockDir);
-		if (!info) return { removed: false, skipped: "lock_no_longer_dead_or_missing" };
+		if (!info) {
+			if (record.reason !== "empty_file_lock_dir") {
+				return { removed: false, skipped: "lock_no_longer_dead_or_missing" };
+			}
+			try {
+				const entries = await fs.readdir(lockDir);
+				if (entries.length !== 0) return { removed: false, skipped: "lock_no_longer_dead_or_missing" };
+				await fs.rmdir(lockDir);
+				return { removed: true };
+			} catch (error) {
+				if (isEnoent(error)) return { removed: false, skipped: "lock_no_longer_dead_or_missing" };
+				return { removed: false, error: errorMessage(error) };
+			}
+		}
 
 		const probeResult = ctx.probe(info.pid);
 		if (probeResult.status !== "dead") {

package/src/config/file-lock.ts

@@ -14,6 +14,21 @@ const DEFAULT_OPTIONS: Required<FileLockOptions> = {
 	retries: 50,
 	retryDelayMs: 100,
 };
+export class FileLockAcquireError extends Error {
+	readonly code = "acquire_timeout";
+
+	constructor(
+		readonly filePath: string,
+		readonly lockPath: string,
+		readonly attempts: number,
+		readonly holder: string,
+	) {
+		super(
+			`Failed to acquire lock for ${filePath} after ${attempts} attempts: ${holder} (${lockPath}); a live owner is never displaced`,
+		);
+		this.name = "FileLockAcquireError";
+	}
+}
 
 type LockInfo = FileLockOwnerToken;
 
@@ -243,6 +258,12 @@ async function releaseLock(lockPath: string, owner: FileLockOwnerToken): Promise
 	const outcome = await removeFileLockDirForGc(lockPath, owner);
 	if (outcome !== "removed") throw new Error(`Failed to release file lock: ${outcome}.`);
 }
+async function lockHolderDescription(lockPath: string): Promise<string> {
+	const info = await readLockInfo(lockPath);
+	if (!info) return "unknown holder";
+	return `pid ${info.pid}`;
+}
+
 async function acquireLock(filePath: string, options: FileLockOptions = {}): Promise<() => Promise<void>> {
 	const opts = { ...DEFAULT_OPTIONS, ...options };
 	const lockPath = getLockPath(filePath);
@@ -255,7 +276,7 @@ async function acquireLock(filePath: string, options: FileLockOptions = {}): Pro
 		if (await removeStaleLockForAcquire(lockPath, stale)) continue;
 		await Bun.sleep(opts.retryDelayMs);
 	}
-	throw new Error(`Failed to acquire lock for ${filePath} after ${opts.retries} attempts`);
+	throw new FileLockAcquireError(filePath, lockPath, opts.retries, await lockHolderDescription(lockPath));
 }
 
 /**

package/src/config/model-registry.ts

@@ -29,6 +29,7 @@ import {
 	UNK_MAX_TOKENS,
 	unregisterCustomApis,
 } from "@sayknow-cli/ai";
+import { detectDiscoveredApiFamily } from "@sayknow-cli/ai/utils/discovery/openai-compatible";
 
 // Sentinel for local-only OAuth token (LM Studio, vLLM) — declared inline to avoid loading
 // any provider module at startup. Must match `DEFAULT_LOCAL_TOKEN` in oauth/lm-studio.ts.
@@ -212,6 +213,36 @@ type ProviderValidationMode = "models-config" | "runtime-register";
 
 const OPENAI_REQUEST_TRANSFORM_APIS = new Set<Api>(["openai-completions", "openai-responses"]);
 
+const OPENAI_FAMILY_APIS = new Set<Api>([
+	"openai-completions",
+	"openai-responses",
+	"openai-codex-responses",
+	"azure-openai-responses",
+]);
+
+function isOpenAIFamilyApi(api: Api): boolean {
+	return OPENAI_FAMILY_APIS.has(api);
+}
+
+function dominantOpenAIFamilyModelApi(models: readonly { api?: string }[] | undefined): Api | undefined {
+	if (!models || models.length === 0) return undefined;
+	const counts = new Map<Api, number>();
+	for (const model of models) {
+		const api = model.api as Api | undefined;
+		if (api === undefined || !isOpenAIFamilyApi(api)) continue;
+		counts.set(api, (counts.get(api) ?? 0) + 1);
+	}
+	let best: Api | undefined;
+	let bestCount = 0;
+	for (const [api, count] of counts) {
+		if (count > bestCount) {
+			best = api;
+			bestCount = count;
+		}
+	}
+	return best;
+}
+
 function getKnownProviderApis(providerName: string): Set<Api> {
 	const apis = new Set<Api>();
 	for (const model of getBundledModels(providerName as Parameters<typeof getBundledModels>[0])) {
@@ -1563,17 +1594,30 @@ export class ModelRegistry {
 				keylessProviders.add(providerName);
 			}
 
-			if (providerConfig.discovery && providerConfig.api) {
+			const effectiveDiscoveryBaseUrl = providerConfig.baseUrl ?? resolveProviderBaseUrlFromEnv(providerName);
+			const providerApi =
+				(providerConfig.api as Api | undefined) ??
+				dominantOpenAIFamilyModelApi(providerConfig.models as { api?: string }[] | undefined);
+			const autoDiscovery: ProviderDiscovery | undefined =
+				!providerConfig.discovery &&
+				!localOpenAICompat &&
+				providerApi !== undefined &&
+				isOpenAIFamilyApi(providerApi) &&
+				effectiveDiscoveryBaseUrl !== undefined
+					? { type: "openai-models-list" }
+					: undefined;
+			const effectiveDiscovery = providerConfig.discovery ?? autoDiscovery;
+			if (effectiveDiscovery && providerApi) {
 				discoverableProviders.push({
 					provider: providerName,
-					api: providerConfig.api as Api,
-					baseUrl: providerConfig.baseUrl ?? resolveProviderBaseUrlFromEnv(providerName),
+					api: providerApi,
+					baseUrl: effectiveDiscoveryBaseUrl,
 					headers: providerConfig.headers,
 					compat: providerConfig.compat,
 					requestTransform: providerConfig.requestTransform,
 					cacheRetention: providerConfig.cacheRetention,
-					discovery: providerConfig.discovery,
-					optional: false,
+					discovery: effectiveDiscovery,
+					optional: !providerConfig.discovery,
 				});
 			}
 
@@ -2280,50 +2324,82 @@ export class ModelRegistry {
 				}
 				return new Error(`HTTP ${response.status} from ${modelsUrl}`);
 			},
-			mapModel: (item, defaults) => ({
-				...defaults,
-				reasoning: isOmlx,
-				...(isOmlx
-					? {
-							thinking: {
-								mode: "effort" as const,
-								minLevel: Effort.Low,
-								maxLevel: Effort.High,
-								defaultLevel: Effort.Medium,
-								levels: [Effort.Low, Effort.Medium, Effort.High],
-							},
-						}
-					: {}),
-				contextWindow:
-					parseDiscoveryLimit(item.max_model_len) ??
-					parseDiscoveryLimit(item.context_length) ??
-					parseDiscoveryLimit(item.context_window) ??
-					parseDiscoveryLimit(item.max_context_length) ??
-					UNK_CONTEXT_WINDOW,
-				maxTokens:
-					parseDiscoveryLimit(item.max_completion_tokens) ??
-					parseDiscoveryLimit(item.max_tokens) ??
-					parseDiscoveryLimit(item.max_output_tokens) ??
-					UNK_MAX_TOKENS,
-				headers,
-				compat: {
-					...(providerConfig.compat ?? {}),
-					supportsStore: false,
-					supportsDeveloperRole: false,
-					supportsReasoningEffort: isOmlx,
+			mapModel: (item, defaults) => {
+				const api = this.#resolveDiscoveredModelApi(
+					providerConfig,
+					typeof item.id === "string" ? item.id : "",
+					item,
+				);
+				return {
+					...defaults,
+					api,
+					reasoning: isOmlx,
 					...(isOmlx
 						? {
-								thinkingFormat: "qwen-chat-template" as const,
-								reasoningContentField: "reasoning_content" as const,
+								thinking: {
+									mode: "effort" as const,
+									minLevel: Effort.Low,
+									maxLevel: Effort.High,
+									defaultLevel: Effort.Medium,
+									levels: [Effort.Low, Effort.Medium, Effort.High],
+								},
 							}
 						: {}),
-				},
-			}),
+					contextWindow:
+						parseDiscoveryLimit(item.max_model_len) ??
+						parseDiscoveryLimit(item.context_length) ??
+						parseDiscoveryLimit(item.context_window) ??
+						parseDiscoveryLimit(item.max_context_length) ??
+						UNK_CONTEXT_WINDOW,
+					maxTokens:
+						parseDiscoveryLimit(item.max_completion_tokens) ??
+						parseDiscoveryLimit(item.max_tokens) ??
+						parseDiscoveryLimit(item.max_output_tokens) ??
+						UNK_MAX_TOKENS,
+					headers,
+					compat: {
+						...(providerConfig.compat ?? {}),
+						supportsStore: false,
+						supportsDeveloperRole: false,
+						supportsReasoningEffort: isOmlx,
+						...(isOmlx
+							? {
+									thinkingFormat: "qwen-chat-template" as const,
+									reasoningContentField: "reasoning_content" as const,
+								}
+							: {}),
+					},
+				};
+			},
 		});
 		if (discovered === null) throw new Error(`Invalid OpenAI-compatible model catalog from ${baseUrl}`);
 		return this.#applyProviderModelOverrides(providerConfig.provider, discovered);
 	}
 
+	#resolveDiscoveredModelApi(
+		providerConfig: DiscoveryProviderConfig,
+		modelId: string,
+		entry?: { id?: unknown; owned_by?: unknown },
+	): Api {
+		let matchedPrefixLength = -1;
+		let prefixApi: Api | undefined;
+		for (const [prefix, routedApi] of Object.entries(providerConfig.discovery.apiByModelPrefix ?? {})) {
+			if (modelId.startsWith(prefix) && prefix.length > matchedPrefixLength) {
+				prefixApi = routedApi as Api;
+				matchedPrefixLength = prefix.length;
+			}
+		}
+		if (prefixApi !== undefined) return prefixApi;
+		if (providerConfig.discovery.type === "openai-models-list") {
+			const detected = detectDiscoveredApiFamily(entry ?? { id: modelId });
+			if (detected === "anthropic-messages") return "anthropic-messages";
+			if (detected === "openai-completions") {
+				return isOpenAIFamilyApi(providerConfig.api) ? providerConfig.api : "openai-completions";
+			}
+		}
+		return providerConfig.api;
+	}
+
 	#normalizeLlamaCppBaseUrl(baseUrl?: string): string {
 		const defaultBaseUrl = "http://127.0.0.1:8080";
 		const raw = baseUrl || defaultBaseUrl;

package/src/config/models-config-schema.ts

@@ -185,6 +185,7 @@ export type ModelOverride = z.infer<typeof ModelOverrideSchema>;
 
 export const ProviderDiscoverySchema = z.object({
 	type: z.enum(["ollama", "llama.cpp", "lm-studio", "omlx", "sglang", "openai-models-list"]),
+	apiByModelPrefix: z.record(z.string().min(1), z.string().min(1)).optional(),
 });
 
 const LocalOpenAICompatSchema = z

package/src/defaults/skc/skills/ultragoal/SKILL.md

@@ -37,6 +37,9 @@ skc ultragoal complete-goals --retry-failed
 skc ultragoal checkpoint --goal-id <id> --status complete --evidence "<evidence>" --quality-gate-json <quality-gate-json-or-path>
 skc ultragoal checkpoint --goal-id <id> --status failed --evidence "<blocker/evidence>"
 skc ultragoal record-review-blockers --goal-id <id> --title "Resolve final review blockers" --objective "<blocker-resolution objective>" --evidence "<review findings>"
+skc ultragoal succession offer --target-repo <path> --goal-id <id> --authorize "<statement>" --authorized-by <identity>
+skc ultragoal succession adopt --offer <path>
+skc ultragoal succession status --json
 ```
 
 Use these exact goal-tool calls for the inline goal state:

package/src/defaults/skc/ui-skills/LICENSE.appllama

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antmind Ventures Private Limited (appllama.io)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/defaults/skc/ui-skills/LICENSE.emilkowalski

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emil Kowalski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/defaults/skc/ui-skills/NOTICE.md

@@ -0,0 +1,43 @@
+# Bundled frontend UI/UX skills
+
+These `SKILL.md` files are vendored from upstream skill repositories so SKC
+sessions can invoke frontend UI/UX craft skills without a separate user
+install. They are **not** SKC public workflow skills: the four public
+workflows remain `deep-interview`, `ralplan`, `ultragoal`, and `team`.
+
+Regenerate with:
+
+```bash
+bun scripts/build-ui-skill-bundle.ts \
+  --source emilkowalski=<checkout> \
+  --source appllama=<checkout>
+```
+
+Only `SKILL.md` is compiled into the binary, and a bundled skill's `baseDir`
+is a virtual `embedded:skc/...` path. Companion reference files are therefore
+inlined into each `SKILL.md` as appendices by the generator; do not add
+loose companion files here expecting them to be readable at runtime.
+
+## Sources
+
+| Upstream | License | Vendored skills |
+| --- | --- | --- |
+| [emilkowalski/skills](https://github.com/emilkowalski/skills) | MIT (`LICENSE.emilkowalski`), Copyright (c) 2026 Emil Kowalski | `emil-design-eng`, `animate`, `review-animations`, `improve-animations`, `find-animation-opportunities`, `pick-ui-library`, `prototype`, `mobile-native`, `animation-vocabulary`, `apple-design`, `ask-sonner` |
+| [Appllama/appllama-skills](https://github.com/Appllama/appllama-skills) | MIT (`LICENSE.appllama`) | `appllama-app-design-skill` |
+
+## Deliberate exclusions
+
+- `write-swift`, `animate-expo` (emilkowalski) — not web frontend craft.
+- `appllama-usage` (Appllama) — it exists only to drive the paid Appllama MCP
+  (`mcp.appllama.io`). SKC neither ships nor enables that connector, so
+  bundling it would instruct the agent to call tools that do not exist.
+  `appllama-app-design-skill` is upstream-documented as standalone.
+
+- [`Jakubantalik/transitions.dev`](https://github.com/Jakubantalik/transitions.dev) — **not vendored.** Its terms license only the `transitions-dev` CLI and Refine tooling under MIT; the transition collection is governed by a separate "Using the transitions" clause that permits unlimited use in your own projects but forbids repackaging or publishing the collection (or a substantial part of it). SKC therefore never carries the content: the agent installs it into the user's own project on demand via `npx -y skills@latest add Jakubantalik/transitions.dev --skill transitions-dev -a universal -y`. See `hooks/ui-skill-keywords.ts`.
+- [`DavidHDev/react-bits`](https://github.com/DavidHDev/react-bits) — **components not vendored.** React Bits is a shadcn component registry, not an agent skill repo (it ships no `SKILL.md`), and its MIT + Commons Clause license forbids selling, sublicensing, or redistributing the components "alone, in a bundle, or as a ported version". The bundled `react-bits` skill is therefore **SKC-authored guidance**: when to reach for the registry, how to install one component (`npx shadcn@latest add @react-bits/<Component>-<Variant>`), the `components.json` precondition, and a factual catalog of component names. No upstream component source is included; components are installed from the registry into the user's own project.
+
+## Trademarks
+
+The Appllama name, llama, and logo are trademarks of Antmind Ventures Private
+Limited. The MIT license does not grant rights to use them; they appear here
+only to attribute the source of the vendored skill.