@mesh-tech/mesh-cli 0.1.1 → 0.12.1

package/skills/core/SKILL.md

@@ -0,0 +1,365 @@
+---
+name: core
+description: >
+  The `mesh` developer CLI (@mesh-tech/mesh-cli) — Zitadel/OIDC login,
+  CodeArtifact registry auth, Pulumi deploy/stack passthrough, app scaffolding
+  (create-app), local dev orchestration (dev), SSM tunnels (tunnel), DB access
+  (db), Secrets Manager (secrets), Headscale VPN (vpn), Temporal inspection
+  (temporal), workflow IR extraction (workflow), agent artifact export
+  (artifacts), reading deployed-agent conversations (conversations), and both
+  app API docs and the generated developer portal / CLI reference (docs).
+  Activate when running any `mesh ...`
+  command, scaffolding a tenant app, opening a bastion/DB tunnel, deploying a
+  Pulumi stack via the deployer role, wiring local dev, or building the docs
+  portal.
+metadata:
+  version: '0.1'
+  category: 'tooling'
+  type: core
+---
+
+# `@mesh-tech/mesh-cli`
+
+Developer CLI for Mesh Platform. Binary name is **`mesh`**. Installed standalone or
+transitively via the app-kit bundle.
+
+## Running it (MESH-2261)
+
+**In this monorepo the CLI runs from TypeScript source — there is no build step and
+no `dist/` to go stale.** The `bin` is a launcher (`bin/mesh.mjs`) that runs
+`bin/mesh.ts` under `tsx`, so you always get the local source of whatever
+worktree/app you're in. (At publish time `build-for-publish` rewrites the `bin` to
+the built `./dist/bin/mesh.js` for consumers.)
+
+- **Any cwd:** `pnpm exec mesh <cmd>` — works in the repo root, any worktree, or an
+  app subdir, even in a never-built worktree (no `pnpm build` needed).
+- **Repo/worktree root:** `pnpm mesh <cmd>` (the root `"mesh"` script).
+- **Bare `mesh <cmd>`:** run `pnpm exec mesh install-shim` **once** — it writes a tiny
+  cwd-aware resolver to `~/.local/bin/mesh` (build-free; survives worktree switches
+  and pulls). After that, `mesh dev` etc. run the local source directly. The shim is
+  **not** version-pinned: it walks up from your cwd to the nearest
+  `node_modules/.bin/mesh`, so it always runs the mesh-cli the **current workspace**
+  resolves — the worktree's live source in-repo, or the repo's pinned published
+  version in a standalone consumer repo. One global shim, correct local version.
+- **NEVER** run `node …/dist/bin/mesh.js` directly — that path doesn't exist in-repo
+  (the CLI isn't built here) and, if it does from a stray publish, it's stale. Use one
+  of the forms above.
+- **Suspect you're running a stale copy?** `mesh --version` prints provenance
+  (MESH-2479): `source @ <commit> <date>` means this checkout's TypeScript source;
+  `published build <date>, commit <commit>` means a packaged install. If the commit
+  isn't your checkout's HEAD (or it says `published build` inside a worktree), your
+  resolution is stale — remedy: re-run the scoped install so `.bin/mesh` exists here
+  (`pnpm install --frozen-lockfile --filter @mesh-tech/mesh-cli...`), then invoke via
+  `pnpm exec mesh` (or re-run `pnpm exec mesh install-shim` once if the shim itself
+  was overwritten).
+
+```bash
+# Standalone consumer repo (published package, runs built dist):
+npm i -D @mesh-tech/mesh-cli   # or pnpm add -D
+pnpm exec mesh --help
+```
+
+Built on `commander`. Most commands auto-detect tenant/env/stack from Pulumi config
+in the cwd or its parents; AWS-touching commands resolve credentials in this order:
+ambient env creds (CI) → cached Zitadel JWT from `mesh login` (`AssumeRoleWithWebIdentity`) → AWS SSO profile (`AssumeRole`).
+
+> **`mesh registry login` is the exception, and tries a step *before* all three:**
+> the Zitadel-gated **registry-auth broker**. It exchanges the id token `mesh login`
+> already cached for a CodeArtifact read token minted with the broker's own AWS
+> identity, so installing `@mesh-tech/*` needs **no AWS account, no AWS CLI and no
+> `~/.aws/config`** — only a Mesh account holding the `registry:read` role. The three
+> AWS paths remain the fallback (CI, client-owned tenant accounts, publishing).
+> See [`docs/guides/new-developer-setup.md`](../../../../docs/guides/new-developer-setup.md).
+
+> **`mesh` is the front door — don't run raw `pulumi` or `aws`.** Every Pulumi op
+> goes through `mesh deploy <op>` (up/preview/destroy/refresh/import/state/cancel/
+> stack output) and stack lifecycle through `mesh stack init`/`rm` — all assume the
+> stack's deployer role with an up-front **login preflight** (a clear "run `mesh login
+> --device`" instead of a raw AWS error). This works in a sandbox with **no `~/.aws`
+> access**: creds are passed as env vars (deploy/db/secrets), `mesh dev` writes its
+> self-refreshing profile under the session scratch dir, and `mesh login --export`
+> falls back to a mesh-managed AWS config when `~/.aws` isn't writable. The one
+> genuine bootstrap that still needs raw pulumi: setting the initial
+> `mesh:deployerRole` on a brand-new stack.
+
+## Command reference
+
+Top-level commands (each `register*` is wired in `src/program.ts`, which `bin/mesh.ts` runs):
+
+| Command | Subcommands | Does | Key flags / args |
+|---|---|---|---|
+| `mesh login <context>` | (also `mesh logout <context>`) | Zitadel OIDC PKCE or device-code auth; caches creds in `~/.config/mesh/`. Context like `mesh.dev`. Auto-discovers config via SSM then HTTPS `.well-known/mesh.json`. | `--status` (reports the cached Zitadel session, or — when there isn't one — the AWS identity the credential chain resolves, so an SSO profile or a key/secret pair passes too; non-zero only when neither works), `--device`, `--export` (print AWS `export`s for `eval`), `--role <arn>`, `--region <r>` |
+| `mesh registry` | `login [context]`, `status`, `publish` | CodeArtifact auth → refreshes `~/.npmrc` token (12h) + adds `@mesh-tech` scope to project `.npmrc` + **strips an unscoped CodeArtifact `registry=` line from `~/.npmrc`** (after writing `~/.npmrc.bak-<ts>`) — that line is what a raw CodeArtifact sign-in *without* `--namespace @mesh-tech` leaves behind, and it makes CodeArtifact your DEFAULT registry so every *public* install 401s at the 12h expiry. Skipped under `--ci`, where the unscoped login is deliberate. `status` probes the registry rather than grepping the file: expired/missing token or a hijack exits 1, an unreachable registry warns and exits 0. **Step 0 is the Zitadel-gated broker:** with a context (`mesh registry login mesh.dev`) the CLI POSTs the cached id token to the platform's `registry-auth` service, which returns a CodeArtifact read token minted with its OWN AWS identity — so this path needs no AWS account, CLI or profile at all. It writes the same two `~/.npmrc` lines the AWS path does. Falls back to the AWS chain when the platform publishes no broker, when the broker is unreachable, or with `--no-broker`; a 403 (a valid Mesh account without the `registry:read` role) is fatal and does **not** fall through. `--publish` and `--profile` deliberately skip the broker — both are AWS-identity paths. `--profile mesh-dev` auto-runs the AWS SSO login when the session is stale. Also runs automatically after `mesh login {tenant}.{env}` (F2). `login --publish` assumes the registry's publisher role (from `--role` or the registry SSM export); `publish` pushes package snapshots. | `login`: `--no-broker`, `--profile <sso>`, `--role <arn>`, `--ci`, `--skip-npmrc`, `--publish`; `publish`: `--snapshot` |
+| `mesh db` | `connect`, `credentials`(alias `creds`), `env`, `psql`, `exec <command...>` | Access tenant DBs through an SSM bastion tunnel. `env` prints `export`s for `eval`; `exec` runs a command with `DATABASE_URL` injected. | `-t/--tenant`, `-e/--env`, `-a/--app`, `--app-tenant`, `--app-stage`; `exec` also: `--secret <arn>`, `--ssl <require\|no-verify\|disable>`, `--port <n>` |
+| `mesh deploy ...` | passthrough | Runs `pulumi` with the stack's `mesh:deployerRole` assumed. Unknown opts/args pass through; defaults to `up` if no subcommand. | `-s/--stack <name>` (stripped before pulumi `up`); everything else → pulumi (`preview`, `up --yes`, `destroy`, `stack output …`) |
+| `mesh dev` | `logs <service>`, `restart <service>`, `list`, `test-user [name]` | Two modes. **Tethered** (deployed stack): reads the Pulumi stack dev output, opens tunnels, injects Secrets Manager secrets; needs VPN/AWS creds. **Local** (`--local`, auto when the app has no `Pulumi.yaml`): synthesizes services from the app layout (subdirs with a `dev` script) and wires them to the `mesh start` platform (Temporal `local-dev`, app DB, Zitadel, ministack via `AWS_ENDPOINT_URL`) — zero AWS/VPN/Pulumi. `--externals` (local mode; `--mock` is an alias) also realizes the app's declared external services (package.json → `mesh.externals`; legacy `mesh.mocks` still read). Each declaration runs in one of three MODES — `mock` (the service is emulated: `openapi` → a Prism mock server from a spec, or `src` → a mock process), `local` (a local version of the real service: a `compose` file + published `port`, e.g. a vendor-shaped DB — up `--wait` before the app's services; a realization another checkout already started is **adopted** instead of failing — declared port already served **by a container this compose file defines** → adopt as-is (a publisher the file doesn't define — a native install or unrelated container — is a hard **conflict**, never adopted, since credentials would seed against the wrong service); a stopped foreign container holding the compose `container_name` → `docker start` + adopt — so startup order across checkouts doesn't matter; adopted externals stay out of session state and `--kill` tears down only externals this session created, volumes kept), `remote` (connect to the ACTUAL service: inline vendor `credentials`, or the credentials the app's tenant environment is configured with via `remote.env`). A declaration may carry SEVERAL realizations; `mode` picks the default and `--externals name=mode` overrides it per run (`--externals plaid-db=remote,plaid`). Remote externals get a blackbox uptime probe against their real endpoint. Failing to realize a remote external is fatal only when you named it; a bare `--externals` warns and keeps going, so the local loop still works with no AWS identity. Every realization seeds its ExternalService credential secret (`{{url}}`/`{{host}}`/`{{port}}` from the stand-in's endpoint, `{{env:VAR}}` from the shell) so `resolveCredentials()` runs the deployed code path against the stand-in. Runners: tmux (default) or `--runner docker` (CI/headless — services run as a docker compose project with host networking; parity `--status`/`--kill`/`logs`/`restart`). | root: `--local`, `--externals [name[=mode],…]` (alias `--mock`), `--runner <tmux\|docker>`, `--app <path>`, `--stage`, `--headless`, `--kill`, `--status`, `--json`, `--session <name>`, `--profile <sso>`; `logs`: `--tail <n>`; `test-user`: `--tenant/--env/--region` |
+| `mesh start` / `mesh stop` / `mesh status` | — | Full-local Mesh platform via docker compose (project `mesh-local`, assets ship in the CLI package): Postgres, Temporal (+UI), Zitadel, SpiceDB, ministack (local AWS fabric: SSM/Secrets/S3 registry), memcached, OpenSearch, **and the hosted observability backends** (OTel collector + Loki + Tempo + Prometheus — the Hub's logs/traces/metrics views run unchanged). Seeds tenant `local`/env `dev` on first boot and reconciles every Zitadel-provisioned app tenant into the registry. **No AWS creds, VPN, or Pulumi state needed — Docker only.** The **Hub is included by default** — three overlay services, `hub-api` + `hub-ui` + `hub-auth` (an oauth2-proxy; it is what binds the front-door port and proxies to `hub-ui`, so front-door 401s/redirect loops are in ITS logs, not `hub-api`'s) — the front door at http://localhost:9000 — `MESH_HUB_PORT=<port>` publishes it elsewhere when 9000 is taken; export it for `mesh status` too (images build once from the published @mesh-tech/hub tarball; needs `mesh registry login` the first time; `--no-hub` opts out). Auth contract (MESH-2479): `--with-hub` refreshes to the latest published hub after preflighting the CodeArtifact token — with an expired/missing token it falls back to the already-built local images (warn + fixing command), or fails fast naming `mesh registry login --profile mesh-dev` when none exist; the default (no-flag) path with an expired/missing token starts hub-less and names the same fix. Non-TTY runs (CI, agents, piped output) get an `[HH:MM:SS]` prefix on every step line plus a heartbeat during long fetches/builds — `MESH_LOG_TIMESTAMPS=1/0` forces the prefix on/off (default: on when stderr is not a TTY). | `start`: `--no-seed`, `--no-hub`, `--with-hub`; `stop`: `--destroy` (drops volumes/seeds); `status`: `--json` |
+| `mesh hub` | `dev` | One-command local Hub over a running dev-local stack. Launches the CURRENT-CODE Hub (apps/hub api+ui from a mesh-platform checkout) pointed at an existing `mesh dev` session — auto-assembles `HUB_TENANT`/`HUB_SCOPE_ENV`/`HUB_SCOPE_TENANTS` (session platform context), `TEMPORAL_ADDRESS` (session tunnel), `AWS_*` (session scratch profile), `DEV_USER_*`+`DEV_USER_TOKEN_URL` (session dev identity; starts its own token-server if the session predates it, so tokens stay fresh past ~1h). Refuses to launch with an empty tenant scope (which the Hub renders as silently blank). Runs in tmux session `mesh-hub-dev`. | `dev`: `--session <name>`, `--tenants <csv>`, `--port` (or `MESH_HUB_DEV_PORT`, default 9000; the containerized `mesh start` Hub uses the separate `MESH_HUB_PORT`), `--api-port <3002>`, `--platform-dir <dir>` (or `MESH_PLATFORM_DIR`), `--print-env`, `--kill` |
+| `mesh create-app` | — | Scaffold a tenant app. Composable mode (primitives) or legacy template mode. Interactive when TTY + missing flags. Run at the root of an **empty** `{tenant}-mesh-apps` git clone (a `.git` with no `package.json`/`apps/`/`tenants/` and no enclosing pnpm workspace), it first generates the repo-level shape — `pnpm-workspace.yaml` over `apps/*`, private root `package.json`, scoped-registry `.npmrc`, base `tsconfig.json`, `.gitignore`, `README.md`, `apps/` — then scaffolds the app. Never overwrites an existing file. | `--tenant`, `--name`, `--primitives <csv>` (`service,database,temporal,bucket`), `--template <workflow\|api-auth\|api-role-gating\|external-service>`, `--test` (writes to `tests/tenants/`) |
+| `mesh init` | `app-tenant` | The repo doctor (A1–A3): read-only check pipeline — CLI auth, registry access, public npm not hijacked, platform reachable (Hub API), app-tenant registration, deployer role, repo shape, agent skills — each failure names the exact `mesh` fix. **Registry access** is a live probe of the CodeArtifact token, not a grep of `~/.npmrc`: an expired token `fail`s (it used to `pass`), an unreachable registry `warn`s (a network fault is not an auth fault). **Public npm not hijacked** fails when `~/.npmrc` carries an unscoped `registry=<codeartifact>` line, which makes CodeArtifact your default registry — one `mesh registry login` fixes both. Exit 0 iff all pass; re-run any time. `--fix` applies developer-scope fixes (registry token, skills sync); operator actions stay remediations — and `--profile <p>` is the SSO profile `--fix` logs into CodeArtifact with, echoed back in the `fix:` command each check prints so the advertised command is the one that runs. | `app-tenant`: `--tenant <name>`, `--context <ctx>` (default `local`), `--hub-url <url>`, `--fix`, `--profile <sso>`, `--json` |
+| `mesh skills` | `sync` | Agent-skill distribution (D1/D2): installs the base building-with-Mesh skills into the repo's `.claude/skills/mesh-*/` (managed-marker files) and wires TanStack-Intent discovery for the pattern skills shipping inside `@mesh-tech/*` packages (`.intent/hooks/` gate + `.claude/settings.json` SessionStart hook + AGENTS.md fence — the PR #2356 mechanism, vendored). Idempotent; runs automatically after `mesh create-app`. | `sync`: `--check` (CI/doctor: exit 1 when missing/stale), `--root <path>` |
+| `mesh docs` | `build`, `portal`, `cli-reference` | `build` builds/validates an **app's** OpenAPI specs from `docs/docs.config.json` (file copy or SymXchange generation). `start`/`stop`/`list` are the simple front door: `start` serves the docs on loopback — DETACHED in a tmux session named `mesh-docs` by default (prints the bare URL once live; `stop` kills the session; `--foreground` or any non-TTY runs in the foreground) — serving the working tree in a mesh-platform checkout, or the published `@mesh-tech/docs` artifact fetched from the role-gated CodeArtifact registry anywhere else (docs version == the @mesh-tech/* baseline it describes; `-v` pins, default latest; cached under `~/.cache/mesh/docs/`). `list` shows the published docs versions. `portal` assembles the **Mesh developer portal** (docs.meshtech.io) from every `docs.json`-opted-in doc root in the repo — a directory publishes its markdown iff it holds a `docs.json`; route/title/order/nav derive from the tree and each file, so adding a doc is adding one file — then hands the assembled tree to Zudoku (`apps/docs/`): default runs `zudoku build`, `--serve` runs `zudoku dev`, `--assemble-only`/`-o` stop after assembly. Links between published files are rewritten to routes; links to unpublished repo files become blob links. Reserved directory names (`plans/`, `designs/`, `incidents/`, … the frozen list in `src/docs/schema.ts`) are excluded at any depth. `cli-reference` regenerates `docs/portal/generated/cli-reference.md` from THIS command tree, so it can't document a flag the binary lacks. `portal --check` is the CI gate (`pnpm check:docs-portal`): docs.json schema validation, reserved-segment fail-close, broken links, and CLI-reference staleness; `--diff-base <ref>` prints the publish-set diff for PR job summaries. Hidden commands and `--version` are excluded from the reference. | `build`: `-c/--config <path>` (default `docs/docs.config.json`); `portal`: `-o/--out <dir>`, `--assemble-only`, `--serve`, `-p/--port <n>` (default `3000`), `--check`, `--print-manifest`, `--diff-base <ref>`, `--manifest-out <path>`; `cli-reference`: `-o/--out <path>`, `--check`; `start`: `-v/--version <v>` (default: latest), `-p/--port <n>` (default `4400`; `0` is foreground-only), `--dev` (foreground HMR), `--foreground`; `stop`: no flags; `list`: no flags |
+| `mesh stack` | `init`, `rm <name>` | `init` creates a personal dev stack `dev-{github-user}`, copying base-stack config, setting `mesh:deploy: false`, inheriting KMS secrets provider; `--worktree` appends the git-worktree token (`dev-{user}-{token}`) so concurrent worktrees deploy to **distinct** stacks (SSM paths, Temporal namespace, Nexus endpoint all derive from the stack name → one discriminator isolates all three; no-op on the primary checkout). `rm <name>` removes a personal stack (backend state + local config), credentialed. Both assume the deployer role — no raw `pulumi` / manual creds needed. | `init`: `--from <stack>`, `--name <stack>`, `--worktree`; `rm`: `--yes` |
+| `mesh tenant` | `add <name>`, `list` | Register/inspect app tenants on a platform stack. Run from the **platform layer** of a tenant platform repo (e.g. `mesh-sandbox/platform`). `add` inserts the tenant under `mesh:tenants` in `Pulumi.<stack>.yaml` via a comment-preserving YAML round-trip (untouched lines don't reformat), refuses a tenant that is already declared (an existing entry may carry fields a re-add would drop), derives the `{name}-{env}` subdomain from the stack name (echoed in the success line), and guards against running on the core layer or an app dir; it then prints the deploy + verify sequence — `mesh deploy up` is what makes the registration live. `list` prints what the stack config declares, so "is it registered?" is answerable without opening YAML (warns when the project doesn't look like a platform layer, so an empty result isn't mistaken for "no tenants"). | `add`: `--display-name <name>`, `--subdomain <sub>`, `--zitadel-org-id <id>`, `--stack <stack>`, `--json`; `list`: `--stack <stack>`, `--json` |
+| `mesh tunnel [group]` | `external <name>` | SSM port-forward to platform services. Groups: `dev` (temporal+db), `temporal`. **`external <name>`** tunnels to a *registered* `ExternalService`: host/port are read from its credential secret (`mesh/{app-tenant}/{app-stage}/external/{name}`) — the same values deployed apps resolve at runtime — so anything the bastion can reach is tunnelable with no per-service CLI entry and no bastion services-map change. `-t/-e` are **optional everywhere** — they fall back to the same Pulumi/SST context detection `mesh dev` uses, and `AWS_REGION`/`AWS_PROFILE` default from the nearest Pulumi config + the `{tenant}-{env}` profile convention (region falls back to the effective profile's own `region` — the `[default]` profile when none was resolved — before the platform default us-east-2). | root: `-t/--tenant`, `-e/--env`, `-l/--list`, `-s/--services <csv\|group>`, `--db-port`, `--temporal-ui-port`, `--temporal-frontend-port`; `external`: `-p/--port` (default: the remote port), `-k/--key <key>` (multi-instance `credentials.keyedBy` externals), `--app-tenant`/`--app-stage` (credential axis; default to `-t`/`-e`) |
+| `mesh secrets` | `exec <command...>`, `set [service]`, `migrate-config` | Manage external-service creds in Secrets Manager. `exec` injects secrets as env; `set` reads field schema from SSM and prompts (or `--json`). | `set`: `--key <id>` (multi-instance), `--all`, `--json <str>`, `--stage`, `--region`; `migrate-config`: `--force`, `--dry-run`, `--stage`, `--region` |
+| `mesh artifacts` | `get <ref>` | Download workflow artifact files from an AI-agent conversation. Ref `<conversationId>:<artifactId>` (artifactId defaults to `workflow-artifact`). | `-o/--output <dir>`, `--target <name>`, `--api-url <url>`, `--context <ctx>` (default `mesh.dev`) |
+| `mesh conversations` (alias `conv`) | `list`, `show <id>`, `artifacts <id>` | Read a deployed Mesh agent's conversations: list the caller's conversations, render a transcript, or list a conversation's artifacts. Resolves against the same `agent-targets` registry the MCP `agent_*` tools use. | all three: `--target <name>`, `--api-url <url>` (overrides `--target`), `--context <ctx>` (used with `--api-url`, default `mesh.dev`), `--json` (default when stdout isn't a TTY) |
+| `mesh vpn` | `connect <context>`, `disconnect`, `status`, `tunnel <up\|down\|status>`, `api-key`, `pre-auth-key`, `users` | Headscale VPN mgmt via Tailscale + kubectl. **`connect` now defaults to the userspace `tailscaled`** (brew formula, NOT the GUI Tailscale.app) — the same daemon `mesh dev --transport tailscale` / `mesh vpn tunnel` use, so it **runs headless / under the sandbox** and exposes a local SOCKS5 proxy (route a tool via `ALL_PROXY=socks5://127.0.0.1:<port>`). It relays a one-time browser-register URL for Zitadel auth. `--system` opts into the whole-machine GUI Tailscale.app (system TUN) — needs the app installed and **cannot run headless/sandboxed** (Sparkle.framework abort). For auto-forwarded VPC services (Temporal/RDS) prefer **`mesh vpn tunnel up`** or `mesh dev`. `tunnel status` reports runner **ownership** (`Runner: owned (verified)` vs `NOT OWNED (<reason>)` — a port answering a dial is not proof it's mesh's, MESH-2407); `--json` adds `owned` (bool) + `ownership` (reason string). Admin subcommands `exec` into the `headscale-0` pod. | root: `-t/--tenant` (default `mesh`), `-e/--env` (default `dev`), `-n/--namespace`; `connect`/`disconnect`: `--system`; `tunnel up`: `--context <ctx>`; `tunnel down`: `--stop` (stop daemon, keep login), `--logout`; `tunnel status`: `--json`; `pre-auth-key`: `-u/--user` (**required**), `--expiration <24h>`, `--reusable`, `--ephemeral` |
+| `mesh workflow` | `extract-ir <path>` | Parse Temporal workflow TS source → WorkflowIR graph (nodes+edges). Prints JSON or uploads to S3. | `--app <name>`, `--upload <bucket>` (both required together for S3) |
+| `mesh temporal` | `describe <wfId> [runId]`, `history <wfId> [runId]`, `recover-conversation <wfId> [runId]`, `capture-history <wfId> [runId]` | Inspect Temporal workflows for the current app/stack; reconstruct an agent conversation transcript from durable history when the worker can't replay it; capture a full history to a local replay fixture. | shared: `--stack`, `--address`, `--namespace`; `history`: `-n/--limit <200>`, `-f/--follow`, `--no-compact`, `-p/--show-payloads` (decrypts via `TEMPORAL_ENCODING_KEY` from the K8s secret); `recover-conversation`: `--out <path>`, `--json`, `--snapshot` (structured `{conversationId,messages,artifacts,focus}` blob); `capture-history`: `--out <path>` (default `~/.mesh/replay-histories/<wfId>.json`, do not commit) | <!-- skill-lint-disable-next-line — row documents the mesh-owned kubectl wrappers; the backticked `aws eks get-token` describes what the CLI runs internally, not an operator step -->
+| `mesh kubectl` / `mesh logs` / `mesh exec` | `kubectl [args…]`, `logs [service\|deployment/x\|k=v]`, `exec <service> -- <cmd>` | Cluster access for a **deployed** app — debug CrashLoops/logs without broader creds. Assumes the app's `mesh:deployerRole`, builds a session kubeconfig from the platform `eks` SSM export (`aws eks get-token` — no `eks:DescribeCluster` / `~/.kube/config` needed), shells out to kubectl. Defaults the namespace to the app's own (deployer RBAC is tenant-namespace-scoped). **Use `--stack <name>` to target the deployed stack (e.g. `dev`, not `dev-local`).** | `--stack <name>`; `logs`: `-f/--follow`, `--tail <200>`, `-c/--container`, `--previous`; `exec`: `-c/--container` |
+
+## Core workflows
+
+### 1. Onboard: auth + install dependencies
+
+```bash
+mesh login mesh.dev          # OIDC; auto-uses device flow in remote/headless envs
+mesh login mesh.dev --device # FORCE device flow (browser callback times out over SSH/tailscale)
+mesh registry login mesh.dev # registry token via the Zitadel broker (no AWS needed) + project .npmrc scope
+pnpm install                 # now resolves @mesh-tech/* from CodeArtifact
+```
+
+### 1b. Run the platform fully locally (no cloud)
+
+```bash
+mesh start                   # docker compose up + health waits + first-boot seed
+                             # (seeds: tenant registry, hub DB, Temporal ns local-dev,
+                             #  Zitadel org/CLI app/test users, artifacts bucket;
+                             #  reconciles Zitadel app tenants into the Hub registry)
+# → open http://localhost:9000 — the Hub, your local operations dashboard
+#   (sign in via the local Zitadel: admin@local.mesh or dev@local.mesh / LocalDev1!)
+mesh login local             # PKCE against the seeded Zitadel (dev@local.mesh / LocalDev1!)
+mesh status                  # per-component health, endpoints, ports (--json for agents)
+cd <your app> && mesh dev    # local mode auto-wires services to this stack:
+                             # per-app Temporal namespace {tenant}-dev-{app}, auth
+                             # auto-provisioning, self-registration in the Hub, and
+                             # service logs shipped to Loki (Hub logs view)
+mesh stop --destroy          # tear down incl. volumes (resets seeds)
+```
+
+**The local platform is a machine-wide singleton** — one compose project
+(`mesh-local`), one set of host ports — shared by every checkout and project
+on the machine. App/tenant work composes safely on top of it: `mesh dev
+--local` provisions only tenant-scoped state (Zitadel org, Temporal
+namespace, registry/secret prefixes, per-app mock compose projects), so
+concurrent projects coexist on one running stack. Only `mesh start`/`mesh
+stop` mutate the shared containers, and both refuse to act on a stack a
+DIFFERENT checkout started (compose config drift would recreate shared
+containers out from under the other project) — `mesh start --takeover` /
+`mesh stop --force` override deliberately.
+Device flow prints a URL + short code (e.g. `identity.dev.mesh-platform.trabian.com/device?user_code=XXXX-XXXX`);
+open it, enter the code, wait for `✓ Logged in as …`. Over SSH always use `--device` — the
+browser-callback flow times out. After login, `mesh dev`/`mesh deploy` resolve AWS creds via a
+self-refreshing credential_process (the deployer role), so no separate `--export` eval is needed for those.
+
+### 2. Scaffold and run an app locally
+
+```bash
+mesh create-app --tenant acme --name billing --primitives service,database,temporal
+cd tenants/acme/apps/billing && pnpm install
+mesh stack init              # personal dev-{github-user} stack (deploy:false)
+mesh deploy up --yes         # pulumi up via mesh:deployerRole
+mesh dev                     # tunnels + secrets + tmux (needs VPN for VPC access)
+mesh dev logs api            # tail one service;  mesh dev --kill to stop
+```
+
+### 2b. Watch your dev-local stack in the Hub (`mesh hub dev`)
+
+```bash
+cd <your app repo>           # a repo with a running `mesh dev` session
+mesh hub dev                 # → local current-code Hub at http://localhost:9000
+                             #   scoped to this session's tenant: workflow types with
+                             #   live run counts, execution timelines incl. child slices
+mesh hub dev --print-env     # inspect the assembled env without launching
+mesh hub dev --kill          # tear down (tmux session mesh-hub-dev)
+```
+
+Zero hand-set env vars: the command reads the `mesh dev` session's state file
+and tmux environment — Temporal tunnel address, AWS scratch profile, dev-user
+identity, per-session token-server — and derives the Hub scope
+(`HUB_TENANT`/`HUB_SCOPE_ENV`/`HUB_SCOPE_TENANTS`) from the session's platform
+context. Needs a mesh-platform checkout for the Hub's source (auto-detected
+when you're inside one; otherwise `--platform-dir` / `MESH_PLATFORM_DIR`).
+An empty tenant scope is a loud error, never a blank Hub. On the full-local
+platform (`mesh start`) use its built-in containerized Hub instead.
+
+### 3. Concurrent `mesh dev` across git worktrees and sibling apps (auto-isolation)
+
+Run the **same plain `mesh dev`** from each worktree's app dir — there is nothing special to
+configure. `mesh dev` derives a deterministic token from the worktree path and threads it through
+the tmux session name, the tmpdir session-state + env-file dir and the Temporal task-queue suffix, so
+two worktrees don't kill each other's session — as long as their directory basenames differ, since the
+session name carries the worktree's sanitized basename, not the hash. The reserved **service-port
+block is derived from (worktree, app)**, not the worktree alone — a repo can hold several apps whose
+sessions run concurrently (e.g. `scu-mesh-apps`' `plaid-token-manager` + `plaid-reporting`), and one
+block per worktree handed both the same ports.
+
+```bash
+# worktree A
+cd .worktrees/feature-a/tests/tenants/acme/apps/demo-agent
+mesh dev --dry-run          # preview: session name, port block, state/env paths, task queue
+mesh dev                    # launch (attaches tmux; --headless to skip)
+
+# worktree B — SAME command, different shell; auto-isolated
+cd .worktrees/feature-b/tests/tenants/acme/apps/demo-agent
+mesh dev
+
+# sibling app in worktree A — same worktree, still its own port block
+cd .worktrees/feature-a/tests/tenants/acme/apps/silverlake-demo
+mesh dev
+```
+
+- The **primary checkout** keeps its historical identity (`${project}-dev` session, the app's
+  preferred ports). Only **linked worktrees** get an offset session name + a port block in the 40000+
+  range. `mesh dev --dry-run` labels which you are (`primary checkout` vs `linked worktree (block N)`).
+- **Port blocks are disjoint by default, not by construction.** The block is a hash bucketed into 63
+  slots, so two `(worktree, app)` pairs *can* land on the same block; the in-block free-port probe and
+  the ephemeral-port fallback are the backstop when they do — but that backstop is the same
+  check-then-bind probe that raced two still-booting sessions onto one port before #2889, so treat a
+  shared block as a live hazard, not a handled case. Two consequences worth knowing before you
+  debug a collision as a regression:
+  - Sibling apps in the **primary checkout** are deliberately excluded — they keep preferred-port
+    semantics (block 0) and rely on that probe, so run them from linked worktrees if you need them
+    isolated. This is the layout most tenant app repos use day to day.
+  - App-scoping raises the number of hashed entities from *#worktrees* to *#worktrees × #apps*, so
+    bucket collisions get likelier as you add apps.
+
+  A deterministic, collision-free allocator that also folds primary checkouts back in is tracked as
+  **MESH-2375**.
+- **Do NOT force a shared `--session`** across worktrees — that defeats the auto-isolation and
+  reintroduces the collision. Omit `--session` and let it derive per worktree.
+- `mesh dev --kill` / `--status` act only on the current worktree's session.
+- If the stack was last deployed from a *different* worktree, `mesh dev` **refuses** to launch a service
+  whose source resolves outside the current worktree (guards against silently running stale code) — re-run
+  `mesh deploy up` in this worktree.
+- **Deploying isolated stacks per worktree?** The `mesh dev` isolation above is local-only. To
+  `mesh deploy up` a `deploy:false` personal stack from several worktrees at once, give each worktree
+  its own stack with `mesh stack init --worktree` — otherwise they collide on SSM export paths
+  (`ParameterAlreadyExists`) and the Temporal namespace (both derive from the stack name).
+  `mesh deploy up`/`destroy` **warns** when it sees a shared (non-worktree) stack name in a linked worktree.
+
+### 4. Deploy (pulumi passthrough)
+
+```bash
+mesh deploy preview
+mesh deploy up --yes
+mesh deploy stack output dev --json
+mesh deploy destroy
+# Requires `mesh:deployerRole` in Pulumi.<stack>.yaml:
+#   pulumi config set mesh:deployerRole arn:aws:iam::<acct>:role/<tenant>-<env>-apps-deployer
+```
+
+`<env>` is the **platform environment** (`dev`, `prod`), which is not always your
+Pulumi stack name — a stack called `dev-jane` still deploys against the `dev`
+platform and so assumes `…-dev-apps-deployer`. The distinction is load-bearing
+beyond the role name: the deployer's KMS-alias grant is scoped to
+`alias/{tenant}-{env}-*`, so an app that creates an alias has to prefix it the
+same way. See [Naming resources so the deployer can create them](https://github.com/mesh-tech/mesh-platform/blob/main/libs/infra-components/docs/concepts/deploying.md#naming-resources-so-the-deployer-can-create-them).
+
+### 5. Database access
+
+```bash
+mesh db exec --ssl=require -- npx prisma migrate dev --name init
+mesh db psql                       # interactive session through the bastion
+eval "$(mesh db env)"              # load DATABASE_URL / DB_* into the shell
+mesh db exec --secret <arn> -- node seed.js   # direct mode, skips SSM discovery
+```
+
+### 6. External secrets
+
+```bash
+mesh secrets set external/symitar                         # interactive (schema from SSM)
+mesh secrets set external/symitar --json '{"baseUrl":"…"}'
+mesh secrets set external/symitar --key 12345 --json '{…}'  # multi-instance (key = FI id)
+mesh secrets exec -- node ./script.js                     # secrets injected as env
+```
+
+### 7. Read a remote agent's conversation context
+
+```bash
+mesh conversations list --target fub          # discover conversation ids
+mesh conversations show <id> --target fub     # transcript
+mesh conversations artifacts <id> --target fub
+mesh artifacts get <id>:<artifactId> --target fub
+```
+
+`--target` resolves the same `~/.config/mesh/agent-targets.json` registry the
+MCP `agent_*` tools use; see the dedicated
+`libs/mesh-cli/skills/pull-remote-agent-context` skill for the full recipe
+(registry format, auth model, the `conversation_unavailable` → `mesh temporal
+recover-conversation` break-glass path, and the MCP-vs-CLI relationship).
+
+### 8. Relaunch safety — don't strand live conversations
+
+For a **code-only** change, prefer a scoped `mesh dev restart <service>` over a full
+`mesh dev` relaunch — it's faster and touches only that service. Restart the
+**worker** only when you actually changed worker/workflow code.
+
+Both a relaunch and a `restart <worker>` recreate the Temporal worker onto current
+code. If the **workflow** source (`agent-sdk` / `workflow-interpreter` /
+`agent-contracts`) changed since the session started, in-flight conversations replay
+against the new code — a replay-incompatible change **strands** them. `mesh dev` now
+fingerprints that source at launch and **warns + refuses (use `--force`)** when it
+changed on a relaunch/worker-restart. The fix is not `--force`: keep the change
+replay-compatible — gate it with `wf.patched()` and regenerate the replay goldens
+(see the `temporal-workflow-safety` skill + the CI replay gate). Restarting unchanged
+code, or a non-worker service (ui/api), never warns.
+
+For **config/deploy** changes (not code): `mesh dev restart <svc> --refresh-env`
+re-reads stack/SSM output; if the *topology* changed, run `mesh deploy up` first
+(`mesh dev doctor` flags config staleness).
+
+## Config / environment requirements
+
+| Need | Source |
+|---|---|
+| Tenant / env / stage | flags (`-t/-e`, `--stage`) → `MESH_TENANT`/`MESH_STAGE`/`SST_STAGE` env → Pulumi config in cwd/parents → defaults (`mesh`/`dev`) |
+| AWS creds | ambient env → cached Zitadel JWT (`mesh login`) → AWS SSO profile; region from `AWS_REGION`/`AWS_DEFAULT_REGION` else `us-east-2` |
+| Login config | `~/.config/mesh/config.json`; creds cache `~/.config/mesh/credentials.json` |
+| Deploy role | `mesh:deployerRole` (and optional `mesh:adminDeployerRole`) in `Pulumi.<stack>.yaml` |
+| Login role for `--export` | `--role` → `MESH_AWS_ROLE` → cached `defaultRole` for the context |
+| Registry | `@mesh-tech` scope; CodeArtifact token written to `~/.npmrc` (12h TTL) |
+| `vpn`, `temporal --show-payloads` | a working `kubectl` kubeconfig for the target EKS cluster |
+| Temporal client / S3 upload | optional deps `@temporalio/client`, `@aws-sdk/client-s3` (lazy-loaded) |
+
+## Failure modes / gotchas
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `No Pulumi.yaml found` | run outside a Pulumi app dir | cd into the app (deploy/stack/temporal use `findAppRoot`) |
+| `No mesh:deployerRole found` | stack config missing the role | `mesh deploy config set mesh:deployerRole <arn>` |
+| `Could not determine stack` (deploy) | no selected stack & no `--stack` | `mesh deploy stack select <name>` or pass `--stack` |
+| `artifacts get` → ECONNREFUSED / 404 | agent API down or convo expired | start API (`mesh dev`) or pass `--api-url`; restart API after code changes |
+| `login` config not found | context not discoverable | a known first-party short context (`mesh.dev`) resolves anonymously — no AWS needed. Otherwise use the platform's full domain (`mesh login dev.<tenant>.meshtech.io`). Only if neither works: ensure AWS SSO is active + the platform is deployed (SSM `cliClientId`), or add config to `~/.config/mesh/config.json` |
+| `vpn`/`temporal --show-payloads` fail | kubeconfig not set / expired creds | refresh the tenant cluster kubeconfig (`mesh vpn connect <ctx>` wires it; kubeconfig absorption into `mesh deploy` is planned) then retry | <!-- skill-lint-disable-next-line — next row's backticked `kubectl …` is a quoted ERROR SYMPTOM, not an operator command; the row's fix column already routes through mesh dev -->|
+| `kubectl could not read a kubeconfig … macOS blocks it` (from `mesh kubectl`/`logs`/`exec`/`temporal` in a bare shell) | macOS Full-Disk-Access blocks reading `~/.kube` from a shell outside the `mesh dev` session | run the command **inside** the `mesh dev` tmux window, or `export KUBECONFIG=$TMPDIR/mesh-dev-sessions/<session>.kubeconfig` first |
+| `mesh temporal …` won't authenticate against a **deployed** Temporal | passing `--address` (or `TEMPORAL_ADDRESS`) skips the app/stack resolution that mints a Zitadel **Bearer** — auth falls back to ambient env | omit `--address` and run from the app dir so `mesh temporal` resolves the authenticated frontend over the tunnel; use `--address` only for a local/unauthenticated Temporal |
+| `mesh dev` chose "VPN direct" then api/worker spin on `ECONNREFUSED …:27233` | tailnet-blind VPN *presence* check picked direct routing the mesh VPC doesn't actually serve | **no manual fallback needed** — current `mesh dev` TCP-probes the frontend and auto-falls back to SSM tunnels (MESH-2016); if still stuck, force `--transport ssm` (or `--no-vpn`) |
+| `mesh dev` / `mesh vpn tunnel up` → `Tunnel port(s) for tenant '<t>' are bound by a process mesh does not own` | a foreign or orphaned listener holds a forwarder port; mesh refuses to adopt it rather than route traffic to the wrong upstream (MESH-2407) | `mesh vpn -t <t> tunnel down --stop` to reap mesh-owned runners; if the port is still held, `lsof -nP -iTCP:<port> -sTCP:LISTEN` and stop that process (if it names another mesh runner, it belongs to a different tenant — tear that one down). `mesh vpn -t <t> tunnel status` shows `Runner: owned (verified)` when healthy |
+| `mesh vpn tunnel down`/`up` or `mesh dev` → `Refusing to signal <the tunnel supervisor pid \| the tunnel runner process group \| the VPN daemon pid> recorded for tenant '<t>' — …`, or `Refusing to signal a tunnel runner pid discovered from 'ps' for tenant '<t>' — …` | the pid is corrupt or stale — from `tunnel-state.json` / `runner.json` / `daemon.json` (truncated write, hand edit, older build) for the first three, or from the live `ps` argv scan for the fourth. POSIX `kill(2)` overloads the pid argument and teardown negates before signalling, so a `1` there would SIGTERM every process you can signal — mesh refuses it instead | usually **nothing** — it is a warning, the rest of the teardown still runs and the state file is cleared, so re-running the command is clean. If it recurs: **when the message names a file**, `rm` that exact path; **the `discovered from 'ps'` variant names none** — there is no state file to clear, so just re-run. Either way finish with `mesh vpn -t <t> tunnel status` to confirm |
+| `mesh kubectl`/`logs`/`exec` → `Could not resolve the EKS cluster … Parameter tried: /mesh-platform/<name>/<env>/core/eks`; `mesh dev` → `EKS cluster resolve failed (/mesh-platform/<name>/<env>/core/eks): …` | the platform segment of the SSM path is wrong (or the platform core layer isn't deployed) — cluster data lives under the app's HUB platform name, and an `AccessDeniedException` here usually means the wrong path, not missing SSM permissions | check `mesh:platform` in the app's `Pulumi.<stack>.yaml` (its `name` is the hub, e.g. `trabian`) and log into that platform's context (`mesh login <platform>.<env>`) |
+| 401/403 installing `@mesh-tech/*` | stale CodeArtifact token | `mesh registry login` (or `--ci` in CI) |
+| 401 installing a **public** package (`npm view lodash version` fails) | an unscoped `registry=<codeartifact>` line in `~/.npmrc` makes CodeArtifact the DEFAULT registry, so public packages resolve through it and 401 at the 12h token expiry | `mesh registry login` — it removes the line after backing `~/.npmrc` up; confirm with `npm config get registry` (expect `https://registry.npmjs.org/`) |
+| `--export` prints nothing | no role resolved | pass `--role <arn>` or set `MESH_AWS_ROLE` |
+| `--export` / `EPERM … ~/.aws` in a sandbox | `~/.aws` not writable | it now auto-falls back to a mesh-managed config (`~/.config/mesh/aws-config`) and also exports `AWS_CONFIG_FILE`; or prefer `mesh deploy <op>` (no shell profile needed) |
+| `workflow extract-ir` no S3 upload | only one of `--app`/`--upload` given | pass both, or omit both to print JSON |
+
+## Programmatic API
+
+`@mesh-tech/mesh-cli` re-exports its utils (`src/utils/index.ts`):
+
+```ts
+import { detectContext, getPlatformBastionInfo } from "@mesh-tech/mesh-cli";
+const ctx = detectContext();                                  // { tenant, stage, ... }
+const bastion = await getPlatformBastionInfo(ctx.tenant, ctx.platformEnv);
+```
+
+Exports include `detectContext`, `getPlatformBastionInfo` (bastion), credentials,
+pulumi, vpn, and log helpers.
+
+## See also
+
+- `@mesh-tech/app-kit#core` — app-kit bundles this CLI; consumers usually invoke it as `pnpm mesh <cmd>`
+- `@mesh-tech/credentials#core` — credential resolution the auth/deploy flows build on

package/skills/pull-remote-agent-context/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: pull-remote-agent-context
+description: >
+  Read a deployed Mesh agent's conversation history, artifacts, or workflow
+  design from the `mesh` CLI. Activate when asked to pull/read/inspect a
+  hosted agent's conversation transcript, list its conversations, fetch a
+  workflow artifact/design it produced, or when the `agent_*` MCP tools
+  (agent_list_conversations, agent_check_conversation, agent_get_artifacts,
+  agent_get_workflow_design) are unavailable and the same read needs to
+  happen via the CLI instead.
+metadata:
+  version: '0.1'
+  category: 'tooling'
+  type: intent
+---
+
+# Pull a deployed agent's conversation context
+
+`mesh conversations` (alias `mesh conv`) reads a deployed Mesh agent's
+conversations directly from its agent-api, over the same read surface the
+`agent_*` MCP tools use. This is the CLI-native path when those MCP tools
+aren't wired up, or when you're already in a shell.
+
+## The recipe
+
+```bash
+mesh conversations list --target <name>              # discover conversation ids
+mesh conversations show <id> --target <name>          # render the transcript
+mesh conversations artifacts <id> --target <name>      # list its artifacts
+mesh artifacts get <id>:<artifactId> --target <name>   # download artifact files
+```
+
+## One-shot: `mesh conversations pull` (recommended)
+
+To pull a whole conversation + everything it produced into a session bundle in
+one command — the fast path when you're feeding a workflow-builder conversation
+into a coding session:
+
+```bash
+mesh conversations pull <id> --target <name> -o <dir>
+```
+
+It writes:
+
+```
+<dir>/
+  index.json            # conversation meta, artifact map, saveLocations, subagent tree, warnings[]
+  conversation.md       # the transcript (intent)
+  designs/<slug>/
+    design-ir.json      # the LIVE design IR (authoritative; resolved server-side)
+    manifest.json       # realized bindings (signals + service ops) — from the design's vcs folder
+    README.md           # + any other docs the design's folder holds, verbatim
+    design-ir.saved.json  # ONLY if the saved IR drifted from live (a warning is emitted)
+  ui/<slug>.json        # agent-built UI specs
+  subagents/<childId>.md  # recursive delegate transcripts (childId "/" → "__")
+```
+
+Key behaviors:
+
+- **Designs come from the agent-api**, which resolves the latest IR itself — no
+  draft-branch guessing for the IR.
+- **Each design also pulls its OWN vcs folder verbatim** (a scoped shallow clone
+  of just that design's repo, resolving the `drafts/*` ref that carries it), so
+  docs/notes beyond the IR ride along. `--no-vcs` skips this (IR-only).
+- **Everything else the conversation referenced is cataloged, never cloned** —
+  any tenant's knowledge-base / context repo (a `resource: vcs` drive-ref,
+  whatever it's named) and any other artifact kind appears in
+  `index.json.references[]` with a ready-to-run `pullHint`, but its content is
+  not pulled. Pull a **specific** doc on demand (one path, not the whole repo)
+  with `mesh vcs get <repo> <path> --target <name>` (CLI) or `agent_get_repo_doc`
+  (MCP) — browse `conversation.md` to see which docs matter.
+- **Subagents recurse by default** (cycle-guarded); `--no-recursive` for direct
+  delegates only.
+- **Best-effort**: nothing aborts the pull — per-unit failures land in
+  `index.json.warnings[]`.
+
+Reach for the granular verbs below when you want just the transcript, just the
+artifact list, or a single artifact's files.
+
+`list`/`show`/`artifacts` all accept the same `--target <name>` /
+`--api-url <url>` / `--context <ctx>` / `--json` options (`mesh artifacts get`
+takes `--target`/`--api-url`/`--context` plus `-o/--output <dir>`, no
+`--json` — it always writes files). Start with `list` unless you already have
+a conversation id.
+
+## The shared registry (`--target`)
+
+`--target <name>` resolves against `~/.config/mesh/agent-targets.json`
+(override with env `MESH_AGENT_TARGETS`) — **the exact same registry and
+names the MCP `agent_*` tools use** (`@mesh-tech/agent-targets`, consumed by
+both `mesh-cli` and `@mesh-tech/mesh-mcp`). `--target fub` on the CLI and
+`target: "fub"` on `agent_send_message` hit the same origin with the same
+identity. A registry entry looks like:
+
+```json
+{
+  "defaultTarget": "hub",
+  "targets": {
+    "fub": {
+      "apiBaseUrl": "https://...",
+      "conversationPathPrefix": "/c",
+      "tenant": "fub",
+      "env": "dev",
+      "loginContext": "mesh.dev"
+    }
+  }
+}
+```
+
+**`mesh agent-targets add/refresh/list` (the SSM-backed generator) is NOT
+shipped yet.** Do not tell a user or agent to run it. Until it exists:
+- If the registry file already has the target you need, just pass
+  `--target <name>`.
+- If it doesn't (or the file doesn't exist), either hand-author an entry in
+  `~/.config/mesh/agent-targets.json` (schema above; see
+  `packages/agent-remote/agent-targets.example.json` for a fuller example),
+  or skip the registry entirely and pass `--api-url <url>` (+ `--context <ctx>`,
+  default `mesh.dev`) ad hoc — no registry lookup happens in that case.
+
+Resolution precedence: `--api-url` (if given) > `--target` (if given,
+resolved from the registry) > the registry's `defaultTarget` > the
+`AGENT_API_URL`/`API_URL` env vars > `http://localhost:8787`. An unknown
+`--target` name errors listing the available names.
+
+## Auth model
+
+Auth is a Zitadel bearer, the same one `mesh login <context>` already caches
+— no AWS role needed just to read. Each registry entry's `loginContext`
+picks which cached login to use (default `mesh.dev`); with `--api-url`,
+pass `--context <ctx>` to pick it explicitly. One `mesh login mesh.dev`
+(device flow works headless) reaches any deployed agent through its
+oauth2-proxy. A 401/403/redirect from an agent-api call means auth didn't
+reach it — re-run `mesh login <that context>`.
+
+## MCP tools unavailable? Same registry, direct CLI path
+
+When the `agent_*` MCP tools (`agent_list_conversations`,
+`agent_check_conversation`, `agent_get_artifacts`,
+`agent_get_workflow_design`, `agent_list_targets`, ...) aren't reachable —
+no MCP server configured, or you're a plain shell/CLI agent — `mesh
+conversations` reaches the identical agent-api directly, with the same
+`--target` name and the same login. Nothing is lost by going CLI-only:
+list → show → artifacts covers list/read/artifacts; `mesh artifacts get`
+covers file export; workflow-design (the MCP's `agent_get_workflow_design`)
+has no direct CLI verb yet — get it via `mesh conversations artifacts <id>`
+(artifact index) plus `mesh artifacts get <id>:<artifactId>` for the IR/files.
+
+## Transcript break-glass: `conversation_unavailable`
+
+`mesh conversations show <id>` reads the **live** worker (fast, decoded).
+If the worker can no longer replay that workflow (code drift), it 503s with
+`conversation_unavailable` and the CLI's error message already includes the
+next step:
+
+```bash
+mesh temporal recover-conversation <id>
+```
+
+This reconstructs the transcript from durable Temporal history instead
+(needs the Temporal encoding key; see the `core` skill's `temporal` row).
+Add `--snapshot` for a structured, store-ready `{ messages, artifacts,
+focus }` blob instead of a markdown transcript.
+
+## Output
+
+- Piped or redirected (non-TTY), or `--json` passed: compact JSON, one line,
+  field names mirroring the agent-api payload — parse this.
+- A TTY without `--json`: an aligned table (`list`: double-space-padded
+  columns, `ID  TITLE  UPDATED` — NOT `·`-separated; `artifacts`:
+  `ARTIFACT-ID · KIND · TITLE` + a ready-to-copy `mesh artifacts
+  get <id>:<artifactId>` download line; `show`: `role: content` blocks with
+  `tool-calls:`/`artifacts:` notes).
+
+An agent scripting this should just pipe (`mesh conversations list --target
+fub | jq ...`) rather than pass `--json` — output auto-detects non-TTY.
+
+## Errors, decoded
+
+| Symptom | Meaning | Fix |
+|---|---|---|
+| `auth did not reach the agent` | 401/403/redirect | `mesh login <loginContext>` (the target's, or `--context`) |
+| `conversation/artifact not found ... (<id>)` | 404, or not owned by this identity | `mesh conversations list --target <name>` to see valid ids |
+| `... conversation_unavailable ... try: mesh temporal recover-conversation <id>` | 503, worker can't replay | run the suggested `recover-conversation` |
+| `Unknown target "<name>". Available: ...` | `--target` not in the registry | pick a listed name, hand-author the entry, or use `--api-url` |
+| `No agent target given and no registry ...` | no `--target`/`--api-url` and no registry file | pass `--api-url <url>`, or hand-author `~/.config/mesh/agent-targets.json` |
+| `Registry at <path> is invalid: ...` | the JSON fails schema validation | fix the file, or pass `--api-url` |
+
+## See also
+
+- `libs/mesh-cli/skills/core/SKILL.md` — full `mesh` command reference,
+  including the `conversations`/`artifacts`/`temporal` rows this skill
+  builds on.
+- `packages/agent-remote/agent-targets.example.json` — a worked registry
+  file with `hub`/`fub`/`acme`/`local` entries.