@farthershore/cli 0.9.1 → 0.10.0

package/README.md

@@ -101,9 +101,10 @@ manifest compiles.
 
 ### `farthershore build`
 
-Build a product-as-code `product/product.config.ts` with the repo-local
-`./node_modules/.bin/farthershore-manifest-build` binary. The command
-emits a Manifest IR envelope to `manifest-ir.json` by default.
+Build a product-as-code `product/product.config.ts` with the Product SDK
+manifest builder. The CLI first uses the builder installed under `product/`,
+then falls back to a root install. The command emits a Manifest IR envelope to
+`manifest-ir.json` by default.
 
 ```bash
 farthershore build
@@ -113,11 +114,17 @@ farthershore build --format json
 # Optional dry-run compile against core after the local build succeeds
 farthershore build --validate weather-api --format json
 farthershore build --validate weather-api --env preview --format json
+
+# Apply the accepted lifecycle state through core without relying on GitHub
+farthershore build --apply weather-api --format json
+farthershore build --apply weather-api --env preview --format json
 ```
 
 ### `farthershore product`
 
-Product lifecycle commands — direct API, no local manifest upload flow.
+Product 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
@@ -149,11 +156,17 @@ farthershore product compile weather-api --branch env/preview --format json
 ```
 
 `product create` provisions a managed GitHub repo and returns clone-URL +
-agent bootstrap instructions in the response. 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; variable-value meters (tokens, credits, spend)
-are settled from upstream `x-fs-cost-{key}` response headers.
+agent bootstrap instructions in the response. That repo is required for the
+starter `frontend/` project and normal customization workflow. Product SDK
+changes can be validated with `farthershore build --validate` and applied to the
+repo-backed product with `farthershore build --apply`.
+
+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/metering`.
 
 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:
@@ -239,6 +252,29 @@ Read recent usage off the management API.
 farthershore usage summary weather-api --format json
 ```
 
+### `farthershore metering-token`
+
+Provision runtime metering tokens for upstream services. Core stores only token
+hashes; the raw token is returned once and should be deployed as
+`FARTHERSHORE_METERING_TOKEN`.
+
+```bash
+farthershore metering-token list weather-api --format json
+farthershore metering-token create weather-api --name "prod-api" --format json
+farthershore metering-token create weather-api --name "preview-api" --env preview --format json
+farthershore metering-token revoke weather-api <tokenId> --yes --format json
+```
+
+Pair the token with `@farthershore/metering` in the upstream:
+
+```ts
+import { withUsage } from "@farthershore/metering";
+
+return withUsage(request, Response.json(result), {
+  tokens_used: result.tokensUsed,
+});
+```
+
 ### `farthershore connect`
 
 GitHub OAuth and Stripe Connect flows are browser-only. These commands