howone 0.1.53 → 0.2.1

package/bin/index.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { createRequire } from "node:module";
 import { execFile } from "node:child_process";
-import { readdir, rename, stat, writeFile } from "node:fs/promises";
+import { readFile, readdir, rename, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
@@ -62,6 +62,18 @@ async function main() {
 		await runDeploy(command.options);
 		return;
 	}
+	if (scope === "capabilities" || scope === "capability" || scope === "caps") {
+		await runCapabilitiesCommand(subcommand, rest, command.options);
+		return;
+	}
+	if (scope === "skills" || scope === "skill") {
+		await runSkillsCommand(subcommand, rest, command.options);
+		return;
+	}
+	if (scope === "run") {
+		await runCapabilityRun(compact([subcommand, ...rest]), command.options);
+		return;
+	}
 	if (scope === "ai" && subcommand === "run") {
 		await runAiRun(rest, command.options);
 		return;
@@ -87,9 +99,22 @@ function parseCommand(args) {
 			"next",
 			"force",
 			"yes",
-			"json"
+			"json",
+			"stream"
 		],
-		string: ["template", "cwd"],
+		string: [
+			"template",
+			"cwd",
+			"scope",
+			"input",
+			"output",
+			"prompt",
+			"api-url",
+			"token",
+			"status",
+			"reason"
+		],
+		number: ["limit"],
 		configuration: { "camel-case-expansion": false }
 	});
 	return {
@@ -103,6 +128,16 @@ function parseCommand(args) {
 			yes: Boolean(parsed.yes),
 			json: Boolean(parsed.json),
 			cwd: typeof parsed.cwd === "string" ? parsed.cwd : void 0,
+			scope: typeof parsed.scope === "string" ? parsed.scope : void 0,
+			input: typeof parsed.input === "string" ? parsed.input : void 0,
+			output: typeof parsed.output === "string" ? parsed.output : void 0,
+			prompt: typeof parsed.prompt === "string" ? parsed.prompt : void 0,
+			apiUrl: typeof parsed["api-url"] === "string" ? parsed["api-url"] : void 0,
+			token: typeof parsed.token === "string" ? parsed.token : void 0,
+			stream: Boolean(parsed.stream),
+			status: typeof parsed.status === "string" ? parsed.status : void 0,
+			limit: typeof parsed.limit === "number" && Number.isFinite(parsed.limit) ? parsed.limit : void 0,
+			reason: typeof parsed.reason === "string" ? parsed.reason : void 0,
 			help: Boolean(parsed.help) || hasHelp,
 			version: Boolean(parsed.version) || hasVersion
 		}
@@ -182,6 +217,244 @@ async function runAiRun(pathArgs, options) {
 	}
 	printPending("howone ai run", result.message ?? "AI run is not implemented yet.");
 }
