howone 0.2.0 → 0.2.2

package/bin/index.mjs

@@ -359,7 +359,7 @@ async function readCapabilityRunInput(options) {
 	}
 }
 function resolveHowoneApiUrl(options) {
-	return (options.apiUrl ?? process.env.HOWONE_API_URL ?? process.env.NEXT_PUBLIC_SERVER_URL ?? "https://howone.dev").replace(/\/+$/, "");
+	return (options.apiUrl ?? "https://howone.dev").replace(/\/+$/, "");
 }
 function resolveHowoneApiToken(options) {
 	return options.token ?? process.env.HOWONE_API_TOKEN ?? process.env.HOWONE_AGENT_TOKEN;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "howone",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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.

package/templates/vite/.howone/skills/howone/03-ai-capabilities/02-workflow-contract-rules.md

@@ -41,19 +41,6 @@ service reject the request or produce a workflow the runtime cannot execute reli
 }
 ```
 
-## Supported Capability Boundary
-
-Design contracts only for capability families listed in `03-service-capability-catalog.md`.
-Do not invent general workflow powers beyond that catalog. In particular:
-
-- streaming execution and realtime partial results are not supported;
-- file work is limited to creating or modifying text, PDF, DOCX, PPTX, and XLSX outputs;
-- video work is limited to generation, concatenation, and first/last-frame extraction;
-- audio work is limited to TTS, speech recognition, and concatenating audio files.
-
-If the requested behavior needs anything outside the catalog, stop the AI workflow path and explain
-the missing capability or ask the user to narrow the feature.
-
 ## Loose JSON Schema
 
 The workflow engine is agentic. Overly strict schemas reduce reliability.
@@ -244,21 +231,6 @@ Instead:
 2. app code persists through the entity runtime after SDK handoff;
 3. durable fields map to the entity contract.
 
-## No Streaming Contracts
-
-HowOne AI workflow capability contracts are non-streaming. Do not add schema fields or descriptions
-that imply:
-
-- token streaming;
-- realtime audio/video processing;
-- incremental chunks;
-- event streams;
-- SSE/WebSocket workflow output;
-- live progress messages from the workflow.
-
-If the app needs progress UX, keep it app-owned: show pending/running/completed/failed states around
-the non-streaming workflow result.
-
 ## External Data Assumptions
 
 Do not require user-provided datasets unless the user said they have them.
@@ -442,84 +414,6 @@ Bad:
 }
 ```
 
-### RSS feed extraction
-
-```json
-{
-  "inputSchema": {
-    "type": "object",
-    "properties": {
-      "rss_url": {
-        "type": "string",
-        "format": "uri",
-        "description": "RSS feed URL to fetch and parse."
-      },
-      "language": {
-        "type": "string",
-        "description": "Language for any generated summary text."
-      }
-    },
-    "required": ["rss_url"]
-  },
-  "outputSchema": {
-    "type": "object",
-    "properties": {
-      "items": {
-        "type": "array",
-        "description": "RSS feed items with title, URL, published date, and summary in the requested language when generated.",
-        "items": {
-          "type": "object",
-          "properties": {
-            "title": { "type": "string" },
-            "url": { "type": "string", "format": "uri" },
-            "published_at": { "type": "string" },
-            "summary": { "type": "string" }
-          }
-        }
-      }
-    },
-    "required": ["items"]
-  }
-}
-```
-
-### File creation or modification
-
-```json
-{
-  "inputSchema": {
-    "type": "object",
-    "properties": {
-      "file_type": {
-        "type": "string",
-        "description": "Target file type: txt, md, pdf, docx, pptx, or xlsx."
-      },
-      "content_or_instruction": {
-        "type": "string",
-        "description": "Content to create or instruction for modifying the source file."
-      },
-      "source_file_url": {
-        "type": "string",
-        "format": "uri",
-        "description": "Optional URL of an existing file to modify."
-      }
-    },
-    "required": ["file_type", "content_or_instruction"]
-  },
-  "outputSchema": {
-    "type": "object",
-    "properties": {
-      "file_url": {
-        "type": "string",
-        "format": "uri",
-        "description": "Public URL of the created or modified file."
-      }
-    },
-    "required": ["file_url"]
-  }
-}
-```
-
 ## Contract Checklist
 
 - Required inputs are essential only.
@@ -528,7 +422,6 @@ Bad:
 - Input/output property names do not overlap.
 - Text output descriptions specify language.
 - Description says what, not how.
