tktl-cli 0.1.0a1__tar.gz

tktl_cli-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: [self-hosted, ub-arm-2core-ue2]
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run ty check src/ tests/
+
+  test:
+    runs-on: [self-hosted, ub-arm-2core-ue2]
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+      - run: uv sync
+      - run: uv run pytest -x -v --ignore=tests/test_integration
+
+  package:
+    runs-on: [self-hosted, ub-arm-2core-ue2]
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+      - run: uv build
+      - name: Verify no sensitive files in wheel
+        run: |
+          WHEEL=$(ls dist/*.whl)
+          FOUND=$(unzip -l "$WHEEL" | grep -cE '(openapi/|templates/.*\.json|\.env)' || true)
+          if [ "$FOUND" -ne 0 ]; then
+            echo "::error::Wheel contains excluded files:"
+            unzip -l "$WHEEL" | grep -E '(openapi/|templates/.*\.json|\.env)'
+            exit 1
+          fi
+      - name: Verify no sensitive files in sdist
+        run: |
+          SDIST=$(ls dist/*.tar.gz)
+          FOUND=$(tar tzf "$SDIST" | grep -cE '(openapi/|templates/.*\.json|\.env)' || true)
+          if [ "$FOUND" -ne 0 ]; then
+            echo "::error::Sdist contains excluded files:"
+            tar tzf "$SDIST" | grep -E '(openapi/|templates/.*\.json|\.env)'
+            exit 1
+          fi
+
+  integration:
+    runs-on: [self-hosted, ub-arm-2core-ue2]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [lint, test]
+    env:
+      TKTL_DEV_API_KEY: ${{ secrets.TKTL_DEV_API_KEY }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+      - run: uv sync
+      - name: Verify API key is set
+        run: |
+          if [ -z "$TKTL_DEV_API_KEY" ]; then
+            echo "::error::TKTL_DEV_API_KEY is not set. Add DEV_API_KEY as a repository secret."
+            exit 1
+          fi
+          echo "API key is configured (${#TKTL_DEV_API_KEY} chars)"
+      - run: uv run pytest tests/test_integration -v --tb=short

tktl_cli-0.1.0a1/.github/workflows/publish.yml

@@ -0,0 +1,68 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  lint:
+    runs-on: [self-hosted, ub-arm-2core-ue2]
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run ty check src/ tests/
+
+  test:
+    runs-on: [self-hosted, ub-arm-2core-ue2]
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+      - run: uv sync
+      - run: uv run pytest -x -v --ignore=tests/test_integration
+
+  build:
+    runs-on: [self-hosted, ub-arm-2core-ue2]
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+      - run: uv build
+      - name: Verify no sensitive files in wheel
+        run: |
+          WHEEL=$(ls dist/*.whl)
+          FOUND=$(unzip -l "$WHEEL" | grep -cE '(openapi/|templates/.*\.json|\.env)' || true)
+          if [ "$FOUND" -ne 0 ]; then
+            echo "::error::Wheel contains excluded files:"
+            unzip -l "$WHEEL" | grep -E '(openapi/|templates/.*\.json|\.env)'
+            exit 1
+          fi
+      - name: Verify no sensitive files in sdist
+        run: |
+          SDIST=$(ls dist/*.tar.gz)
+          FOUND=$(tar tzf "$SDIST" | grep -cE '(openapi/|templates/.*\.json|\.env)' || true)
+          if [ "$FOUND" -ne 0 ]; then
+            echo "::error::Sdist contains excluded files:"
+            tar tzf "$SDIST" | grep -E '(openapi/|templates/.*\.json|\.env)'
+            exit 1
+          fi
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    runs-on: [self-hosted, ub-arm-2core-ue2]
+    needs: [build]
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+      - run: uv publish --trusted-publishing always dist/*

tktl_cli-0.1.0a1/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.ruff_cache/
+.env
+.tktl-local/
+tmp/

tktl_cli-0.1.0a1/ADR.md

@@ -0,0 +1,246 @@
+# ADR: tktl CLI Architecture Decisions
+
+> **Legend:** 🔶 = work-in-progress or planned
+
+---
+
+## Context
+
+- We want agents to author and test flows, as per Q2 2026 OKR
+    - [We built a set of tools (CLI + skill) for agentic whole flow authoring that have at least 10 internal and 2 external weekly users. All functionality is built in such a way that they can be integrated into an on-platform copilot on the Agents infrastructure in Q3'26.](https://www.notion.so/We-built-a-set-of-tools-CLI-skill-for-agentic-whole-flow-authoring-that-have-at-least-10-interna-32f0a226e5be80f3a1c2d51a7f8d7fd5?pvs=21)
+- Three consumer types need the same operations:
+    - Humans in terminals
+    - Automation scripts (automated updates, rollouts)
+    - Agents: local (Claude Code/Codex) and on-platform (hosted agent runtime)
+- We need to support large flow editing
+    - Flow versions can contain thousands of nodes, producing 10,000+ line JSON on GET
+    - The Flow API has no node-level endpoints. Nodes are embedded in the version graph
+    - PATCH requires the full node set in the body (otherwise 409)
+- Multiple users and agents may edit the same flow version concurrently
+
+---
+
+## Principles
+
+**We optimize for**
+
+- **Agent efficiency:** surgical operations + auto-JSON + cache decomposition keep context windows small
+- **Zero code duplication:** one ops layer serves CLI, agents, scripts, and future interfaces
+- **Simple concurrency:** ETag retries + node locks, invisible to the user, prevent data loss
+- **Composability:** every command produces structured JSON for shell pipelines and automation
+- **Low token cost:** `--summary`, `--section`, per-node cache files minimize data transferred to agents
+- **Fast iteration:** APIs are stable, CLI and skill can change faster, especially during internal testing
+- **Agents code:** we embrace agent coding, kept on point from specification files in repository
+
+**We accept**
+
+- **Client-side node extraction:** the CLI must fetch and decompose the full version graph. Cache mitigates this but first-fetch is expensive
+- 🔶 **Internal Flow API exposure:** should be moved to public-facing workspace API before public release
+- **Cache staleness risk:** 5-minute TTL can serve stale data. ETag validation on writes catches this but reads may be outdated
+- 🔶 **Local tooling assumption:** the design leans on `jq`, `grep`, `diff` and filesystem access. Risk for on-platform runtime where bash is not exposed
+
+---
+
+## Decision
+
+### 1. Repo code structure
+
+#### 1.1 Library-first, CLI as interface
+
+- All business logic in `tktl.ops` as importable Python functions
+- CLI (`tktl.cli`) is a thin Typer wrapper: parse args → call ops → format output
+- No business logic in the CLI layer, ever
+- Three access modes from the same code: CLI, Python import, MCP tool
+
+```
+tktl.cli         → Typer (arg parsing + output formatting only)
+tktl.ops         → business logic, caching, locking, ID resolution
+tktl.api         → hand-written HTTP orchestration (auth, headers, retries)
+tktl.generated   → auto-generated from OpenAPI (never edit)
+```
+
+#### 1.2 CLI as primary interface, not MCP
+
+We expose 60+ commands across 13 resource groups, growing. At that scale, CLI beats MCP:
+
+- **Zero schema bloat.** MCP injects every tool's schema upfront (thousands of tokens). CLI has zero upfront cost, agent calls `--help` on demand.
+- **Shell composability.** `tktl nodes list credit-scoring v1 | jq '.[].name' | grep -i "risk"`. Each command composes with every Unix tool.
+- **Debuggability.** Human can run the exact same command the agent ran. MCP calls are opaque.
+- **Token efficiency.** >10x more efficient than equivalent MCP tool definitions.
+
+**When MCP makes sense:** non-developer access (analysts in chat UIs) or multi-agent runtime discovery.
+
+**Three-layer stack:**
+
+| Layer | Role | Example |
+|---|---|---|
+| **Capability (CLI)** | `--help` flags, JSON output, semantic exit codes | `tktl nodes describe credit-scoring v1 <id>` |
+| **Procedure (Skill)** | How to use the CLI effectively: workflows, gotchas | `skills/flow-builder/SKILL.md` |
+| **Bridge (MCP)** | 🔶 Thin wrapper calling CLI under the hood | Planned: `tktl-mcp-server` |
+
+#### 1.3 Agent skills over vendor-specific commands
+
+- Skills in `skills/` using [agentskills.io](https://agentskills.io) format, not `.claude/commands/`
+- Vendor-neutral, works across 35+ agent products
+- Each skill: `SKILL.md` + `references/` subfolder loaded on demand
+
+#### 1.4 CLI resource ordering and structure
+
+Pattern: `tktl <resource> <action>`. Consistent verbs across all resources.
+
+| Resource | Read actions | Write actions |
+|---|---|---|
+| `flows` | `list`, `describe`, `explain`, `history` | `create`, `update`, `run`, `batch`, `wizard` |
+| `versions` | `list`, `describe`, `diff`, `changes` | `create`, `duplicate`, `publish`, `archive` |
+| `nodes` | `list`, `describe` | `add`, `edit`, `remove` |
+| `update` | -- | `apply` (node config, params, schemas, full replace) |
+| `groups` | `list`, `describe` | `create`, `update`, `delete`, `add-nodes`, `remove-nodes` |
+| `datasets` | `list`, `describe`, `rows`, `download` | `create`, `upload`, `add-rows`, `update-row`, `delete-row`, `add-column`, `rename-column`, `delete-column`, `fill-column`, `sync-schema`, `delete` |
+| `connections` | `list` | `create`, `create-resource`, `update-secrets` |
+| `comments` | `list` | `add`, `delete` |
+| `folders` | `list` | `create` |
+| `auth` | `status` | `login`, `logout` |
+| `config` | `get`, `list` | `set` |
+| `cache` | `status` | `refresh`, `clear` |
+| `render` | -- | *(top-level command)* |
+
+**Read/write split enables agent permission models.** Coding agents auto-allow reads (`list`, `describe`, `diff`, etc.) and require approval for writes (`create`, `update`, `delete`, `run`, etc.). The verb convention makes this trivial to configure. New resources follow the same verbs, so the permission model covers them automatically.
+
+#### 1.5 Configuration, authentication, and workspace routing
+
+**Config** (`~/.tktl/config.json`): `org`, `workspace`, `env` (sandbox/live), optional URL overrides. Multiple environments via `TKTL_CONFIG_DIR`.
+
+**Auth**: API key in `~/.tktl/credentials.json` (mode `0600`), attached as `X-Api-Key` header.
+
+**Three API surfaces** 🔶 (to be consolidated):
+
+| API | Used by |
+|---|---|
+| **Flow API** (`flow-api.taktile.com`) | All flow management: versions, nodes, groups, datasets, locks |
+| **Taktile API** (`api.taktile.com`) | `auth login`, workspace management |
+| **Workspace base URL** (per-workspace) | Flow execution (`flows run`, `flows batch`). Resolved from workspace object, cached. |
+
+🔶 Plan: consolidate Flow API onto workspace base URL before public release.
+
+### 2. CLI design
+
+#### 2.1 Everything is JSON, pipes to jq
+
+- Structured JSON to stdout, auto-detected (JSON for non-TTY, Rich tables for TTY)
+- Errors to stderr as structured JSON with semantic exit codes (0-6, 10)
+- Pipe to `jq`, `grep`, or any Unix tool
+
+#### 2.2 Surgical reads and writes
+
+- Targets the **smallest possible object** (single node, single parameter)
+- `--full` for full document, `--summary` for one-liners, `--section` for single fields
+- Large flows: `nodes list` returns ~3 lines per node, `nodes describe` returns ~30 lines for one node. Full-graph PATCH assembled by ops layer, invisible to caller.
+
+#### 2.3 Human-readable identifiers
+
+The original assumption was that human-readable names make the CLI more usable for both humans and agents. This holds for some resources but breaks on others.
+
+- Flows by **slug**, versions by **name**: works well, both are unique
+- Nodes, groups, datasets, connections, folders: by **UUID** (no guaranteed unique name)
+
+🔶 **URL-to-identifier mismatch.** Platform URLs use UUIDs but CLI expects slugs/names. Agent must look up the mapping first. Needs to be addressed: accept UUIDs as alternative input, or add `tktl resolve <uuid>`.
+
+#### 2.4 Cache-first with per-node decomposition
+
+- One version fetch → decomposed into per-node files at `~/.tktl/cache/`
+- Subsequent reads are local file reads, not API calls
+- ETag-based conditional GETs (304 saves bandwidth)
+- Writes invalidate only affected files
+
+```
+~/.tktl/cache/
+├── index.json                          # slug→ID, name→ID
+├── flows/{flow_id}/versions/{ver_id}/
+│   ├── metadata.json                   # version meta + etag (no graph)
+│   ├── full.json                       # backup for --full reads
+│   └── nodes/
+│       ├── _index.json                 # lightweight node list
+│       └── {node_id}.json             # individual node (~20-50 lines)
+```
+
+A 200-node flow: one API call, then all reads from cache.
+
+#### 2.5 Optimistic concurrency via ETags
+
+- PATCH/PUT sends `if-match: {etag}`. On 412: re-fetch → re-merge → resend (up to 3 retries)
+- Node-level locks embedded in PATCH body. TTL-based expiry (300s). `--force` breaks locks.
+- All invisible to the caller
+
+#### 2.6 Batch execution with local results tracking
+
+- `tktl flows batch`: 1-50 parallelism, max 1000 rows, CSV/JSON/JSONL or platform dataset
+- Results as append-only JSONL in `~/.tktl/runs/{slug}/{run_id}/`
+- `--query "output.data.decision"` for field extraction across rows
+
+#### 2.7 Telemetry with PostHog
+
+- Emitted from `tktl.ops`, tracked regardless of interface (CLI, library, MCP)
+- Per-operation: `op`, `success`, `duration_ms`, `output_tokens`, `cache_hit`, `etag_retries`
+- Opt-out via `tktl config set telemetry false`
+
+### 3. Testing and tooling
+
+#### 3.1 Toolchain
+
+- **uv** (package manager), **ruff** (lint + format), **ty** (type checker), **hatchling** (build)
+- Pre-commit hook: `ruff check` → `ruff format --check` → `ty check --error-on-warning`
+- CI: lint → unit tests (fake API) → integration tests (real dev, main-only)
+
+#### 3.2 Fake API server
+
+Unit tests run against a Starlette ASGI app (`tests/fake_api/`) with in-memory state, wired via `httpx.ASGITransport`. No network calls, full HTTP semantics enforced:
+
+| Rule | Behavior |
+|---|---|
+| ETag mismatch | 412 Precondition Failed |
+| ETag match on GET | 304 Not Modified |
+| Lock conflict | 409 Conflict |
+| Merge patch | RFC 7396 (null deletes, nested recursion) |
+| Missing resources | 404 |
+
+Why fake server, not mocks: exercises the full stack (CLI → ops → api → HTTP → server), tests concurrency logic against real behavior, deterministic seed data.
+
+#### 3.3 Integration tests against dev
+
+Integration tests hit the real Taktile dev environment with real HTTP calls.
+
+Why: the fake server can't catch API behavior changes, undocumented edge cases, or response format drift. Only way to verify the generated API client works against the real server.
+
+What: flow listing, version PATCH with ETag negotiation, full build-and-run cycle (duplicate → add nodes → set schemas → execute → verify). Test versions cleaned up in fixture teardown.
+
+Gating: requires `TKTL_DEV_API_KEY`, `@pytest.mark.integration`, CI runs only on push to `main`, uses a dedicated safe flow (`no-op-2`).
+
+---
+
+## Consequences
+
+### Expected Cost Impact
+
+- **API calls:** cache decomposition = 1 fetch per version, not per node. 200-node flow: 1 API call instead of 200.
+- **Tokens:** `nodes list` on 200-node flow: ~600 lines vs 10,000+ for full graph. Single `nodes describe`: ~30 lines.
+- **Bandwidth:** conditional GETs return 304 for unchanged versions.
+- 🔶 **To measure:** actual token usage per session, cache hit rates, API calls per agent task.
+
+### Positive Consequences
+
+- **Large flows work.** Cache decomposition + surgical reads make a 1000-node flow as easy to navigate as a 5-node flow.
+- **Local tooling works.** JSON output → `jq`, `grep`, `diff` all work. Cache is a file tree. 🔶 Needs alternative for on-platform agents.
+- **One ops layer, many interfaces.** CLI, Python import, MCP, on-platform copilot. No duplication.
+- **Concurrent editing is safe.** ETag retries + node locks, transparent to caller.
+- **API client stays in sync.** Generated from OpenAPI spec. Spec change = regenerate + test.
+- **Fast tests.** Fake server enforces real HTTP semantics without network. Suite runs in seconds.
+
+### Negative Consequences
+
+- **First fetch is expensive.** Cold start for 1000-node flow = 10,000+ line response. Subsequent reads are cheap.
+- **Full-graph PATCH complexity.** API requires all nodes in body. Ops layer hides this but implementation is non-trivial.
+- 🔶 **Two API surfaces.** Different base URLs for management vs execution. Will be unified.
+- **Generated code in repo.** Spec updates produce large diffs. Reviewers learn to ignore `tktl.generated/`.
+- **Cache staleness.** 5-minute TTL, acceptable when agent owns the version.
+- 🔶 **Node ID ergonomics.** UUID-only addressing. Revisit if name uniqueness can be enforced.
+- 🔶 **Local tooling dependency.** `jq`, `grep`, filesystem access assumed. Risk for on-platform runtime (Q3'26). Ops layer Python import mitigates partially.

tktl_cli-0.1.0a1/AGENTS.md

@@ -0,0 +1,106 @@
+# Agent Instructions
+
+You are implementing the `tktl` CLI. Follow these files:
+
+## Project Documentation
+
+| File | Purpose |
+|:---|:---|
+| `docs/specs/core-implementation.md` | Full technical spec — source of truth for all behaviour, data models, API mappings, architecture. |
+| `docs/specs/batch-run.md` | Batch run spec — multi-row execution, file formats, results storage, history, query extraction. |
+| `docs/specs/posthog-instrumentation.md` | PostHog telemetry spec — event types, byte tracking, privacy. |
+| `docs/plans/` | Implementation plans with checkbox task lists. Read before starting work. |
+| `skills/` | Agent skills in [agentskills.io](https://agentskills.io) format. |
+| `README.md` | Project overview and usage examples. |
+| `src/tktl/openapi/flow-api-openapi.json` | OpenAPI spec for the Taktile Flow API. |
+| `src/tktl/openapi/taktile-api-openapi.json` | OpenAPI spec for the Taktile API (auth, login). |
+| `src/tktl/openapi/workspace-datasets-openapi.json` | OpenAPI spec for the Workspace Datasets API. |
+| `src/tktl/openapi/workspace-dataset-jobs-openapi.json` | OpenAPI spec for the Workspace Dataset Jobs API. |
+| `.env.example` | Environment variables for local integration testing. |
+
+When working on a new feature, check `docs/specs/` for an existing spec first. If none exists, write one before implementing.
+
+## Plans
+
+Plans live in `docs/plans/` as simple markdown files with checkbox task lists. They track
+implementation progress for a spec or ticket. A plan is the agent's working state —
+read it first to build context, update it as you go.
+
+**Format:**
+
+```markdown
+# Plan: <Title>
+
+**Spec:** `docs/specs/<name>.md`
+**Ticket:** [TICKET-ID](url)
+
+## Tasks
+
+- [x] Completed task
+- [ ] Open task
+- [ ] Another open task
+
+## Blocked
+
+- [ ] Decision needed: <question>
+```
+
+**Rules:**
+- One plan per spec or ticket. Name it `plan-<topic>.md`.
+- Use `- [ ]` for open, `- [x]` for done. Nothing else.
+- Blocked items go under `## Blocked` — skip them and work on unblocked tasks.
+- When you discover new work, add it to the task list.
+- Prefix done plans with `done-` (e.g., `done-plan-core-initial.md`).
+
+## Execution Loop
+
+1. Find the relevant spec in `docs/specs/` and the plan in `docs/plans/` (if one exists).
+2. If the task is blocked (needs human input), move it to **Blocked** in the plan, then skip to the next unblocked task.
+3. If you discover new work, add it to the **Tasks** section in the plan.
+4. Execute following TDD: write the test first, watch it fail, implement, watch it pass.
+5. After each task: run `uv run pytest`, `uv run ruff check .`, `uv run ruff format .`. Fix any failures before moving on.
+6. Run `uv run ty check src/ tests/` — all code must pass strict type checking.
+7. Check off the task in the plan (`- [x]`).
+8. Commit after each completed phase.
+9. Go to step 1. **Do not stop until every task is checked off.**
+
+## Key Constraints
+
+- **Library-first**: all logic lives in `src/tktl/ops/`. CLI commands are thin wrappers.
+- **Test-driven**: never write implementation before writing the failing test.
+- **Astral-only tooling**: use `uv`, `ruff`, `ty`. No pip, no mypy, no black.
+- **Fake API for unit tests**: unit tests run against the fake server in `tests/fake_api/`.
+- **Real API for integration tests**: integration tests in `tests/test_integration/` hit the real Taktile dev environment. They require `TKTL_DEV_API_KEY` in `.env`.
+- **No hallucinated endpoints**: the Flow API has no node-level endpoints. Nodes are extracted client-side from the version graph. Check `docs/specs/core-implementation.md` Appendix A for the exact endpoints.
+- **Session header required**: PATCH requests that modify rule_2, split_2, or assignment_node metas require a `session` header.
+- **Full nodes in PATCH**: the API requires ALL nodes in the graph patch body, not just the modified one. Sending only the target node causes 409 "graph not fully connected".
+- **Pre-commit hook**: runs ruff check + ruff format + ty check. Install via `uv run python scripts/install-hooks.py`.
+
+## Agent Behaviour (always active)
+
+1. **Clarify before implementing — but use Chrome first for context only.**
+   - **Always use the CLI to retrieve flow, version, and node data.** When you need to describe, inspect, or reason about flow logic, schemas, node configuration, or graph structure, use `tktl versions describe`, `tktl nodes list`, `tktl nodes describe`, etc. Never scrape the browser UI to read flow logic — the CLI returns the complete, structured data.
+   - Chrome is for **context resolution only**: parse the URL to extract org_id, workspace_id, flow_id, version_id, and node_id. Then pass those identifiers to the CLI. **Do NOT run `tktl config list` or other CLI config commands to find out what's active when Chrome is open.**
+   - If Chrome tools are absent: use `tktl config list` to resolve workspace/org, and list open factual AND logic questions before writing any API calls.
+   - Only ask the user about things neither the CLI nor Chrome can tell you: undecided business logic, thresholds not yet defined, ambiguous requirements.
+   - Never guess at connection names, node IDs, or field values.
+
+2. **Render before building.** Always run `tktl render --text "..."` with a complete Mermaid diagram and get user approval before any `tktl versions duplicate` or `tktl nodes add` calls.
+
+3. **Schema first.** Every flow must have explicit input and output schemas. Define them before (or immediately after) creating the version — before adding any logic nodes. For every field the flow reads from `data.*`, declare it in `--schema-in`. For every field the flow writes to `data.*` that the caller will consume, declare it in `--schema-out`. Without schemas: `data: {}` is returned and batch runs can't be queried by field. Apply with:
+   ```bash
+   tktl update apply <slug> <ver> --schema-in @input_schema.json --schema-out @output_schema.json
+   ```
+   Include schema design in the Mermaid brainstorm step — label the I/O nodes with the actual field names.
+
+4. **Chrome tools — read and show only. NEVER edit via Chrome.**
+   All flow edits go through the CLI. Chrome MCP tools have exactly two permitted uses:
+   - **Inspect** — read the current state to orient yourself (e.g. what workspace/flow/node is open, what a node's config looks like). Use this to answer your own questions before asking the user.
+   - **Navigate to show the user** — open a URL so the user can see something (a flow, a node pane, a Mermaid PNG preview). Only navigate; do not interact further.
+
+   When Chrome tools are present:
+   - After rendering a Mermaid PNG → use `Bash: open {png_path}` (macOS) to open the PNG in Preview. Do NOT use Chrome navigate for `file://` paths — Chrome MCP prepends `https://` and mangles them.
+   - After creating or duplicating a version → navigate Chrome to the Taktile flow URL.
+   - When asked to show a node → navigate to `?node={node_id}&right-pane-tab=logic`. If the node_id is unknown, use `tktl nodes list <slug> <version>` to look it up — never use JavaScript or click the canvas.
+   - Build Taktile URLs via `from tktl.config import Config, derive_app_url` + `from tktl.ops.render import build_flow_url`. The `org_id` is auto-fetched and cached by `build_deps()`.
+   - URL pattern: `/flow/{flow_id}/version/{version_id}` — always singular `flow`, always include version. Never `/flows/`, never omit the version.

tktl_cli-0.1.0a1/CLAUDE.md

@@ -0,0 +1,21 @@
+# Claude Code Instructions
+
+Read and follow `AGENTS.md` for all implementation guidance.
+
+## Reference Docs
+
+| File | Purpose |
+|:---|:---|
+| `skills/flow-builder/references/node-configs.md` | Per-type node config examples and gotchas |
+| `skills/flow-builder/references/flow-patterns.md` | Node sequence patterns by use case |
+| `skills/flow-builder/references/debugging.md` | Debugging procedures for flow issues |
+| `skills/flow-builder/references/executing-flows-and-local-testing.md` | Running flows, async mode, mocking, integration test patterns |
+| `skills/flow-builder/references/working-with-child-flows-and-loop-nodes.md` | Child flows, subflow mocking via `mock_data`, cross-workspace promotion |
+
+## Rendering Flows
+
+When asked to render/visualize/diagram a flow, always:
+1. Use the CLI: `uv run tktl versions describe <slug> <version> --preview`
+2. Open the resulting PNG in Preview: `open <path>`
+
+Do not generate raw Mermaid text in the conversation.

tktl_cli-0.1.0a1/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: tktl-cli
+Version: 0.1.0a1
+Summary: A developer- and agent-friendly CLI for managing Taktile decision flows.
+Requires-Python: >=3.11
+Requires-Dist: graphviz>=0.21
+Requires-Dist: httpx>=0.28
+Requires-Dist: posthog>=7.0
+Requires-Dist: pydantic>=2.12
+Requires-Dist: rich>=14.0
+Requires-Dist: typer>=0.24