gflow-cli 0.2.0a1__tar.gz

gflow_cli-0.2.0a1/.claude/README.md

@@ -0,0 +1,58 @@
+# `.claude/` — repo-local Claude Code surface
+
+This directory holds **internal maintainer workflows** that are bundled with the repo so any contributor running Claude Code in this checkout gets the same environment.
+
+> Distinct from `skills/flow-cli/SKILL.md` at the repo root, which is the **published** Skill end users install into their own Claude Code to learn how to use `gflow` from agent contexts. `.claude/` is for *us*, the maintainers; `skills/` is for *them*, the users.
+
+## Layout
+
+```
+.claude/
+├── README.md              ← this file
+└── commands/              ← repo-local slash commands
+    └── release.md         ← `/release` — automates the version-bump + tag + push flow
+```
+
+Optional additions when needed:
+
+```
+.claude/
+├── settings.json          ← Claude Code settings (NOT committed if user-specific)
+├── hooks/                 ← repo-local PreToolUse / PostToolUse / Stop hooks
+└── skills/                ← internal maintainer skills (not for end users)
+    └── <name>/SKILL.md
+```
+
+## Adding a slash command
+
+Drop a Markdown file into `commands/`. Filename (without `.md`) becomes the command name. The first paragraph is the description Claude shows in `/help`. The rest is the prompt the agent executes.
+
+Example: `commands/foo.md` → invoked as `/foo`.
+
+## Adding an internal skill
+
+Same shape as the published one in `skills/flow-cli/`:
+
+```markdown
+---
+name: my-skill
+description: When to invoke this skill (1-2 sentences).
+---
+
+# Body of the skill — how to do the thing.
+```
+
+Drop into `.claude/skills/<name>/SKILL.md`.
+
+## Settings
+
+`settings.json` is intentionally not committed by default — permissions and tool allowlists are usually a per-developer preference. If we ever agree on a project-wide set (e.g. always allow `uv run pytest` without a prompt), commit it then.
+
+## Hooks
+
+Same caveat as settings — repo-local hooks override user hooks and can surprise contributors. Only commit a hook when there's a strong, project-wide reason (e.g. block commits that would expose secrets).
+
+## See also
+
+- [CLAUDE.md](../CLAUDE.md) — project memory hub for any AI agent.
+- [docs/INDEX.md](../docs/INDEX.md) — full documentation index.

gflow_cli-0.2.0a1/.claude/commands/release.md