-- Contract does not imply streaming, realtime output, or event delivery.
 - No CRUD/auth/upload/payment/app-state requirements.
 - Feature fits an available capability.
 - Schema is raw valid JSON.

package/templates/vite/.howone/skills/howone/03-ai-capabilities/03-service-capability-catalog.md

@@ -3,41 +3,29 @@
 Use this reference **only** for HowOne **workflow-service AI** feasibility. It lists what the current
 workflow service supports—not everything a full product may use.
 
-Infrastructure or products the user operates themselves (clusters, custom servers, third-party
-APIs, etc.) are **app-owned** per `01-architect/01-app-generation.md`. They are out of scope for
-this catalog and must not be rejected as "AI not supported" when the user only needs to connect to them in app code.
+Explicit user-owned integrations are outside this catalog per
+`01-architect/01-app-generation.md`. Use that exception only when the user explicitly asks to
+connect something outside HowOne. Ordinary generated AI app requests should be checked against this
+catalog first.
 
 Source: `docs/ai-capability.md`.
 
-## Global Boundaries
-
-Streaming is not supported. Do not design token streams, realtime audio/video processing,
-incremental workflow chunks, SSE/WebSocket workflow output, or live workflow progress events as
-HowOne AI capability. Progress UI is app-owned around a non-streaming workflow result.
-
-If the requested behavior is not listed in this catalog, do not simulate it or silently approximate
-it. State the missing capability and offer the closest supported version only when it preserves the
-user's original goal.
-
 ## Quick Selection Table
 
 | User asks for | Use capability family | Typical inputs | Typical outputs |
 |---|---|---|---|
 | Latest info, research, source-backed answer | Web search / crawling | `topic`, `prompt`, `url`, `search_level` | `answer`, `sources`, `page_content` |
-| Parse posts from an RSS feed | Fetch RSS feed from RSS URL | `rss_url`, optional filters | `items`, `source_metadata` |
-| Generate or transform text | Text generation / transformation | `prompt`, `source_text`, `language`, format instructions | `generated_text` or structured JSON |
 | Generate artwork/photo/logo/mockup | Image generation | `image_description`, `style_preference`, optional references | `generated_image_url` |
 | Edit an image | Image editing | `source_image_url`, `edit_instruction` | `edited_image_url` |
 | OCR or visual analysis | Image analysis / OCR | `image_urls`, `analysis_prompt` | `analysis_result` or `extracted_text` |
 | Generate short video | Video generation | `video_prompt`, aspect/duration/frame URLs | `video_url` |
-| Join video clips | Concatenate videos | `video_urls` | `merged_video_url` |
-| Extract first/last frame | Extract first and last frame | `source_video_url` | `first_frame_image_url`, `last_frame_image_url` |
-| Text to speech | TTS / text-to-speech | `text_to_generate`, `language`, `voice_hint` | `audio_url` |
-| Speech to text | Speech recognition | `source_audio_url`, `language` | `transcript_text`, optional `utterances` |
-| Merge audio | Concatenate audio files | `audio_urls` | `merged_audio_url` |
+| Join clips / extract frames | Video editing | `video_urls` or `video_url` | `video_url` or `image_url` |
+| Text to speech | Audio generation | `text_to_generate`, `language`, `voice_hint` | `audio_url` |
+| Speech to text | Audio recognition | `source_audio_url`, `language` | `transcript_text`, optional `utterances` |
+| Merge audio | Audio merging | `audio_urls` | `merged_audio_url` |
 | Stock/index history | Financial data retrieval | `trading_symbol`, `unit`, `start`, `end` | `price_history` |
 | Literature search/citations | Academic research | `query` | `papers`, `bibtex` |
-| Create or modify documents/spreadsheets/slides | File creation / modification | `file_type`, `content_or_instruction`, optional `source_file_url` | `file_url` |
+| Save generated file | File storage | `file_type`, `content` | `file_url` |
 
 If the requested behavior is not in this table or the detailed sections below, do not invent it.
 
@@ -65,46 +53,6 @@ Rules:
 - Do not use search as an outbound API caller.
 - Include source links in output when the product promises research.
 
