chore: update AI tooling docs/settings

.claude/settings.json

@@ -15,15 +15,44 @@
       "Bash(flow browse:*)",
       "Bash(flow mcp:*)",
       "Bash(flow exec:*)",
-      "Bash(node:*)",
-      "Bash(npm view:*)",
+      "mcp__flow__run_command",
+      "mcp__flow__run_executable",
+      "mcp__flow__get_execution_logs",
+      "mcp__flow__sync_executables",
+      "mcp__flow__write_flowfile",
+      "mcp__flow__get_workspace_config",
       "mcp__flow__list_executables",
       "mcp__flow__get_info",
       "mcp__flow__get_executable",
       "mcp__flow__get_workspace",
       "mcp__flow__list_workspaces",
       "mcp__flow__execute"
     ],
-    "deny": []
+    "ask": [
+      "Bash(git push:*)",
+      "Bash(git reset --hard:*)",
+      "Bash(git clean:*)",
+      "Bash(gh pr create:*)",
+      "Bash(gh issue create:*)",
+      "Bash(gh release:*)",
+      "Bash(flow publish:*)",
+      "Bash(docker push:*)"
+    ],
+    "deny": [
+      "Edit(types/**/*.gen.go)",
+      "Write(types/**/*.gen.go)",
+      "Edit(docs/cli/**)",
+      "Write(docs/cli/**)",
+      "Edit(docs/types/**)",
+      "Write(docs/types/**)",
+      "Edit(docs/public/schemas/**)",
+      "Write(docs/public/schemas/**)",
+      "Bash(flow secret get:*)",
+      "Bash(flow secret list:*)",
+      "Bash(env)",
+      "Bash(printenv:*)",
+      "Read(./.env)",
+      "Read(./.env.*)"
+    ]
   }
 }

.claude/skills/new-command/SKILL.md

@@ -3,24 +3,28 @@ name: new-command
 description: Scaffold a new Cobra CLI command following the project's patterns.
 disable-model-invocation: true
 argument-hint: "<verb> [noun] — what the command does"
-allowed-tools: Bash(flow build:*) Bash(go build:*) Read
+allowed-tools: mcp__flow__execute, mcp__flow__run_command, mcp__flow__list_executables, Bash(flow build:*), Bash(go build:*), Read
 ---
 
 Scaffold a new Cobra CLI command for: $ARGUMENTS
 
 Before writing any code, read a similar existing command to match the exact style:
-- Simple verb commands: `cmd/exec.go`
-- Noun/verb subcommands: any file under `cmd/workspace/` or `cmd/vault/`
+- Simple verb commands: `cmd/internal/exec.go`
+- Noun/verb subcommands: `cmd/internal/workspace.go` or `cmd/internal/vault.go` — each groups its
+  subcommands in a single file rather than a directory
 
 Then follow these patterns:
 
-1. **File location**: `cmd/<verb>.go` for top-level, or `cmd/<noun>/<verb>.go` for subcommands
-2. **Command registration**: register in the parent command's `init()` or `cmd/root.go`
+1. **File location**: `cmd/internal/<noun>.go`. Only `root.go` lives directly in `cmd/`; every
+   command handler is under `cmd/internal/`. Shared helpers go in `cmd/internal/helpers.go`,
+   flags in `cmd/internal/flags/`, output shaping in `cmd/internal/response/`.
+2. **Command registration**: register on the parent command, or add to `rootCmd` in `cmd/root.go`
 3. **Error handling**:
    - Runtime errors → `errhandler.HandleFatal(ctx, cmd, err)`
    - Flag/arg misuse → `errhandler.HandleUsage(ctx, cmd, "message", args...)`
    - Never use `log.Fatal`, `os.Exit`, or `logger.Log().FatalErr()` in `cmd/`
 4. **Context**: resolve workspace context via `pkg/context` before delegating to `internal/services`
 5. **Output**: respect `--output` flag (text/json/yaml) for structured responses
 
-After scaffolding, verify it builds: `flow build binary ./bin/flow`
+After scaffolding, verify it builds — prefer `mcp__flow__execute` with ref `build binary` and
+argument `./bin/flow` over a raw shell call.

.claude/skills/new-exec-type/SKILL.md

@@ -3,26 +3,30 @@ name: new-exec-type
 description: Add a new executable type to the flow runner (a new kind of automation block users can define in .flow files).
 disable-model-invocation: true
 argument-hint: "<type-name> — description of what this executable type does"
-allowed-tools: Bash(flow generate:*) Bash(flow validate:*) Bash(flow build:*) Bash(go test:*) Read
+allowed-tools: mcp__flow__execute, mcp__flow__run_command, mcp__flow__list_executables, Bash(flow generate:*), Bash(flow validate:*), Bash(flow build:*), Bash(go test:*), Read
 ---
 
 Add a new executable type to the flow runner for: $ARGUMENTS
 
 An "executable type" is a new automation block users can declare in `.flow` files (like `exec`, `serial`, `parallel`, `render`). Follow these steps in order:
 
