@mesh-tech/mesh-cli 0.25.0 → 0.26.0

package/README.md

@@ -3,295 +3,123 @@
 `mesh` is the command-line entry point to the **Mesh platform** — Trabian's
 platform for building and running financial-services applications.
 
-It is the one `@mesh-tech/*` package published to public npm, so a clean laptop
-can install it with **no registry auth at all**, and the CLI then bootstraps
-everything else: your package-registry access, a new app, a full local stack,
-the documentation — and, only when you deploy somewhere, your platform login.
-
-This page is the getting-started path. Every command below also answers
-`--help`, and the complete reference ships inside the docs you start in
-[step 5](#5-read-the-full-docs).
-
----
-
-## Requirements
-
-| Need | Why |
-|---|---|
-| Node 22+ and `pnpm` (`corepack enable`) | Everything below |
-| Docker Desktop (or equivalent) | Only for `mesh start` / `mesh dev` |
-| A Mesh account | Issued by your Mesh contact; used by `mesh registry login` |
-| `registry` access on that account | The grant that unlocks `@mesh-tech/*` packages and the docs |
-
-**You do not need an AWS account** to install packages, run an app locally, or
-read the docs. AWS credentials only come into play if you *deploy*
-(`mesh deploy`, `mesh stack`).
-
-**You do not need a platform context either.** Package-registry access is one
-global identity, separate from any deployed platform. `mesh login <tenant>.<env>`
-is only for people who deploy to (or operate) a platform — see
-[Deploying to a platform](#deploying-to-a-platform).
-
----
-
-## 1. Install
+It is the one `@mesh-tech/*` package on public npm, so a clean laptop installs it
+with no registry auth at all, and the CLI bootstraps everything else: your
+package access, a new app, a full local stack, a whole platform in your own AWS
+account, and the docs.
 
 ```bash
 npm i -g @mesh-tech/mesh-cli
-mesh --version
-```
-
-`mesh --version` must print **0.12.0 or newer**. If it prints `0.1.x`, or the
-install fails with `E401`, see [Troubleshooting](#troubleshooting) — both are
-known, one-command fixes.
-
-## 2. Get registry access
-
-```bash
-mesh registry login
-mesh registry status
+mesh registry login     # package access — one browser trip
+mesh init               # everything else: it asks where your tenant runs
 ```
 
-One command, one browser round-trip. `mesh registry login` knows which registry
-it is talking to; it signs you in with your Mesh identity (a browser opens —
-add `--device` on a headless box or over SSH), asks the platform's
-registry-auth broker for a package-read token, and writes the `@mesh-tech`
-scope + token into your `~/.npmrc`. No AWS credential is created on your
-machine, and the token is short-lived by design (12 hours) — re-run
-`mesh registry login` when it expires (your sign-in is kept; no second browser
-trip).
+`mesh init` starts from nothing. "Nowhere yet — set up a new Mesh platform in my
+AWS account" is one of the answers it offers, and it asks for the handful of
+values that differ per install (region, public domain, Pulumi state bucket, AWS
+profile) with a default on each, so Enter is a valid answer.
 
-**If your account does not hold the grant yet**, the command tells you so and
-prints the access-request URL the platform returned (or names the admin to
-ask). Contact your Mesh contact to have **registry access granted to your
-user**, then run `mesh registry login` again — it re-mints your sign-in so the
-new role is in the token the broker sees. If it still says not authorized,
-start a fresh sign-in: `mesh registry logout && mesh registry login`.
-
-Everything after this point — installing `@mesh-tech/*` packages, scaffolding
-an app, and the local docs server — depends on this step. `mesh init` (next)
-runs it for you.
-
-## 3. Set up your tenant
-
-```bash
-mesh init
-```
-
-Run it in your `<tenant>-mesh-apps` clone, or in a brand-new empty folder — the
-wizard runs `git init` there for you. It asks which tenant this repo belongs to
-and where it runs — *local only* (`mesh start` / `mesh dev`) or *a deployed Mesh
-platform* — then checks your registry access (signing you in if step 2 was
-skipped), bootstraps the repo layout, installs the agent skills, and prints a
-summary with the next command.
-Every answer has a flag, so a headless run is one line:
-
-```bash
-mesh init --tenant acme --local --yes         # no prompts; --json for a machine-readable summary
-```
-
-## 4. Create an app
-
-```bash
-mesh create-app --tenant acme --name billing --primitives service,database,temporal
-```
-
-Scaffolds a new tenant application. `--primitives` selects what the app gets
-(`service`, `database`, `temporal`, `bucket`; default `service`). Run
-`mesh create-app --help` for the full option list, or omit the flags to be
-prompted. After `mesh init`, `--tenant` defaults to the tenant it recorded.
-
-`create-app` checks your registry access **before** it writes anything: with
-no usable token it stops and points at `mesh init` (add
-`--skip-registry-check` to scaffold offline anyway).
-
-### Run it locally
-
-Two commands, in this order:
-
-```bash
-mesh start          # the full-local Mesh platform — Docker only, no AWS, no VPN
-mesh dev            # from inside your app repo: run the app against it
-```
-
-- `mesh status` — component health, endpoints, and ports.
-- `mesh stop` — stop the local platform (`--destroy` also drops volumes).
-- `mesh dev doctor` — diagnoses a dev session (credentials, tunnels, config,
-  ports, Temporal) and names the fix.
-- `mesh dev logs <service>` / `mesh dev restart <service>` — per-service control.
-- `mesh dev --externals` — also realize the app's declared external services,
-  mocked from their OpenAPI spec, run locally, or pointed at the real vendor.
-
-`mesh start` brings up the platform's own services in Docker (the Hub included,
-when its images are available — `--no-hub` skips it); `mesh dev` runs *your*
-app's processes against them.
-
-Where things are once it is up (printed at the end of `mesh start` and first
-by `mesh status`):
-
-- **Hub** — <http://localhost:9000>. Sign in as `dev@local.mesh` / `LocalDev1!`.
-  The account is seeded; there is no need to register one.
-- **Mailbox** — <http://localhost:8025>. Every email the local platform sends
-  (sign-up confirmation, password reset) lands here; nothing leaves your machine.
-- `mesh login local` logs the CLI in against the same local identity.
-
-If `mesh start` stops on `already in use`, it names the container or process
-holding the port; stop that (or move it) and run `mesh start` again.
+---
 
-## 5. Read the full docs
+## Let your agent drive it
 
-The Mesh documentation is served **locally, by the CLI** — same access grant as
-the packages, no public site to keep in sync:
+The CLI is built to be driven by a coding agent. One command installs the agent
+skills — the full command reference, the conventions, and the runbooks — into
+your repo:
 
 ```bash
-mesh docs start     # → http://localhost:4400
-mesh docs stop
+mesh skills sync
 ```
 
-`mesh docs start` runs detached (in a tmux session named `mesh-docs`) and prints
-the URL once the server answers. Outside a `mesh-platform` checkout it fetches
-the published docs artifact from the role-gated registry, so it needs
-[step 2](#2-get-registry-access) to have succeeded. Useful flags:
+After that you do not have to learn the CLI: tell your agent *"set up a Mesh
+platform for tenant `acme` in my AWS account and get a hello-world app running"*
+and it has everything it needs. Every command below is also fully flagged
+(`--yes`, `--json`), so nothing an agent runs depends on a prompt.
 
-| Flag | Effect |
-|---|---|
-| `-p, --port <port>` | serve on another port (`0` picks a free one) |
-| `-v, --version <version>` | pin a docs version (default: latest) |
-| `--foreground` | serve in the foreground (automatic for agents/CI) |
-
-`mesh docs list` shows the published versions. The full `mesh` CLI reference —
-every command, every flag, generated from the binary itself — is a page inside
-that site.
+Prefer to drive it yourself? Everything works by hand — read on.
 
 ---
 
-## Deploying to a platform
+## Requirements
 
-Most app developers never need this section — the platform is already running
-for you, and everything above works without it.
+| Need | Why |
+|---|---|
+| Node 22+ and `pnpm` (`corepack enable`) | Everything below |
+| Docker Desktop (or equivalent) | Only for `mesh start` / `mesh dev` |
+| A Mesh account with `registry` access | Issued by your Mesh contact; used by `mesh registry login` |
+| An AWS account + `aws` CLI | Only if you **deploy** (`mesh deploy`, or setting up a platform) |
 
-If your tenant has a **deployed** Mesh platform (a `<tenant>.<env>` context
-such as `acme.dev`), sign in to it:
+## Two sign-ins, and which one you need
 
-```bash
-mesh login acme.dev            # browser; --device over SSH
-mesh login acme.dev --status   # who you are there
-mesh logout acme.dev
-```
+Two commands say "log in". They are not alternatives — they unlock different
+things, and most people only ever need the first:
 
-That session is what `mesh deploy`, `mesh stack`, the Hub, and the VPN use. It
-has nothing to do with package access — a platform login never touches your
-`~/.npmrc` — which is why `mesh init` asks *where the tenant runs* and only
-signs you in to a platform on the "deployed" branch.
+| | What it unlocks | Needs |
+|---|---|---|
+| **`mesh registry login`** | **Packages.** Installing `@mesh-tech/*`, scaffolding an app, the docs. | A Mesh account. **No AWS, no platform, no context.** |
+| **`mesh login <tenant>.<env>`** | **A deployed platform.** `mesh deploy`, `mesh stack`, the Hub, the VPN. | A platform that exists, and access to it. |
 
-Deploying also needs AWS credentials that can reach the tenant's account. If
-your deployer account can read the registry as well, `mesh registry login
---profile <aws-profile>` refreshes the package token through that profile
-instead of the broker — that flag is for deployers only.
+`mesh registry login` writes a short-lived (12h) token into your `~/.npmrc`;
+re-run it when it expires. `mesh login` never touches `~/.npmrc`. If your account
+does not hold the registry grant yet, the command says so and prints the
+access-request URL (or names the admin to ask).
 
-### Setting up a platform of your own
+## Build and run an app
 
 ```bash
-mesh init platform acme --domain example.com
+mesh init                     # tenant, where it runs, registry access, repo, skills
+mesh create-app --name billing --primitives service,database,temporal
+mesh start                    # the full-local Mesh platform — Docker only, no AWS, no VPN
+mesh dev                      # from the app repo: run your app against it
 ```
 
-scaffolds a tenant **platform** repo (the core + platform Pulumi layers on
-`@mesh-tech/infra-components`) that deploys with `mesh deploy` unmodified.
-
-For an existing app repo, `mesh init app-tenant` is the **doctor**, not a
-scaffolder: it checks auth, registry access, tenant registration, repo shape,
-and agent skills, and repairs what it can with `--fix`. Re-run it any time
-something looks wrong.
-
----
+`mesh start` brings up the platform's own services (Postgres, Temporal, Zitadel,
+the local AWS fabric, and the **Hub** at <http://localhost:9000> — sign in as
+`dev@local.mesh` / `LocalDev1!`). Mail the local platform sends lands in the
+mailbox at <http://localhost:8025>. `mesh status` reprints all of it;
+`mesh stop` shuts it down; `mesh dev doctor` diagnoses a broken session.
 
-## Troubleshooting
+## Set up a platform of your own
 
-### `npm i -g @mesh-tech/mesh-cli` fails with `E401`
-
-This machine already points the `@mesh-tech` scope at the private registry with
-an **expired** token, and npm maps registries per *scope*, never per package —
-so it tried the private registry for a package that is published publicly.
-Override the scope for this one command:
+If nothing is deployed yet, `mesh init` offers to scaffold you one; the same
+scaffold on its own is:
 
 ```bash
-npm i -g @mesh-tech/mesh-cli --@mesh-tech:registry=https://registry.npmjs.org
+mesh init platform acme --domain a-domain-you-control.com
 ```
 
-`--registry=…` alone does **not** work: a scope mapping outranks it. Refreshing
-the token (`mesh registry login`) fixes it too.
-
-The release publishes the same version of `@mesh-tech/mesh-cli` to both
-registries in the same job, so the two copies are the same artifact — there is
-no fork to reconcile. Every *other* `@mesh-tech/*` package is private-registry
-only, so keep the scope mapping for `pnpm install` in an app repo; only the CLI
-bootstrap needs the override.
-
-### The install works, but `mesh --version` prints `0.1.x`
+It writes a tenant **platform** repo (the core + platform Pulumi layers on
+`@mesh-tech/infra-components`) that deploys with `mesh deploy` unmodified, asks
+for the per-install values, offers to create the Pulumi state bucket, and prints
+the deploy sequence — including the one manual step in the middle: **delegating
+the NS records** of the new public zone, without which the deploy stalls on its
+ACM certificate.
 
-You got an abandoned public package from February 2026 that predates the current
-CLI — nothing after it will work. Reinstall:
+The platform layer builds service images with Docker, so it needs a working
+Docker daemon; the core layer does not.
 
-```bash
-npm rm -g @mesh-tech/mesh-cli
-npm i -g @mesh-tech/mesh-cli
-```
+For an existing app repo, `mesh init app-tenant` is the **doctor**, not a
+scaffolder: it checks auth, registry access, tenant registration, repo shape and
+agent skills, and repairs what it can with `--fix`.
 
-### `mesh: not inside a Mesh workspace (no node_modules/.bin/mesh found)`
+## Read the docs
 
-An old launcher shim at `~/.local/bin/mesh` is shadowing the global CLI on your
-`PATH`. The package is installed and fine — just unreachable.
+The Mesh documentation is served **locally, by the CLI** — same access grant as
+the packages:
 
 ```bash
-which -a mesh          # the shim is listed above the npm global bin
-rm ~/.local/bin/mesh   # if you don't develop the platform itself
+mesh docs start     # → http://localhost:4400   (mesh docs stop to end it)
 ```
 
-If you *do* work in a `mesh-platform` checkout, run
-`pnpm exec mesh install-shim --force` there instead — the current shim runs the
-checkout's source inside a checkout and falls through to the global CLI
-everywhere else.
-
-### `Your Mesh account (…) is not authorized to read @mesh-tech packages.`
-
-Your account and session are fine; you don't hold the registry grant yet. The
-message names the request URL (or the admin to ask) — see
-[step 2](#2-get-registry-access). Once granted, `mesh registry login` again —
-it re-mints your sign-in so the new role reaches the broker (a role only rides
-in tokens issued after it was granted). Still refused?
-`mesh registry logout && mesh registry login` starts a fresh sign-in.
-
-### `No registry access on this machine — @mesh-tech packages cannot be installed.`
-
-`mesh create-app` checked before scaffolding and found no usable token. Run
-`mesh init` (or just `mesh registry login`), then re-run `create-app`.
-
-### `AWS profile '…' cannot read the Mesh registry`
-
-You passed `--profile` to `mesh registry login`. That flag skips the broker and
-uses the profile's AWS identity, which is only right for deployers whose AWS
-account is allowed to read the registry. To install packages you do not need
-AWS at all — drop the flag: `mesh registry login`.
-
-### `Registry broker unavailable (…)`
-
-The broker could not be reached, and the CLI fell back to the AWS credential
-chain, which this machine does not have. Retry in a minute:
-`mesh registry login`. If you deploy and have an AWS account:
-`mesh registry login --profile <aws-profile>`.
-
-### `Could not resolve the Mesh package registry`
-
-You are offline, or the platform's discovery document is unreachable. Retry
-once you are online: `mesh registry login`.
+The full `mesh` reference — every command, every flag, generated from the binary
+— is a page inside that site. `mesh --help` and `--help` on any subcommand
+answer the same questions at the terminal.
 
 ---
 
-## Getting help
-
-- `mesh --help`, and `--help` on any subcommand.
-- `mesh docs start` — the full documentation, locally.
-- Anything else: your Mesh contact.
+- **Something not working?** [Troubleshooting](./docs/troubleshooting.md) — the
+  failures people actually hit, each with its one-command fix.
+- **Anything else:** your Mesh contact.
 
 ## License