@sabaiway/agent-workflow-kit 1.5.2 → 1.7.0

package/bridges/antigravity-cli-bridge/bin/agy.sh

@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+# Universal, neutral wrapper around Google's Antigravity CLI (`agy`).
+#
+# Antigravity CLI is the successor to Gemini CLI: as of 2026-06-18 the old
+# Gemini CLI stopped serving Google AI Pro / Ultra / free tiers, and access to
+# Google's models from the terminal moved to `agy`. This wrapper is the single
+# entry point so callers never have to remember the flag spelling.
+#
+# Auth: SUBSCRIPTION ONLY. We use the cached OAuth token at
+# ~/.gemini/antigravity-cli/antigravity-oauth-token (Google AI Pro) and the
+# quota that comes with it. To make that guarantee hard, the wrapper unsets any
+# API-key env var so a stray key can never silently switch us to paid
+# pay-as-you-go billing.
+#
+# This is a THIN, FLOW-AGNOSTIC wrapper on purpose: it just runs one headless
+# prompt and prints the text response. It does NOT encode any orchestration
+# policy (no plan contract, no auto-approve, no workspace edits) — that is left
+# to whatever flow we design later, which can opt in via passthrough flags.
+#
+# Models (pass the exact display string from `agy models`, or set AGY_MODEL):
+#   Gemini 3.5 Flash (Low|Medium|High), Gemini 3.1 Pro (Low|High),
+#   Claude Sonnet 4.6 (Thinking), Claude Opus 4.6 (Thinking), GPT-OSS 120B (Medium)
+#
+# Usage (installed on PATH as `agy-run`):
+#   agy-run "your prompt"                    # prompt as an argument
+#   echo "your prompt" | agy-run -           # prompt from stdin
+#   agy-run @path/to/prompt.md               # prompt from a file
+#   AGY_MODEL="Claude Opus 4.6 (Thinking)" agy-run "..."   # pick a model
+#   AGY_TIMEOUT=10m agy-run "..."            # override print timeout (agy's soft bound)
+#   AGY_HARD_TIMEOUT=8m agy-run "..."        # override the hard wall-clock cap (timeout(1))
+#   agy-run "..." -- --add-dir . --dangerously-skip-permissions
+#                                            # passthrough agy flags (future flows)
+set -euo pipefail
+
+# 1. Make `agy` findable even when ~/.bashrc was not sourced.
+export PATH="$HOME/.local/bin:$PATH"
+
+# 2. Force the subscription path: never let an API key hijack billing. Unset EVERY *_API_KEY for the
+#    agy subprocess — the explicit Google/Antigravity ones first, then any other *_API_KEY that may
+#    have been added later (`compgen` is a bash builtin; the shebang guarantees bash).
+unset ANTIGRAVITY_API_KEY GEMINI_API_KEY GOOGLE_API_KEY GOOGLE_GENAI_API_KEY 2>/dev/null || true
+while IFS= read -r _api_key_var; do
+  unset "$_api_key_var" 2>/dev/null || true
+done < <(compgen -v 2>/dev/null | grep '_API_KEY$' || true)
+
+if ! command -v agy >/dev/null 2>&1; then
+  echo "error: 'agy' (Antigravity CLI) not found on PATH. Install it and run 'agy' once to sign in." >&2
+  exit 127
+fi
+
+# `-` (empty) => skip --model and let agy use settings.json; default to Pro.
+AGY_MODEL="${AGY_MODEL-Gemini 3.1 Pro (High)}"
+AGY_TIMEOUT="${AGY_TIMEOUT:-5m}"
+# Hard wall-clock cap (defaults to AGY_TIMEOUT). agy's own --print-timeout is NOT a reliable
+# wall-clock kill — a run was observed surviving 32 min past a 10m --print-timeout — so we also wrap
+# agy in timeout(1). A heavy `--add-dir` agentic prompt on the slowest model can otherwise run
+# unbounded, and once a caller backgrounds it nothing kills it. Raise only for a known-healthy run.
+AGY_HARD_TIMEOUT="${AGY_HARD_TIMEOUT:-$AGY_TIMEOUT}"
+
+if [[ $# -lt 1 ]]; then
+  echo "usage: $0 <prompt | - | @file> [-- extra agy flags...]" >&2
+  exit 2
+fi
+
+prompt_src="$1"; shift
+
+# Split off any passthrough flags after a literal `--`. Extra args WITHOUT the `--` separator are a
+# mistake — they would be silently dropped, so fail loudly instead (no silent failures).
+passthrough=()
+if [[ $# -gt 0 ]]; then
+  if [[ "$1" == "--" ]]; then
+    shift
+    passthrough=("$@")
+  else
+    echo "error: unexpected argument '$1'. Pass extra agy flags after a literal '--':" >&2
+    echo "       $0 <prompt | - | @file> -- <agy flags...>" >&2
+    exit 2
+  fi
+fi
+
+if [[ "$prompt_src" == "-" ]]; then
+  prompt="$(cat)"
+elif [[ "${prompt_src:0:1}" == "@" ]]; then
+  file="${prompt_src:1}"
+  if [[ ! -f "$file" ]]; then
+    echo "error: prompt file '$file' not found" >&2
+    exit 2
+  fi
+  prompt="$(cat "$file")"
+else
+  prompt="$prompt_src"
+fi
+
+if [[ -z "${prompt// }" ]]; then
+  echo "error: empty prompt" >&2
+  exit 2
+fi
+
+model_flag=()
+if [[ -n "$AGY_MODEL" ]]; then
+  model_flag=(--model "$AGY_MODEL")
+fi
+
+agy_cmd=(agy "${model_flag[@]}" --print-timeout "$AGY_TIMEOUT" "${passthrough[@]}" -p "$prompt")
+
+# Hard wall-clock cap via timeout(1) (GNU `timeout` on Linux, `gtimeout` from coreutils on macOS).
+# This is the real guard — a backgrounded, hung agy survives its own --print-timeout otherwise.
+timeout_bin=""
+if command -v timeout >/dev/null 2>&1; then
+  timeout_bin="timeout"
+elif command -v gtimeout >/dev/null 2>&1; then
+  timeout_bin="gtimeout"
+fi
+
+if [[ -z "$timeout_bin" ]]; then
+  echo "warning: no 'timeout'/'gtimeout' on PATH — running agy WITHOUT a hard wall-clock cap" >&2
+  echo "         (install coreutils to enable AGY_HARD_TIMEOUT=$AGY_HARD_TIMEOUT)." >&2
+  exec "${agy_cmd[@]}"
+fi
+
+# --kill-after: if agy ignores the initial TERM, SIGKILL it 10s later. Capture rc (don't `exec`) so
+# we can turn a timeout into an explicit, actionable error instead of a silent non-zero.
+set +e
+"$timeout_bin" --kill-after=10s "$AGY_HARD_TIMEOUT" "${agy_cmd[@]}"
+rc=$?
+set -e
+if [[ $rc -eq 124 || $rc -eq 137 ]]; then
+  echo "error: agy exceeded the hard cap AGY_HARD_TIMEOUT=$AGY_HARD_TIMEOUT and was terminated." >&2
+  echo "       This usually means a heavy '--add-dir' agentic run, or the slowest model looping." >&2
+  echo "       Retry with a faster model (e.g. AGY_MODEL='Gemini 3.5 Flash (High)') or a" >&2
+  echo "       self-contained prompt without --add-dir. Raise AGY_HARD_TIMEOUT only if the run is healthy." >&2
+fi
+exit $rc

package/bridges/antigravity-cli-bridge/bin/agy.test.mjs

@@ -0,0 +1,59 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, chmodSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const WRAPPER = join(HERE, 'agy.sh');
+
+// Build a sandbox HOME whose ~/.local/bin holds a STUB `agy`. The wrapper prepends
+// "$HOME/.local/bin" to PATH, so it resolves our stub instead of the real binary — no network,
+// no real subscription CLI, fully hermetic.
+const makeSandbox = (stubBody) => {
+  const home = mkdtempSync(join(tmpdir(), 'agy-wrapper-test-'));
+  const bin = join(home, '.local', 'bin');
+  mkdirSync(bin, { recursive: true });
+  const stub = join(bin, 'agy');
+  writeFileSync(stub, stubBody, { mode: 0o755 });
+  chmodSync(stub, 0o755);
+  return home;
+};
+
+const runWrapper = (home, env, prompt = 'hello') =>
+  spawnSync('bash', [WRAPPER, prompt], {
+    env: { HOME: home, PATH: `${join(home, '.local', 'bin')}:${process.env.PATH}`, ...env },
+    encoding: 'utf8',
+    timeout: 20000,
+  });
+
+describe('agy.sh — hard wall-clock cap (timeout(1))', () => {
+  it('kills a hung agy at AGY_HARD_TIMEOUT and reports it (non-zero + actionable guidance)', () => {
+    const home = makeSandbox('#!/usr/bin/env bash\nsleep 30\n');
+    const started = Date.now();
+    const r = runWrapper(home, { AGY_HARD_TIMEOUT: '2s', AGY_TIMEOUT: '2s', AGY_MODEL: '' });
+    const elapsed = Date.now() - started;
+    rmSync(home, { recursive: true, force: true });
+    assert.ok(elapsed < 13000, `wrapper must return well under the kill-after window, took ${elapsed}ms`);
+    assert.notEqual(r.status, 0, 'a timed-out run must exit non-zero');
+    assert.match(r.stderr, /exceeded the hard cap/, 'must explain the hard-cap kill');
+  });
+
+  it('passes a fast agy run through unchanged (exit 0, stdout preserved)', () => {
+    const home = makeSandbox('#!/usr/bin/env bash\necho "OK reply"\nexit 0\n');
+    const r = runWrapper(home, { AGY_HARD_TIMEOUT: '10s', AGY_TIMEOUT: '10s', AGY_MODEL: '' });
+    rmSync(home, { recursive: true, force: true });
+    assert.equal(r.status, 0, `expected clean exit, got ${r.status}; stderr=${r.stderr}`);
+    assert.match(r.stdout, /OK reply/);
+  });
+
+  it('propagates a non-timeout agy failure code verbatim (no false hard-cap message)', () => {
+    const home = makeSandbox('#!/usr/bin/env bash\necho "boom" >&2\nexit 3\n');
+    const r = runWrapper(home, { AGY_HARD_TIMEOUT: '10s', AGY_TIMEOUT: '10s', AGY_MODEL: '' });
+    rmSync(home, { recursive: true, force: true });
+    assert.equal(r.status, 3, 'a genuine agy failure code must pass through');
+    assert.doesNotMatch(r.stderr, /exceeded the hard cap/, 'must not mislabel a non-timeout failure');
+  });
+});

package/bridges/antigravity-cli-bridge/capability.json

@@ -0,0 +1,22 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "name": "antigravity-cli-bridge",
+  "kind": "execution-backend",
+  "version": "1.0.0",
+  "provides": ["review", "probe"],
+  "roles": {
+    "review": { "cmd": "agy-run", "source": "bin/agy.sh", "template": "references/review-prompt.md", "output": "advisory" },
+    "probe": { "cmd": "agy-run", "source": "bin/agy.sh", "output": "advisory" }
+  },
+  "detect": {
+    "installed": {
+      "env": "ANTIGRAVITY_CLI_BRIDGE_DIR",
+      "default": "~/.claude/skills/antigravity-cli-bridge",
+      "file": "SKILL.md"
+    }
+  },
+  "cost": "subscription",
+  "quota": { "kind": "subscription", "finite": true },
+  "provenance": { "author": "sabaiway", "source": "github:sabaiway/agent-workflow" }
+}

package/bridges/antigravity-cli-bridge/references/driving-agy.md

@@ -0,0 +1,108 @@
+# How the main agent drives `agy`
+
+`agy` is a **delegated-execution backend**: the main agent stays the orchestrator and hands `agy` a
+bounded, self-contained sub-task. `agy` answers from the **subscription** quota, so the goal is
+maximum useful output per token of that quota. Treat its output as **advisory** — the main agent owns
+edits, verification, and final judgment.
+
+## Delegation checklist
+
+1. Pick the narrowest useful question.
+2. Choose the cheapest model that can answer it.
+3. Include only the relevant excerpts, paths, constraints, and the expected output shape.
+4. State permission boundaries in the prompt (no edits, no git writes).
+5. Run `agy-run` headlessly.
+6. Treat the response as advisory and verify before acting.
+
+## Model selection
+
+| Task | Model |
+|---|---|
+| Reachability / smoke / "is it wired?" | `Gemini 3.5 Flash (Low)` |
+| Cheap probes, summaries | `Gemini 3.5 Flash (Medium)` |
+| Quick review with a little more effort | `Gemini 3.5 Flash (High)` |
+| Reasoning, plan critique, careful drafting | `Gemini 3.1 Pro (High)` (wrapper default) |
+| Same reasoning, lower quota cost | `Gemini 3.1 Pro (Low)` |
+| A different engine's opinion | `Claude Sonnet 4.6 (Thinking)`, `Claude Opus 4.6 (Thinking)`, or `GPT-OSS 120B (Medium)` |
+
+Don't reach for Pro by reflex — Flash answers most reachability/probe questions for a fraction of the
+quota.
+
+## Quota economy
+
+Subscription quota is finite. Prefer:
+
+- A short probe on Flash before a large Pro run.
+- One sharp question over broad "review everything" prompts.
+- Prompt files with trimmed excerpts instead of whole repositories.
+- `AGY_TIMEOUT=2m` for probes, longer timeouts only for deep reviews.
+- Reusing a conversation with `--continue` when the context is already loaded.
+
+## Continue vs. fresh
+
+```bash
+# Continue the most recent conversation (cheaper than re-sending context):
+agy-run "Given your previous review, list only the top three risks." -- --continue
+
+# Resume a specific conversation by id:
+agy-run "Continue from the prior architecture critique; focus on test gaps." -- --conversation <id>
+```
+
+Use conversation state only when it saves quota or preserves useful context. For auditable decisions,
+prefer self-contained prompts.
+
+## Escalation policy (edits, network, git)
+
+The wrapper passes no `--add-dir`, no `--dangerously-skip-permissions`, and no `--sandbox`. Treat this
+as a **policy boundary you enforce in the prompt, not an enforced sandbox** — so prompt `agy` as a
+read-only reviewer, and reach for `-- --sandbox` for anything that might trigger terminal/tool work:
+
+```text
+Do not edit files. Do not run git write commands. Do not branch, add, commit, stash, reset, or
+rewrite history. Return findings and suggested changes only.
+```
+
+- **Repo edits** stay with the orchestrator. If a flow truly needs `agy` to write files, opt in
+  explicitly — `agy-run "..." -- --add-dir . --dangerously-skip-permissions` — and review the diff.
+- **New dependencies / network installs** are done by hand, not by `agy`.
+- **Git writes** (branch/commit) are never delegated — the orchestrator commits after review.
+- Prefer `-- --sandbox` for any prompt that might trigger terminal work.
+
+## Project-context prompts
+
+Probe reachability from a project root (cheap model):
+
+```bash
+AGY_MODEL="Gemini 3.5 Flash (Low)" agy-run \
+  "Read the cwd context file and report the dialogue language plus one Hard Constraint."
+AGY_MODEL="Gemini 3.5 Flash (Low)" agy-run \
+  "Without using a file pointer, is there a project-specific planning skill in this repo? Name it and cite its path."
+```
+
+Plan-review prompt shape:
+
+```text
+You are reviewing the plan below from the current repository root.
+Use the root context file and per-workspace skills if they are reachable.
+Do not edit files. Do not run git write commands.
+Return: 1) blocking issues  2) non-blocking risks  3) missing verification  4) a concise recommendation.
+The implementation plan text follows in this same prompt.
+```
+
+Diff/code-review prompt shape (provide the diff as text):
+
+```text
+Review this diff against the stated constraints.
+Focus on bugs, behavioural regressions, missing tests, and violations of the project rules.
+Cite file paths and line hints from the diff where possible. Do not summarise unless there are no findings.
+The project constraints and diff text follow in this same prompt.
+```
+
+## Handling output
+
+`agy` returns plain text. Do not assume it is complete, current, or machine-valid. Before acting:
+
+- Check claims against local files or primary sources available to the main agent.
+- Re-run local tests and linters yourself.
+- Reject advice that conflicts with user instructions, repository rules, or security boundaries.
+- Summarise uncertainty clearly when reporting back to the user.

package/bridges/antigravity-cli-bridge/references/models-and-flags.md

@@ -0,0 +1,93 @@
+# `agy` models & flags (reference)
+
+The source of truth is the live binary: `agy --version`, `agy --help`, `agy models`. The tables below
+were captured from **v1.0.10**; if the binary disagrees, the binary wins. The wrapper command is
+`agy-run`, backed by `bin/agy.sh`.
+
+## Headless behaviour
+
+Use `-p`, `--print`, or `--prompt` to run one non-interactive prompt and print the text response. The
+wrapper always uses headless `-p`. **There is no JSON output mode in v1.0.10** — ask for Markdown,
+bullets, tables, or fenced blocks when the caller needs structure, then validate the text yourself.
+
+## Wrapper contract
+
+```bash
+agy-run <prompt | - | @file> [-- extra agy flags...]
+```
+
+Inputs:
+
+- Prompt text: `agy-run "say OK"`.
+- Stdin: `echo "say OK" | agy-run -`.
+- Prompt file: `agy-run @prompt.md`.
+- Extra `agy` flags after `--`: `agy-run @prompt.md -- --add-dir . --continue`. Extra args **without**
+  the `--` separator are rejected with a usage error (they are never silently dropped).
+- A literal prompt that **begins with `@`** is read as a file path. Pass such prompts via stdin
+  instead: `printf '%s' '@handle, review this' | agy-run -`.
+
+Environment:
+
+| Var | Default | Effect |
+|---|---|---|
+| `AGY_MODEL` | `Gemini 3.1 Pro (High)` | model display string; set empty (`AGY_MODEL=`) to drop `--model` and let `agy` use `settings.json` |
+| `AGY_TIMEOUT` | `5m` | value passed to `--print-timeout` |
+
+Subscription invariant: the wrapper prepends `$HOME/.local/bin` to `PATH` and clears
+`ANTIGRAVITY_API_KEY` / `GEMINI_API_KEY` / `GOOGLE_API_KEY` / `GOOGLE_GENAI_API_KEY` before execution.
+Auth comes from the user's cached OAuth token, never from bundled credentials.
+
+## Models
+
+Pass the **exact display string** from `agy models`, or set `AGY_MODEL`.
+
+| Model string | Practical use |
+|---|---|
+| `Gemini 3.5 Flash (Low)` | lowest-cost smoke tests and simple rewrites |
+| `Gemini 3.5 Flash (Medium)` | cheap probes, fast summaries, context-reachability checks |
+| `Gemini 3.5 Flash (High)` | fast review when a little more reasoning effort is useful |
+| `Gemini 3.1 Pro (Low)` | cheaper Pro pass for medium reasoning |
+| `Gemini 3.1 Pro (High)` | wrapper default; hard reasoning, plan critique, architecture review |
+| `Claude Sonnet 4.6 (Thinking)` | cross-vendor reasoning comparison |
+| `Claude Opus 4.6 (Thinking)` | expensive deep critique when the user wants another high-end pass |
+| `GPT-OSS 120B (Medium)` | open-weights-style comparison / diversity pass |
+
+Examples:
+
+```bash
+AGY_MODEL="Gemini 3.5 Flash (Medium)" agy-run "Read AGENTS.md and report one Hard Constraint."
+AGY_MODEL="Claude Sonnet 4.6 (Thinking)" AGY_TIMEOUT=10m agy-run @review-prompt.md
+```
+
+## Flags (from `agy --help`, v1.0.10)
+
+| Flag | Meaning | Notes |
+|---|---|---|
+| `-p`, `--print`, `--prompt` | run one headless prompt and print the text response | the wrapper uses `-p` |
+| `--print-timeout <dur>` | cap headless wait time | CLI default `5m0s`; wrapper default `5m` via `AGY_TIMEOUT` |
+| `--model <string>` | select a model | must match an `agy models` display string exactly |
+| `-i`, `--prompt-interactive` | run an initial prompt, then continue interactively | not used by the wrapper |
+| `-c`, `--continue` | continue the most recent conversation | pass after the wrapper's `--` |
+| `--conversation <id>` | resume a specific conversation by id | use only when the user provides/records the id |
+| `--add-dir <dir>` | add a directory to the workspace | repeatable; for explicit extra context |
+| `--dangerously-skip-permissions` | auto-approve all tool permissions | avoid by default; use only with explicit user approval |
+| `--sandbox` | run with terminal restrictions enabled | prefer when delegating a prompt that might trigger tool/terminal work |
+| `--log-file <path>` | override the CLI log-file path | keep logs secret-free and out of committed artifacts |
+
+## Subcommands (v1.0.10)
+
+`changelog`, `help`, `install`, `models`, `plugin` / `plugins`, `update`.
+
+**Not available in v1.0.10:** any JSON output mode, and any `agy inspect`. Output is plain text.
+
+## Project-context flags
+
+`agy` reads context from its current working directory:
+
+```text
+.antigravity.md > GEMINI.md > AGENTS.md
+.agents/skills/
+```
+
+Use `--add-dir` for extra directories not already reachable from cwd. Subdirectory `CLAUDE.md` files
+are **not** auto-loaded — include those local rules manually in the prompt when they matter.

package/bridges/antigravity-cli-bridge/references/review-prompt.md

@@ -0,0 +1,51 @@
+# Review prompt template — `agy-run` (review role)
+
+The `review` role of `antigravity-cli-bridge` delegates a **read-only second opinion** to `agy`.
+`agy` cannot see the conversation and (in v1.0.10) has no JSON output, so the prompt must be
+**self-contained** and ask for **plain-Markdown findings only** — no repo edits, no git writes.
+Fill the `{{…}}` slots, pipe it to `agy-run`, then verify every finding locally before acting.
+
+```text
+You are a meticulous staff-level reviewer giving a SECOND OPINION. You are read-only:
+do not propose to edit files, run commands, or make git changes — return findings only.
+
+## What to review
+{{TARGET}}   # e.g. "the implementation plan below" or "the working-tree diff below"
+
+## Project rules
+Read the repo's root AGENTS.md (your cwd) and obey its Hard Constraints and conventions.
+If AGENTS.md declares a verification/gate set, judge the change against it; if it declares
+none, say so — do NOT invent checks.
+
+## Material
+{{CONTENT}}  # paste the plan text, or the unified diff, or the file excerpts under review
+
+## Focus (optional)
+{{FOCUS}}    # e.g. "correctness of the new reducer", "backward-compat of the stamp takeover"
+
+## Output — Markdown, this exact shape, nothing else
+### Verdict
+One line: SHIP / SHIP WITH NITS / REWORK, plus a one-sentence reason.
+### Blocking
+Numbered. Correctness bugs, contract violations, data loss, security. Cite file:line.
+Empty? write "none".
+### Non-blocking
+Numbered. Simplifications, reuse, naming, missing tests. Cite file:line.
+### Questions
+Anything ambiguous that changes your verdict if answered.
+```
+
+## Usage
+
+```bash
+# critique a plan
+AGY_MODEL="Gemini 3.1 Pro (High)" agy-run @/tmp/review-prompt.filled.md
+
+# critique the current diff (build the prompt with the diff pasted into {{CONTENT}})
+git diff | ...  # assemble the filled prompt, then:
+agy-run @/tmp/review-prompt.filled.md
+```
+
+Treat the result as **advisory** — `agy` output may be incomplete or out of date. The orchestrator
+re-runs the project's real gates and owns every accepted change. See
+[`driving-agy.md`](./driving-agy.md).

package/bridges/antigravity-cli-bridge/setup/README.md

@@ -0,0 +1,65 @@
+# Setting up Antigravity CLI (`agy`) on a clean machine
+
+This setup is **secret-free**. `agy` itself is **not** bundled — it requires a binary install and a
+one-time interactive sign-in with your own subscription. Do this once per machine, then the skill
+works in any project.
+
+## 1. Install the binary
+
+```bash
+curl -fsSL https://antigravity.google/cli/install.sh | bash
+export PATH="$HOME/.local/bin:$PATH"   # add to ~/.bashrc / ~/.zshrc to persist
+agy --version                          # expect 1.0.10 or newer
+```
+
+- The binary is **`agy`** (not `antigravity`); it installs to `~/.local/bin/agy`.
+- Keep `$HOME/.local/bin` on `PATH` (the wrapper also prepends it defensively).
+
+## 2. Sign in once (subscription only)
+
+Run `agy` once interactively and complete the **OAuth** sign-in with a **Google AI Pro/Ultra**
+account:
+
+```bash
+agy
+```
+
+This caches an OAuth token under `~/.gemini/antigravity-cli/` (`antigravity-oauth-token`). That token
+is **personal** — never copy, commit, package, print, or share that directory or token. This skill
+needs no API keys and must not be configured with API-key billing; the wrapper unsets every
+`*_API_KEY` so billing can never silently fall back to pay-as-you-go.
+
+## 3. Put the wrapper on `PATH` as `agy-run`
+
+The skill ships the wrapper at `bin/agy.sh`. Expose it on `PATH` under the stable name `agy-run`
+(idempotent; refuses to clobber a non-symlink):
+
+```bash
+mkdir -p "$HOME/.local/bin"
+skill_dir="$HOME/.claude/skills/antigravity-cli-bridge"   # adjust if installed elsewhere
+dst="$HOME/.local/bin/agy-run"
+if [ -e "$dst" ] && [ ! -L "$dst" ]; then
+  echo "STOP: $dst exists and is not a symlink"; exit 1
+fi
+chmod +x "$skill_dir/bin/agy.sh"
+ln -sfn "$skill_dir/bin/agy.sh" "$dst"
+export PATH="$HOME/.local/bin:$PATH"
+command -v agy-run
+```
+
+## 4. Smoke test
+
+```bash
+agy --version
+echo "say OK" | agy-run -
+```
+
+Expected: the version prints (`1.0.10` or newer), then a short reply containing `OK`. If `agy-run`
+reports `'agy' not found`, fix your `PATH` (step 1). If it asks you to sign in, complete step 2.
+
+## Notes
+
+- `agy-run` is headless and plain-text only; there is no JSON output mode.
+- `AGY_MODEL` selects the exact model display string; `AGY_TIMEOUT` controls `--print-timeout`.
+- Extra `agy` flags go after `--`, e.g. `agy-run @prompt.md -- --add-dir .`.
+- Re-run interactive `agy` only when the OAuth token expires or the account changes.