takomi 2.1.39 → 2.1.41

package/docs/features/TakomiFlow_Portable_Plugin.md

@@ -1,78 +1,82 @@
-# TakomiFlow Portable Plugin
-
-## Goal
-
-Move the proven TakomiFlow Google Flow automation into this repository as the source-of-truth portable package so users and agents can install it on fresh machines, reuse existing trusted Chrome sessions, and operate through MCP when available or CLI when not.
-
-## Components
-
-### Codex Plugin
-
-- `plugins/takomi-flow/`
-  - source-of-truth plugin package
-  - bundled skill, MCP server, CLI, schemas, prompts, and provider contract
-  - branded icon assets for store listing, dark mode, and composer surfaces
-  - browser automation scripts for trusted Chrome attach and Flow generation
-- `.agents/plugins/marketplace.json`
-  - repo-local marketplace entry for `takomi-flow`
-- `scripts/install-takomi-flow.ps1`
-  - optional installer for copying/registering the plugin into user/global Codex plugin paths
-- `assets/.agent/skills/takomi-flow/SKILL.md`
-  - standalone harness-visible skill for agents that do not load Codex plugin skills
-  - merged install/repair and runtime workflow instructions so agents have one TakomiFlow entrypoint
-
-### Agent Surface
-
-- First-run agents should run `doctor`, then check whether `http://127.0.0.1:9222` is already serving Chrome DevTools Protocol.
-- If CDP is alive, agents should reuse it.
-- If CDP is missing, agents should start `trusted-chrome` and ask the user to sign into Google Flow manually.
-- Agents should prefer MCP tools when the harness supports MCP and the plugin is installed.
-- Agents should offer plugin installation/repair in Codex only after user approval.
-- Agents should fall back to CLI commands and standalone skill instructions when MCP or plugins are absent.
-
-### Runtime Surface
-
-- CLI-first core: `node scripts/takomi-flow.mjs <command>`.
-- MCP adapter: `node scripts/mcp-server.mjs`.
-- Browser profile: user-local trusted Chrome profile by default.
-- Outputs: run folders with `run.json`, `assets.json`, `report.md`, screenshots, downloads, and optional video frames.
-
-## Data Flow
-
-1. Agent discovers or installs the plugin from this repo.
-2. Agent runs readiness checks.
-3. Agent checks for an existing trusted Chrome CDP instance.
-4. Agent reuses the instance or launches trusted Chrome.
-5. User signs in manually when needed.
-6. Agent prepares and validates a Flow request.
-7. Agent submits only with explicit spend approval.
-8. Agent records `projectUrl`, downloads assets, catalogs outputs, and writes a report.
-
-## Database Schema
-
-No database is required.
-
-Persistent state is file-based:
-
-- request JSON under `requests/`
-- run metadata in `run.json`
-- asset metadata in `assets.json`
-- Markdown handoff in `report.md`
-
-## Install / Portability Rules
-
-- MCP is optional, not required.
-- A harness without MCP can still use the CLI and skill instructions.
-- A fresh computer can bootstrap by running the repo installer or directly invoking the plugin CLI from this repo.
-- Global/user writes must be explicit installer actions, not hidden side effects.
-- Project URLs must be captured for every generated Flow project.
-
-## Verification
-
-- Plugin validation should pass with the Codex plugin validator.
-- Skill validation should pass with the Codex skill validator.
-- MCP smoke should pass when Node dependencies are installed.
-- CLI `doctor`, `capabilities`, `template`, `workflow`, `inspect`, `assets`, and `report` should work without MCP.
-- Store art should resolve from `assets/logo.png`, `assets/logo-dark.png`, and `assets/composer-icon.png`.
-- Store examples should show real creative workflows, not only a generic safe browser workflow prompt.
-- The generated neon TakomiFlow icon is used as the plugin logo and composer icon source.
+# TakomiFlow Portable Plugin
+
+## Goal
+
+Move the proven TakomiFlow Google Flow automation into this repository as the source-of-truth portable package so users and agents can install it on fresh machines, reuse existing trusted Chrome sessions, and operate through MCP when available or CLI when not.
+
+## Components
+
+### Codex Plugin
+
+- `plugins/takomi-flow/`
+  - source-of-truth plugin package
+  - bundled skill, MCP server, CLI, schemas, prompts, and provider contract
+  - branded icon assets for store listing, dark mode, and composer surfaces
+  - browser automation scripts for trusted Chrome attach and Flow generation
+- `.agents/plugins/marketplace.json`
+  - repo-local marketplace entry for `takomi-flow`
+- `scripts/install-takomi-flow.ps1`
+  - optional installer for copying/registering the plugin into user/global Codex plugin paths
+- `assets/.agent/skills/takomi-flow/SKILL.md`
+  - standalone harness-visible skill for agents that do not load Codex plugin skills
+  - merged install/repair and runtime workflow instructions so agents have one TakomiFlow entrypoint
+
+### Agent Surface
+
+- First-run agents should run `doctor`, then check whether `http://127.0.0.1:9222` is already serving Chrome DevTools Protocol.
+- If CDP is alive, agents should reuse it.
+- If CDP is missing, agents should start `trusted-chrome` and ask the user to sign into Google Flow manually.
+- For repeated generations, agents should reuse the current Flow project tab or pass `projectUrl`; clicking `New project` requires explicit `allowNewProject`.
+- If a project chat is stale or broken, agents should recover by creating a fresh chat inside the same project before asking for manual intervention.
+- Agents should prefer MCP tools when the harness supports MCP and the plugin is installed.
+- Agents should offer plugin installation/repair in Codex only after user approval.
+- Agents should fall back to CLI commands and standalone skill instructions when MCP or plugins are absent.
+
+### Runtime Surface
+
+- CLI-first core: `node scripts/takomi-flow.mjs <command>`.
+- MCP adapter: `node scripts/mcp-server.mjs`.
+- Browser profile: user-local trusted Chrome profile by default.
+- Outputs: run folders with `run.json`, `assets.json`, `report.md`, screenshots, downloads, and optional video frames.
+
+## Data Flow
+
+1. Agent discovers or installs the plugin from this repo.
+2. Agent runs readiness checks.
+3. Agent checks for an existing trusted Chrome CDP instance.
+4. Agent reuses the instance or launches trusted Chrome.
+5. User signs in manually when needed.
+6. Agent resolves the target project from `projectUrl` or the current project tab.
+7. Agent prepares and validates a Flow request.
+8. Agent submits only with explicit spend approval.
+9. Agent records `projectUrl`, downloads assets, catalogs outputs, and writes a report.
+
+## Database Schema
+
+No database is required.
+
+Persistent state is file-based:
+
+- request JSON under `requests/`
+- run metadata in `run.json`
+- asset metadata in `assets.json`
+- Markdown handoff in `report.md`
+
+## Install / Portability Rules
+
+- MCP is optional, not required.
+- A harness without MCP can still use the CLI and skill instructions.
+- A fresh computer can bootstrap by running the repo installer or directly invoking the plugin CLI from this repo.
+- Global/user writes must be explicit installer actions, not hidden side effects.
+- Project URLs must be captured for every generated Flow project.
+- New Flow projects are opt-in; project reuse is the default.
+
+## Verification
+
+- Plugin validation should pass with the Codex plugin validator.
+- Skill validation should pass with the Codex skill validator.
+- MCP smoke should pass when Node dependencies are installed.
+- CLI `doctor`, `capabilities`, `template`, `workflow`, `inspect`, `assets`, and `report` should work without MCP.
+- Store art should resolve from `assets/logo.png`, `assets/logo-dark.png`, and `assets/composer-icon.png`.
+- Store examples should show real creative workflows, not only a generic safe browser workflow prompt.
+- The generated neon TakomiFlow icon is used as the plugin logo and composer icon source.

