@farthershore/cli 0.14.0 → 0.14.2

package/README.md

@@ -1,8 +1,10 @@
 # @farthershore/cli
 
-Create and manage [FartherShore](https://farthershore.com) software products
-from the terminal. Designed for AI agents and humans alike — every command
-supports `--format json` for non-TTY scripting.
+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.
 
 ## Install
 
@@ -47,6 +49,23 @@ farthershore auth whoami         # Show current org, role, scopes
 farthershore auth logout         # Clear stored credentials
 ```
 
+## Agent skills
+
+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.
+
+```bash
+farthershore skills recommend --format json
+SKILLS_CMD=$(farthershore skills recommend --format json | jq -r '.data.recommendation.command')
+eval "$SKILLS_CMD"
+
+# Refresh only the track for the SDK that changed:
+farthershore skills recommend --format json \
+  | jq -r '.data.recommendation.tracks[] | "\(.packageName) -> \(.command)"'
+```
+
 ## Global flags
 
 | Flag                  | Description                                              |
@@ -70,11 +89,11 @@ farthershore auth logout         # Clear stored credentials
 
 ### `farthershore init`
 
-Scaffold a starter software-product repo from a named plan preset. Each preset
-fills in the 5-knob spec in a single decorated `product/product.config.ts` — one
-`@Product` class with `@Meter`/`@Feature`/`@Plan` members.
+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
-`product/package.json`, `product/tsconfig.json`, and `.gitignore`, matching the
+`business/package.json`, `business/tsconfig.json`, and `.gitignore`, matching the
 two-root shape generated by dashboard product creation.
 
 ```bash
@@ -98,107 +117,118 @@ Templates (sourced from shared-types `listPlanPresets()`):
 | `prepaid` | $50 one-time signup credit, then PAYG                        |
 | `metered` | Pure pay-as-you-go at $0.001/request                         |
 
-After `init`, edit the `@Product({ name, origin })` decorator in
-`product/product.config.ts`. `origin` is the business logic destination Farther
+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 product. Pass repeatable
+members to the class 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 product. Omitting `--surface`
+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 `product/` once, then run `farthershore build` from the repo
-root to confirm the scaffolded product compiles locally. Customize `frontend/`
+`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.
 
 ### `farthershore build`
 
-Build a product-as-code `product/product.config.ts` with the Product SDK
-manifest builder. The CLI first uses the builder installed under `product/`,
+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
-`manifest-ir.json` by default. Server-side validation and accepted lifecycle
-state are handled by the GitHub bot when `product/**` changes are pushed to the
-repo-backed product.
+`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.
 
 ```bash
 farthershore build
-farthershore build --entry product/product.config.ts --out manifest-ir.json
+farthershore build --entry business/business.config.ts --out business-build.json
 farthershore build --format json
 ```
 
-### `farthershore product`
+### `farthershore business`
 
-Product lifecycle commands. Creation requires a connected GitHub account because
+Business lifecycle commands. Creation requires a connected GitHub account because
 Farther Shore always provisions the editable `frontend/` starter repo for a new
 product.
 
 ```bash
-farthershore product list --format json
-farthershore product show weather-api --format json
-farthershore product show weather-api --env preview --format json
+farthershore business list --format json
+farthershore business show weather-api --format json
+farthershore business show weather-api --env preview --format json
 
-farthershore product create \
+farthershore business create \
   --name weather-api \
   --display-name "Weather API" \
-  --origin https://api.example.com \
   --format json
 
 # Meter templates — the same smart defaults the dashboard offers:
 #   requests (default) | ai-tokens | credits | spend | compute
-farthershore product create \
+farthershore business create \
   --name llm-api \
-  --origin https://api.llm.example.com \
   --meters ai-tokens \
   --format json
 
 # Or a fully custom meter list (key[:display[:unit]], repeatable):
-farthershore product create --name image-api \
-  --origin https://api.images.example.com \
+farthershore business create --name image-api \
   --meter requests \
   --meter images:Images:image \
   --format json
 
-# Seed initial Product SDK surfaces (repeatable). Defaults to frontend + API.
-farthershore product create \
+# Seed initial Business SDK surfaces (repeatable). Defaults to frontend + API.
+farthershore business create \
   --name support-agent \
-  --origin https://app.example.com \
-  --repo-owner acme \
-  --repo-name support-agent \
   --surface frontend \
   --surface agent \
   --format json
 
-farthershore product update weather-api --display-name "Weather" --format json
-farthershore product publish weather-api --format json
-farthershore product delete weather-api --yes --format json
+farthershore business update weather-api --display-name "Weather" --format json
+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
 ```
 
-`product create` provisions a managed GitHub repo and returns clone-URL +
-agent bootstrap instructions in the response. That repo is required for the
-starter `frontend/` project and normal customization workflow. Product 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.
-
-Plan pricing lives on the plan (see `farthershore plan create` below) — the
-product itself no longer carries a `billingStrategy`. Omitting both meter flags
-gives the product a `requests` meter. Plain request counting is
-platform-managed. Variable-value meters such as tokens, credits, or compute must
-be declared in the Product SDK as route `reports` and reported by the upstream
-with `@farthershore/backend`.
+`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:
 
 ```bash
-farthershore product create \
-  --name llm-api \
-  --origin https://api.example.com \
-  --meters ai-tokens                                            # 1. create
-farthershore connect stripe llm-api                             # 2. connect billing
-farthershore plan create llm-api --key pro --name "Pro" \
-  --recurring-fee-cents 2900                                    # 3. how you charge
-farthershore product publish llm-api                            # 4. go live
+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
 ```
 
-`product publish` enforces the same gates as the dashboard: at least one
+`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`).
@@ -216,9 +246,9 @@ farthershore env delete weather-api preview --yes --format json
 
 ### `farthershore plan`
 
-Plan CRUD via the management API. The body uses the unified 5-knob
-shape (see "Plan knobs" below) — pass cents-denominated flags for
-whichever knobs the plan flavor needs.
+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.
 
 ```bash
 # Human-readable table (default in TTY)
@@ -228,26 +258,8 @@ farthershore plan list weather-api --format table
 # JSON envelope (default outside TTY; suitable for jq pipelines)
 farthershore plan list weather-api --format json
 
-# Flat subscription: recurring fee only
-farthershore plan create weather-api \
-  --key pro \
-  --name "Pro" \
-  --recurring-fee-cents 2900 \
-  --format json
-
-# Included usage: fee + monthly credit grant
-farthershore plan create weather-api \
-  --key included \
-  --name "Included" \
-  --recurring-fee-cents 2000 \
-  --grant recurring:2000 \
-  --format json
-
-# Free plan
-farthershore plan create weather-api --key free --name "Free" --free --format json
-
-farthershore plan update weather-api <planId> --recurring-fee-cents 3900 --format json
-farthershore plan delete weather-api <planId> --yes --env preview --format json
+# Operate 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 persona`
@@ -336,9 +348,9 @@ farthershore token revoke <tokenId> --yes --format json
 
 #### Plan knobs
 
-Every 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.
+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                                                 |
 | ------------------------- | ---------------- | ------------------------------------------------------- |
@@ -418,8 +430,8 @@ plans:
 #### `grants[]` array
 
 Plans accept a typed `grants[]` array. It is the only public credit surface.
-For CLI plan create/update, pass one or more canonical grants with
-`--grant <kind:amount_cents>`.
+Declare grants in the Business SDK program and push the repo change through the
+normal change-set flow.
 
 Valid `kind` values:
 
@@ -498,20 +510,20 @@ A typical agent flow:
 ```bash
 export FARTHERSHORE_TOKEN=mk_xxx
 
-farthershore product create \
+farthershore business create \
   --name weather-api \
-  --origin https://api.example.com \
   --format json
 
-farthershore plan create weather-api --key free --name "Free" --free --format json
-farthershore plan create weather-api \
-  --key pro --name "Pro" --recurring-fee-cents 2900 --format json
-
+gh repo clone acme/weather-api
+cd weather-api
+# Edit business/business.config.ts with the Business SDK.
 farthershore build --format json
-farthershore product show weather-api --format json
+git push --set-upstream origin feature/pricing
+farthershore change-set list weather-api --format json
+farthershore business show weather-api --format json
 ```
 
-For product updates, edit `product/product.config.ts` or any modules it imports
+For business updates, edit `business/business.config.ts` or any modules it imports
 and build locally with:
 
 ```bash
@@ -522,9 +534,9 @@ farthershore build --format json
 
 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-writable product surface:
+`fs_*` prefix and cover the agent-operable platform surface:
 
-- Products: `fs_product_list`, `fs_brand_update`, `fs_product_publish`
+- 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`
@@ -559,4 +571,4 @@ 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 Product SDK compilation.
+`GITHUB_ACTIONS` for local Business SDK compilation.