graph-agents-cli 0.3.1__py3-none-any.whl

graph_agents_cli/skills/data/graph-agents-cli-workflow/references/internals.md

@@ -0,0 +1,67 @@
+# Underlying commands reference
+
+`graph-agents-cli` wraps lower-level tools and shells out to them; it never imports a Kubernetes
+or Docker SDK. When you need a flag or behaviour the CLI does not expose, or when the 3-strikes
+rule says stop retrying, run the underlying command directly from the project root.
+
+Tools are located with `require_tool` (`PATH`, then well-known locations) and every subprocess is
+logged; `--dry-run` on `deploy` prints the exact command lines.
+
+## Develop and test
+
+| `graph-agents-cli` command | Runs |
+|---|---|
+| `playground` (runtime `fastapi`) | `APP_ENV=dev uv run uvicorn <agent_directory>.fast_api_app:app --reload --host 127.0.0.1 --port <port>` (port 8000 by default; opens the browser unless `--no-open`) |
+| `playground` (runtime `langgraph-server`) | `APP_ENV=dev uv run langgraph dev --no-browser --port <port>` (the server is the application; `/chat` and `/playground` are custom routes from `langgraph.json` `http.app`) |
+| `playground --graph` (either runtime) | `uv run langgraph dev --port <port>` and opens LangGraph Studio; needs the `langgraph-cli[inmem]` dev dependency |
+| `run "prompt"` (runtime `fastapi`) | checks the port first (the first free one of 18080-18089, or `--port` / `GRAPH_AGENTS_CLI_RUN_PORT`, exit 3 when taken), starts `uv run uvicorn <agent_directory>.fast_api_app:app --host 127.0.0.1 --port <port>` detached (with the settings of `.env` in its environment from the start, below the shell's, as `load_dotenv` would set them; `playground` does the same), records `.graph-agents-cli/run_server.json` (`pid`, `port`, `started_at`, `last_activity`, `runtime`, `checkpointer`, `state` `starting`/`ready`, `create_time`), `POST /chat` with `Accept: text/event-stream`, prints the reply, stops a server it started itself (also on SIGTERM/SIGHUP/Ctrl-C, with signals held until the record is removed); a server that exits during startup or misses the 60 s `GET /health` readiness check is terminated and reported (exit 2); a recorded PID now owned by another process is never signalled; local runs send `Authorization: Bearer <API_KEY>` from `.env` unless `--header`/`GRAPH_AGENTS_CLI_API_KEY` is given (under `jwt`, `GRAPH_AGENTS_CLI_API_KEY` holds the token, from `auth dev-token` locally) |
+| `run "prompt"` (runtime `langgraph-server`) | same lifecycle with `uv run langgraph dev --no-browser --port <port>` (in-memory server locally) |
+| `run --url URL --mode chat` | `POST <URL>/chat` (SSE) with the credential from `--header`, `GRAPH_AGENTS_CLI_API_KEY`, or `--cookie` |
+| `run --url URL --mode a2a` | needs the `a2a` extra (one-line hint with the install command otherwise, before any server starts); fetches `<URL>/a2a/<agent_directory>/.well-known/agent-card.json` (then the root card), then JSON-RPC to `<URL>/a2a/<agent_directory>`; locally targets `http://127.0.0.1:<port>/a2a/<agent_directory>` without probing |
+| `install` | `uv sync` (`--clean` deletes `.venv` first; `--locked` is `uv sync --locked`) |
+| `lint` | `uv run ruff check .` + `uv run ruff format . --check` + the CLI's own `dev/policy_check.py`, which parses every `*.py` under `<agent_directory>/tools/` (subpackages and their `__init__.py` included, the top-level `__init__.py` excluded, symlinked directories followed once) with `ast`, reads the literal `API_CALLS` list (no import, no model SDK), validates `api-policy.yaml` with the runtime's strict schema and checks each entry against the named API's rules and, when set, its OpenAPI spec (resolved relative to the project root); prints a table, the `graph-agents-cli api` command that would allow each refused call, and the violation count; `--policy-only` skips ruff |
+| `lint --fix` | `uv run ruff check . --fix && uv run ruff format .` then the policy check |
+| `api add\|access\|allow\|deny\|revoke\|limits\|remove` | no subprocess: reads `api-policy.yaml` and the manifest, validates with the shared rules, edits the text at the positions PyYAML reports (comments and key order kept; the result re-parsed and compared with the intended document), prints a unified diff of `api-policy.yaml`, `graph-agents-cli-manifest.yaml`, `.env.example` and `deployment/helm/<name>/values*.yaml`, then writes each through a temporary file renamed over it, line endings and an existing file's mode kept, a new file at 0666 less the umask (`--dry-run` stops before) |
+| `api show` / `api check` | the policy check of `lint` (`api check` is exactly `lint --policy-only`) |
+| `build` | `docker build -t <registry>/<name>:<tag> -f Dockerfile .` (the Dockerfile is runtime-specific: a multi-stage `python:3.12.14-slim-bookworm` image with a pinned uv in the build stage only, or `FROM langchain/langgraph-api:0.14.4-py3.12` for `langgraph-server`, checked against `uv.lock` at build time; both run as 1000:1000; `langgraph build` is never used); the registry is validated first (exit 3 for `ghcr.io/CHANGE-ME` or an invalid reference) |
+
+## Evaluate
+
+| Command | Runs |
+|---|---|
+| `eval generate` | starts the local server as `run` does (or uses `--url`), sends each case's messages to `POST /chat` on a fresh `thread_id`, derives `response`, `tool_calls`, `usage`, `latency_ms`, `status` from the SSE events, writes `artifacts/traces/traces_<ts>.json` |
+| `eval grade` | deterministic `expect` checks in the CLI process first; then stages `.graph-agents-cli/judge_runner.py` into the project and runs `uv run python .graph-agents-cli/judge_runner.py in.json out.json` from the project root, which calls `app.app_utils.model.get_judge_model()` (JUDGE_* env; `--judge-provider/--judge-model` are passed as `JUDGE_MODEL_PROVIDER`/`JUDGE_MODEL_NAME`) for judge and custom metrics; writes `artifacts/grade_results/results_<ts>.json` (suffix `_2`, `_3` on a name clash); no eval service and no LangChain in the CLI |
+| `eval run` | `generate` then `grade`, worst exit code wins; each stage honours an installed extension override |
+| `eval analyze` | in-process deterministic clustering of non-passed cases into `artifacts/analysis_<ts>.json`; `--judge` summarises clusters through the same judge runner |
+| `eval submit` | LangSmith SDK (`langsmith` extra): creates or updates the dataset and examples, then an experiment with runs and feedback from the results file |
+
+## Deploy
+
+| Command | Runs |
+|---|---|
+| `infra check` | tool presence (helm, kubectl, docker, gh, argocd when `cd: argocd`); `kubectl version` (cluster reachable, Kubernetes >= 1.28); `kubectl get crd httproutes.gateway.networking.k8s.io` then `kubectl get gatewayclass` (when `gateway.enabled`); `kubectl get ingressclass` (when `ingress.enabled`); `kubectl get crd certificates.cert-manager.io` (when `tls.certManager.enabled`); `kubectl get apiservice v1beta1.metrics.k8s.io` (when `hpa.enabled`); `kubectl get namespace argocd` + `kubectl get crd applications.argoproj.io` (when `cd: argocd`); `kubectl get namespace <ns>`, `kubectl -n <ns> get secret <pull-secret>` (from `imagePullSecrets`) and `kubectl -n <ns> get secret <name>-app` (its required keys); the `CHANGE-ME` placeholders in the manifest registry, the chart's `image.repository` and `env`, `.github/CODEOWNERS` and the Argo CD `repoURL`; `gh api repos/<owner>/<repo>/environments/production`, `.../environments/staging` and `.../branches/main/protection` when `gh` is logged in and `cd != skip`, plus (helm-push) `.../environments/<env>/secrets/DEPLOY_KUBECONFIG` and the repository/organization kubeconfig secrets; `--profile disconnected` adds the disconnected-profile checks (provider, `OPENAI_BASE_URL`, runtime, registry, tracing, CI runner labels, `GRAPH_AGENTS_CLI_NO_UPDATE_CHECK`). Read-only |
+| `secrets apply --env <env>` | resolves the env file (`.env.<env>`; `.env` for dev only) and the kube context (confirmed outside dev); `kubectl create namespace <namespace>` when absent; `kubectl get secret <release>-app -o json` (live keys, merged under the file's); `kubectl -n <namespace> create secret generic <release>-app --from-env-file=<0600 temporary file holding only the allow-listed keys> --dry-run=client -o yaml \| kubectl apply --server-side --field-manager=graph-agents-cli --force-conflicts -f -`; the temporary file is deleted afterwards; a leftover `last-applied-configuration` annotation is removed; `API_KEY` is generated only when absent from the file and from the live Secret and then written to the env file (0600), never printed; multi-line values are exit 3; not refused under CI |
+| `secrets status --env <env>` | `kubectl -n <namespace> get secret <release>-app -o json` and lists present, missing required, missing optional and unexpected key names; exit 1 when the Secret or a required key is missing (`--strict`: any allow-listed key), 2 when kubectl fails |
+| `deploy --env dev` (direct, local-load) | a read-only check of the Secret it would produce (required keys; exit 1 before building) and of the release (`helm history`; a `pending-*` revision is exit 2); `docker build -t <registry>/<name>:<tag>` (`git rev-parse --short HEAD`, plus `-dirty-<time>` for uncommitted changes, else a UTC timestamp, or `--tag`); then `kind load docker-image` / `k3d image import` / `docker save` + `k3s ctr images import` (no sudo; usually needs root) / `minikube image load` (none for docker-desktop, rancher-desktop, orbstack), chosen from the cluster's nodes and confirmed with `kind get clusters` / `k3d cluster list` / `minikube profile list`; the Secret pipeline of `secrets apply` (skipped when dev has no env file); `helm dependency build deployment/helm/<name>` when a subchart is missing from `charts/`; `helm upgrade --install <release> deployment/helm/<name> -n <namespace> --create-namespace -f values.yaml -f values-<env>.yaml --set image.repository=...,image.tag=<tag>,existingSecret=<release>-app --wait --timeout <5m> --kube-context <context>`; on failure `kubectl get pods`, container states, warning events and logs, then `helm rollback <release> <last good>` (or `helm uninstall` of a failed first install) with `--atomic` |
+| `deploy --env <env>` (direct, registry) | the same checks, `docker build`, `docker push <registry>/<name>:<tag>`, the Secret pipeline, `helm dependency build` when needed, `helm upgrade --install ... --wait --timeout` with the same failure handling |
+| `deploy --image <ref> --env <env>` (helm-push, from the CI runner) | the live Secret's required keys and the release state, `helm dependency build` when needed, then `helm upgrade --install ...` only; refused outside CI (`GITHUB_ACTIONS=true`) for staging/prod even with `--image`, unless `--force-direct` |
+| `deploy --env <env> --image <ref>` (argocd) | rewrites `image.tag` in `origin/main`'s copy of `deployment/helm/<name>/values-<env>.yaml` (`git cat-file blob`; the working tree is untouched), then builds branch `deploy/<env>/<short sha>` with git plumbing (`git fetch origin main`, `hash-object --stdin`, `read-tree`, `update-index` with a repo-relative path, `write-tree`, `commit-tree`, `update-ref`; the checkout is never switched), `git push --force-with-lease=refs/heads/deploy/<env>/<short sha>:<sha on origin>` (nothing when origin already holds the change), `gh pr list`/`gh pr create --repo <host>/<owner>/<repo>` (or GitHub REST with `GITHUB_TOKEN`/`GH_TOKEN`/`GH_ENTERPRISE_TOKEN`; `GH_HOST` for GitHub Enterprise Server); without `--image` the tag is `--tag` or the short git sha with a warning; never helm, never merges |
+| `deploy --status --env <env>` | `kubectl -n <namespace> rollout status deploy/<release>` or, in argocd mode, `argocd app get <name>-<env>` |
+| `deploy --restart --env <env>` | `kubectl -n <namespace> rollout restart deploy/<release>` (warns that Argo self-heal may revert it in argocd environments) |
+| `deploy --dry-run` | prints every command above with a `[dry-run]` prefix and `helm template` output without executing, except `helm dependency build`, which is executed when subcharts are missing because the render needs them |
+
+## Rollback
+
+- Direct and helm-push modes: a failed rollout is rolled back by `deploy` itself (`--atomic`,
+  the default), acting only on the revision that run created. For a release that deployed fine,
+  `helm history <release> -n <namespace>` then `helm rollback <release> <revision> -n <namespace>`.
+- argocd mode: revert the values change on `main` with a PR (the same gate applies), then let Argo
+  reconcile. `argocd app history` and `argocd app rollback` are Argo-side tools for emergencies.
+
+## Scaffold
+
+| Command | Runs |
+|---|---|
+| `create` | cookiecutter layering (`base_templates/_shared` -> `base_templates/python` -> `deployment_targets/<target>` -> `agents/langgraph`), conditional-file selection by runtime and CD mode, copies `uv-<runtime>.lock` to `uv.lock` (substituting the project name), reconciles the manifest against the contract, then `uv sync`; remote `--agent` specs are shallow-cloned with `git`; the registry default comes from the git `origin` owner |
+| `scaffold enhance` | renders old and new baselines and runs the 3-way merge; a backup goes to `~/.graph-agents-cli/backups/<dir>_<project id>_<timestamp>/` first (0700, the newest 5 per project kept); a runtime or provider change also merges the chart values and `.github/agent.env` key by key around your edits; when the merge changes the manifest it is rewritten through the YAML dumper (block style, comments dropped) and `.github/agent.env` is updated |
+| `scaffold upgrade` | `uvx --from <spec of the old build> graph-agents-cli scaffold create ...` to regenerate the authentic old baseline (the `--baseline-ref` build, else the commit the manifest's `cli_build` records for a build between releases, else the `cli_version` release), then the 3-way merge; at the running version it compares `cli_build` (build id, then `template_digest`) and says "already at version" when nothing differs; stops without changes (exit 2) if that build cannot be fetched unless `--baseline current`, which cannot tell edits from template changes since the old version; records the running build in `cli_build` |

graph_agents_cli/skills/data/graph-agents-cli-workflow/references/spec-template.md

@@ -0,0 +1,56 @@
+# Agent spec template
+
+Write `.graph-agents-cli-spec.md` in the project's working directory. **If the project declares a
+`process:` (manifest or guidance file), do not write this file as a substitute for that process's
+documents; the process's approvals are the gate.** This template applies when no process is
+declared.
+
+```markdown
+# Agent Spec
+
+## Overview
+The agent's purpose, who calls it, and how it works in two or three sentences.
+
+## Example Use Cases
+Concrete examples with expected inputs and outputs. These become the first eval cases.
+
+## Tools Required
+Each tool with its purpose. For tools that call an external API: the API name, the HTTP method and
+operationId (or path) it calls, and the credential (`forward`, `bearer`, or `none`). Every
+operation listed here must be allowed by `api-policy.yaml`.
+
+## Model and Egress
+Provider (`openai` | `anthropic` | `gemini` | `openai-compatible`) and model. State explicitly what
+context may leave the network (prompts, tool results, retrieved data) and whether traces may be
+exported (`TRACING_ENABLED`, `TRACE_CAPTURE`).
+
+## Runtime and Persistence
+`fastapi` (default) or `langgraph-server`; `memory` locally and `postgres` when deployed;
+whether threads must survive restarts; whether any tool call requires a human-in-the-loop
+interrupt.
+
+## Authentication
+`shared-bearer` (internal tools, dev), `jwt` (per-user OIDC tokens; conversation ownership
+enforced; read-across roles listed), or `custom` (the project's own policy, for example an existing
+application's session).
+
+## Constraints and Safety Rules
+Specific rules, not generic statements: what the agent must never do, which operations are denied,
+what to refuse, how to handle missing data.
+
+## Success Criteria
+Measurable outcomes for evaluation: which `expect` checks each use case must satisfy, which judge
+metrics apply with what threshold, and which of those are quality metrics with a `min_pass_rate`.
+
+## Deployment Shape
+Prototype first (`--prototype`) or Kubernetes; if Kubernetes: registry, CD mode
+(`skip` | `helm-push` | `argocd`), environments, and who owns secrets.
+
+## Assumptions
+One line per decision you made for the user (data sources, auth method, model, schedule). The user
+corrects these at review.
+```
+
+Optional sections for detailed specs: **Edge Cases to Handle**, **Graph Design** (nodes, edges,
+subgraphs, interrupts), **Data Sources and Auth**, **Non-Functional Requirements** (latency,
+token budgets), **Future Phases**.

graph_agents_cli/skills/data/graph-agents-cli-workflow/references/terminology.md

@@ -0,0 +1,119 @@
+# Terminology: user terms to CLI values
+
+Users describe the same thing in many ways. Map their words to graph-agents-cli values before
+choosing flags or editing configuration.
+
+## Runtime and framework
+
+| User says | CLI value |
+|---|---|
+| "LangGraph", "a graph", "StateGraph", "ReAct agent", "create_agent" | `--agent langgraph` (the only bundled template); the graph lives in `app/agent.py` |
+| "plain FastAPI", "just a container", "no license", "simplest thing" | `--runtime fastapi` (default) |
+| "LangGraph Platform", "LangGraph Server", "Agent Server", "langgraph-api", "Assistants/Threads/Runs API", "Studio-compatible server" | `--runtime langgraph-server` (needs Postgres and Redis; the deployed `langgraph-api` image checks for a LangGraph licence at startup, so it is outside the disconnected profile; the local `langgraph dev` server needs no licence) |
+| "LangGraph Studio", "visual graph debugger" | `graph-agents-cli playground --graph` (`langgraph dev`, bypasses auth) |
+| "chat page", "try it in the browser" | `graph-agents-cli playground` (`/playground`, only when `APP_ENV=dev`) |
+| "A2A", "agent-to-agent", "agent card" | built in: `/a2a/<agent_directory>/.well-known/agent-card.json`; `run --mode a2a`; tasks are private to their principal, kept in Postgres under `CHECKPOINTER=postgres` (every replica sees them, restarts keep them), else in process memory (`A2A_TASK_TTL_S`) |
+| "health check", "liveness", "readiness", "probe" | `GET /health` (liveness), `GET /ready` (the database answers) |
+| "metrics", "Prometheus", "monitoring" | `GET /metrics` (`METRICS_ENABLED`, optional `METRICS_TOKEN`); chart `metrics.serviceMonitor` / `metrics.scrapeAnnotations` |
+| "timeout", "runaway agent", "loop" | `RUN_TIMEOUT_S`, `MODEL_TIMEOUT_S`, `MODEL_MAX_RETRIES`, `RECURSION_LIMIT` |
+| "concurrent requests on one conversation" | one run per thread: 409 `{"code": "thread_busy"}` |
+| "rate limiting", "throttling" | not built in: configure it at the Gateway or ingress |
+
+## Models
+
+| User says | CLI value |
+|---|---|
+| "OpenAI", "GPT" | `--model-provider openai`, key `OPENAI_API_KEY` |
+| "Anthropic", "Claude" | `--model-provider anthropic`, key `ANTHROPIC_API_KEY` |
+| "Gemini", "AI Studio key" | `--model-provider gemini`, key `GOOGLE_API_KEY` (the AI Studio API key path only) |
+| "Ollama", "vLLM", "TGI", "OpenRouter", "local model", "self-hosted model", "open-source model", "OpenAI-compatible" | `--model-provider openai-compatible`, `OPENAI_BASE_URL`, key `MODEL_API_KEY` |
+| "judge model", "grader", "LLM-as-judge" | `JUDGE_MODEL_PROVIDER`, `JUDGE_MODEL_NAME`, `JUDGE_BASE_URL`, `JUDGE_API_KEY` (default to the agent's) |
+| "fake model", "no key in CI" | provider `fake` (tests only; never offered by `create`) |
+
+## Persistence
+
+| User says | CLI value |
+|---|---|
+| "memory", "remember the conversation", "threads", "checkpoints", "session" | the checkpointer; continuity is by `thread_id` on `/chat` |
+| "Postgres", "durable", "survives restarts", "multiple replicas" | `--checkpointer postgres`; `CHECKPOINTER=postgres` + `POSTGRES_DSN` (fastapi) or `DATABASE_URI` + `REDIS_URI` (langgraph-server) |
+| "in-memory", "no database locally" | `CHECKPOINTER=memory` (the `.env.example` default; run records are in-process) |
+| "run history", "usage records" | run records (follow the checkpointer; payload only under `TRACE_CAPTURE=full`) |
+| "list my conversations", "delete a conversation" | `GET /threads`, `DELETE /threads/{thread_id}` (owner only) |
+| "data retention", "purge old conversations" | `RETENTION_DAYS` (0 keeps everything; an hourly best-effort purge of idle threads) |
+
+## Auth and outbound API access
+
+| User says | CLI value |
+|---|---|
+| "API key", "bearer token", "shared secret", "internal tool" | `--auth-policy shared-bearer`; `API_KEY` in the Secret; clients send `Authorization: Bearer` |
+| "OIDC", "SSO", "JWT", "access token", "per-user identity", "who owns the conversation" | `--auth-policy jwt` (per-user principals from a verified token: `AUTH_JWT_ISSUER`, `AUTH_JWT_AUDIENCE`, JWKS or public key) |
+| "our app's session cookie", "existing roles", "custom header", "gateway identity headers" | `--auth-policy custom` (stub fails closed until implemented in `app/policies/custom.py`); clients use `--header` or `--cookie` |
+| "support staff may read conversations", "admins" | `AUTH_READ_ACROSS_ROLES` (read others' threads), `AUTH_ADMIN_ROLES` (manage assistants, crons and the store under `langgraph-server`) |
+| "which endpoints may the agent call", "read-only", "read-write", "only these operations", "allow-list", "deny" | `api-policy.yaml` (`apis: <name>:` with `allowed_methods`, `allowed_operations`, `denied_operations`, optional `limits`), changed with `graph-agents-cli api add --access read-only\|read-write\|custom`, `api access`, `api allow`, `api deny`, `api revoke`; seeded by `create --api-policy <file>`. The access level is the user's choice per API; there is no default |
+| "the agent may call it at most N times", "rate limit the API", "don't hammer the backend" | `limits: {max_calls_per_run, rate_per_minute}` on the API (`graph-agents-cli api limits`); per run and per replica |
+| "ask a human before the agent writes", "confirm before cancelling", "human in the loop", "approval" | an `approval` block on the API (`graph-agents-cli api approval NAME --methods POST,DELETE --approvers requester`, or `--operations cancelOrder`): the run pauses before the gated call and an approver decides it (`run` asks on a terminal; `graph-agents-cli approvals approve\|reject`). Approval never widens access |
+| "four-eyes", "a second person must approve", "a manager signs off" | `--approvers role:<name>` without `requester` (another principal holding the role decides), under the `jwt` or `custom` auth policy (`shared-bearer` has one principal) |
+| "the customer confirms changes but an admin approves new orders", "different approvers for different actions" | a list of approval rules on one API: `graph-agents-cli api approval NAME --add-rule --operations createOrder --approvers role:admin` after the first rule; the first rule in file order that covers a call gates it (`--rule N` changes one). Never a second API entry for the same backend |
+| "don't let customer text steer the agent", "prompt injection", "act only on the user's own records" | tool results are fenced as untrusted data (`UntrustedToolResults`) and the default prompt forbids following them; write tools (and reads across customers in staff sessions) call `require_user_mentioned` and `require_owner`, and write APIs use `auth: forward` so the upstream authorizes the user (`/graph-agents-cli-langgraph-code` section 2a) |
+| "call our backend API", "backend client", "call the service as the user" | `get_client("<api>")` from `app/app_utils/api_client.py`, the only HTTP path to external APIs (`auth: none`, `bearer`, or `forward` for the caller's own credential); tools declare `API_CALLS` |
+
+## Deployment
+
+| User says | CLI value |
+|---|---|
+| "Kubernetes", "k8s", "our cluster", "on-prem", "self-hosted", "OpenShift", "RKE2", "kubeadm" | `--deployment-target kubernetes` (Helm chart in `deployment/helm/<name>/`) |
+| "kind", "k3s", "k3d", "minikube", "Docker Desktop", "local cluster" | environment `dev` with local-load (image loaded into the node, no registry) |
+| "prototype", "just locally", "no deployment yet" | `--prototype` (target `none`, `cd: skip`) |
+| "GitOps", "Argo", "pull-based", "PR to deploy" | `--cd argocd` |
+| "runner in our network", "push-based", "CI deploys" | `--cd helm-push` (self-hosted GitHub runner; the `DEPLOY_KUBECONFIG` secret of the `staging` / `production` environment) |
+| "CI only", "I'll deploy by hand" | `--cd skip` (direct modes) |
+| "registry", "GHCR", "Harbor", "where do images go" | `--registry <url/org>` (default `ghcr.io/<org>`) |
+| "ingress", "route", "hostname", "TLS" | chart values: `gateway` (Gateway API `HTTPRoute`, default) or `ingress`; `tls.existingSecret` or `tls.certManager` |
+| "dev / staging / prod", "namespaces" | environments `dev`, `staging`, `prod`; namespace `<name>-<env>`; `values-<env>.yaml`; Secret `<name>-app` |
+| "secrets", "rotate the key" | `secrets apply --env <env>` (from `.env.<env>`; `--rotate-api-key` for `API_KEY`) then `deploy --restart --env <env>` |
+| "which cluster", "kube context" | `environments.<env>.context` in the manifest, or `--context`; outside dev the current context needs a confirmation or `--yes` |
+| "who approves production" | the merge of the PR touching `values-prod.yaml` (code owners, no self-approval, `pr_checks` green); the GitHub `production` environment gates promotion from CI |
+| "air-gapped", "disconnected", "no internet", "offline" | the disconnected profile (`infra check --profile disconnected`, `login --profile disconnected`) |
+
+## Evaluation and observability
+
+| User says | CLI value |
+|---|---|
+| "test cases", "golden set", "eval dataset" | `tests/eval/datasets/*.json` |
+| "must contain", "must call tool X", "no tool calls", "under N ms" | `expect.contains`, `expect.tool_calls`, `expect.no_tool_calls`, `expect.max_latency_ms` |
+| "exact case", "in any turn", "across the whole conversation" | `expect.case_insensitive: false` (`contains`/`not_contains` ignore case by default); `expect.scope: all_turns` (checks read every turn, not only the final one) |
+| "quality score", "rubric", "graded by a model" | `judge.<metric>` with `threshold`; mandatory unless listed under `quality_metrics:` |
+| "allow 90 % to pass" | `quality_metrics.<metric>.min_pass_rate: 0.9` (judge metrics only) |
+| "upload to LangSmith", "experiment" | `eval submit` |
+| "tracing", "traces", "spans" | `TRACING_ENABLED=true` (off by default) |
+| "log the prompts", "full payloads" | `TRACE_CAPTURE=full` (default `metadata`) |
+| "OpenTelemetry", "OTLP", "our collector", "Jaeger", "Tempo" | `OTEL_EXPORTER_OTLP_ENDPOINT` (used when no `LANGSMITH_API_KEY`) |
+
+## Renamed in graph-agents-cli 0.2.0
+
+| 0.1.0 name | 0.2.0 name |
+|---|---|
+| `--auth-policy product-session`, `ProductSessionPolicy` | `--auth-policy custom`, `CustomPolicy` in `app/policies/custom.py` (the old name is read as `custom` with a warning) |
+| `product-policy.yaml`, `--product-policy`, manifest `product_api:` | `api-policy.yaml` (`apis: {<name>: ...}`), `--api-policy`, `api_policy: {policy_file: api-policy.yaml}` |
+| `PRODUCT_CALLS`, `product_client` | `API_CALLS` (with `"api"`), `api_client.get_client("<api>")` |
+| `CLI_VERSION_PIN` in `.github/agent.env` | `GRAPH_AGENTS_CLI_SPEC` (a full install spec) |
+| default guidance file `GEMINI.md` | `AGENTS.md` |
+| repository secret `KUBECONFIG` (helm-push) | environment secret `DEPLOY_KUBECONFIG` |
+
+## Migration note
+
+Old names from google-agents-cli and their replacements, for users who still use them:
+
+| Old term | Now |
+|---|---|
+| ADK, Agent Development Kit, `root_agent` | LangGraph; `graph` in `app/agent.py` |
+| Agent Engine, Agent Runtime, Cloud Run, GKE, `--deployment-target agent_runtime\|cloud_run\|gke` | `--deployment-target kubernetes` |
+| Vertex AI, gcloud ADC, `GOOGLE_CLOUD_PROJECT`, `GOOGLE_GENAI_USE_VERTEXAI` | provider keys (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `MODEL_API_KEY`) plus a kubeconfig |
+| Agent Platform Sessions, Cloud SQL sessions, `--session-type` | `--checkpointer memory\|postgres` |
+| Cloud Build, `--cicd-runner google_cloud_build\|github_actions` | GitHub Actions always; `--cd argocd\|helm-push\|skip` |
+| Terraform, `infra single-project`, `infra cicd` | none; `infra check` is read-only |
+| Secret Manager | Kubernetes Secret `<release>-app` via `secrets apply` |
+| Cloud Trace, Cloud Logging, BigQuery Agent Analytics, `--bq-analytics` | LangSmith or OTLP behind `TRACING_ENABLED` |
+| Agent Platform eval service, `eval optimize`, `eval dataset synthesize`, `eval results` | in-process deterministic checks and judge; those commands were removed |
+| `publish gemini-enterprise`, Agent Registry, Agent Gateway | removed; `deploy` exposes the agent in-cluster |
+| `agents-cli-manifest.yaml`, `AGENTS_CLI_*` env vars, `~/.agents-cli` | `graph-agents-cli-manifest.yaml`, `GRAPH_AGENTS_CLI_*`, `~/.graph-agents-cli` |

graph_agents_cli/system/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2026 graph-agents-cli contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""``graph-agents-cli system``: several agent projects that call each other, seen as one."""