@@ -0,0 +1,86 @@
+---
+description: Cut a new flow-cli release — bump version, update CHANGELOG, tag, push.
+---
+
+# `/release` — Cut a new flow-cli release
+
+You are about to release a new version of `flow-cli`. Follow this sequence verbatim — every step matters.
+
+## Inputs
+
+Ask the user (if not already provided):
+1. **Version** — the new SemVer (e.g. `0.2.0`, `0.2.0a1`, `1.0.0-rc1`). If they don't know, look at the latest entry in `CHANGELOG.md` `[Unreleased]` and propose the next bump (PATCH for fixes only, MINOR for new features, MAJOR for breaks).
+2. **Pre-release?** — `0.x.y` is alpha by definition. Only the user can say if a `0.x.y-rc1` should ship.
+
+## Sequence
+
+1. **Verify clean working tree.**
+   ```bash
+   git status --short
+   ```
+   Must be empty. If not, abort and tell the user to commit/stash first.
+
+2. **Verify on `main`, up-to-date with `origin/main`.**
+   ```bash
+   git rev-parse --abbrev-ref HEAD     # must be "main"
+   git fetch origin
+   git rev-list HEAD..origin/main      # must be empty
+   ```
+
+3. **Run quality gates.** Reject if any fail.
+   ```bash
+   uv run ruff check src tests
+   uv run ruff format --check src tests
+   uv run pyright src
+   uv run pytest -q --cov=flow_cli --cov-fail-under=80
+   ```
+
+4. **Bump version** in `pyproject.toml`:
+   ```toml
+   [project]
+   version = "<NEW_VERSION>"
+   ```
+
+5. **Update `CHANGELOG.md`:**
+   - Move all entries under `## [Unreleased]` to a new `## [<NEW_VERSION>] — YYYY-MM-DD` section.
+   - Leave `## [Unreleased]` empty.
+   - Update the link footer:
+     ```
+     [Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v<NEW_VERSION>...HEAD
+     [<NEW_VERSION>]: https://github.com/ffroliva/gflow-cli/releases/tag/v<NEW_VERSION>
+     ```
+
+6. **Commit the release prep.**
+   ```bash
+   git add pyproject.toml CHANGELOG.md
+   git commit -m "release: v<NEW_VERSION>"
+   ```
+
+7. **Tag.** Pre-release tags include `-rc*` / `-alpha*` / `-beta*`:
+   ```bash
+   git tag -a v<NEW_VERSION> -m "v<NEW_VERSION>"
+   ```
+
+8. **Push commit + tag.**
+   ```bash
+   git push origin main
+   git push origin v<NEW_VERSION>
+   ```
+
+9. **Report.** Tell the user:
+   - The pushed tag triggers `.github/workflows/release.yml`.
+   - Watch <https://github.com/ffroliva/gflow-cli/actions> for the release workflow.
+   - On success: PyPI publish + GitHub Release with auto-generated notes.
+   - On failure (most common: PyPI Trusted Publishing not yet configured), point them to <https://pypi.org/manage/account/publishing/>.
+
+## Critical reminders
+
+- **NEVER** add `Co-Authored-By: Claude` (or any AI co-author) to the release commit.
+- **NEVER** force-push a release tag once it's been created on GitHub. If a release ships broken, bump to the next PATCH and ship a fix; never rewrite tag history.
+- **NEVER** `--no-verify` your way past hooks. If a hook complains, fix the underlying issue.
+- If quality gates fail at step 3, **STOP**. Do not proceed. Surface the failures to the user.
+
+## See also
+
+- [README § Releases](../../README.md#releases) — full release policy & cadence
+- [PLAN § Phase 5](../../PLAN.md#phase-5--public-alpha-release) — first-release exit criteria

gflow_cli-0.2.0a1/.env.template

@@ -0,0 +1,59 @@
+# flow-cli — example environment variables.
+# Copy to `.env` (in this repo or in $FLOW_CLI_HOME) and customise.
+# All variables are OPTIONAL — defaults work out of the box for most users.
+
+# -----------------------------------------------------------------------------
+# Auth & profiles
+# -----------------------------------------------------------------------------
+
+# Root directory for Playwright persistent contexts (signed-in Google sessions).
+# Default: %USERPROFILE%/.flow-cli  (Windows)
+#          ~/.flow-cli              (macOS / Linux)
+# FLOW_CLI_HOME=
+
+# Default profile name. Override per-call with `--profile <name>`.
+FLOW_CLI_PROFILE=default
+
+# -----------------------------------------------------------------------------
+# Output paths
+# -----------------------------------------------------------------------------
+
+# Where downloaded assets land. Subfolders are created per kind/date:
+#   <output_dir>/images/<YYYY-MM-DD>/<job_id>_<index>.png
+#   <output_dir>/videos/<YYYY-MM-DD>/<job_id>.mp4
+#
+# Default (via `platformdirs`):
+#   Windows: %USERPROFILE%\Downloads\flow-cli
+#   macOS:   ~/Downloads/flow-cli
+#   Linux:   $XDG_DOWNLOAD_DIR/flow-cli  (falls back to ~/Downloads/flow-cli)
+# FLOW_CLI_OUTPUT_DIR=
+
+# -----------------------------------------------------------------------------
+# Provider selection
+# -----------------------------------------------------------------------------
+
+# Backend to use for generations.
+#   flow      - reverse-engineered Flow REST API (default, requires Ultra/Pro)
+#   official  - official Veo SDK (planned for v0.3+, requires Gemini API key)
+FLOW_CLI_PROVIDER=flow
+
+# Gemini API key — only required when FLOW_CLI_PROVIDER=official.
+# Get one at https://aistudio.google.com/apikey
+# FLOW_CLI_GEMINI_API_KEY=
+
+# -----------------------------------------------------------------------------
+# Runtime tuning
+# -----------------------------------------------------------------------------
+
+# Per-request HTTP timeout (seconds). Veo videos can take 60-180s each.
+FLOW_CLI_TIMEOUT_SECONDS=600
+
+# Logging level — DEBUG | INFO | WARNING | ERROR
+FLOW_CLI_LOG_LEVEL=INFO
+
+# Log format — auto | text | json
+#   auto = text on TTY, json when piped (default)
+FLOW_CLI_LOG_FORMAT=auto
+
+# Concurrency for batch operations (requires multiple profiles, v0.4+).
+FLOW_CLI_CONCURRENCY=1

gflow_cli-0.2.0a1/.gitattributes

@@ -0,0 +1,63 @@
+# Normalise line endings to LF in the repository (working tree gets LF too).
+# Cross-platform contributors don't need to worry about CRLF/LF — the repo
+# is the source of truth, and Git enforces LF on add/commit.
+
+# Default: detect text vs binary, force LF on text.
+* text=auto eol=lf
+
+# Code
+*.py        text eol=lf
+*.toml      text eol=lf
+*.json      text eol=lf
+*.yml       text eol=lf
+*.yaml      text eol=lf
+*.lock      text eol=lf
+*.txt       text eol=lf
+*.cfg       text eol=lf
+*.ini       text eol=lf
+
+# Docs / config
+*.md        text eol=lf
+*.template  text eol=lf
+*.example   text eol=lf
+.gitignore  text eol=lf
+.gitattributes text eol=lf
+LICENSE     text eol=lf
+
+# Shell scripts
+*.sh        text eol=lf
+*.bash      text eol=lf
+
+# Windows scripts MUST stay CRLF or they break under PowerShell / cmd.exe
+*.ps1       text eol=crlf
+*.bat       text eol=crlf
+*.cmd       text eol=crlf
+
+# Binary — never touch
+*.png       binary
+*.jpg       binary
+*.jpeg      binary
+*.gif       binary
+*.webp      binary
+*.ico       binary
+*.mp4       binary
+*.mov       binary
+*.webm      binary
+*.mp3       binary
+*.wav       binary
+*.flac      binary
+*.zip       binary
+*.tar       binary
+*.gz        binary
+*.bz2       binary
+*.7z        binary
+*.pdf       binary
+*.woff      binary
+*.woff2     binary
+*.ttf       binary
+*.otf       binary
+*.eot       binary
+*.so        binary
+*.dll       binary
+*.dylib     binary
+*.exe       binary

gflow_cli-0.2.0a1/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install deps
+        run: uv sync --extra dev
+
+      - name: Lint
+        run: uv run ruff check src tests
+
+      - name: Type check
+        run: uv run pyright src
+
+      - name: Test (smoke only)
+        run: uv run pytest -q

gflow_cli-0.2.0a1/.github/workflows/release.yml

@@ -0,0 +1,51 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write       # for creating GitHub Releases
+  id-token: write       # for PyPI Trusted Publishing (OIDC)
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/gflow-cli
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Verify tag matches pyproject version
+        run: |
+          TAG=${GITHUB_REF_NAME#v}
+          PROJ_VERSION=$(grep -E '^version = ' pyproject.toml | head -1 | cut -d'"' -f2)
+          if [ "$TAG" != "$PROJ_VERSION" ]; then
+            echo "::error::Tag ($TAG) does not match pyproject.toml version ($PROJ_VERSION)"
+            exit 1
+          fi
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # No api-token needed — uses OIDC Trusted Publishing.
+        # Configure once at https://pypi.org/manage/account/publishing/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*
+          prerelease: ${{ contains(github.ref_name, '-') }}

gflow_cli-0.2.0a1/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+env/
+
+# uv
+.uv-cache/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.mypy_cache/
+.ruff_cache/
+.pyright/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Project-specific — secrets / session storage (NEVER commit)
+auth/                  # any project-local auth dir
+profile_*/             # Chromium persistent contexts (any name)
+*.cookies.json         # exported cookie jars
+storage_state.json     # Playwright storage_state output
+secrets.json           # generic secrets file
+.env                   # local env overrides (the .env.template IS committed)
+.env.local
+.env.*.local
+
+# Generated outputs
+out/
+tmp/
+*.mp4
+*.png
+!docs/**/*.png         # docs images are OK
+!tests/fixtures/**/*.png
+samples/*.captured.json # sandbox-recorded API exchanges may contain PII
+
+# Claude Code worktrees and lock files
+.claude/worktrees/
+.claude/scheduled_tasks.lock

gflow_cli-0.2.0a1/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to `flow-cli` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0a1] — 2026-05-09
+
+### Added
+- **`gflow video t2v`** — generate a video from a text prompt via Veo 3.1.
+  Flags: `--aspect 9:16|16:9|1:1`, `--seed`, `--output`, `--profile`, `--poll-interval`.
+- **`gflow video i2v`** — generate a video from a start image + text prompt (Veo 3.1 I2V).
+- **`gflow video batch`** — run a TSV manifest of video generations against one shared project.
+- `flow_cli.api` package — low-level REST client (`FlowApiClient`) + value objects
+  (`GenerateVideoRequest`, `VideoOperation`, `VideoStatus`) for video generation.
+- `flow_cli.api.recaptcha` — reCAPTCHA Enterprise token minting via Playwright `page.evaluate`.
+  `TokenMinter` caches the discovered site key per session; `mint(action)` is called immediately
+  before each generation request.
+- `flow_cli.manifest` — TSV manifest parser for `gflow video batch`. Supports optional
+  `start_image`, `end_image`, `aspect`, `output_path` columns; skips `# `-prefixed comments.
+- `FLOW_CLI_HEADLESS` env var (`bool`, default `true`). Set to `false` if reCAPTCHA refuses
+  to mint tokens in headless mode (Google bot detection fallback).
+- `scripts/smoke_e2e.py` — one-shot live T2V smoke test; run after `gflow auth login` to
+  verify the full happy path (create project → generate_video → poll → download).
+- **`CLAUDE.md`** at repo root — project memory hub for AI coding agents
+  (Claude Code reads natively; Cursor/Codex/Gemini/Aider can read as reference).
+- **`.claude/`** directory — repo-local Claude Code surface for maintainers.
+  - `.claude/README.md` — what goes here, how to extend.
+  - `.claude/commands/release.md` — `/release` slash command that automates
+    version bump + CHANGELOG migration + tag + push, with quality gates.
+- `flow_cli.profile_store` — profile inventory + default-profile persistence
+  in `$FLOW_CLI_HOME/config.toml`. Five-step resolution chain (CLI flag > env >
+  config > auto-select > raise) with named exceptions
+  (`NoProfilesError`, `NoDefaultProfileError`).
+- New auth subcommands: bare `gflow auth`, `gflow auth list`, `gflow auth use <name>`,
+  `gflow auth logout [--profile NAME] [-y]`. First login auto-sets default profile.
+- `KNOWN_ISSUES.md` at repo root — open/mitigated/resolved issues with workarounds.
+- `docs/` tree (INDEX, AUTHENTICATION, CONFIGURATION, ARCHITECTURE, USAGE, SECURITY).
+- `.env.template` documenting every supported env var.
+- GitHub Actions CI: ruff, pyright, pytest on Python 3.11 and 3.12.
+- GitHub Actions release workflow: tag-triggered PyPI publish via Trusted Publishing.
+- MIT license, comprehensive README, [`DISCLAIMER.md`](DISCLAIMER.md), [`CONTRIBUTING.md`](CONTRIBUTING.md).
+- [`skills/flow-cli/SKILL.md`](skills/flow-cli/SKILL.md) — installable Claude Code Skill.
+
+### Removed
+- `flow_cli.providers.FlowProvider` and `flow_cli.models` — superseded by `flow_cli.api`.
+- Legacy CLI stubs: `gflow upload`, `gflow generate`, `gflow status`, `gflow download`,
+  `gflow i2v`. Replaced by the wired `gflow video` subgroup.
+
+## [0.1.0] — _unreleased_
+
+First skeleton. Not functional end-to-end yet.
+
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.2.0a1...HEAD
+[0.2.0a1]: https://github.com/ffroliva/gflow-cli/releases/tag/v0.2.0a1
+[0.1.0]: https://github.com/ffroliva/gflow-cli/releases/tag/v0.1.0

gflow_cli-0.2.0a1/CLAUDE.md

@@ -0,0 +1,130 @@
+# CLAUDE.md
+
+> **Project memory hub for AI coding agents.** Claude Code reads this natively. Other agents (Cursor, Codex, Gemini CLI, Aider) should read this as a top-level reference.
+
+## What this project is
+
+`flow-cli` is an unofficial Python CLI that drives [Google Flow](https://labs.google/fx/tools/flow) (Veo image-to-video, Imagen text-to-image) from the terminal by reverse-engineering Flow's private REST API at `aisandbox-pa.googleapis.com`. Built for Google AI Ultra/Pro subscribers who want to spend their Flow credits via batch automation rather than the web UI.
+
+**Same pattern as `edge-tts`:** a community SDK over a private cloud API.
+
+## On every session start
+
+1. Read **[docs/INDEX.md](docs/INDEX.md)** — routing layer for all project docs.
+2. Read **[PLAN.md](PLAN.md)** — current phase, next concrete tasks, ADRs.
+3. Read **[KNOWN_ISSUES.md](KNOWN_ISSUES.md)** — open issues to avoid re-discovering.
+4. Check **[CHANGELOG.md](CHANGELOG.md) `[Unreleased]`** — what's recently shipped.
+
+## Active phase
+
+**Phase 1 — Foundation** (refactor scaffold into layered structure, wire `pydantic-settings`, `structlog`, command/query bus). See [PLAN § Phase 1](PLAN.md#phase-1--foundation-target-12-days). Subset already landed: profile-store + `gflow auth` UX (commit `d821f39`).
+
+## Architecture (skim)
+
+Layered Clean / Hexagonal — see **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** for the full diagram and rationale.
+
+```text
+interfaces/   →  application/   →  domain/   ←  infrastructure/
+   CLI            commands /          pure         FlowProvider,
+                  queries /         business        Playwright,
+                  handlers /          logic         filesystem
+                  ports
+```
+
+Dependency rule: **`domain/` depends on nothing**. `application/` depends on `domain/` + ports (Protocols). `infrastructure/` implements the ports. `interfaces/` wires it together.
+
+## CRITICAL rules — invariant, never violate
+
+- **Never commit secrets.** `.gitignore` excludes `auth/`, `profile_*/`, `*.cookies.json`, `storage_state.json`, `secrets.json`, `.env`, `.env.local`, `.env.*.local`. If you see one of these staged, abort and tell the user.
+- **Never add `Co-Authored-By: Claude` (or any AI co-author) to commit messages.** Author attribution is the human user's only.
+- **Sessions belong outside the repo.** Default location is `$LOCALAPPDATA/flow-cli/profile_*` (Windows) or `~/.local/share/flow-cli/profile_*` (POSIX) via [`platformdirs`](https://github.com/platformdirs/platformdirs). Never store sessions in `/tmp`, `%TEMP%`, or anywhere the OS auto-reaps.
+- **No `print()` in `src/`** — use `structlog` (or `logging` until structlog lands in Phase 1).
+- **Domain layer is pure** — `src/flow_cli/domain/*` must not import `application/`, `infrastructure/`, or `interfaces/`. No I/O, no frameworks.
+- **Frozen dataclasses for value objects.** Aggregates may have controlled mutation methods, but VOs (AspectRatio, Prompt, JobId, ...) are immutable.
+- **Async all the way down.** Handlers and providers are `async def`. CLI is the only place that calls `asyncio.run(...)`.
+- **TDD is non-negotiable.** Red → Green → Refactor → Commit. Coverage floor: **80% overall**, **90% on `domain/` and `application/`**. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Coding conventions
+
+- **Python 3.11+**, strict typing (`pyright --strict` on `src/flow_cli/`), `from __future__ import annotations` at the top of every module.
+- **`@dataclass(frozen=True)`** for value objects and DTOs. `Protocol` for ports.
+- **`pathlib.Path`** everywhere — never raw strings for filesystem paths.
+- **Click + Rich** for the CLI, **httpx + Playwright** for I/O, **pytest + pytest-bdd** for tests.
+- **Conventional Commits** for messages (`feat:`, `fix:`, `docs:`, `test:`, `chore:`, `refactor:`, etc.). See examples in `git log`.
+- **Short files, single responsibility.** ~200-400 lines typical, 800 max. Split into `package/<topic>.py` if growing.
+
+## How to verify your work
+
+Run all four BEFORE asking to commit:
+
+```bash
+uv run ruff check src tests          # lint
+uv run ruff format --check src tests # formatting
+uv run pyright src                   # types
+uv run pytest -q --cov=flow_cli      # tests + coverage
+```
+
+CI runs the same four on every push (see `.github/workflows/ci.yml`).
+
+## Where to look
+
+| I need to… | Read this |
+|---|---|
+| Understand the architecture | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
+| Add a CLI command | [docs/USAGE.md](docs/USAGE.md) + existing patterns in `src/flow_cli/cli.py` |
+| Add a Provider route | [PLAN.md § 4 Feature specs](PLAN.md#4-feature-specs) + existing stubs in `src/flow_cli/providers/flow.py` + capture data in `samples/captured_requests.json` |
+| Touch auth | [docs/AUTHENTICATION.md](docs/AUTHENTICATION.md) |
+| Add a config knob | [docs/CONFIGURATION.md](docs/CONFIGURATION.md) + `.env.template` + (later) `src/flow_cli/shared/config.py` |
+| Write a test | [CONTRIBUTING.md § TDD](CONTRIBUTING.md#test-driven-development-mandatory) + existing patterns in `tests/` |
+| Cut a release | [README § Releases](README.md#releases) — bump version in `pyproject.toml`, update CHANGELOG, `git tag vX.Y.Z`, push |
+| Track a known issue | [KNOWN_ISSUES.md](KNOWN_ISSUES.md) |
+| Understand security posture | [docs/SECURITY.md](docs/SECURITY.md) |
+
+## Common tasks
+
+### Run the CLI from source
+
+```bash
+uv sync
+uv run gflow --help
+uv run gflow auth                              # bare command — list profiles or login
+uv run gflow auth login --profile experiments  # named profile
+```
+
+### Add a new test (TDD)
+
+1. Write the failing test in `tests/<area>/test_<thing>.py`.
+2. `uv run pytest tests/<area>/test_<thing>.py` — verify it fails for the right reason.
+3. Implement the minimum production code to pass.
+4. Refactor.
+5. `uv run pytest -q --cov=flow_cli` — verify nothing else broke and coverage didn't regress.
+
+### Update a doc
+
+1. Edit the file under `docs/`.
+2. Add a row to `docs/INDEX.md` if it's a new file.
+3. Update `CHANGELOG.md` `[Unreleased]` only if the change is user-visible.
+
+## Things NOT to do
+
+- Don't add a feature without a PLAN entry (or update PLAN if scope shifts).
+- Don't `pip install` — always `uv add` so the lockfile stays in sync.
+- Don't put new files in the repo root unless they're truly top-level (LICENSE, README, PLAN, CHANGELOG, etc.). Code goes in `src/`, tests in `tests/`, docs in `docs/`.
+- Don't introduce a new dependency without listing the rationale in PLAN's Decision Log.
+- Don't `--no-verify` your way past a hook. Fix the hook's complaint instead.
+- Don't generate placeholder content (lorem ipsum, "todo: implement"). Either skip the file or write the real thing.
+
+## Reasoning style for an agent
+
+- **Verify before claiming done.** Run the quality gates and read the output. "Tests pass" without evidence is not acceptable.
+- **Small, atomic commits.** Each commit message captures one logical change.
+- **Question scope creep.** If the user asks for X and you're tempted to also fix Y, ask first.
+- **Plan before implementing** for anything > 1 file or > 50 LoC. Write the plan into PLAN.md or a comment, then execute.
+- **Show your work.** When you change something non-obvious, leave a one-line comment with the WHY (not the WHAT — the diff already shows the what).
+
+## See also
+
+- [README.md](README.md) — public-facing project overview
+- [docs/INDEX.md](docs/INDEX.md) — full doc routing
+- [PLAN.md](PLAN.md) — implementation roadmap with phases & ADRs
+- [.claude/README.md](.claude/README.md) — what's in `.claude/` and how to extend it