+async function runCapabilitiesCommand(subcommand, pathArgs, options) {
+	if (!subcommand || subcommand === "search") {
+		const query = pathArgs.join(" ").trim();
+		if (!query) throw new CliError("E_QUERY_REQUIRED", "Search query is required.");
+		await runCapabilitySearch(query, options);
+		return;
+	}
+	if (subcommand === "list") {
+		await runCapabilityList(options);
+		return;
+	}
+	if (subcommand === "inspect" || subcommand === "show") {
+		const ref = pathArgs[0];
+		if (!ref) throw new CliError("E_CAPABILITY_REF_REQUIRED", "Capability reference is required.");
+		await runCapabilityInspect(ref, options);
+		return;
+	}
+	if (subcommand === "proposals") {
+		await runCapabilityProposals(options);
+		return;
+	}
+	if (subcommand === "apply") {
+		const proposalId = pathArgs[0];
+		if (!proposalId) throw new CliError("E_PROPOSAL_ID_REQUIRED", "Capability proposal id is required.");
+		await runCapabilityProposalAction("apply", proposalId, options);
+		return;
+	}
+	if (subcommand === "reject") {
+		const proposalId = pathArgs[0];
+		if (!proposalId) throw new CliError("E_PROPOSAL_ID_REQUIRED", "Capability proposal id is required.");
+		await runCapabilityProposalAction("reject", proposalId, options);
+		return;
+	}
+	throw new CliError("E_COMMAND_UNKNOWN", `Unknown capabilities command: ${["capabilities", subcommand].join(" ")}`);
+}
+async function runSkillsCommand(subcommand, pathArgs, options) {
+	const ref = pathArgs[0];
+	if (subcommand === "export") {
+		if (!ref) throw new CliError("E_SKILL_REF_REQUIRED", "Skill reference is required.");
+		await runSkillProjection("export", ref, options);
+		return;
+	}
+	if (subcommand === "install") {
+		if (!ref) throw new CliError("E_SKILL_REF_REQUIRED", "Skill reference is required.");
+		await runSkillProjection("install", ref, options);
+		return;
+	}
+	if (subcommand === "publish") {
+		if (!ref) throw new CliError("E_SKILL_REF_REQUIRED", "Skill reference is required.");
+		await runSkillProjection("publish", ref, options);
+		return;
+	}
+	throw new CliError("E_COMMAND_UNKNOWN", `Unknown skills command: ${["skills", subcommand].filter(Boolean).join(" ")}`);
+}
+async function runCapabilitySearch(query, options) {
+	const params = new URLSearchParams({ q: query });
+	if (options.scope) params.set("scope", options.scope);
+	await printRegistryResult("capabilities search", await callHowoneRegistryApi(`/api/capabilities/search?${params}`, {
+		options,
+		requireAuth: options.scope !== "public"
+	}), options);
+}
+async function runCapabilityList(options) {
+	const params = new URLSearchParams();
+	if (options.scope) params.set("scope", options.scope);
+	await printRegistryResult("capabilities list", await callHowoneRegistryApi(`/api/capabilities${params.size ? `?${params}` : ""}`, {
+		options,
+		requireAuth: options.scope !== "public"
+	}), options);
+}
+async function runCapabilityInspect(ref, options) {
+	const result = await callHowoneRegistryApi(`/api/capabilities/${encodeURIComponent(ref)}`, {
+		options,
+		requireAuth: options.scope !== "public"
+	});
+	await printRegistryResult(`capabilities inspect ${ref}`, result, options);
+}
+async function runCapabilityProposals(options) {
+	const params = new URLSearchParams();
+	if (options.status) params.set("status", options.status);
+	if (options.limit) params.set("limit", String(options.limit));
+	await printRegistryResult("capabilities proposals", await callHowoneRegistryApi(`/api/capabilities/proposals${params.size ? `?${params}` : ""}`, {
+		options,
+		requireAuth: true
+	}), options);
+}
+async function runCapabilityProposalAction(action, proposalId, options) {
+	const result = await callHowoneRegistryApi(`/api/capabilities/proposals/${encodeURIComponent(proposalId)}/${action}`, {
+		options,
+		requireAuth: true,
+		init: {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(action === "reject" ? { reason: options.reason } : {})
+		}
+	});
+	await printRegistryResult(`capabilities ${action} ${proposalId}`, result, options);
+}
+async function runCapabilityRun(pathArgs, options) {
+	const actionRef = pathArgs[0];
+	if (!actionRef && !options.prompt) throw new CliError("E_ACTION_REF_REQUIRED", "Capability action reference is required, or use --prompt for query-based routing.");
+	const input = await readCapabilityRunInput(options);
+	const body = {
+		...actionRef ? { actionRef } : {},
+		...options.prompt ? { prompt: options.prompt } : {},
+		input,
+		stream: Boolean(options.stream)
+	};
+	const result = await callHowoneRegistryApi("/api/capabilities/run", {
+		options,
+		requireAuth: true,
+		init: {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(body)
+		}
+	});
+	await printRegistryResult(actionRef ? `run ${actionRef}` : "run query", result, options);
+}
+async function runSkillProjection(action, ref, options) {
+	const method = action === "export" ? "GET" : "POST";
+	const result = await callHowoneRegistryApi(`/api/capabilities/skills/${encodeURIComponent(ref)}/${action}`, {
+		options,
+		requireAuth: action !== "export",
+		init: { method }
+	});
+	await printRegistryResult(`skills ${action} ${ref}`, result, options);
+}
+async function readCapabilityRunInput(options) {
+	if (!options.input) return {};
+	const raw = options.input.trim();
+	const content = raw.startsWith("{") || raw.startsWith("[") ? raw : await readFile(path.resolve(options.cwd ?? process.cwd(), raw), "utf-8");
+	try {
+		const parsed = JSON.parse(content);
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new CliError("E_INPUT_INVALID", "Capability input must be a JSON object.");
+		return parsed;
+	} catch (error) {
+		if (error instanceof CliError) throw error;
+		throw new CliError("E_INPUT_INVALID", error instanceof Error ? error.message : "Invalid JSON input.");
+	}
+}
+function resolveHowoneApiUrl(options) {
+	return (options.apiUrl ?? "https://howone.dev").replace(/\/+$/, "");
+}
+function resolveHowoneApiToken(options) {
+	return options.token ?? process.env.HOWONE_API_TOKEN ?? process.env.HOWONE_AGENT_TOKEN;
+}
+async function callHowoneRegistryApi(apiPath, args) {
+	const token = resolveHowoneApiToken(args.options);
+	if (args.requireAuth && !token) throw new CliError("E_AUTH_REQUIRED", "Set HOWONE_API_TOKEN or pass --token to access private/workspace capabilities.");
+	const url = `${resolveHowoneApiUrl(args.options)}${apiPath.startsWith("/") ? apiPath : `/${apiPath}`}`;
+	const headers = new Headers(args.init?.headers);
+	if (token) headers.set("Authorization", `Bearer ${token}`);
+	headers.set("Accept", args.options.stream ? "text/event-stream, application/json" : "application/json");
+	const response = await fetch(url, {
+		...args.init,
+		headers
+	});
+	const contentType = response.headers.get("content-type") ?? "";
+	if (args.options.stream && contentType.includes("text/event-stream")) return readSseResponse(response);
+	const text = await response.text();
+	const body = text ? parseJsonOrText(text) : null;
+	if (!response.ok) throw new CliError("E_API_REQUEST_FAILED", `HowOne API request failed: HTTP ${response.status}`, {
+		status: response.status,
+		body
+	});
+	return body;
+}
+async function readSseResponse(response) {
+	if (!response.ok) throw new CliError("E_API_REQUEST_FAILED", `HowOne API request failed: HTTP ${response.status}`);
+	if (!response.body) return {
+		ok: true,
+		events: []
+	};
+	const reader = response.body.getReader();
+	const decoder = new TextDecoder();
+	const events = [];
+	let buffer = "";
+	while (true) {
+		const { value, done } = await reader.read();
+		if (done) break;
+		buffer += decoder.decode(value, { stream: true });
+		let boundary = buffer.indexOf("\n\n");
+		while (boundary >= 0) {
+			const chunk = buffer.slice(0, boundary).trim();
+			buffer = buffer.slice(boundary + 2);
+			if (chunk) {
+				events.push(chunk);
+				console.log(chunk);
+			}
+			boundary = buffer.indexOf("\n\n");
+		}
+	}
+	const tail = buffer.trim();
+	if (tail) {
+		events.push(tail);
+		console.log(tail);
+	}
+	return {
+		ok: true,
+		events
+	};
+}
+function parseJsonOrText(text) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+async function printRegistryResult(command, result, options) {
+	if (options.output) await writeFile(path.resolve(options.cwd ?? process.cwd(), options.output), `${JSON.stringify(result, null, 2)}\n`, "utf-8");
+	if (options.json || options.output) {
+		if (!options.output) console.log(JSON.stringify(result, null, 2));
+		return;
+	}
+	console.log(formatPanel(pc.bold(command), [formatRegistrySummary(result)]));
+}
+function formatRegistrySummary(result) {
+	if (typeof result === "string") return result;
+	if (!result || typeof result !== "object") return String(result);
+	const record = result;
+	const data = record.data ?? record.results ?? record.capabilities ?? record.actions;
+	if (Array.isArray(data)) {
+		if (!data.length) return "No capabilities found.";
+		return data.slice(0, 12).map((item) => {
+			if (!item || typeof item !== "object") return `- ${String(item)}`;
+			const row = item;
+			const name = row.name ?? row.title ?? row.slug ?? row.actionRef ?? row.proposalSlug ?? row.id ?? "capability";
+			const description = row.description ?? row.summary ?? row.reason ?? row.status;
+			return `- ${String(name)}${description ? `: ${String(description)}` : ""}`;
+		}).join("\n");
+	}
+	const name = record.name ?? record.title ?? record.slug ?? record.actionRef ?? record.proposalSlug ?? record.id;
+	const description = record.description ?? record.summary ?? record.reason ?? record.status;
+	if (name || description) return [name ? String(name) : void 0, description ? String(description) : void 0].filter(Boolean).join("\n");
+	return JSON.stringify(result, null, 2);
+}
 async function resolveCreatePlan(pathArgs, options, cwd, isInteractive) {
 	const template = resolveTemplateOption(options);
 	const projectName = pathArgs[0] === "template" ? pathArgs[1] : pathArgs[0];
@@ -417,6 +690,18 @@ function printHelp(pathArgs) {
 		printReservedHelp("howone deploy", "Deploy support is reserved and not implemented yet.");
 		return;
 	}
+	if (topic === "capabilities" || topic === "capabilities search") {
+		printCapabilitiesHelp();
+		return;
+	}
+	if (topic === "skills") {
+		printSkillsHelp();
+		return;
+	}
+	if (topic === "run") {
+		printRunHelp();
+		return;
+	}
 	if (topic === "ai" || topic === "ai run") {
 		printReservedHelp("howone ai run [aiId]", "AI run support is reserved and not implemented yet.");
 		return;
@@ -429,6 +714,11 @@ function printRootHelp() {
 		"",
 		pc.bold("Commands"),
 		formatCommand("init app [name]", "Create an app from a template"),
+		formatCommand("capabilities search <query>", "Search callable HowOne capabilities"),
+		formatCommand("capabilities inspect <ref>", "Inspect a capability package or action"),
+		formatCommand("capabilities proposals", "List generated capability proposals"),
+		formatCommand("run <package.action>", "Run a callable capability action"),
+		formatCommand("skills export <ref>", "Export a skill projection for a capability"),
 		formatCommand("create", "Reserved placeholder"),
 		formatCommand("deploy", "Reserved placeholder"),
 		formatCommand("ai run [aiId]", "Reserved placeholder"),
@@ -439,8 +729,10 @@ function printRootHelp() {
 		"",
 		pc.bold("Examples"),
 		`  ${pc.cyan("howone init app my-app --template vite")}`,
-		`  ${pc.cyan("howone deploy")}`,
-		`  ${pc.cyan("howone ai run generateImage")}`
+		`  ${pc.cyan("howone capabilities search \"海报生成\" --scope public")}`,
+		`  ${pc.cyan("howone capabilities proposals --status pending_review")}`,
+		`  ${pc.cyan("howone run poster-generator.createPoster --input input.json --output result.json")}`,
+		`  ${pc.cyan("howone run --prompt \"帮我生成一张 AI 发布会海报\" --stream")}`
 	]));
 }
 function printInitHelp() {
@@ -469,6 +761,71 @@ function printReservedHelp(command, description) {
 		`${pc.yellow("Pending")} This command is available as a stable placeholder.`
 	]));
 }
