@farthershore/cli 0.28.0 → 0.30.0

package/README.md

@@ -3,7 +3,7 @@
 Create and operate [FartherShore](https://farthershore.com) software businesses
 from the terminal.
 
-**Status: `0.25.0`.** Pre-1.0 — the command surface is stable but may still
+**Status: `0.30.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,
@@ -11,8 +11,8 @@ and bills access to it at the edge. Business 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,
+repo: provision a managed business repo, validate it locally before you push,
+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.
@@ -32,50 +32,35 @@ npx @farthershore/cli --help
 The package also ships an MCP stdio server for agents:
 
 ```bash
-FARTHERSHORE_TOKEN=mk_xxx npx -p @farthershore/cli farthershore-mcp
+FARTHERSHORE_TOKEN="$FARTHERSHORE_TOKEN" npx -p @farthershore/cli farthershore-mcp
 ```
 
 ## Authentication
 
-Create a maker token at
-[farthershore.com/settings/tokens](https://farthershore.com/settings/tokens),
-then store it locally:
+Use the credential supplied to the current environment:
 
 ```bash
-# Interactive — prompts for the token
-farthershore auth login
-
-# Non-interactive — pass it directly
-farthershore auth login --token mk_xxx
-
-# Or skip the file entirely with an env var (CI / agents)
-export FARTHERSHORE_TOKEN=mk_xxx
+export FARTHERSHORE_TOKEN="<provided credential>"
+farthershore auth whoami --format json
 ```
 
-Tokens are stored in `~/.farthershore/credentials.json`. A maker token is
-exchanged for a short-lived CLI access token on the first authenticated request.
+The CLI exchanges that credential for a short-lived access token on the first
+authenticated request. Do not write credentials into the managed repository.
 
 ```bash
-farthershore auth whoami         # Show current org, role, and scopes
 farthershore auth logout         # Clear stored credentials
 ```
 
-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.
-
 ## Quickstart
 
-Scaffold a business, validate it, connect billing, and publish:
+Create a managed business repo, author the business, validate it, and push:
 
 ```bash
-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"
+# 1. Create the managed repo. Human output is exactly its URL.
+REPO_URL=$(farthershore business create weather-api)
 
-# 2. Edit business behavior in the repo
-gh repo clone acme/weather-api
+# 2. Clone it and author business/ from scratch.
+git clone "$REPO_URL"
 cd weather-api
 # ...edit business/business.ts with @farthershore/business...
 
@@ -86,9 +71,9 @@ farthershore validate --business weather-api
 git push --set-upstream origin feature/pricing
 farthershore change-set list weather-api    # inspect checks + apply state
 
-# 5. Connect billing, then go live
-farthershore connect stripe weather-api
-farthershore business publish weather-api
+# 5. Inspect accepted state, then use the CLI for platform operations.
+farthershore business status weather-api --format json
+farthershore operations list --format json
 ```
 
 Plans, prices, limits, routes, meters, and origins are **repo-controlled**:
@@ -120,41 +105,6 @@ write commands cover **operational** state that lives outside the manifest
 
 Run `farthershore <group> --help` for the full flag set of any command.
 
-### `farthershore init`
-
-Scaffold a starter business repo locally from a named plan preset. Each preset
-fills in a functional `business/business.ts` using `fs.requests()`,
-`fs.route()`, `fs.plan()`, and a default `fs.business()` export, then creates the matching customer
-`frontend/` project, repo-local `business/package.json`, `business/tsconfig.json`,
-and `.gitignore`.
-
-```bash
-# Interactive walkthrough (TTY only) — pick a preset and a path
-farthershore init
-
-# Non-interactive — pass --template explicitly (required when not a TTY)
-farthershore init --template free
-farthershore init --template starter --force
-farthershore init --template metered --format json
-farthershore init --template starter --surface frontend --surface agent
-```
-
-| 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 pay-as-you-go               |
-| `metered` | Pure pay-as-you-go at $0.001/request                         |
-
-After `init`, add functional meter, route, group, and plan declarations to grow
-the business. Configure the platform-owned upstream origin separately.
-Pass repeatable
-`--surface <frontend|api|docs|widget|dashboard|webhook|worker|agent>` to seed a
-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 create`
 
 Create local project components inside a managed builder repo. `create api`
@@ -201,42 +151,27 @@ farthershore validate --local-only --format json
 
 ### `farthershore business`
 
-Business lifecycle. Creation provisions a managed GitHub repo (the source of
-truth for business 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.
+Business lifecycle. Creation provisions a managed GitHub repo as the source of
+truth for business behavior and returns its URL. A new business starts as a
+DRAFT with repository tooling but no predefined business program.
 
 ```bash
 farthershore business list --format json
 farthershore business show weather-api --format json
 farthershore business show weather-api --env preview --format json
 
-farthershore business create \
-  --name weather-api \
+farthershore business create weather-api \
   --display-name "Weather API" \
   --format json
 
-# 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
-
-# Or a fully custom meter list (key[:display[:unit]], repeatable):
-farthershore business create --name image-api \
-  --meter requests \
-  --meter images:Images:image \
-  --format json
-
-# Seed initial Business SDK surfaces (repeatable; defaults to frontend + api):
-farthershore business create \
-  --name support-agent \
-  --surface frontend \
-  --surface agent \
-  --format json
-
 farthershore business publish weather-api --format json
 farthershore business delete weather-api --yes --format json
 ```
 
+The JSON result includes `data.business`, `data.repoUrl`, and recovery metadata.
+Gather the product requirements, create the `business/` program, and author its
+plans, prices, limits, routes, and meters from scratch.
+
 `business update` changes platform-owned fields such as display name,
 description, icon, and logo (icon/logo accept PNG, JPEG, or WEBP). Plans,
 prices, limits, routes, and meters are repo-controlled and must be changed
@@ -253,9 +188,8 @@ farthershore business update weather-api \
   --clear-icon --clear-logo --format json
 ```
 
-`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`).
+`business publish` enforces the same go-live gates as the dashboard and returns
+stable remediation errors when a prerequisite is missing.
 
 ### `farthershore change-set`
 
@@ -457,46 +391,20 @@ update` requires `--kind`, `--duration-months`, and the amount flag for that kin
 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 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
-farthershore connect stripe weather-api --format json
-```
+### Farther Shore agent skills
 
-### `farthershore token`
-
-Manage maker tokens for the current org.
+Install or refresh the complete skills bundle together. When a newer tagged
+bundle is available, the CLI prints the same command with the release tag in
+the GitHub URL.
 
 ```bash
-farthershore token list --format json
-farthershore token create --name "ci-bot" --scope businesses:update businesses:publish --format json
-farthershore token rotate <tokenId> --sync-to-github --format json
-farthershore token revoke <tokenId> --yes --format json
-```
-
-### `farthershore skills`
-
-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.
-
-```bash
-farthershore skills recommend --format json
-SKILLS_CMD=$(farthershore skills recommend --format json | jq -r '.data.recommendation.command')
-eval "$SKILLS_CMD"
+npx skills add https://github.com/farther-shore/skills/tree/v2.1.0 --skill '*' -g -y
 ```
 
 ### `farthershore operations`
 
 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).
+(`contract`) and which are CLI/API operations (`operate`).
 
 ```bash
 farthershore operations list --format json
@@ -509,14 +417,8 @@ stdout — `{ ok, op, data }` on success, or `{ ok: false, op, error }` on failu
 where `error` carries a stable `code`, `message`, HTTP `status`, a `retryable`
 flag, and a remediation `hint` when one is registered. Diagnostics go to stderr.
 
-In table mode, failures print `Error [CODE]: message` plus a `Hint:` line:
-
-```text
-Error [STRIPE_NOT_CONFIGURED]: connect Stripe before running billing operations
-Hint: Stripe isn't connected on this business. Connect it in the dashboard before running billing operations.
-```
-
-The bracketed code is stable across releases — quote it in support threads.
+In table mode, failures print `Error [CODE]: message` plus a `Hint:` line. The
+bracketed code is stable across releases — quote it in support threads.
 
 Exit codes are a branchable taxonomy so a script can tell failure classes apart
 without parsing text:
@@ -542,11 +444,12 @@ validate --local-only` need no network or auth and are safe to run in CI.
 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.
+environments, organizations, audit logs, notifications, plans, frontends,
+backends, runtime tokens, webhooks, promo codes, consumers, secrets, personas,
+and usage.
 
 ```bash
-FARTHERSHORE_TOKEN=mk_xxx farthershore-mcp
+FARTHERSHORE_TOKEN="$FARTHERSHORE_TOKEN" farthershore-mcp
 ```
 
 ## Learn more