-## RSS Feed Fetching
-
-Use for fetching and parsing a specific RSS feed URL.
-
-Inputs:
-
-- `rss_url`: URL of the RSS feed;
-- optional filtering instructions, item limit, language, or summary instruction.
-
-Outputs:
-
-- feed `items` with title, URL, date, and optional summary;
-- source/feed metadata when useful.
-
-Rules:
-
-- Use RSS only when the user has or asks for an RSS URL.
-- Use web search/crawling when the user asks for general latest information without a feed URL.
-- Do not treat RSS fetching as arbitrary API integration.
-
-## Text Generation And Transformation
-
-Use for writing, rewriting, summarizing, translating, classifying, extracting, and structured JSON
-generation when no specialized media/retrieval capability is needed.
-
-Inputs:
-
-- `prompt` or `source_text`;
-- optional `language`, audience, tone, format, or transformation instruction.
-
-Outputs:
-
-- generated text or structured JSON fields needed by the product.
-
-Rules:
-
-- Text outputs must specify language behavior.
-- Keep structured outputs minimal and product-facing.
-- Do not claim streaming tokens or realtime generation.
-
 ## Image Generation
 
 Use for new images from prompts or prompt + reference URLs.
@@ -189,12 +137,12 @@ Rules:
 
 - Keep individual clips short, generally 5-10 seconds.
 - For consistency, generate/use a first-frame image.
-- For longer videos, generate clips and concatenate via video composition utilities.
+- For longer videos, generate clips and concatenate via video editing.
 - Audio in video works best with one speaker per clip.
 
-## Video Composition Utilities
+## Video Editing
 
-Use only for concatenating video clips or extracting first/last frames.
+Use for concatenating clips or extracting first/last frames.
 
 Inputs:
 
@@ -203,16 +151,14 @@ Inputs:
 
 Outputs:
 
-- concatenate: `merged_video_url`;
-- frame extraction: `first_frame_image_url`, `last_frame_image_url`.
+- `merged_video_url` or `frame_image_url`.
 
 Rules:
 
 - Inputs must be accessible URLs.
 - Best results when clips share resolution/aspect ratio.
-- Do not claim arbitrary video editing beyond concatenation and first/last-frame extraction.
 
-## Text To Speech
+## Audio Generation
 
 Use for text-to-speech.
 
@@ -231,10 +177,10 @@ Outputs:
 Rules:
 
 - Single speaker per call.
-- For dialogue, generate each speaker line and concatenate audio files.
+- For dialogue, generate each speaker line and merge audio.
 - `audio_hint` should describe voice in English.
 
-## Speech Recognition
+## Audio Recognition
 
 Use for speech-to-text.
 
@@ -253,24 +199,6 @@ Rules:
 
 - Audio must be URL-accessible.
 - Silent or low-quality audio can produce empty/poor transcript.
-- Do not promise realtime transcription or streaming captions.
-
-## Audio Concatenation
-
-Use for joining multiple audio files in order.
-
-Inputs:
-
-- `audio_urls`: two or more accessible audio URLs.
-
-Outputs:
-
-- `merged_audio_url`.
-
-Rules:
-
-- Use this after separate TTS calls for multi-speaker dialogue.
-- Do not claim arbitrary audio editing beyond concatenation.
 
 ## Financial Data Retrieval
 
@@ -315,15 +243,14 @@ Rules:
 - Availability varies by academic source.
 - PDF assets should be handled as URLs.
 
-## File Creation And Modification
+## File Storage
 
-Use when the workflow needs to create or modify supported files.
+Use when workflow needs to save generated content into a file.
 
 Inputs:
 
-- `file_type`: `txt`, `md`, `pdf`, `docx`, `pptx`, or `xlsx`;
-- `content_or_instruction`: content to create or instruction for modification;
-- optional `source_file_url`: URL of an existing file to modify.
+- `file_type`: `json`, `yaml`, `csv`, `pdf`, `md`, or `txt`;
+- `content`: string content to save.
 
 Outputs:
 
@@ -331,20 +258,18 @@ Outputs:
 
 Rules:
 
-- Supported file work is create/modify only for text, PDF, DOCX, PPTX, and XLSX.
-- Do not use file output as a database.
-- If app needs records/history, persist file URLs through entities.
-- Do not claim arbitrary binary editing, ZIP manipulation, or filesystem access.
+- Structured content must be serialized to string before saving.
+- Do not use file storage as a database.
+- If app needs records/history, persist file URL through entities.
 
 ## Composition Patterns
 
 | Pattern | Workflow design |
 |---|---|
 | Image -> Video | generate first-frame image, pass as `first_frame_url` to video generation |
-| Multi-clip video | generate short clips, concatenate via video composition utilities |
-| Dialogue audio | generate each speaker line, concatenate audio files |
-| RSS -> Digest | fetch RSS feed, synthesize a digest, optionally create a supported file |
-| Search -> Report | web search/crawl, synthesize structured report, optionally create a supported file |
+| Multi-clip video | generate short clips, concatenate via video editing |
+| Dialogue audio | generate each speaker line, merge audio |
+| Search -> Report | web search/crawl, synthesize structured report, optionally save file |
 | Video -> Image edit -> Video | extract frame, edit frame, use as next reference |
 | RAG document chat | indexing workflow + query workflow |
 