+function printCapabilitiesHelp() {
+	console.log(formatPanel(`${pc.bold("HowOne capabilities")}`, [
+		`${pc.dim("Usage")}    howone capabilities <command> [options]`,
+		"",
+		pc.bold("Commands"),
+		formatCommand("search <query>", "Search private, workspace, installed, or public capabilities"),
+		formatCommand("list", "List capabilities in a scope"),
+		formatCommand("inspect <ref>", "Inspect package/action schemas and runtime bindings"),
+		formatCommand("proposals", "List generated proposals for the current user"),
+		formatCommand("apply <proposalId>", "Apply a generated proposal to the registry"),
+		formatCommand("reject <proposalId>", "Reject a generated proposal"),
+		"",
+		pc.bold("Options"),
+		formatCommand("--scope <scope>", "private, workspace, installed, public, or global"),
+		formatCommand("--status <status>", "Filter proposal list by status"),
+		formatCommand("--limit <number>", "Limit result count"),
+		formatCommand("--reason <text>", "Reason for rejecting a proposal"),
+		formatCommand("--api-url <url>", "HowOne registry API origin"),
+		formatCommand("--token <token>", "Agent API token; defaults to HOWONE_API_TOKEN"),
+		formatCommand("--json", "Print machine-readable JSON output"),
+		"",
+		pc.bold("Examples"),
+		`  ${pc.cyan("howone capabilities search \"海报生成\" --scope public")}`,
+		`  ${pc.cyan("howone capabilities inspect poster-generator.createPoster")}`,
+		`  ${pc.cyan("howone capabilities proposals --status pending_review")}`,
+		`  ${pc.cyan("howone capabilities apply 00000000-0000-0000-0000-000000000000")}`
+	]));
+}
+function printRunHelp() {
+	console.log(formatPanel(`${pc.bold("Run a capability")}`, [
+		`${pc.dim("Usage")}    howone run <package.action> [options]`,
+		"",
+		pc.bold("Options"),
+		formatCommand("--input <json|file>", "JSON object or path to JSON input file"),
+		formatCommand("--prompt <text>", "Natural-language query routed through the registry"),
+		formatCommand("--output <file>", "Write JSON result to a file"),
+		formatCommand("--stream", "Request SSE and print events as they arrive"),
+		formatCommand("--api-url <url>", "HowOne registry API origin"),
+		formatCommand("--token <token>", "Agent API token; defaults to HOWONE_API_TOKEN"),
+		formatCommand("--json", "Print machine-readable JSON output"),
+		"",
+		pc.bold("Examples"),
+		`  ${pc.cyan("howone run poster-generator.createPoster --input input.json")}`,
+		`  ${pc.cyan("howone run --prompt \"帮我生成一张 AI 发布会海报\" --stream")}`
+	]));
+}
+function printSkillsHelp() {
+	console.log(formatPanel(`${pc.bold("HowOne skill projections")}`, [
+		`${pc.dim("Usage")}    howone skills <command> <ref> [options]`,
+		"",
+		pc.bold("Commands"),
+		formatCommand("export <ref>", "Export an agent-facing skill artifact"),
+		formatCommand("install <ref>", "Install a public or workspace skill projection"),
+		formatCommand("publish <ref>", "Request publication of a capability skill projection"),
+		"",
+		pc.bold("Options"),
+		formatCommand("--api-url <url>", "HowOne registry API origin"),
+		formatCommand("--token <token>", "Agent API token; defaults to HOWONE_API_TOKEN"),
+		formatCommand("--json", "Print machine-readable JSON output"),
+		"",
+		pc.bold("Examples"),
+		`  ${pc.cyan("howone skills export poster-generator")}`,
+		`  ${pc.cyan("howone skills install poster-generator")}`
+	]));
+}
 function printPending(command, message) {
 	console.log(formatPanel(pc.bold(command), [`${pc.yellow("Pending")} ${message}`]));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "howone",
-  "version": "0.1.53",
+  "version": "0.2.1",
   "private": false,
   "description": "HowOne command line tools for creating app templates.",
   "type": "module",

package/templates/vite/.howone/skills/howone/01-architect/01-app-generation.md

@@ -4,7 +4,7 @@ Read immediately after `skill(name="howone")` and before platform design tools,
 edits, or implementation guesses.
 
 HowOne is a generated app platform. This file classifies **user scope**, separates **platform
-contracts** from **app-owned integrations**, and routes to backend, AI, or SDK tracks. Keep design
+contracts** from explicit user-owned integrations, and routes to backend, AI, or SDK tracks. Keep design
 tracks separate: backend design does not require SDK references; AI design does not require SDK
 references until the synced AI manifest is ready for code.
 
@@ -19,15 +19,14 @@ Map the user request to surfaces. Include only what they need.
 | HowOne AI features | `03-ai-capabilities/` → sync → external workflow | Verify catalog before design |
 | SDK wiring, auth, UI calls | `04-app-sdk/` | Only after manifests exist when contracts apply |
 | UI only, no HowOne data/AI | App code under `{appRoot}` | No schema/AI design tools |
-| External systems the user provides | App code + config | Not platform contracts unless combined with rows above |
+| Explicit user-owned integrations | App code + config | Only when the user explicitly asks to connect something outside HowOne |
 
 **Mixed scope:** read at least one file per touched track (`SKILL.md` index) before writing.
 
 ## HowOne platform boundary
 
-Use this decision model for **any** user request. Do not maintain a mental deny-list of technologies
-(K8s, message buses, custom protocols, etc.). Ask whether the ask is a **platform contract surface**
-or **app-owned**.
+Use this decision model for **any** user request. Ask whether the ask is a **platform contract
+surface** or an explicit user-owned integration.
 
 ### Platform provides (evidence required)
 
@@ -42,15 +41,17 @@ If none of these surfaces can express the user's **platform** requirement after
 catalog, and tool schemas, it is a **platform gap**—not an automatic ban on whatever technology the
 user named.
 
-### App-owned (not platform gap)
+### Explicit user-owned integration (not platform gap)
 
-Anything the user runs, hosts, or buys **outside** HowOne contracts: orchestration, clusters,
-custom APIs, message systems, identity products, analytics, payment gateways, etc.
+Use this path only when the user explicitly asks to connect something they run, host, or configure
+outside HowOne contracts. Do not apply it to ordinary generated app requests such as "AI image
+generation app", "AI story app", "login", "cloud sync", or "history"; first check the HowOne
+platform tracks.
 
 - Implement in application code and configuration under `{appRoot}`.
 - **Do not refuse** because HowOne does not provision it.
 - **Do not** call platform design tools to fake it as entities, AI capabilities, or manifest fields.
-- **Do not** tell the user they cannot use their own stack—only clarify it is outside HowOne platform scope.
+- **Do not** tell the user they cannot use their own stack—only clarify it is outside HowOne platform scope when they explicitly asked for that stack.
 
 ### Boundary decision (always)
 
@@ -58,9 +59,9 @@ custom APIs, message systems, identity products, analytics, payment gateways, et
 1. What did the user ask for?
 2. Does it require HowOne persisted data? → entity-schema path or skip
 3. Does it require HowOne AI? → catalog + ai-capabilities path or skip
-4. Is it only their external infrastructure? → app-owned; wire in UI/config
+4. Did they explicitly ask to connect something outside HowOne? → app-owned; wire in UI/config
 5. Did they ask for a platform feature with no contract evidence? → platform stop (generic)
-6. Mixed? → platform parts via tracks; app-owned parts in app code
+6. Mixed? → platform parts via tracks; explicit integrations in app code
 ```
 
 ### Platform scope rules
@@ -69,7 +70,8 @@ custom APIs, message systems, identity products, analytics, payment gateways, et
 - **No invalid shortcuts:** Do not handwrite `.howone/` metadata or guess version/workflow identifiers.
 - **Stop wording:** Name the **missing contract surface** (e.g. no catalog family, no manifest binding, no tool operation)—not the user's technology choice.
 
-When stopping a platform path, separate what HowOne can provide from what remains possible via app-owned integration.
+When stopping a platform path, separate what HowOne can provide from any explicit integration the
+user requested.
 
 Inspect-only platform reads do not replace this file before the first **design write**.
 
@@ -149,9 +151,10 @@ without default) need explicit user alignment before applying the final patch.
 1. Read architecture + **catalog** (feasibility) + contract rules; use playbooks when they match.
 2. Apply one complete capability patch → `sync_ai_artifacts`.
 3. External workflow create/update per workflow-operations reference; keep job/request IDs from tool results.
-4. Read `{appRoot}/.howone/ai/manifest.json`.
-5. Stop AI design. Read SDK references only if implementing app calls.
-6. If persistence required: entity workflow after output contract is fixed.
+4. Wait for the terminal result. A successful update promotes its new workflow ID in the backend capability version.
+5. Run `sync_ai_artifacts` again, then read `{appRoot}/.howone/ai/manifest.json`.
+6. Stop AI design. Read SDK references only if implementing app calls.
+7. If persistence required: entity workflow after output contract is fixed.
 
 Do not fake catalog-backed AI. Platform gap → stop AI design path, explain generically.
 No AI capability dry-run step. Design the contract from the skill references, then apply the final
@@ -169,7 +172,7 @@ capability patch.
 
 ## Checklist before implementation
 
-- [ ] Scope explicit: which tracks apply; app-owned vs platform clear
+- [ ] Scope explicit: which tracks apply; explicit integration vs platform clear
 - [ ] Data and auth posture chosen when data in scope
 - [ ] AI requirements verified against catalog when AI in scope
 - [ ] Manifests synced before SDK codegen

package/templates/vite/.howone/skills/howone/03-ai-capabilities/01-ai-capability-architecture.md

@@ -10,14 +10,6 @@ belongs?** For schema details read `02-workflow-contract-rules.md`. For workflow
 
 ## Platform Mental Model
 
-HowOne workflow-service AI is a bounded catalog, not a general automation runtime. Before designing
-an AI contract, verify the requested behavior matches the supported action families in
-`03-service-capability-catalog.md`.
-
-Streaming is not supported for AI workflow capability design. Do not design streaming execution,
-streaming partial results, realtime tokens, or stream-based workflow contracts. Use non-streaming
-status/result UI in app code when progress feedback is needed.
-
 HowOne AI has five distinct layers:
 
 | Layer | Owns | Does not own |
@@ -43,7 +35,8 @@ user request                         = intent
 agent AI contract proposal           = draft
 applied AI capability version        = validated contract
 .howone/ai/manifest.json             = local synced source for workflow submit and later SDK codegen
-external-ai-capability result        = job/task/config mapping and possible manifest workflowId update
+external-ai-capability submission    = job/task/config mapping; update IDs remain pending
+terminal background finalizer        = promotes successful update IDs in the backend capability version
 SDK/UI implementation                = separate app-sdk track after AI design is complete
 entity schema                        = persistence contract, separate from AI contract
 ```
@@ -62,10 +55,11 @@ Use this flow for new AI features:
 6. Sync `.howone/ai/manifest.json`.
 7. Submit workflow create/update through `external-ai-capability` from the synced manifest.
 8. Store returned job/task IDs and submitted config IDs for polling/debugging.
-9. Poll status until `completed` or `failed`.
-10. Re-read `.howone/ai/manifest.json`; update operations may have written fresh `workflowId` values.
-11. Leave AI design. If app code must call the workflow, read the SDK track and generate bindings.
-12. If output must persist, design entity schema after the output contract is fixed.
+9. Let the host poll status until `completed` or `failed`.
+10. On success, the background finalizer promotes successful update IDs in the backend capability version. Failed operations keep their previous IDs.
+11. Run `sync_ai_artifacts` again, then re-read `.howone/ai/manifest.json`.
+12. Leave AI design. If app code must call the workflow, read the SDK track and generate bindings.
+13. If output must persist, design entity schema after the output contract is fixed.
 
 Do not submit external workflow create/update from a hand-written schema. It should come from the
 synced manifest.
@@ -105,11 +99,13 @@ create:
 update:
   previous config = current manifest capability.workflowId
   new config      = freshly generated UUID
-  manifest        = rewritten so capability.workflowId is the fresh UUID
+  submitted state = local manifest remains unchanged while EAX runs
+  completed state = backend capability version receives the fresh UUID
 ```
 
-The SDK execution binding uses the manifest `workflowId`, which is the EAX config id. After update,
-the new manifest `workflowId` is the only value that should be copied into `src/lib/sdk.ts`.
+The SDK execution binding uses the synced manifest `workflowId`, which is the EAX config id. After
+update completion, run `sync_ai_artifacts`; only the newly synced manifest value should be copied
+into `src/lib/sdk.ts`.
 Do not invent IDs; let the AI design/sync/external workflow tools generate and persist them.
 
 ## Workflow Count Rule
@@ -137,19 +133,15 @@ Workflow may do:
 
 - generate, summarize, translate, classify, extract;
 - search/crawl and synthesize;
-- fetch RSS feeds by RSS URL;
-- generate/edit/analyze images;
-- generate video, concatenate videos, and extract first/last video frames;
-- generate TTS audio, transcribe speech, and concatenate audio files;
+- generate/edit/analyze images, video, and audio;
 - retrieve financial or academic data;
-- create or modify supported files: text, PDF, DOCX, PPTX, and XLSX.
+- save/read generated files through URL-based storage.
 
 Workflow must not do:
 
 - database create/read/update/delete;
 - authentication/session logic;
 - file upload from browser raw bytes;
-- streaming output or realtime event delivery;
 - payment processing;
 - owner assignment or permissions;
 - app navigation, UI state, toast, or modal logic.
@@ -176,7 +168,6 @@ Do not:
 - hide the unsupported part;
 - build a UI that pretends the workflow exists;
 - replace the requested capability with a different one without saying so;
-- imply streaming/realtime AI behavior is available;
 - assume private APIs, external datasets, or providers that are not listed.
 
 Correct response:
@@ -213,7 +204,6 @@ The description can be human readable. The ID must be stable for codegen.
 Before editing files:
 
 - Feature maps to available workflow capabilities.
-- Streaming/realtime output is not required.
 - One workflow per feature unless RAG.
 - Description says what the user gets, not how tools run.
 - Input schema accepts URLs for files, not raw bytes.