@farthershore/cli 0.3.11 → 0.3.12

package/README.md

@@ -107,13 +107,15 @@ farthershore product status --env preview --format json
 
 ### `farthershore product config`
 
-Print the latest accepted product config from FartherShore. GitHub, the
-UI, and the CLI are proposal surfaces; the accepted internal config is the
-valid source of truth.
+Print the accepted or draft product config from FartherShore. GitHub,
+the UI, MCP, and the CLI all write through the same validated internal
+config path. Accepted config is live; draft config is staged until
+`farthershore apply` publishes it.
 
 ```bash
 farthershore product config --format json
 farthershore product config --format yaml
+farthershore product config --state draft --format json
 farthershore product config --env preview --format json
 ```
 
@@ -130,7 +132,7 @@ farthershore product attempts --env preview --format json
 
 ### `farthershore meter`
 
-Create and manage usage meters on the accepted product config.
+Create and manage usage meters in the shared draft product config.
 
 ```bash
 farthershore meter add ai_tokens \
@@ -160,9 +162,10 @@ farthershore feature list --env preview --format json
 
 ### `farthershore plan`
 
-Create and update plans in the accepted product config. Server-side
+Create and update plans in the shared draft product config. Server-side
 validation remains authoritative for rules like one free plan, duplicate
-paid prices, and product-level billing strategy consistency.
+paid prices, and product-level billing strategy consistency before apply
+can publish.
 
 ```bash
 farthershore plan add free \
@@ -224,18 +227,38 @@ farthershore validate path/to/product.yaml
 
 ### `farthershore apply [product]`
 
-Validate the current repo's `product.yaml` first when applying that repo's product, then run the server-side compiler against the pushed branch state for the product. Unpushed local edits are not part of the remote compile. Returns compilation errors and warnings. Exits with code 1 on failure — suitable for CI checks before merging.
+Publish the shared server draft as one product release. Core accepts the
+release only after schema validation, transition-safety validation, and a
+compiler dry-run pass. Mutation commands such as `meter add`,
+`feature add`, and `plan set-price` stage draft changes by default; they
+do not create live product or plan versions until `apply`.
 
 ```bash
-# Inside a product repo (auto-detects from product.yaml)
+# Publish the current shared draft
 farthershore apply
 
-# Or pass the product slug
+# Or pass the product slug explicitly
 farthershore apply my-weather-api
 
-# Validate and remote-compile without applying
+# Validate and compile the draft without publishing
 farthershore apply --dry-run --format json
 farthershore apply --env preview --dry-run --format json
+
+# Submit a local product.yaml as a one-off proposal
+farthershore apply --to product.yaml --dry-run --format json
+farthershore apply --to product.yaml --format json
+
+# Also save that local file as the shared draft before publishing
+farthershore apply --to product.yaml --save-draft --format json
+```
+
+Draft commands help agents inspect and control the release boundary:
+
+```bash
+farthershore draft status --format json
+farthershore draft diff --format json
+farthershore draft validate --format json
+farthershore draft reset --format json
 ```
 
 ## MCP tools
@@ -324,8 +347,10 @@ farthershore plan add pro \
   --meter ai_tokens \
   --feature chat_completions \
   --format json
+farthershore draft validate --format json
 farthershore transition preview --format json
 farthershore apply --dry-run --format json
+farthershore apply --format json
 farthershore product status --format json
 ```