package/docs/takomi-flow-onboarding.md

@@ -1,76 +1,86 @@
-# TakomiFlow Onboarding
-
-TakomiFlow is packaged in this repo at `plugins/takomi-flow`.
-
-## First Run
-
-If all you have is a skill, use the bundled `takomi-flow` skill. It is the single front door: it can operate an already-installed plugin through MCP or CLI, install or repair the Codex plugin after user approval, or stay in skill/CLI mode for harnesses that do not support Codex plugins.
-
-1. Install or register the plugin:
-
-   ```powershell
-   ./scripts/install-takomi-flow.ps1 -InstallDependencies
-   ```
-
-2. Check the local runtime:
-
-   ```powershell
-   node plugins/takomi-flow/scripts/takomi-flow.mjs doctor
-   ```
-
-3. Check whether a trusted Chrome instance is already running:
-
-   ```powershell
-   Invoke-WebRequest http://127.0.0.1:9222/json/version -UseBasicParsing
-   ```
-
-4. If Chrome is already running on port `9222`, reuse it with:
-
-   ```powershell
-   --cdp-url http://127.0.0.1:9222
-   ```
-
-5. If Chrome is not running, launch it:
-
-   ```powershell
-   node plugins/takomi-flow/scripts/takomi-flow.mjs trusted-chrome
-   ```
-
-6. Sign into Google Flow manually in the opened browser.
-
-7. Run a no-spend observe before generation:
-
-   ```powershell
-   node plugins/takomi-flow/scripts/takomi-flow.mjs observe --allow-browser --cdp-url http://127.0.0.1:9222
-   ```
-
-## MCP Or CLI
-
-- If the harness supports MCP, use TakomiFlow MCP tools.
-- If MCP is unavailable, use the CLI commands directly.
-- If a harness has neither MCP nor shell access, use the skill instructions as a handoff checklist for a human/operator.
-
-Generation is always spend-gated. Use `--allow-spend` only after explicit approval.
-
-## Finding It In Codex
-
-After this repo is installed or registered, Codex should show:
-
-- `Takomi Codex` under the `J StaR Films Studios` marketplace section.
-- `TakomiFlow` under the same marketplace section.
-
-On the developer machine, a second `TakomiFlow` may also appear under `Personal` if `scripts/install-takomi-flow.ps1` copied the plugin into `~/plugins/takomi-flow` and registered `~/.agents/plugins/marketplace.json`. That personal entry is useful for local testing; the repo entry is the package source other people should install.
-
-People can search for:
-
-- `TakomiFlow`
-- `Flow`
-- `Google Flow`
-- `image generation`
-- `video generation`
-- `asset pipeline`
-- `Takomi`
-
-If they only have the skill and not the plugin, search/install:
-
-- `takomi-flow`
+# TakomiFlow Onboarding
+
+TakomiFlow is packaged in this repo at `plugins/takomi-flow`.
+
+## First Run
+
+If all you have is a skill, use the bundled `takomi-flow` skill. It is the single front door: it can operate an already-installed plugin through MCP or CLI, install or repair the Codex plugin after user approval, or stay in skill/CLI mode for harnesses that do not support Codex plugins.
+
+1. Install or register the plugin:
+
+   ```powershell
+   ./scripts/install-takomi-flow.ps1 -InstallDependencies
+   ```
+
+2. Check the local runtime:
+
+   ```powershell
+   node plugins/takomi-flow/scripts/takomi-flow.mjs doctor
+   ```
+
+3. Check whether a trusted Chrome instance is already running:
+
+   ```powershell
+   Invoke-WebRequest http://127.0.0.1:9222/json/version -UseBasicParsing
+   ```
+
+4. If Chrome is already running on port `9222`, reuse it with:
+
+   ```powershell
+   --cdp-url http://127.0.0.1:9222
+   ```
+
+5. If Chrome is not running, launch it:
+
+   ```powershell
+   node plugins/takomi-flow/scripts/takomi-flow.mjs trusted-chrome
+   ```
+
+6. Sign into Google Flow manually in the opened browser.
+
+7. Run a no-spend observe before generation:
+
+   ```powershell
+   node plugins/takomi-flow/scripts/takomi-flow.mjs observe --allow-browser --cdp-url http://127.0.0.1:9222
+   ```
+
+## Reusing One Flow Project
+
+For repeated generations, leave trusted Chrome open on the Flow project editor and reuse it:
+
+```powershell
+node plugins/takomi-flow/scripts/takomi-flow.mjs workflow --kind video --prompt "cinematic lab scene" --project-url "https://labs.google/fx/tools/flow/project/..." --submit --allow-browser --allow-spend --cdp-url http://127.0.0.1:9222
+```
+
+TakomiFlow does not click `New project` unless `--allow-new-project` is set. If a chat surface is stale or broken, it tries one fresh chat inside the same project before asking for manual help.
+
+## MCP Or CLI
+
+- If the harness supports MCP, use TakomiFlow MCP tools.
+- If MCP is unavailable, use the CLI commands directly.
+- If a harness has neither MCP nor shell access, use the skill instructions as a handoff checklist for a human/operator.
+
+Generation is always spend-gated. Use `--allow-spend` only after explicit approval.
+
+## Finding It In Codex
+
+After this repo is installed or registered, Codex should show:
+
+- `Takomi Codex` under the `J StaR Films Studios` marketplace section.
+- `TakomiFlow` under the same marketplace section.
+
+On the developer machine, a second `TakomiFlow` may also appear under `Personal` if `scripts/install-takomi-flow.ps1` copied the plugin into `~/plugins/takomi-flow` and registered `~/.agents/plugins/marketplace.json`. That personal entry is useful for local testing; the repo entry is the package source other people should install.
+
+People can search for:
+
+- `TakomiFlow`
+- `Flow`
+- `Google Flow`
+- `image generation`
+- `video generation`
+- `asset pipeline`
+- `Takomi`
+
+If they only have the skill and not the plugin, search/install:
+
+- `takomi-flow`