package/templates/vite/.howone/skills/howone/03-ai-capabilities/04-workflow-operations.md

@@ -3,22 +3,19 @@
 Use this reference when submitting HowOne external AI workflow create/update operations through
 `external-ai-capability`. This is an AI workflow design reference, not an app SDK guide.
 
-Workflow create/update/status operations are asynchronous control-plane operations. They are not
-runtime streaming support. Do not use job polling, task IDs, SSE, or background status as evidence
-that a user-facing AI workflow can stream partial results.
-
 ## Current Tool Contract
 
 Do not hand-build raw workflow HTTP requests in generated app work. Use `external-ai-capability`
 after `.howone/ai/manifest.json` has been synced.
 
-The tool performs:
+The foreground tool performs:
 
 ```text
 POST /workflows
-GET  /jobs/{job_id}
 ```
 
+The host-owned background poller performs `GET /jobs/{job_id}` and finalizes successful bindings.
+
 The tool reads the synced manifest and submits operations for selected capabilities.
 
 ## Create
@@ -69,16 +66,21 @@ Tool behavior:
 
 ```text
 previous config = current manifest capability.workflowId
-new config      = freshly generated UUID
+new config      = freshly generated UUID sent as config_id
 mode            = update
-manifest        = rewritten so capability.workflowId is the fresh UUID
+original_config_id = previous config sent to EAX
+workflow code   = regenerated by EAX from the current capability contract and updatePrompt
+submitted state = local manifest remains unchanged while EAX runs
+completed state = backend capability version receives the fresh UUID
 ```
 
-After update, re-read `.howone/ai/manifest.json`. The new manifest `workflowId` is the value used by
-SDK bindings and future execution.
+After a completed update, run `sync_ai_artifacts` and then re-read `.howone/ai/manifest.json`. The
+newly synced `workflowId` is the value used by SDK bindings and future execution. Failed operations
+keep their previous backend and local manifest bindings.
 
-Do not pass stale `workflowConfigID` values from old docs or older status payloads. The current
-tool owns config rotation and manifest write-back.
+Do not pass stale `workflowConfigID` values from old docs or older status payloads. Agents should
+not pass `original_config_id` directly either; the current tool derives it from the manifest and
+owns config rotation; the background finalizer owns backend binding promotion.
 
 ## Selection Rules
 
@@ -106,9 +108,6 @@ Terminal result meaning:
 | `completed` | workflow operation completed |
 | `failed` / `canceled` / `timed_out` | report error and do not pretend workflow is ready |
 
-For generated apps, progress UI is app-owned and should model non-streaming states such as
-pending/running/completed/failed around the final workflow result.
-
 ## Standard Flow
 
 New AI feature:
@@ -117,6 +116,8 @@ New AI feature:
 ai-capability-design apply_capability_patch
 sync_ai_artifacts
 external-ai-capability { cwd, capabilityNames }
+wait for terminal result
+sync_ai_artifacts
 read .howone/ai/manifest.json
 ```
 
@@ -126,6 +127,8 @@ Schema-changing AI update:
 ai-capability-design apply_capability_patch
 sync_ai_artifacts
 external-ai-capability { cwd, updates: [{ capabilityName, updatePrompt }] }
+wait for terminal result
+sync_ai_artifacts
 read .howone/ai/manifest.json
 ```
 
@@ -133,7 +136,10 @@ Behavior-only update:
 
 ```text
 external-ai-capability { cwd, updates: [{ capabilityName, updatePrompt }] }
+wait for terminal result
+sync_ai_artifacts
 read .howone/ai/manifest.json
+update SDK workflowId bindings from the newly synced manifest
 ```
 
 SDK/code work happens after these steps and belongs to the SDK track.
@@ -144,6 +150,6 @@ SDK/code work happens after these steps and belongs to the SDK track.
 - Create uses the existing manifest `workflowId`.
 - Update lets the tool generate a fresh config UUID.
 - Update has a concrete `updatePrompt`.
-- The manifest is re-read after update.
+- The backend capability version is finalized before local artifacts are synced again.
+- The manifest is re-read only after the post-completion sync.
 - SDK bindings are copied from manifest, not from memory or old status IDs.
-- Status polling is not streaming workflow output.