@farthershore/cli 0.31.1 → 0.33.0

package/README.md

@@ -3,7 +3,7 @@
 Create and operate [FartherShore](https://farthershore.com) software businesses
 from the terminal.
 
-**Status: `0.31.1`.** Pre-1.0 — the command surface is stable but may still
+**Status: `0.33.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,
@@ -21,19 +21,19 @@ the explicitly agent-operable subset of the CLI surface.
 ## Install
 
 ```bash
-npm install -g @farthershore/cli@0.31.1
+npm install -g @farthershore/cli@0.33.0
 ```
 
 Or run it directly with npx:
 
 ```bash
-npx -p @farthershore/cli@0.31.1 farthershore --help
+npx -p @farthershore/cli@0.33.0 farthershore --help
 ```
 
 The package also ships an MCP stdio server for agents:
 
 ```bash
-npx -p @farthershore/cli@0.31.1 farthershore-mcp
+npx -p @farthershore/cli@0.33.0 farthershore-mcp
 ```
 
 ## Authentication
@@ -131,14 +131,49 @@ write commands cover **operational** state that lives outside the manifest
 
 ## Environment variables
 
-| Variable               | Description                                                     |
-| ---------------------- | --------------------------------------------------------------- |
-| `FARTHERSHORE_TOKEN`   | Ephemeral organization-scoped MakerToken; never persisted       |
-| `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`                      | Ephemeral organization-scoped MakerToken; never persisted                |
+| `FARTHERSHORE_API_URL`                    | Platform Core API URL (default `https://core.farthershore.com`)          |
+| `FARTHERSHORE_ENV`                        | Default environment scope when `--env` is omitted                        |
+| `FARTHERSHORE_CONSUMER_TOKEN`             | Ephemeral portal consumer session for `service-account`; never persisted |
+| `FARTHERSHORE_ENVIRONMENT_ID`             | Portal environment UUID fallback for `service-account`                   |
+| `FARTHERSHORE_SUBSCRIBER_ORGANIZATION_ID` | Subscriber organization UUID fallback for `service-account`              |
 
 ## Commands
 
+### Browse platform documentation (no login)
+
+Docs are a read-only virtual filesystem: collections are root folders, sidebar
+sections are directories, and pages are files. Listing a page shows its heading
+anchors. Paths come from the published docs index, not your working directory.
+
+```bash
+farthershore docs ls --format json
+farthershore docs ls backend-sdk --format json
+farthershore docs tree backend-sdk --format json
+farthershore docs ls backend-sdk/connect-your-application --format json
+farthershore docs read backend-sdk/connect-your-application/metering --format json
+farthershore docs ls backend-sdk/connect-your-application/metering --format json
+farthershore docs read backend/metering --section "choose-the-correct-metering-channel" --format json
+farthershore docs search "runtime token" --collection backend-sdk --limit 10 --format json
+farthershore docs collection backend-sdk --format json
+```
+
+Use an anchor returned by `docs ls <page>` for `--section`. `read` also accepts the canonical slug or an
+official docs URL with a `#heading` fragment, so links in skills can be used
+directly. `get` aliases `read`; `list` aliases `ls`. A section includes all its
+child headings and complete code fences. Full pages and collections are not
+truncated; search results are bounded and include a total match count.
+
+`farthershore docs --stage ls` selects stage; production is the default and
+`--api-url` does not change the documentation origin. No credentials or
+organization context are sent. JSON includes source URL and, for content reads,
+the docs source commit. Human output is available with `--format table`.
+The collection-aware `llms.txt` and corpus artifacts must be published first;
+unavailable artifacts produce an error, not stale bundled guidance. Business
+`knowledge` commands are separate authenticated resources.
+
 Run `farthershore <group> --help` for the full flag set of any command.
 
 Database-backed list commands use Core's shared query contract: repeat
@@ -205,6 +240,9 @@ farthershore business list --filter status=ACTIVE --sort updatedAt:desc --search
 farthershore business show weather-api --format json
 farthershore business show weather-api --env preview --format json
 
+# Is the slug free? (normalized, blocked-word and collision checked)
+farthershore business subdomain-check weather-api --format json
+
 farthershore business create weather-api \
   --display-name "Weather API" \
   --format json
@@ -219,7 +257,9 @@ 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,
+description, icon, logo (icon/logo accept PNG, JPEG, or WEBP), and whether the
+product is listed on the organization's public page
+(`https://farthershore.io/organization/<org-slug>`, listed by default). Plans,
 prices, limits, routes, and meters are repo-controlled and must be changed
 through the Business SDK code path.
 
@@ -232,6 +272,8 @@ farthershore business update weather-api \
   --format json
 farthershore business update weather-api \
   --clear-icon --clear-logo --format json
+farthershore business update weather-api \
+  --unlist-from-org-page --format json
 ```
 
 `business publish` enforces the same go-live gates as the dashboard and returns
@@ -239,6 +281,31 @@ stable remediation errors when a prerequisite is missing.
 `business rollback` enqueues a rollback of the specified prior publish workflow
 and requires the exact `business:rollback` permission.
 
+`business rbac` reads a business's Managed-RBAC state — the platform-owned
+`rbacEnabled` flag. `business rbac enable` / `disable` toggle that flag (like
+`docsEnabled`, it is platform-owned and never repo-authored); once enabled,
+subscriber organizations manage roles in their portal. Both toggles are
+idempotent. Subscriber role and assignment state is kept server-side on
+disable, so re-enabling is a pure flag flip.
+
+```bash
+farthershore business rbac weather-api --format json
+farthershore business rbac enable weather-api --format json
+farthershore business rbac disable weather-api --format json
+```
+
+`business rbac subjects list` lists the custom permission vocabulary: subjects
+whose `<subject>:<verb>` permissions are grantable to subscriber roles
+alongside the route-derived catalog. Subjects are **repo-owned** — declared via
+a permission-carrying `fs.group(id, routes, { permission: { verbs, escalatory,
+description } })` in the business repo's `business/` folder and synced from the
+accepted spec. To change them, edit the group declaration, run
+`farthershore validate`, and push; there are no CLI write commands.
+
+```bash
+farthershore business rbac subjects list weather-api --format json
+```
+
 ### `farthershore apply-timeline`
 
 Inspect repo-backed applies — PRs, pushes, releases, checks, semantic diffs,
@@ -269,20 +336,150 @@ to them. Built-in and custom roles use the same list contract.
 ```bash
 farthershore organization role list <organizationId> --filter builtIn=true --sort name --search security --format json
 farthershore organization members <organizationId> --filter roleKey=auditor --sort email:asc --search person --format json
+
+# Primary owner only; hands ultimate authority to another existing member.
+farthershore organization ownership-transfer <organizationId> <newOwnerUserId> --yes --format json
+```
+
+Selecting the default organization is a local credential concern, not an API
+call: `farthershore auth organization use <id-or-slug>` changes the stored
+default, and `--org <id>` overrides it for one command.
+
+### `farthershore token`
+
+Create and administer organization-owned MakerTokens. These commands require a
+signed-in user CLI session (`farthershore login`); an existing MakerToken cannot
+list, mint, approve, rotate, revoke, or otherwise administer credentials. The
+entire group is CLI-only and is deliberately absent from `farthershore-mcp`.
+
+```bash
+# Exact permissions a human may delegate — read this before choosing --permissions.
+farthershore token permission-catalog --org --format json
+
+# Omit --businesses to snapshot ALL current and future org businesses.
+farthershore token create deploy-bot --org \
+  --permissions '["business:read","business:publish"]' \
+  --businesses business_1,business_2 \
+  --idempotency-key org-token-create-2026-08-11 \
+  --format json
+
+farthershore token list --org --format json
+farthershore token approvals --org --format json
+farthershore token approve <approvalId> --org --format json
+farthershore token approve <approvalId> --org \
+  --permissions '["business:read"]' --format json # trim on approval
+farthershore token deny <approvalId> --org --format json
+farthershore token update <tokenId> --org \
+  --permissions '["business:read"]' \
+  --idempotency-key org-token-update-2026-08-11 --format json
+farthershore token rotate <tokenId> --org --format json
+farthershore token revoke <tokenId> --org --yes --format json
+```
+
+Creation and updates that exceed the caller's live authority return
+`data.status: "PENDING"`, an approval id, and **no plaintext credential**. A
+direct ACTIVE create, an approved CREATE, or a rotation returns `data.token`
+exactly once; store it immediately. Human output follows the same rule: it
+prints plaintext only for an ACTIVE one-time-secret response and says explicitly
+when a PENDING request minted nothing.
+
+Create and update accept `--idempotency-key`. Reuse the same key when repeating
+the same logical request after an interrupted invocation. If omitted, the CLI
+generates a key and keeps it stable across its automatic transient retries.
+
+### `farthershore stripe`
+
+Read the Stripe Connect account a business bills through (a per-business
+override when one exists, otherwise the organization default) and remove a
+per-business override. Both require a signed-in owner session; a MakerToken is
+rejected. Connecting Stripe is a browser-only onboarding handshake with Stripe,
+so there is deliberately no `stripe connect` command — do it from the
+dashboard and confirm with `stripe status`.
+
+```bash
+farthershore stripe status weather-api --format json
+farthershore stripe disconnect weather-api --yes --format json
+```
+
+`stripe disconnect` is refused while any subscription on the business is still
+money-bearing.
+
+### `farthershore service-account`
+
+Manage service accounts owned by a subscriber organization. This is a separate
+subscriber-plane trust boundary: it requires a current identity-provider portal
+consumer session in `FARTHERSHORE_CONSUMER_TOKEN`, plus the exact environment
+and subscriber organization context. The consumer bearer has no argv flag and
+is never exchanged or persisted by the CLI. A builder login or MakerToken cannot
+substitute for it.
+
+```bash
+export FARTHERSHORE_CONSUMER_TOKEN='<current portal session token>'
+export FARTHERSHORE_ENVIRONMENT_ID='<environment UUID>'
+export FARTHERSHORE_SUBSCRIBER_ORGANIZATION_ID='<subscriber organization UUID>'
+
+farthershore service-account list <businessId> --format json
+farthershore service-account create <businessId> deploy-bot \
+  --permissions '["route:read","route:write"]' \
+  --scopes '["production"]' \
+  --idempotency-key sa-create-2026-08-11 --format json
+farthershore service-account update <businessId> <serviceAccountId> \
+  --permissions '["route:read"]' \
+  --idempotency-key sa-update-2026-08-11 --format json
+farthershore service-account approvals <businessId> --format json
+farthershore service-account approve <businessId> <approvalId> \
+  --permissions '["route:read"]' --format json # optional trim
+farthershore service-account deny <businessId> <approvalId> --format json
+farthershore service-account rotate <businessId> <serviceAccountId> --format json
+farthershore service-account revoke <businessId> <serviceAccountId> --yes --format json
+```
+
+Pass `--environment-id` and `--subscriber-organization` to override the two
+context environment variables for one command. PENDING create/update responses
+never print `plaintext`. ACTIVE creates
+and rotations print the one-time key once. Create/update idempotency follows the
+same explicit-key or generated stable in-flight retry behavior as org tokens.
+
+This group is direct CLI-only and deliberately has no MCP projection: the MCP
+operation registry carries builder principals, not portal consumer sessions.
+
+### `farthershore limit`
+
+Manage subscriber-owned usage limits with a portal consumer session. `list`
+reads the current limits; `set` creates a limit when `--limit-id` is omitted and
+updates that limit when `--limit-id` is present; `remove` deletes a limit.
+
+```bash
+farthershore limit list <business-id> --format json
+farthershore limit set <business-id> \
+  --quantity requests --mode BLOCK --scope ORG --units 10000 \
+  --format json
+farthershore limit set <business-id> \
+  --limit-id <limit-id> --mode NOTIFY --units 20000 \
+  --notify-at 0.8 --format json
+farthershore limit remove <business-id> <limit-id> --format json
 ```
 
+Changing a limit's scope, subject, or quantity requires removing and recreating
+the limit with the new target.
+
+Every `limit` command requires `FARTHERSHORE_CONSUMER_TOKEN`, containing the
+current portal consumer session token. Pass `--environment-id` and
+`--subscriber-organization`, or set their respective fallbacks
+`FARTHERSHORE_ENVIRONMENT_ID` and
+`FARTHERSHORE_SUBSCRIBER_ORGANIZATION_ID`. These subscriber-portal credentials
+are separate from the organization-scoped MakerToken used by the rest of the
+CLI and are never persisted automatically.
+
 ### `farthershore plan`
 
-Read code-managed plans and operate live subscriber migrations. The CLI does not
+Read code-managed plans. The CLI does not
 create, update, or delete plan definitions — edit the Business SDK program for
 that.
 
 ```bash
 farthershore plan list weather-api                   # table (default in TTY)
 farthershore plan list weather-api --format json
-
-# 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`
@@ -342,17 +539,18 @@ across billing, edge credentials, and subscriptions.
 
 ### `farthershore variables`
 
-Manage write-only private secrets with one exclusive delivery phase. `BUILD`
-values enter only the isolated managed build and are leak-scanned from its
-artifact. `RUNTIME` values stay out of builds and are injected only by Gateway
-for compiled, granted integrations.
+Manage platform-owned variables. The name is the class: an `FS_PUBLIC_` prefix
+makes a value public (inlined into the frontend bundle, readable by every
+visitor); any other name is a write-only secret — available to the isolated
+managed build (leak-scanned from its artifact) and injected by Gateway for any
+compiled integration that references it.
 
 ```bash
 farthershore variables list weather-api --format json
 printf '%s' "$SENTRY_AUTH_TOKEN" | farthershore variables set weather-api \
-  SENTRY_AUTH_TOKEN --delivery build --format json
-printf '%s' "$POSTHOG_SECRET" | farthershore variables set weather-api \
-  POSTHOG_SECRET --delivery runtime --format json
+  SENTRY_AUTH_TOKEN --format json
+printf '%s' "$POSTHOG_PROJECT_KEY" | farthershore variables set weather-api \
+  FS_PUBLIC_POSTHOG_KEY --format json
 farthershore variables revoke weather-api POSTHOG_SECRET --yes --format json
 farthershore variables rm weather-api POSTHOG_SECRET --yes --format json
 ```
@@ -387,7 +585,7 @@ Pair the token with
 your upstream:
 
 ```ts
-import { fartherShore, withUsage } from "@farthershore/backend";
+import { fartherShore } from "@farthershore/backend";
 
 const fs = fartherShore.initFromEnv();
 
@@ -395,7 +593,7 @@ export async function POST(request: Request) {
   const url = new URL(request.url);
   const body = await request.clone().arrayBuffer();
 
-  await fs.verifyRequest({
+  const ctx = await fs.verifyRequest({
     method: request.method,
     path: url.pathname,
     query: url.search,
@@ -404,17 +602,19 @@ export async function POST(request: Request) {
   });
 
   const result = await runWorkflow(await request.json());
-  return withUsage(request, Response.json(result), {
-    tokens_used: result.tokensUsed,
+  await ctx.report({
+    meter: "tokens_used",
+    values: { tokens_used: result.tokensUsed },
   });
+  return Response.json(result);
 }
 ```
 
 ### `farthershore webhook`
 
-Provision outbound webhook endpoints and inspect delivery health. If the business
-declares webhooks under `business/`, writes return
-`409 MANAGED_BY_CODE` so the repo stays canonical.
+Provision outbound webhook endpoints and inspect delivery health. Endpoints are
+platform-owned operate records: they never live in the managed repo, so these
+writes work the same for every business regardless of repo linkage.
 
 ```bash
 farthershore webhook list weather-api --format json
@@ -424,11 +624,38 @@ farthershore webhook create weather-api \
   --format json
 farthershore webhook update weather-api <webhookId> --disable --format json
 farthershore webhook test weather-api <webhookId> --format json
+farthershore webhook trigger weather-api <webhookId> --type payment.failed --format json
 farthershore webhook deliveries weather-api <webhookId> --limit 20 --format json
+farthershore webhook rotate weather-api <webhookId> --format json
 farthershore webhook delete weather-api <webhookId> --yes --format json
 ```
 
-`webhook create` returns the signing secret once; store it in the receiving app.
+`webhook create` and `webhook rotate` return the signing secret once; store it
+in the receiving app. In human mode they also print it as an
+`FS_WEBHOOK_SECRET=` line plus a `createWebhookHandler` snippet.
+
+`webhook test` sends the plain `webhook.test` ping. `webhook trigger --type`
+sends a signed, realistic sample of one catalog event (the deliveries log
+records it under that type) so every handler branch can be exercised locally.
+
+For a receiver on your machine, `webhook listen` is the Stripe-CLI-style loop:
+it opens a Cloudflare quick tunnel to `--forward-to`, creates a temporary
+endpoint on it, prints the endpoint id / tunnel URL / (with `--print-secret`)
+the `FS_WEBHOOK_SECRET=` line, tails deliveries as
+`time  type  status  responseStatus  id`, and deletes the endpoint on Ctrl-C.
+
+```bash
+farthershore webhook listen weather-api \
+  --forward-to http://localhost:3000/webhooks/farthershore \
+  --print-secret --trigger payment.failed
+farthershore webhook listen weather-api --forward-to localhost:3000/webhooks \
+  --events subscription.created,payment.failed --format json
+```
+
+`listen` needs `cloudflared` — bundled as an optional
+`@farthershore/cloudflared-<platform>` dependency, or on your PATH. It has no
+MCP tool (long-running, process-owning). A listener killed hard leaves an
+endpoint with a `*.trycloudflare.com` URL; `webhook delete --yes` removes it.
 
 ### `farthershore promo-code`
 
@@ -455,12 +682,12 @@ Use `--all-plans` to clear plan scoping.
 Install or refresh the platform-verified skills bundle together. The platform
 pins this immutable release, and CI plus a daily repository check compare it to
 GitHub's latest stable release so the guidance cannot silently drift.
-This command requires `@farthershore/cli` 0.31.1 or newer.
+This command requires `@farthershore/cli` 0.33.0 or newer.
 
 ```bash
 farthershore skills install --help
 # If the command is unavailable, upgrade to the required CLI release:
-npm install -g @farthershore/cli@0.31.1
+npm install -g @farthershore/cli@0.33.0
 farthershore skills install
 ```
 
@@ -512,9 +739,9 @@ The MCP server (`farthershore-mcp`) projects its tools from the same operation
 registry that defines the CLI commands. Every MCP tool has a CLI sibling, but
 not every CLI command is exposed through MCP. Tool names use the `fs_*` prefix
 and cover only operations explicitly marked agent-operable in that registry.
-Organization, role, member, and invitation administration requires a live-user
-CLI session and is not projected into MCP; audit logs, notifications, and apply
-timelines are also CLI-only.
+Organization, role, member, invitation, and org MakerToken administration
+requires a live-user CLI session and is not projected into MCP; audit logs,
+notifications, and apply timelines are also CLI-only.
 
 ```bash
 farthershore-mcp