package/docs/takomi-flow-public-distribution.md

@@ -1,94 +1,94 @@
-# TakomiFlow Public Distribution
-
-TakomiFlow is packaged in this repo, but users need one distribution path before it can appear in their Codex Store.
-
-## NPM Package Strategy
-
-Do not create a second npm package by default.
-
-TakomiFlow should ship inside the existing `takomi` / VibeCode Protocol Suite package:
-
-- `plugins/takomi-flow` contains the Codex plugin.
-- `assets/.agent/skills/takomi-flow` contains the standalone non-plugin skill for harnesses that read bundled skills, plus the install/repair instructions for Codex plugin use.
-- `scripts/install-takomi-flow.ps1` installs/registers the bundled plugin into the user's global Codex plugin location.
-
-A separate `takomi-flow` npm package would only be useful later if TakomiFlow needs independent versioning, releases, or dependencies. For now, keeping it inside the existing suite avoids duplicated publishing, duplicated docs, and version drift.
-
-## Best Path
-
-Publish or distribute the VibeCode Protocol Suite, then let users install the TakomiFlow plugin from the suite bundle.
-
-Once they have the suite from GitHub or the published `takomi` package:
-
-```powershell
-git clone https://github.com/JStaRFilms/VibeCode-Protocol-Suite "$HOME\Source\VibeCode-Protocol-Suite"
-cd "$HOME\Source\VibeCode-Protocol-Suite"
-.\scripts\install-takomi-flow.ps1 -InstallDependencies
-```
-
-That installs:
-
-```text
-~/plugins/takomi-flow
-~/.agents/plugins/marketplace.json
-```
-
-Then Codex can show TakomiFlow in the personal/store plugin list.
-
-## Skill-Only Bootstrap
-
-If a user only has skills and no plugin yet, give them the bundled `takomi-flow` skill. That one skill teaches Codex or another harness how to:
-
-1. Check whether TakomiFlow is already installed.
-2. Clone or locate the VibeCode Protocol Suite.
-3. Run `scripts/install-takomi-flow.ps1`.
-4. Install dependencies.
-5. Verify the plugin with `doctor`.
-6. Reuse or launch trusted Chrome.
-
-This is the lightest path when the full plugin is not installed yet, while avoiding a confusing second TakomiFlow installer skill.
-
-## MCP Is Optional
-
-TakomiFlow should be useful in three tiers:
-
-- Full Codex plugin and MCP tools when the harness supports them.
-- CLI-only operation when MCP is unavailable.
-- Skill-only install instructions when the plugin is missing.
-
-The CLI entrypoint remains:
-
-```powershell
-node "$HOME\plugins\takomi-flow\scripts\takomi-flow.mjs" <command>
-```
-
-## Store Search Terms
-
-Users should be able to find it by searching:
-
-- `TakomiFlow`
-- `Takomi Flow`
-- `Google Flow`
-- `Flow automation`
-- `image generation`
-- `video generation`
-- `asset pipeline`
-- `Takomi`
-
-## Publishing Checklist
-
-Before telling users it is public:
-
-1. Push this repo to GitHub.
-2. Confirm `plugins/takomi-flow` is included.
-3. Confirm `assets/.agent/skills/takomi-flow` is included.
-4. Confirm `npm pack --dry-run` includes TakomiFlow files but not `plugins/takomi-flow/node_modules`.
-5. Publish/update the existing `takomi` npm package or release archive.
-6. Test on a clean user profile:
-
-   ```powershell
-   .\scripts\install-takomi-flow.ps1 -InstallDependencies
-   node "$HOME\plugins\takomi-flow\scripts\takomi-flow.mjs" doctor
-   ```
-
-7. Open Codex Store and search `TakomiFlow`.
+# TakomiFlow Public Distribution
+
+TakomiFlow is packaged in this repo, but users need one distribution path before it can appear in their Codex Store.
+
+## NPM Package Strategy
+
+Do not create a second npm package by default.
+
+TakomiFlow should ship inside the existing `takomi` / VibeCode Protocol Suite package:
+
+- `plugins/takomi-flow` contains the Codex plugin.
+- `assets/.agent/skills/takomi-flow` contains the standalone non-plugin skill for harnesses that read bundled skills, plus the install/repair instructions for Codex plugin use.
+- `scripts/install-takomi-flow.ps1` installs/registers the bundled plugin into the user's global Codex plugin location.
+
+A separate `takomi-flow` npm package would only be useful later if TakomiFlow needs independent versioning, releases, or dependencies. For now, keeping it inside the existing suite avoids duplicated publishing, duplicated docs, and version drift.
+
+## Best Path
+
+Publish or distribute the VibeCode Protocol Suite, then let users install the TakomiFlow plugin from the suite bundle.
+
+Once they have the suite from GitHub or the published `takomi` package:
+
+```powershell
+git clone https://github.com/JStaRFilms/VibeCode-Protocol-Suite "$HOME\Source\VibeCode-Protocol-Suite"
+cd "$HOME\Source\VibeCode-Protocol-Suite"
+.\scripts\install-takomi-flow.ps1 -InstallDependencies
+```
+
+That installs:
+
+```text
+~/plugins/takomi-flow
+~/.agents/plugins/marketplace.json
+```
+
+Then Codex can show TakomiFlow in the personal/store plugin list.
+
+## Skill-Only Bootstrap
+
+If a user only has skills and no plugin yet, give them the bundled `takomi-flow` skill. That one skill teaches Codex or another harness how to:
+
+1. Check whether TakomiFlow is already installed.
+2. Clone or locate the VibeCode Protocol Suite.
+3. Run `scripts/install-takomi-flow.ps1`.
+4. Install dependencies.
+5. Verify the plugin with `doctor`.
+6. Reuse or launch trusted Chrome.
+
+This is the lightest path when the full plugin is not installed yet, while avoiding a confusing second TakomiFlow installer skill.
+
+## MCP Is Optional
+
+TakomiFlow should be useful in three tiers:
+
+- Full Codex plugin and MCP tools when the harness supports them.
+- CLI-only operation when MCP is unavailable.
+- Skill-only install instructions when the plugin is missing.
+
+The CLI entrypoint remains:
+
+```powershell
+node "$HOME\plugins\takomi-flow\scripts\takomi-flow.mjs" <command>
+```
+
+## Store Search Terms
+
+Users should be able to find it by searching:
+
+- `TakomiFlow`
+- `Takomi Flow`
+- `Google Flow`
+- `Flow automation`
+- `image generation`
+- `video generation`
+- `asset pipeline`
+- `Takomi`
+
+## Publishing Checklist
+
+Before telling users it is public:
+
+1. Push this repo to GitHub.
+2. Confirm `plugins/takomi-flow` is included.
+3. Confirm `assets/.agent/skills/takomi-flow` is included.
+4. Confirm `npm pack --dry-run` includes TakomiFlow files but not `plugins/takomi-flow/node_modules`.
+5. Publish/update the existing `takomi` npm package or release archive.
+6. Test on a clean user profile:
+
+   ```powershell
+   .\scripts\install-takomi-flow.ps1 -InstallDependencies
+   node "$HOME\plugins\takomi-flow\scripts\takomi-flow.mjs" doctor
+   ```
+
+7. Open Codex Store and search `TakomiFlow`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "takomi",
-  "version": "2.1.39",
+  "version": "2.1.41",
   "description": "🎯 Stop wrestling with AI. Start building with purpose. The artisan's toolkit for agent workflows, Codex skills, and original Takomi capabilities like 21st.dev integration.",
   "type": "module",
   "bin": {

package/plugins/takomi-flow/.mcp.json

@@ -1,11 +1,11 @@
-{
-  "mcpServers": {
-    "takomi-flow": {
-      "type": "stdio",
-      "command": "node",
-      "args": [
-        "scripts/mcp-server.mjs"
-      ]
-    }
-  }
-}
+{
+  "mcpServers": {
+    "takomi-flow": {
+      "type": "stdio",
+      "command": "node",
+      "args": [
+        "scripts/mcp-server.mjs"
+      ]
+    }
+  }
+}