@farthershore/cli 0.15.0 → 0.17.0

package/README.md

@@ -1,12 +1,21 @@
 # @farthershore/cli
 
-Bootstrap and operate [FartherShore](https://farthershore.com) software
-businesses from the terminal. Product behavior is authored in the GitHub repo;
-the CLI is the agent-friendly tool layer for setup, release, observability, and
-runtime operations. Every command supports `--format json` for non-TTY
-scripting. GitHub account linking and Stripe Connect/KYC stay browser-hosted;
-the CLI reports their status so agents can continue after the builder completes
-those flows.
+Create and operate [FartherShore](https://farthershore.com) software businesses
+from the terminal.
+
+**Status: `0.16.0`.** Pre-1.0 — the command surface is stable but may still
+change between minor versions. Pin an exact version in CI.
+
+FartherShore lets you define a software business as code, then sells, meters,
+and bills access to it at the edge. Product behavior — plans, pricing, limits,
+routes, meters, and origins — is authored in your GitHub repo with
+[`@farthershore/business`](https://www.npmjs.com/package/@farthershore/business)
+and applied automatically when you push. This CLI is the tool layer around that
+repo: scaffold a new business, validate it locally before you push, connect
+billing, publish it live, and run day-to-day operations (consumers, secrets,
+backends, webhooks, promo codes, usage). It is designed to be safe for both
+humans and agents — every command takes `--format json` for non-interactive
+scripting, and the same surface is exposed as an MCP server.
 
 ## Install
 
@@ -14,7 +23,7 @@ those flows.
 npm install -g @farthershore/cli
 ```
 
-Or use directly with npx:
+Or run it directly with npx:
 
 ```bash
 npx @farthershore/cli --help
@@ -43,79 +52,84 @@ farthershore auth login --token mk_xxx
 export FARTHERSHORE_TOKEN=mk_xxx
 ```
 
-Tokens are stored in `~/.farthershore/credentials.json`. Maker tokens are
-exchanged for a short-lived CLI access token on first authenticated request.
+Tokens are stored in `~/.farthershore/credentials.json`. A maker token is
+exchanged for a short-lived CLI access token on the first authenticated request.
 
 ```bash
-farthershore auth whoami         # Show current org, role, scopes
+farthershore auth whoami         # Show current org, role, and scopes
 farthershore auth logout         # Clear stored credentials
 ```
 
-## Agent skills
+GitHub account linking and Stripe Connect/KYC are browser-hosted flows; the CLI
+reports their status (see `connect`) so you — or an agent — can continue once the
+flow is finished in the dashboard.
 
-Inside a managed business repo, install SDK-compatible agent skills from the SDK
-versions the repo actually uses. The Business SDK and Frontend SDK tracks are
-recommended independently, so updating `@farthershore/business` does not force a
-`@farthershore/farthershore-js` skill update, or the reverse.
+## Quickstart
+
+Scaffold a business, validate it, connect billing, and publish:
 
 ```bash
-farthershore skills recommend --format json
-SKILLS_CMD=$(farthershore skills recommend --format json | jq -r '.data.recommendation.command')
-eval "$SKILLS_CMD"
+export FARTHERSHORE_TOKEN=mk_xxx
+
+# 1. Create the managed repo (provisions GitHub repo + starter frontend)
+farthershore business create --name weather-api --display-name "Weather API"
+
+# 2. Edit business behavior in the repo
+gh repo clone acme/weather-api
+cd weather-api
+# ...edit business/business.config.ts with @farthershore/business...
+
+# 3. Validate the same way the PR check will, before pushing
+farthershore preflight --business weather-api
+
+# 4. Push — the GitHub bot compiles + applies your manifest
+git push --set-upstream origin feature/pricing
+farthershore change-set list weather-api    # inspect checks + apply state
 
-# Refresh only the track for the SDK that changed:
-farthershore skills recommend --format json \
-  | jq -r '.data.recommendation.tracks[] | "\(.packageName) -> \(.command)"'
+# 5. Connect billing, then go live
+farthershore connect stripe weather-api
+farthershore business publish weather-api
 ```
 
+Plans, prices, limits, routes, meters, and origins are **repo-controlled**:
+change them by editing `business/business.config.ts` and pushing. The CLI's
+write commands cover **operational** state that lives outside the manifest
+(consumers, secrets, backends, webhooks, promo codes, brand presentation).
+
 ## Global flags
 
 | Flag                  | Description                                              |
 | --------------------- | -------------------------------------------------------- |
 | `--token <token>`     | Override auth token for this command                     |
 | `--api-url <url>`     | Override platform Core API URL                           |
-| `--env <environment>` | Environment scope (use `production`/`prod`/`main`)       |
+| `--env <environment>` | Environment scope (`production`/`prod`/`main` aliases)   |
 | `--format <format>`   | `json` for machine-readable output (default for non-TTY) |
-| `--no-input`          | Never prompt; use non-interactive agent-safe paths       |
+| `--no-input`          | Never prompt; use non-interactive, agent-safe paths      |
 | `--version`           | Show version                                             |
 | `--help`              | Show help                                                |
 
 ## Environment variables
 
-| Variable               | Description                                                      |
-| ---------------------- | ---------------------------------------------------------------- |
-| `FARTHERSHORE_TOKEN`   | API token (overrides stored credentials)                         |
-| `FARTHERSHORE_API_URL` | Platform Core API URL (default: `https://core.farthershore.com`) |
-| `FARTHERSHORE_ENV`     | Default environment scope when `--env` is omitted                |
+| Variable               | Description                                                     |
+| ---------------------- | --------------------------------------------------------------- |
+| `FARTHERSHORE_TOKEN`   | API token (overrides stored credentials)                        |
+| `FARTHERSHORE_API_URL` | Platform Core API URL (default `https://core.farthershore.com`) |
+| `FARTHERSHORE_ENV`     | Default environment scope when `--env` is omitted               |
 
 ## Commands
 
-### `farthershore operations`
-
-Print the machine-readable action boundary before an agent attempts a change:
-repo-authored product behavior, API-controlled runtime operations, dual
-repo/API operations, and browser-only prerequisites.
-
-```bash
-farthershore operations list --format json
-```
-
-`contract` rows are changed in `business/business.config.ts` and pushed through
-GitHub. `operate` rows are CLI/Core API actions. `dual` rows reconcile through
-either path. `browserOnlyPrerequisites` currently includes GitHub account
-linking and Stripe Connect onboarding, both status-only from the CLI.
+Run `farthershore <group> --help` for the full flag set of any command.
 
 ### `farthershore init`
 
-Scaffold a starter software-business repo from a named plan preset. Each preset
-fills in the 5-knob spec in a single decorated `business/business.config.ts` — one
-`@Business` class with `@Meter`/`@Feature`/`@Plan` members.
-The command also creates a customer `frontend/` project, repo-local
-`business/package.json`, `business/tsconfig.json`, and `.gitignore`, matching the
-two-root shape generated by dashboard product creation.
+Scaffold a starter business repo locally from a named plan preset. Each preset
+fills in a single decorated `business/business.config.ts` (one `@Business` class
+with `@Meter`/`@Feature`/`@Plan` members) and creates the matching customer
+`frontend/` project, repo-local `business/package.json`, `business/tsconfig.json`,
+and `.gitignore`.
 
 ```bash
-# Interactive walkthrough (TTY only) — pick a preset by number/name + path
+# Interactive walkthrough (TTY only) — pick a preset and a path
 farthershore init
 
 # Non-interactive — pass --template explicitly (required when not a TTY)
@@ -125,35 +139,28 @@ farthershore init --template metered --format json
 farthershore init --template starter --surface frontend --surface agent
 ```
 
-Templates (sourced from shared-types `listPlanPresets()`):
-
 | Template  | Shape                                                        |
 | --------- | ------------------------------------------------------------ |
 | `free`    | $0 plan, hard-enforced 1k requests/month limit               |
 | `starter` | $20/mo + $20 included usage, $0.001/request overage          |
 | `pro`     | $100/mo + $200 included usage, 14-day trial, $0.0005/request |
-| `prepaid` | $50 one-time signup credit, then PAYG                        |
+| `prepaid` | $50 one-time signup credit, then pay-as-you-go               |
 | `metered` | Pure pay-as-you-go at $0.001/request                         |
 
-After `init`, edit the `@Business({ name, origin })` decorator in
-`business/business.config.ts`. `origin` is the business logic destination Farther
-Shore calls for customer-facing actions. Add `@Meter`/`@Feature`/`@Plan`
-members to the class to grow the business. Pass repeatable
+After `init`, edit the `@Business({ name, origin })` decorator — `origin` is the
+business-logic destination FartherShore calls for customer-facing actions — and
+add `@Meter`/`@Feature`/`@Plan` members to grow the business. Pass repeatable
 `--surface <frontend|api|docs|widget|dashboard|webhook|worker|agent>` to seed a
-frontend-only, agent, worker, API, or hybrid business. Omitting `--surface`
-keeps the default `frontend + api` starter and its sample gateway route. Run
-`npm install` in `business/` once, then run `farthershore build` from the repo
-root to confirm the scaffolded business compiles locally. Customize `frontend/`
-for signup, pricing, account, and usage screens.
+specific shape; omitting it keeps the default `frontend + api` starter. Run
+`npm install` in `business/`, then `farthershore build` from the repo root to
+confirm it compiles.
 
 ### `farthershore build`
 
-Build a business-as-code `business/business.config.ts` with the Business SDK
-manifest builder. The CLI first uses the builder installed under `business/`,
-then falls back to a root install. The command emits a Manifest IR envelope to
-`business-build.json` by default. Server-side validation and accepted lifecycle
-state are handled by the GitHub bot when `business/**` changes are pushed to the
-repo-backed business.
+Compile `business/business.config.ts` to a Manifest IR envelope locally (default
+output `business-build.json`). The CLI uses the Business SDK installed under
+`business/`, falling back to a root install. This is local compilation only;
+server-side validation and apply happen when you push `business/**` changes.
 
 ```bash
 farthershore build
@@ -161,11 +168,26 @@ farthershore build --entry business/business.config.ts --out business-build.json
 farthershore build --format json
 ```
 
+### `farthershore preflight`
+
+Run the same verdict the GitHub `farthershore/validate` PR check produces, before
+you push. It builds the manifest twice and compares the IR hash (the determinism
+check the build runner enforces), then — when you pass `--business` — submits the
+IR for a server dry-run that returns compile diagnostics, the semantic diff, and
+an economic-change verdict.
+
+```bash
+farthershore preflight                       # local build + determinism only
+farthershore preflight --business weather-api # + full server verdict
+farthershore preflight --local-only --format json
+```
+
 ### `farthershore business`
 
-Business lifecycle commands. Creation requires a connected GitHub account because
-Farther Shore always provisions the editable `frontend/` starter repo for a new
-product.
+Business lifecycle. Creation provisions a managed GitHub repo (the source of
+truth for product behavior) under your connected GitHub account and returns the
+clone URL plus bootstrap instructions. A new business starts as a DRAFT with a
+generated `frontend/` ready to customize.
 
 ```bash
 farthershore business list --format json
@@ -177,12 +199,9 @@ farthershore business create \
   --display-name "Weather API" \
   --format json
 
-# Meter templates — the same smart defaults the dashboard offers:
+# Seed a meter from the same templates the dashboard offers:
 #   requests (default) | ai-tokens | credits | spend | compute
-farthershore business create \
-  --name llm-api \
-  --meters ai-tokens \
-  --format json
+farthershore business create --name llm-api --meters ai-tokens --format json
 
 # Or a fully custom meter list (key[:display[:unit]], repeatable):
 farthershore business create --name image-api \
@@ -190,71 +209,51 @@ farthershore business create --name image-api \
   --meter images:Images:image \
   --format json
 
-# Seed initial Business SDK surfaces (repeatable). Defaults to frontend + API.
+# Seed initial Business SDK surfaces (repeatable; defaults to frontend + api):
 farthershore business create \
   --name support-agent \
   --surface frontend \
   --surface agent \
   --format json
 
-farthershore business update weather-api --display-name "Weather" --format json
+farthershore business publish weather-api --format json
+farthershore business delete weather-api --yes --format json
+```
+
+`business update` is presentation-only — it changes display name, description,
+icon, and logo (icon/logo accept PNG, JPEG, or WEBP). Plans, prices, limits,
+routes, meters, and origins are repo-controlled and must be changed through the
+Business SDK code path.
+
+```bash
 farthershore business update weather-api \
   --display-name "Weather" \
   --description "Weather API for agents" \
-  --primary-color '#22c55e' \
   --icon-file ./brand/icon.png \
   --logo-file ./brand/logo.webp \
   --format json
 farthershore business update weather-api \
-  --clear-primary-color --clear-icon --clear-logo --format json
-farthershore business publish weather-api --format json
-farthershore business delete weather-api --yes --format json
+  --clear-icon --clear-logo --format json
 ```
 
-`business create` provisions a managed GitHub repo under the connected GitHub
-account and returns clone-URL plus agent bootstrap instructions in the response.
-That repo is the product behavior source of truth. Plans, prices, limits,
-routes, meters, policies, workflows, gateway config, origins, and backend
-definitions are changed by editing the Business SDK program and pushing a
-branch. Business SDK changes can be built locally with `farthershore build`;
-accepted changes are compiled and published by the GitHub bot after they are
-committed and pushed.
-
-`business update` is deliberately presentation-only. It updates operate-state
-fields that are not the product contract: display name, description, primary
-brand color, icon, and logo. Local icon/logo uploads accept PNG, JPEG, or WEBP
-files. Plans, prices, limits, routes, meters, policies, workflows, origins, and
-backend definitions are repo-controlled and must be changed through the Business
-SDK code path.
-
-Omitting both meter flags during bootstrap gives the starter business a
-`requests` meter. Plain request counting is platform-managed. Variable-value
-meters such as tokens, credits, or compute must be declared in the Business SDK
-as route `reports` and reported by the upstream with `@farthershore/backend`.
-
-A new product starts as a DRAFT with a generated `frontend/` project ready for
-customization. Going live mirrors the dashboard's "Finish setting up" checklist:
+`business publish` enforces the same go-live gates as the dashboard: at least one
+plan, an origin, and a verified Stripe connection (clear remediation is printed
+for `STRIPE_NOT_CONNECTED` / `STRIPE_NOT_VERIFIED` / `BILLING_TAX_NOT_ENROLLED`).
+
+### `farthershore change-set`
+
+Inspect repo-backed change sets — PRs, pushes, releases, checks, semantic diffs,
+and apply state — for a business.
 
 ```bash
-farthershore business create \
-  --name llm-api                                                # 1. create repo
-gh repo clone acme/llm-api                                      # 2. edit business/
-farthershore build --format json                                # 3. validate locally
-git push --set-upstream origin feature/pricing                  # 4. open PR
-farthershore change-set list llm-api --format json              # 5. inspect checks
-farthershore connect stripe llm-api                             # 6. connect billing
-farthershore business publish llm-api                           # 7. go live
+farthershore change-set list weather-api --format json
+farthershore change-set inspect weather-api 42 --format json   # by id, PR #, branch, or SHA
 ```
 
-`business publish` enforces the same gates as the dashboard: at least one
-plan, an origin, and a verified Stripe connection (clear remediation is
-printed for `STRIPE_NOT_CONNECTED` / `STRIPE_NOT_VERIFIED` /
-`BILLING_TAX_NOT_ENROLLED`).
-
 ### `farthershore env`
 
-Manage preview/production environments. Production is the default scope
-when `--env` is omitted; `production`, `prod`, and `main` are aliases.
+Manage preview/production environments. Production is the default scope when
+`--env` is omitted (`production`, `prod`, and `main` are aliases).
 
 ```bash
 farthershore env list weather-api --format json
@@ -264,26 +263,40 @@ farthershore env delete weather-api preview --yes --format json
 
 ### `farthershore plan`
 
-Read code-managed plans and operate live subscriber migrations. The CLI does
-not create, update, or delete plan definitions; edit the Business SDK program in
-the repo for product behavior changes.
+Read code-managed plans and operate live subscriber migrations. The CLI does not
+create, update, or delete plan definitions — edit the Business SDK program for
+that.
 
 ```bash
-# Human-readable table (default in TTY)
-farthershore plan list weather-api
-farthershore plan list weather-api --format table
-
-# JSON envelope (default outside TTY; suitable for jq pipelines)
+farthershore plan list weather-api                   # table (default in TTY)
 farthershore plan list weather-api --format json
 
-# Operate live subscribers after a repo-authored plan version is released
+# Migrate live subscribers after a repo-authored plan version is released
 farthershore plan migrate weather-api pro --from 1 --to head --policy next_renewal --format json
 ```
 
+### `farthershore frontend`
+
+Managed Frontend Hosting operations plus a local preview. `deploy`, `status`,
+`rollback`, and `env` operate the hosted build; `preview` runs the generated
+`frontend/`'s `vite dev` with an injected `window.__FS_CONFIG__` shim so the
+portal renders locally exactly as it serves in production.
+
+```bash
+farthershore frontend status weather-api --format json
+farthershore frontend deploy weather-api --format json
+farthershore frontend rollback weather-api --release-id <hash> --format json
+farthershore frontend env list weather-api --format json
+farthershore frontend env set weather-api VITE_PUBLIC_FOO bar --target BUILD --format json
+
+# Local preview (shells out to vite; needs a frontend/ project)
+farthershore frontend preview --core-url http://localhost:8787
+```
+
 ### `farthershore persona`
 
-Test-environment personas — mint fresh `fsk_test_*` API keys so an agent
-can exercise the gateway end-to-end. Only works in test-strategy envs.
+Mint fresh `fsk_test_*` API keys in a test-strategy environment so you can
+exercise the gateway end-to-end.
 
 ```bash
 farthershore persona bootstrap weather-api --env preview --plan pro --format json
@@ -301,47 +314,42 @@ farthershore usage summary weather-api --format json
 
 ### `farthershore consumer`
 
-Manage live business users/consumers. These are API-controlled runtime actions,
-not repo-authored product behavior.
+Manage live business users. These are operational actions, not repo-authored
+behavior.
 
 ```bash
 farthershore consumer list weather-api --format json
-farthershore consumer list weather-api --env preview --format json
 farthershore consumer block weather-api <subscriberId> --yes --format json
 farthershore consumer remove weather-api <subscriberId> --yes --format json
 ```
 
-Use `consumer list` first to discover `subscriberId`. `block` suspends a user
-and revokes active API keys. `remove` is irreversible and tears down subscriber
-state across billing, edge credentials, and subscriptions.
+Use `consumer list` first to find a `subscriberId`. `block` suspends a user and
+revokes active API keys. `remove` is irreversible and tears down subscriber state
+across billing, edge credentials, and subscriptions.
 
 ### `farthershore secret`
 
-Manage private business secrets. These are API-controlled operational values,
-not repo-authored product behavior. Values are encrypted at rest and list/read
+Manage private business secrets. Values are encrypted at rest; list/read
 responses return metadata only.
 
 ```bash
 farthershore secret list weather-api --format json
 printf '%s' "$CLERK_SECRET_KEY" | farthershore secret set weather-api \
-  CLERK_SECRET_KEY \
-  --from-stdin \
-  --target RUNTIME \
-  --format json
+  CLERK_SECRET_KEY --from-stdin --target RUNTIME --format json
 farthershore secret delete weather-api CLERK_SECRET_KEY --yes --format json
 ```
 
-Use `frontend env` for public browser-visible variables such as
-`NEXT_PUBLIC_*`, `VITE_PUBLIC_*`, or analytics keys. Use `secret` for server
-runtime and private build values. `BUILD` secrets are injected only into managed
-frontend builds and require a redeploy after changes; `RUNTIME` secrets are for
-trusted server/backend runtime code and are never emitted into browser config.
+Use `frontend env` for public, browser-visible variables (`VITE_PUBLIC_*`,
+analytics keys). Use `secret` for server runtime and private build values.
+`BUILD` secrets are injected into managed frontend builds and require a redeploy;
+`RUNTIME` secrets are for trusted server/backend code and are never exposed to
+the browser.
 
 ### `farthershore backend`
 
-Create BYO backends and provision runtime tokens for upstream services. Core
-stores only token hashes; the raw token is returned once and should be deployed
-as `FS_RUNTIME_TOKEN`.
+Create bring-your-own backends and provision runtime tokens for your upstream
+services. Only token hashes are stored; the raw token is returned once and should
+be deployed as `FS_RUNTIME_TOKEN`.
 
 ```bash
 farthershore backend list weather-api --format json
@@ -349,14 +357,14 @@ farthershore backend create weather-api \
   --name "Production API" \
   --origin-url https://api.example.com \
   --format json
-farthershore backend tokens list weather-api --format json
 farthershore backend tokens create weather-api --backend <backendId> --format json
 farthershore backend tokens rotate weather-api <tokenId> --format json
 farthershore backend tokens revoke weather-api <tokenId> --yes --format json
-farthershore backend delete weather-api <backendId> --yes --format json
 ```
 
-Pair the token with `@farthershore/backend` in the upstream:
+Pair the token with
+[`@farthershore/backend`](https://www.npmjs.com/package/@farthershore/backend) in
+your upstream:
 
 ```ts
 import { fartherShore, withUsage } from "@farthershore/backend";
@@ -384,10 +392,9 @@ export async function POST(request: Request) {
 
 ### `farthershore webhook`
 
-Provision outbound webhook endpoints and inspect delivery health. The dashboard
-exposes the same API-managed surface. If the business declares webhooks in
-`business/business.config.ts`, Core returns `409 MANAGED_BY_CODE` for writes so
-the repo remains canonical.
+Provision outbound webhook endpoints and inspect delivery health. If the business
+declares webhooks in `business/business.config.ts`, writes return
+`409 MANAGED_BY_CODE` so the repo stays canonical.
 
 ```bash
 farthershore webhook list weather-api --format json
@@ -401,50 +408,32 @@ farthershore webhook deliveries weather-api <webhookId> --limit 20 --format json
 farthershore webhook delete weather-api <webhookId> --yes --format json
 ```
 
-`webhook create` returns the signing secret once. Store it in the receiving app;
-subsequent list/delivery commands never return the secret.
+`webhook create` returns the signing secret once; store it in the receiving app.
 
 ### `farthershore promo-code`
 
-Manage checkout promo codes. Promo codes are API-controlled operational state,
-not part of `business/business.config.ts`, so agents can manage them through the
-CLI just like the dashboard.
+Manage checkout promo codes (operational state, not part of the manifest).
 
 ```bash
 farthershore promo-code list weather-api --format json
 farthershore promo-code create weather-api \
-  --code LAUNCH25 \
-  --kind percent_off \
-  --percent 25 \
-  --duration-months 3 \
-  --plan <planId> \
-  --format json
+  --code LAUNCH25 --kind percent_off --percent 25 --duration-months 3 \
+  --plan <planId> --format json
 farthershore promo-code create weather-api \
-  --code SAVE500 \
-  --kind amount_off \
-  --amount-cents 500 \
-  --duration-months 1 \
-  --format json
-farthershore promo-code update weather-api <promoCodeId> \
-  --code LAUNCH30 \
-  --kind percent_off \
-  --percent 30 \
-  --duration-months 3 \
-  --all-plans \
-  --format json
+  --code SAVE500 --kind amount_off --amount-cents 500 --duration-months 1 --format json
 farthershore promo-code archive weather-api <promoCodeId> --format json
 farthershore promo-code reactivate weather-api <promoCodeId> --format json
 ```
 
-Stripe coupon changes require a complete discount spec, so `promo-code update`
-requires `--kind`, `--duration-months`, and the required amount flag for that
-kind whenever you change code, amount, dates, plan scope, or redemption limits.
+Because a Stripe coupon change requires a complete discount spec, `promo-code
+update` requires `--kind`, `--duration-months`, and the amount flag for that kind
+whenever you change the code, amount, dates, plan scope, or redemption limits.
 Use `--all-plans` to clear plan scoping.
 
 ### `farthershore connect`
 
-GitHub OAuth and Stripe Connect flows are browser-only. These commands
-report status so an agent can poll until the user finishes the flow.
+GitHub OAuth and Stripe Connect are browser-only. These commands report status so
+you can poll until the flow is finished in the dashboard.
 
 ```bash
 farthershore connect github --format json
@@ -460,239 +449,87 @@ farthershore token list --format json
 farthershore token create --name "ci-bot" --scope products:update products:publish --format json
 farthershore token rotate <tokenId> --sync-to-github --format json
 farthershore token revoke <tokenId> --yes --format json
-farthershore token delete <tokenId> --yes --format json
-```
-
-#### Plan knobs
-
-Every repo-authored plan is a configuration of orthogonal billing knobs. Older
-shapes with `pricing.{model, monthlyPriceCents}`, top-level `billing.strategy`,
-or scalar credit grant fields are no longer accepted by the validator.
-
-| Knob                      | Cents/unit       | Meaning                                                 |
-| ------------------------- | ---------------- | ------------------------------------------------------- |
-| `meters[]`                | micros/unit      | Per-dimension usage price (zero or more dimensions)     |
-| `recurring_fee_cents`     | cents            | Charged each billing period (recurring subscription)    |
-| `grants[]`                | varies by kind   | Credit grants, top-ups, rollover, and recharge policy   |
-| `trial_days`              | days             | Waive everything for N days at the start                |
-| `max_monthly_spend_cents` | cents (optional) | Hard cap; the gateway blocks once exceeded (orthogonal) |
-
-Billing math (handled by Stripe Billing v2 at invoice finalization):
-`bill = recurring_fee + max(0, total_meter_cost − applied_credit_balance)`.
-
-Every plan flavor — free, flat, included, overage, prepaid, trial,
-pay-as-you-go — is a knob combination. Examples:
-
-```yaml
-# Free plan: explicit `free: true` flag + hard-enforced limit
-plans:
-  - key: free
-    name: Free
-    free: true
-    recurring_fee_cents: 0
-    limits:
-      - dimension: requests
-        window: { type: named, name: month }
-        capacity: 1000
-        enforcement: enforce
-
-  # Flat subscription: recurring fee only
-  - key: starter
-    name: Starter
-    recurring_fee_cents: 2900
-
-  # Included usage: fee + monthly credit grant + metered
-  - key: pro
-    name: Pro
-    recurring_fee_cents: 2000
-    grants:
-      - kind: recurring
-        amount_cents: 2000
-    meters:
-      - dimension: requests
-        price_per_unit_micros: 1000 # $0.001/request
-
-  # Overage: fee + metered, no credit
-  - key: growth
-    name: Growth
-    recurring_fee_cents: 4900
-    meters:
-      - dimension: requests
-        price_per_unit_micros: 500
-
-  # Prepaid: one-time grant + metered
-  - key: prepaid
-    name: Prepaid
-    grants:
-      - kind: one_time
-        amount_cents: 10000
-    meters:
-      - dimension: requests
-        price_per_unit_micros: 1000
-
-  # Trial: trial_days + recurring fee
-  - key: trial
-    name: Trial
-    recurring_fee_cents: 2900
-    trial_days: 14
-
-  # Pay-as-you-go: metered only (no recurring fee)
-  - key: metered
-    name: Metered
-    meters:
-      - dimension: tokens
-        price_per_unit_micros: 100
 ```
 
-#### `grants[]` array
-
-Plans accept a typed `grants[]` array. It is the only public credit surface.
-Declare grants in the Business SDK program and push the repo change through the
-normal change-set flow.
-
-Valid `kind` values:
-
-| Kind            | Required fields                                        | Use case                                            |
-| --------------- | ------------------------------------------------------ | --------------------------------------------------- |
-| `recurring`     | `amount_cents`                                         | Monthly credit (e.g. $20 included usage)            |
-| `one_time`      | `amount_cents`                                         | Signup bonus / prepaid balance                      |
-| `promotional`   | `amount_cents`, `label`, optional `expires_after_days` | Launch bonus, win-back, holiday promo               |
-| `trial`         | (none)                                                 | Trial entry — requires `trial_days > 0` on the plan |
-| `rollover`      | `percent` (0–100)                                      | "Unused balance rolls over X% to the next period"   |
-| `top_up`        | `sku`, `label`, `price_cents`, `credit_cents`          | Buy-extra-credit SKU exposed in checkout            |
-| `auto_recharge` | `threshold_cents`, `refill_cents`                      | "When balance < $X auto-purchase $Y"                |
-
-`recurring`, `one_time`, `rollover`, and `trial` are single-shot per plan;
-declaring more than one entry of the same kind triggers a warning
-(only the first is honored).
-
-Example:
-
-```yaml
-plans:
-  - key: pro
-    name: Pro
-    recurring_fee_cents: 10000
-    trial_days: 14
-    meters:
-      - dimension: requests
-        price_per_unit_micros: 500
-    grants:
-      - kind: recurring
-        amount_cents: 20000
-      - kind: trial
-      - kind: promotional
-        amount_cents: 1000
-        label: launch-bonus
-        expires_after_days: 30
-      - kind: rollover
-        percent: 25
-      - kind: auto_recharge
-        threshold_cents: 500
-        refill_cents: 5000
-```
+### `farthershore skills`
 
-Validation surfaces:
+Inside a business repo, recommend agent skills matching the FartherShore SDK
+versions the repo actually uses. The Business SDK and Frontend SDK tracks are
+recommended independently, so updating one does not force a skill update for the
+other.
 
-- **error** — invalid `kind` is rewritten to `Unknown grant kind. Valid kinds: …`
-- **warning** — `{ kind: trial }` declared but `trial_days` is 0
-- **warning** — singleton kinds (`recurring`, `one_time`, `rollover`, `trial`) declared more than once
+```bash
+farthershore skills recommend --format json
+SKILLS_CMD=$(farthershore skills recommend --format json | jq -r '.data.recommendation.command')
+eval "$SKILLS_CMD"
+```
 
-#### Deprecation window (Phase 3b)
+### `farthershore operations`
 
-The product top-level `lifecycle.breaking_changes` block declares the
-breaking-change governance policy validated by the GitHub bot/Core release
-path:
+Print the machine-readable action boundary: which operations are repo-authored
+(`contract`), which are CLI/API operations (`operate`), which reconcile through
+either path (`dual`), and which are browser-only prerequisites (GitHub linking,
+Stripe Connect).
 
-```yaml
-lifecycle:
-  breaking_changes:
-    require_deprecation_window_days: 90
-    require_successor_route: true
+```bash
+farthershore operations list --format json
 ```
 
-When the policy is set, Core emits a `route_removed` change for every route
-dropped from `features.<x>.routes[]` and warns when the server-side
-`breaking-change-safety-check` cron will gate publish via `ConsumerActivity`
-lookup. When `require_successor_route` is true, it also adds a
-successor-required warning.
+## Errors and exit codes
 
-The CLI never blocks on the window itself — the per-consumer lookup
-lives server-side (Phase 1c `ConsumerActivity` table + Phase 3b cron).
+In `--format json` mode, every command prints a single canonical envelope to
+stdout — `{ ok, op, data }` on success, or `{ ok: false, op, error }` on failure,
+where `error` carries a stable `code`, `message`, HTTP `status`, a `retryable`
+flag, and a remediation `hint` when one is registered. Diagnostics go to stderr.
 
-## Agent workflow
+In table mode, failures print `Error [CODE]: message` plus a `Hint:` line:
 
-A typical agent flow:
+```text
+Error [STRIPE_NOT_CONFIGURED]: connect Stripe before running billing operations
+Hint: Stripe isn't connected on this product. Connect it in the dashboard before running billing operations.
+```
 
-```bash
-export FARTHERSHORE_TOKEN=mk_xxx
+The bracketed code is stable across releases — quote it in support threads.
 
-farthershore business create \
-  --name weather-api \
-  --format json
+Exit codes are a branchable taxonomy so a script can tell failure classes apart
+without parsing text:
 
-gh repo clone acme/weather-api
-cd weather-api
-# Edit business/business.config.ts with the Business SDK.
-farthershore build --format json
-git push --set-upstream origin feature/pricing
-farthershore change-set list weather-api --format json
-farthershore business show weather-api --format json
-```
+| Exit | Meaning                                                      |
+| ---- | ------------------------------------------------------------ |
+| `0`  | Success                                                      |
+| `2`  | Validation error (HTTP 400/422) — fix your input             |
+| `3`  | Auth / permission error (401/403) — re-authenticate          |
+| `4`  | Conflict / managed-by-code (409) — change it in the repo     |
+| `5`  | Server error (5xx) — retry                                   |
+| `1`  | Any other failure (local error, 402/404, argument errors, …) |
 
-For business updates, edit `business/business.config.ts` or any modules it imports
-and build locally with:
+## CI and agent usage
 
-```bash
-farthershore build --format json
-```
+The CLI is non-interactive whenever a token is available via `--token` or
+`FARTHERSHORE_TOKEN` — `auth login` only prompts when stdin is a TTY and no token
+was passed, so it is safe to script. `farthershore build` and `farthershore
+preflight --local-only` need no network or auth and are safe to run in CI.
 
 ## MCP server
 
-The MCP server (`farthershore-mcp`) projects tool definitions from the same
-operation registry that generates the CLI command groups. Tool names use the
-`fs_*` prefix and cover the agent-operable platform surface:
-
-- Products: `fs_business_list`, `fs_brand_update`, `fs_business_publish`
-- Environments: `fs_env_list`, `fs_env_create`
-- Plans: `fs_plan_list`
-- Backends: `fs_backend_list`, `fs_backend_create`, `fs_backend_delete`
-- Runtime tokens: `fs_runtime_token_list`, `fs_runtime_token_mint`,
-  `fs_runtime_token_rotate`, `fs_runtime_token_revoke`
-- Webhooks: `fs_webhook_list`, `fs_webhook_create`, `fs_webhook_update`,
-  `fs_webhook_delete`, `fs_webhook_test`, `fs_webhook_deliveries`
-- Promo codes: `fs_promo_code_list`, `fs_promo_code_create`,
-  `fs_promo_code_update`, `fs_promo_code_archive`,
-  `fs_promo_code_reactivate`
-- Consumers: `fs_consumer_list`, `fs_consumer_block`, `fs_consumer_remove`
-- Secrets: `fs_secret_list`, `fs_secret_set`, `fs_secret_delete`
-- Personas: `fs_persona_bootstrap`, `fs_persona_list`, `fs_persona_revoke`
-- Usage and maker tokens: `fs_usage_read`, `fs_maker_token_list`
-
-Every MCP tool has a sibling CLI operation by construction; the parity test in
-`apps/cli/src/operations/mcp-cli-parity.test.ts` enforces that invariant.
-
-## Errors and exit codes
-
-The CLI exits `0` on success and `1` on any failure (including
-commander-level argument errors). When the API returns a 4XX/5XX, the
-CLI prints the canonical error code in brackets and a one-line
-remediation hint when one is registered:
+The MCP server (`farthershore-mcp`) projects its tools from the same operation
+registry that defines the CLI commands, so every MCP tool has a CLI sibling. Tool
+names use the `fs_*` prefix and cover the agent-operable surface: businesses,
+environments, plans, frontends, backends, runtime tokens, webhooks, promo codes,
+consumers, secrets, personas, usage, and maker tokens.
 
-```text
-Error [STRIPE_NOT_CONFIGURED]: connect Stripe before running billing operations
-Hint: Stripe isn't connected on this product. Connect it in the dashboard before running billing operations.
+```bash
+FARTHERSHORE_TOKEN=mk_xxx farthershore-mcp
 ```
 
-The bracketed code is stable across releases — quote it in support threads.
+## Learn more
 
-`farthershore auth whoami --format json` emits a stable JSON shape suitable
-for CI scripts.
+- Platform documentation: [farthershore.com](https://farthershore.com)
+- Author product behavior:
+  [`@farthershore/business`](https://www.npmjs.com/package/@farthershore/business)
+- Report usage from your backend:
+  [`@farthershore/backend`](https://www.npmjs.com/package/@farthershore/backend)
 
-## CI / agent usage
+## License
 
-The CLI is non-interactive whenever a token is available via the
-`--token` flag or `FARTHERSHORE_TOKEN` env var — `auth login` only
-prompts when stdin is a TTY and no token argument was passed, so it's
-safe to script. `farthershore build` is CI-safe and can be run under `CI` /
-`GITHUB_ACTIONS` for local Business SDK compilation.
+MIT