-1. **Schema first** — add the new type's fields to `types/executable/schema.yaml`.
-   Read the existing schema to match the structure. Run `flow generate` to regenerate `types/executable/generated.go`.
+1. **Schema first** — add the new type's fields to `types/executable/executable_schema.yaml`.
+   Read the existing schema to match the structure. Regenerate with the `generate` executable
+   (`mcp__flow__execute`, ref `generate`) — it rewrites `types/executable/executable.gen.go`.
+   Never edit the `.gen.go` file directly.
 
-2. **Runner handler** — create `internal/runner/<type>.go` implementing the runner interface.
-   Read `internal/runner/exec.go` or `internal/runner/serial.go` as reference for the exact interface and pattern.
+2. **Runner handler** — each type is its own package: create `internal/runner/<type>/<type>.go`.
+   Read `internal/runner/exec/exec.go` or `internal/runner/serial/serial.go` as reference for the
+   exact interface and pattern.
 
 3. **Register the type** — wire the new handler into `internal/runner/runner.go` (the dispatch table).
 
 4. **Parser support** — update `internal/fileparser/` if needed to recognize and validate the new type during YAML parsing.
 
-5. **Tests** — add unit tests in `internal/runner/<type>_test.go` using Ginkgo.
+5. **Tests** — add unit tests in `internal/runner/<type>/<type>_test.go` using Ginkgo.
    Use `Describe`/`It`/`Entry` — never `FDescribe`/`FIt`. Cover happy path and error cases.
 
-6. **Validate** — run `flow validate` to confirm generate, lint, and tests all pass.
+6. **Validate** — run the `validate` executable (`mcp__flow__execute`, ref `validate`) to confirm
+   generate, lint, and tests all pass.
 
 Do not skip the schema step — editing generated files directly will cause CI to fail.

.claude/skills/pr-ready/SKILL.md

@@ -2,15 +2,17 @@
 name: pr-ready
 description: Run a pre-PR readiness check and report READY or NOT READY.
 disable-model-invocation: true
-allowed-tools: Bash(git *) Bash(flow validate:*) Bash(flow generate:*) Bash(go test:*) Read
+allowed-tools: mcp__flow__execute, mcp__flow__run_command, mcp__flow__list_executables, Bash(git:*), Bash(flow validate:*), Bash(flow generate:*), Bash(go test:*), Read
 ---
 
 Check whether the current branch is ready to open a PR. Work through each item and report PASS or FAIL:
 
 1. **No focus markers** — `grep -rn "FDescribe\|FIt\|FEntry\|FContext\|FWhen" --include="*.go" .`
    Any match is a FAIL — these silently exclude all other tests in the suite.
 
-2. **Validation passes** — run `flow validate`. All steps must pass.
+2. **Validation passes** — run the `validate` executable via `mcp__flow__execute` (ref: `validate`).
+   All steps must pass. Use `mcp__flow__run_command` for the `git`/`grep` checks below so they land
+   in flow's history alongside it.
 
 3. **No debug artifacts** — grep for `fmt.Println`, `spew.Dump` in `cmd/`, `internal/`, `pkg/`.
    Flag anything that looks like leftover debug output (not legitimate logging).

.claude/skills/validate/SKILL.md

@@ -1,16 +1,22 @@
 ---
 name: validate
 description: Run flow validate and fix any failures. Invoke after completing a feature or bug fix to confirm the codebase is clean before committing.
-allowed-tools: Bash(flow validate:*) Bash(flow generate:*) Bash(flow lint:*) Bash(flow test:*) Bash(go test:*) Read
+allowed-tools: mcp__flow__execute, mcp__flow__run_command, mcp__flow__list_executables, mcp__flow__get_execution_logs, Bash(flow validate:*), Bash(flow generate:*), Bash(flow lint:*), Bash(flow test:*), Bash(go test:*), Read
 ---
 
-Run `flow validate` — it runs these steps in order: `generate` → `lint` → `test` → `validate generated` (checks for uncommitted generated diffs in CI).
+Run the `validate` executable via `mcp__flow__execute` (ref: `validate`) rather than a raw shell
+call, so the run inherits workspace env/secrets and is captured in flow's history.
+
+It runs these steps in order: `generate` → `lint` → `test` → `validate generated` (checks for uncommitted generated diffs in CI).
 
 For each failure, diagnose and fix before moving on:
 
-- **generate fails**: Schema syntax error in `types/*/schema.yaml` — read and fix the schema
+- **generate fails**: Schema syntax error in the source schema — `types/executable/*_schema.yaml`, or `types/{config,workspace,common}/schema.yaml`. Read and fix the schema, never the `.gen.go` output.
 - **lint fails**: Read the golangci-lint output, fix each violation, re-run
 - **test fails**: Read the Ginkgo output, identify the failing spec, fix the root cause — do not skip or comment out tests
-- **validate generated fails**: Generated files are out of sync — run `flow generate` and stage the regenerated files; this is always the fix
+- **validate generated fails**: Generated files are out of sync — re-run the `generate` executable and stage the regenerated files; this is always the fix
+
+Use `mcp__flow__get_execution_logs` with `mine: true` to re-read output from a run instead of
+re-running it.
 
-Do not report done until `flow validate` exits 0 with all steps passing.
+Do not report done until `validate` exits 0 with all steps passing.

.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "flow": {
+      "type": "stdio",
+      "command": "flow",
+      "args": ["mcp"]
+    }
+  }
+}