@farthershore/cli 0.3.8 → 0.3.10

package/dist/commands/apply.js

@@ -223,6 +223,17 @@ export function registerApplyCommand(program, getClient) {
         "Automatically scopes to the current git branch so env branches compile against their own plans.")
         .option("--branch <branch>", "Override the branch used for env-scoped compilation (default: auto-detected)")
         .option("--dry-run", "Run local validation and remote compile without applying product state")
+        .addHelpText("after", `
+Agent notes:
+  apply first validates local product.yaml when it matches the target product, then asks core to compile the pushed branch state.
+  Unpushed local edits are not included in remote compile. Push or use CLI config commands for API-backed changes.
+  Use --format json for stable output: ok, success, errors, warnings, nextActions.
+
+Examples:
+  farthershore apply --dry-run --format json
+  farthershore apply my-weather-api --dry-run --format json
+  farthershore apply my-weather-api --branch feature/billing-change --dry-run --format json
+`)
         .action(async (productArg, opts) => {
         const client = getClient();
         const globalFormat = program.opts().format;

package/dist/commands/billing.js

@@ -1,10 +1,34 @@
 import { loadAcceptedSpec, objectAt, printResult, resolveProductId, updateSpec, } from "./helpers.js";
 export function registerBillingCommands(program, getClient) {
-    const billing = program.command("billing").description("Manage billing");
-    const strategy = billing.command("strategy").description("Billing strategy");
+    const billing = program
+        .command("billing")
+        .description("Manage product-level billing strategy and transition policy")
+        .addHelpText("after", `
+Agent notes:
+  Billing strategy is product-level for paid plans. Paid plans should not mix strategies.
+  Strategies: free_trial, flat_subscription, included_usage, subscription_overage, pay_as_you_go, prepaid_credits.
+  Subscriber actions: preserve_current_period, switch_immediately, switch_immediately_prorate, new_subscribers_only.
+
+Examples:
+  farthershore billing strategy get --format json
+  farthershore billing strategy set prepaid_credits --transition preserve_current_period --format json
+  farthershore billing policy set --default preserve_current_period --proration none --format json
+`);
+    const strategy = billing
+        .command("strategy")
+        .description("Get or set the product-level billing strategy")
+        .addHelpText("after", `
+Examples:
+  farthershore billing strategy get --format json
+  farthershore billing strategy set subscription_overage --format json
+`);
     strategy
         .command("get")
         .option("--product <product>", "Product id or name")
+        .addHelpText("after", `
+Example:
+  farthershore billing strategy get --format json
+`)
         .action(async (opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);
@@ -18,9 +42,14 @@ export function registerBillingCommands(program, getClient) {
     strategy
         .command("set <strategy>")
         .option("--product <product>", "Product id or name")
-        .option("--transition <action>", "Default subscriber transition action", "preserve_current_period")
+        .option("--transition <action>", "Default subscriber transition action: preserve_current_period, switch_immediately, switch_immediately_prorate, new_subscribers_only", "preserve_current_period")
         .option("--proration <mode>", "Proration mode", "none")
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Examples:
+  farthershore billing strategy set prepaid_credits --transition preserve_current_period --format json
+  farthershore billing strategy set pay_as_you_go --dry-run --format json
+`)
         .action(async (nextStrategy, opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);
@@ -36,12 +65,23 @@ export function registerBillingCommands(program, getClient) {
             message: "Billing strategy updated",
         });
     });
-    billing
-        .command("policy set")
+    const policy = billing
+        .command("policy")
+        .description("Set subscriber change policy defaults")
+        .addHelpText("after", `
+Example:
+  farthershore billing policy set --default preserve_current_period --proration none --format json
+`);
+    policy
+        .command("set")
         .option("--product <product>", "Product id or name")
-        .option("--default <action>", "Default subscriber action", "preserve_current_period")
+        .option("--default <action>", "Default subscriber action: preserve_current_period, switch_immediately, switch_immediately_prorate, new_subscribers_only", "preserve_current_period")
         .option("--proration <mode>", "Proration mode", "none")
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Example:
+  farthershore billing policy set --default preserve_current_period --proration none --format json
+`)
         .action(async (opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);

package/dist/commands/feature.js

@@ -1,9 +1,25 @@
 import { findPlan, loadAcceptedSpec, objectAt, printResult, resolveProductId, stringArrayAt, updateSpec, } from "./helpers.js";
 export function registerFeatureCommands(program, getClient) {
-    const feature = program.command("feature").description("Manage features");
+    const feature = program
+        .command("feature")
+        .description("Manage route-bound product features")
+        .addHelpText("after", `
+Agent notes:
+  Features gate routes. Add a feature with one or more METHOD:/path routes, then bind it to plans.
+  Use METHOD:* only when the feature should cover all methods for a path.
+
+Examples:
+  farthershore feature add chat_completions --route POST:/v1/chat/completions --format json
+  farthershore feature bind chat_completions --plan pro --format json
+  farthershore feature list --format json
+`);
     feature
         .command("list")
         .option("--product <product>", "Product id or name")
+        .addHelpText("after", `
+Example:
+  farthershore feature list --format json
+`)
         .action(async (opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);
@@ -19,6 +35,11 @@ export function registerFeatureCommands(program, getClient) {
         .option("--product <product>", "Product id or name")
         .option("--route <route>", "Route binding METHOD:/path; repeatable", collect, [])
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Examples:
+  farthershore feature add chat_completions --route POST:/v1/chat/completions --format json
+  farthershore feature add weather_read --route GET:/v1/weather --route GET:/v1/forecast --dry-run --format json
+`)
         .action(async (key, opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);
@@ -35,6 +56,10 @@ export function registerFeatureCommands(program, getClient) {
         .requiredOption("--plan <plan>", "Plan key")
         .option("--product <product>", "Product id or name")
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Example:
+  farthershore feature bind chat_completions --plan pro --format json
+`)
         .action(async (key, opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);
@@ -53,6 +78,10 @@ export function registerFeatureCommands(program, getClient) {
         .requiredOption("--plan <plan>", "Plan key")
         .option("--product <product>", "Product id or name")
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Example:
+  farthershore feature unbind chat_completions --plan starter --format json
+`)
         .action(async (key, opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);

package/dist/commands/login.js

@@ -4,10 +4,25 @@ import { loadConfig, saveConfig, saveCredentials, clearCredentials, } from "../c
 import { resolveToken } from "../auth.js";
 import * as output from "../output.js";
 export function registerAuthCommands(program) {
-    const auth = program.command("auth").description("Manage authentication");
+    const auth = program
+        .command("auth")
+        .description("Manage authentication")
+        .addHelpText("after", `
+Agent notes:
+  Prefer FARTHERSHORE_TOKEN in CI/agent environments. Use auth set-key for local persistent credentials.
+
+Examples:
+  farthershore auth set-key "$FARTHERSHORE_TOKEN"
+  farthershore whoami --format json
+`);
     auth
         .command("set-key [token]")
         .description("Set your API token")
+        .addHelpText("after", `
+Examples:
+  farthershore auth set-key mk_xxx
+  farthershore auth set-key "$FARTHERSHORE_TOKEN"
+`)
         .action(async (tokenArg) => {
         await setKey(tokenArg);
     });

package/dist/commands/meter.js

@@ -1,9 +1,25 @@
 import { loadAcceptedSpec, objectAt, printResult, resolveProductId, updateSpec, } from "./helpers.js";
 export function registerMeterCommands(program, getClient) {
-    const meter = program.command("meter").description("Manage usage meters");
+    const meter = program
+        .command("meter")
+        .description("Manage product usage meters and rating sources")
+        .addHelpText("after", `
+Agent notes:
+  Meters define what usage is measured. Plans reference meters; plans do not define provider-specific rates.
+  Rating sources: fixed, provider_catalog, upstream_reported, external_rate_api, custom.
+
+Examples:
+  farthershore meter add ai_tokens --selector model --measure input_tokens --measure output_tokens --rating provider_catalog --catalog llm_models --format json
+  farthershore meter add requests --measure count --rating fixed --format json
+  farthershore meter list --format json
+`);
     meter
         .command("list")
         .option("--product <product>", "Product id or name")
+        .addHelpText("after", `
+Example:
+  farthershore meter list --format json
+`)
         .action(async (opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);
@@ -20,12 +36,18 @@ export function registerMeterCommands(program, getClient) {
         .option("--product <product>", "Product id or name")
         .option("--selector <field>", "Selector field, for example model")
         .option("--measure <measure>", "Measure name; repeatable", collect, [])
-        .option("--rating <source>", "Rating source", "fixed")
+        .option("--rating <source>", "Rating source: fixed, provider_catalog, upstream_reported, external_rate_api, custom", "fixed")
         .option("--catalog <catalog>", "Catalog key for provider_catalog rating")
         .option("--resolver <resolver>", "Resolver id for external/custom rating")
         .option("--amount-field <path>", "Amount field for upstream_reported rating")
         .option("--currency-field <path>", "Currency field for upstream_reported rating")
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Examples:
+  farthershore meter add ai_tokens --selector model --measure input_tokens --measure output_tokens --rating provider_catalog --catalog llm_models --format json
+  farthershore meter add requests --measure count --rating fixed --dry-run --format json
+  farthershore meter add upstream_cost --measure cost_micros --rating upstream_reported --amount-field usage.cost_micros --format json
+`)
         .action(async (key, opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);
@@ -45,12 +67,17 @@ export function registerMeterCommands(program, getClient) {
     meter
         .command("rating set <key>")
         .option("--product <product>", "Product id or name")
-        .requiredOption("--rating <source>", "Rating source")
+        .requiredOption("--rating <source>", "Rating source: fixed, provider_catalog, upstream_reported, external_rate_api, custom")
         .option("--catalog <catalog>", "Catalog key for provider_catalog rating")
         .option("--resolver <resolver>", "Resolver id for external/custom rating")
         .option("--amount-field <path>", "Amount field for upstream_reported rating")
         .option("--currency-field <path>", "Currency field for upstream_reported rating")
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Examples:
+  farthershore meter rating set ai_tokens --rating provider_catalog --catalog llm_models --format json
+  farthershore meter rating set upstream_cost --rating upstream_reported --amount-field usage.cost_micros --dry-run --format json
+`)
         .action(async (key, opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);

package/dist/commands/plan.js

@@ -1,9 +1,27 @@
 import { findPlan, loadAcceptedSpec, plans, printResult, resolveProductId, stringArrayAt, updateSpec, } from "./helpers.js";
 export function registerPlanCommands(program, getClient) {
-    const plan = program.command("plan").description("Manage product plans");
+    const plan = program
+        .command("plan")
+        .description("Manage free and paid plans in the accepted product config")
+        .addHelpText("after", `
+Agent notes:
+  Plans are keyed by plan name/key, not by usage type.
+  Only one free plan is allowed. Free plans should include a hard enforced limit.
+  Duplicate paid prices are rejected server-side. Use --dry-run before risky changes.
+  Limit format is meter:window:capacity:enforcement, for example ai_tokens:month:100000:enforce.
+
+Examples:
+  farthershore plan add free --free --limit ai_tokens:month:100000:enforce --feature chat_completions --format json
+  farthershore plan add pro --price-monthly 2900 --credits-monthly-micros 500000000 --meter ai_tokens --feature chat_completions --format json
+  farthershore plan list --format json
+`);
     plan
         .command("list")
         .option("--product <product>", "Product id or name")
+        .addHelpText("after", `
+Example:
+  farthershore plan list --format json
+`)
         .action(async (opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);
@@ -25,6 +43,12 @@ export function registerPlanCommands(program, getClient) {
         .option("--feature <feature>", "Enabled feature; repeatable", collect, [])
         .option("--limit <limit>", "Limit meter:window:capacity:enforcement; repeatable", collect, [])
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Examples:
+  farthershore plan add free --free --limit ai_tokens:month:100000:enforce --feature chat_completions --format json
+  farthershore plan add pro --price-monthly 2900 --credits-monthly-micros 500000000 --meter ai_tokens --feature chat_completions --format json
+  farthershore plan add starter --price-monthly 900 --meter requests --feature weather_read --dry-run --format json
+`)
         .action(async (key, opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);
@@ -47,6 +71,10 @@ export function registerPlanCommands(program, getClient) {
         .requiredOption("--monthly <cents>", "Monthly price in cents", parseInteger)
         .option("--currency <currency>", "Currency", "USD")
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Example:
+  farthershore plan set-price pro --monthly 4900 --dry-run --format json
+`)
         .action(async (key, opts) => {
         await mutatePlan(program, getClient(), opts.product, key, opts.dryRun, (plan) => {
             plan.free = false;
@@ -63,6 +91,11 @@ export function registerPlanCommands(program, getClient) {
         .option("--product <product>", "Product id or name")
         .requiredOption("--limit <limit>", "Limit meter:window:capacity:enforcement")
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Examples:
+  farthershore plan set-limit free --limit ai_tokens:month:100000:enforce --format json
+  farthershore plan set-limit pro --limit ai_tokens:month:1000000:track --dry-run --format json
+`)
         .action(async (key, opts) => {
         await mutatePlan(program, getClient(), opts.product, key, opts.dryRun, (plan) => {
             const next = parseLimit(opts.limit);
@@ -82,6 +115,10 @@ export function registerPlanCommands(program, getClient) {
         .option("--product <product>", "Product id or name")
         .requiredOption("--monthly-micros <micros>", "Monthly included credits", parseInteger)
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Example:
+  farthershore plan set-credits pro --monthly-micros 500000000 --format json
+`)
         .action(async (key, opts) => {
         await mutatePlan(program, getClient(), opts.product, key, opts.dryRun, (plan) => {
             plan.credits = { monthlyIncludedMicros: opts.monthlyMicros };
@@ -92,6 +129,10 @@ export function registerPlanCommands(program, getClient) {
         .argument("<feature>")
         .option("--product <product>", "Product id or name")
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Example:
+  farthershore plan add-feature pro chat_completions --format json
+`)
         .action(async (key, feature, opts) => {
         await mutatePlan(program, getClient(), opts.product, key, opts.dryRun, (plan) => {
             const features = stringArrayAt(plan, "features");
@@ -104,6 +145,10 @@ export function registerPlanCommands(program, getClient) {
         .argument("<feature>")
         .option("--product <product>", "Product id or name")
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Example:
+  farthershore plan remove-feature starter chat_completions --dry-run --format json
+`)
         .action(async (key, feature, opts) => {
         await mutatePlan(program, getClient(), opts.product, key, opts.dryRun, (plan) => {
             plan.features = stringArrayAt(plan, "features").filter((candidate) => candidate !== feature);
@@ -113,6 +158,10 @@ export function registerPlanCommands(program, getClient) {
         .command("remove <key>")
         .option("--product <product>", "Product id or name")
         .option("--dry-run", "Validate without mutating")
+        .addHelpText("after", `
+Example:
+  farthershore plan remove starter --dry-run --format json
+`)
         .action(async (key, opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);

package/dist/commands/product.js

@@ -2,15 +2,38 @@ import { saveConfig } from "../config.js";
 import * as output from "../output.js";
 import { commandFormat, printResult, resolveProductId } from "./helpers.js";
 export function registerProductCommands(program, getClient) {
-    const product = program.command("product").description("Manage products");
+    const product = program
+        .command("product")
+        .description("Manage products and inspect the latest accepted internal product config")
+        .addHelpText("after", `
+Agent notes:
+  Product commands use core APIs, not local files. After product create, the product is selected in ~/.farthershore/config.json.
+  GitHub, UI, and CLI edits are proposals. product config/status read the accepted internal config.
+
+Examples:
+  farthershore product create weather-api --base-url https://api.example.com --strategy prepaid_credits --format json
+  farthershore product status --format json
+  farthershore product config --format yaml
+  farthershore product attempts --format json
+`);
     product
         .command("create <name>")
-        .description("Create a product and select it for subsequent CLI commands")
+        .description("Create a product, initialize accepted config, and select it for later commands")
         .requiredOption("--base-url <url>", "Backend API base URL")
-        .option("--strategy <strategy>", "Product billing strategy", "flat_subscription")
+        .option("--strategy <strategy>", "Product billing strategy: free_trial, flat_subscription, included_usage, subscription_overage, pay_as_you_go, prepaid_credits", "flat_subscription")
         .option("--description <desc>", "Product description")
         .option("--display-name <name>", "Display name")
         .option("--dry-run", "Print the create request without mutating")
+        .addHelpText("after", `
+Examples:
+  farthershore product create weather-api --base-url https://api.example.com --format json
+  farthershore product create ai-gateway --base-url https://api.example.com --strategy prepaid_credits --format json
+
+Next commands:
+  farthershore meter add --help
+  farthershore feature add --help
+  farthershore plan add --help
+`)
         .action(async (name, opts) => {
         if (opts.dryRun) {
             printResult(program, "Product create dry run", {
@@ -64,6 +87,10 @@ export function registerProductCommands(program, getClient) {
         .command("status")
         .description("Show selected product status")
         .option("--product <product>", "Product id or name")
+        .addHelpText("after", `
+Example:
+  farthershore product status --format json
+`)
         .action(async (opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);
@@ -76,9 +103,14 @@ export function registerProductCommands(program, getClient) {
     });
     product
         .command("config")
-        .description("Show latest accepted internal product config")
+        .description("Show latest accepted internal product config as json or yaml")
         .option("--product <product>", "Product id or name")
         .option("--format <format>", "Output format: json or yaml")
+        .addHelpText("after", `
+Examples:
+  farthershore product config --format json
+  farthershore product config --format yaml
+`)
         .action(async (opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);
@@ -93,6 +125,10 @@ export function registerProductCommands(program, getClient) {
         .command("attempts")
         .description("Show rejected product config attempts")
         .option("--product <product>", "Product id or name")
+        .addHelpText("after", `
+Example:
+  farthershore product attempts --format json
+`)
         .action(async (opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);

package/dist/commands/transition.js

@@ -7,13 +7,30 @@ import { analyzePlanTransition } from "./plan-transition.js";
 export function registerTransitionCommands(program, getClient) {
     const transition = program
         .command("transition")
-        .description("Preview subscriber impact for product config changes");
+        .description("Preview subscriber impact for product config changes")
+        .addHelpText("after", `
+Agent notes:
+  New subscribers use accepted config immediately. Existing subscribers follow billing.subscriberChangePolicy.
+  Preview before price, feature, limit, credit, rating, or strategy changes.
+
+Examples:
+  farthershore transition preview --format json
+  farthershore transition preview --to product.yaml --format json
+`);
     transition
         .command("preview")
         .description("Compare the latest accepted config to a proposed config and show subscriber transition impact")
         .option("--product <product>", "Product id or name")
         .option("--to <file>", "Proposed product YAML file")
         .option("--format <format>", "Output format: table or json")
+        .addHelpText("after", `
+Examples:
+  farthershore transition preview --format json
+  farthershore transition preview --to product.yaml --format json
+
+Output includes:
+  ok, productId, transitionPreview, errors, warnings, nextActions
+`)
         .action(async (opts) => {
         const client = getClient();
         const productId = await resolveProductId(client, opts.product);

package/dist/commands/validate.js

@@ -170,7 +170,17 @@ function reportValidationResult(result) {
 export function registerValidateCommand(program) {
     program
         .command("validate [file]")
-        .description("Validate a local product.yaml file")
+        .description("Validate a local product.yaml file without API calls")
+        .addHelpText("after", `
+Agent notes:
+  Use validate before committing product.yaml changes. This is local schema validation only.
+  Use apply --dry-run for remote compiler validation against pushed branch state.
+
+Examples:
+  farthershore validate
+  farthershore validate product.yaml
+  farthershore apply --dry-run --format json
+`)
         // Action body is sync; commander only requires a thenable on
         // .action when await is used. Drop `async` keyword.
         .action((file) => {

package/dist/index.js

@@ -24,11 +24,38 @@ const pkg = JSON.parse(await readFile(join(__dirname, "..", "package.json"), "ut
 const program = new Command();
 program
     .name("farthershore")
-    .description("FartherShore CLI — create and manage API products")
+    .description("FartherShore CLI — agent-friendly commands to create, configure, validate, and launch API products")
     .version(pkg.version)
     .option("--token <token>", "Override auth token")
     .option("--api-url <url>", "Override API base URL")
-    .option("--format <format>", "Output format: table, json");
+    .option("--format <format>", "Output format. Use --format json for stable machine-readable agent output")
+    .addHelpText("after", `
+Agent discovery:
+  Start with:
+    farthershore --help
+    farthershore product --help
+    farthershore meter add --help
+    farthershore feature add --help
+    farthershore plan add --help
+    farthershore transition preview --help
+    farthershore apply --help
+
+Agent end-to-end API workflow:
+  farthershore auth set-key "$FARTHERSHORE_TOKEN"
+  farthershore product create weather-api --base-url https://api.example.com --strategy prepaid_credits --format json
+  farthershore meter add ai_tokens --selector model --measure input_tokens --measure output_tokens --rating provider_catalog --catalog llm_models --format json
+  farthershore feature add chat_completions --route POST:/v1/chat/completions --format json
+  farthershore plan add free --free --limit ai_tokens:month:100000:enforce --feature chat_completions --format json
+  farthershore plan add pro --price-monthly 2900 --credits-monthly-micros 500000000 --meter ai_tokens --feature chat_completions --format json
+  farthershore transition preview --format json
+  farthershore apply --dry-run --format json
+  farthershore product status --format json
+
+Useful constants:
+  Billing strategies: free_trial, flat_subscription, included_usage, subscription_overage, pay_as_you_go, prepaid_credits
+  Rating sources: fixed, provider_catalog, upstream_reported, external_rate_api, custom
+  Transition actions: preserve_current_period, switch_immediately, switch_immediately_prorate, new_subscribers_only
+`);
 // Lazy client — created on first use with resolved auth
 function getClient() {
     const config = loadConfig();

package/node_modules/@farther-shore/shared-types/README.md

@@ -0,0 +1,63 @@
+# @farther-shore/shared-types
+
+Cross-repo TypeScript DTOs and Zod schemas. Published to GitHub
+Packages as `@farther-shore/shared-types`. Consumed by every other
+repo that needs to talk to `core`.
+
+For the rationale (drift becomes a TypeScript compile error, not a
+runtime bug), see [`/docs/conventions.md §11`](../docs/conventions.md#11-schema-first-via-shared-types).
+
+For agent-specific repo guidance, see [`AGENTS.md`](AGENTS.md).
+
+## Subpath layout
+
+| Subpath | Consumers | Contents |
+|---|---|---|
+| `@farther-shore/shared-types` | core (root) | shared primitives, `MeterDefinition`, `NamedWindow` |
+| `@farther-shore/shared-types/edge-kv-keys` | core publisher + gateway reader | KV key builders, payload shapes, `wrapEnvelope` / `readEnvelope`, `KV_KEY_SCHEMA_VERSION` |
+| `@farther-shore/shared-types/plans` | web-ui form, core compiler, CLI validate | `ProductSpec`, `PlanSpec`, `BuilderPlan`, the canonical Zod schemas |
+| `@farther-shore/shared-types/portal` | dev-portal | `PortalSubscriberContext`, `PortalPlan`, `PortalUsageResponse`, `PortalApiKey` |
+| `@farther-shore/shared-types/consumer` | web-ui My Subscriptions | `SubscriptionDto`, `SubscriptionsResponse` |
+| `@farther-shore/shared-types/builder-context` | web-ui builder bootstrap | `BuilderContext`, `BuilderMembership`, `PlatformPlan` |
+| `@farther-shore/shared-types/admin` | fs-admin | `PlanTemplate`, `PortalResolveResponse`, `DocsSection` |
+| `@farther-shore/shared-types/web-ui` | web-ui | `BuilderOrganization`, `Product`, `StripeStatus`, `PromoCode`, `CreateProductInput` |
+| `@farther-shore/shared-types/api` | all | `PaginatedResponse`, error response shapes |
+
+## Local dev / tests
+
+```bash
+npm install
+npm run build      # tsc → dist/
+npm test           # vitest type tests
+npm run lint
+```
+
+## Publish workflow
+
+1. Bump `version` in `package.json` (semver).
+2. Commit + push.
+3. `git tag v<x.y.z> && git push origin v<x.y.z>` — the tag triggers
+   the GitHub Actions publish workflow which pushes to GitHub
+   Packages.
+4. Bump the version in each consumer repo's `package.json` +
+   `npm install`. The version-tag is the canonical signal; pushing
+   to `main` alone does NOT publish.
+
+## Cross-repo dependencies
+
+- No imports from other internal packages.
+- Type-only — never imports runtime libraries (`zod` is a runtime
+  dep but only used for schema definitions).
+- Consumed by: `core`, `gateway`, `web-ui`, `dev-portal`, `fs-admin`,
+  `farthershore` (CLI), `sdk`, `fs-usage-consumer`, `fs-dlq-consumer`.
+
+## Adding a new type
+
+1. Add the type to the appropriate subpath module.
+2. If a new subpath is needed, add it to `package.json`'s `exports`
+   map (mirror the existing pattern).
+3. Bump version, tag, push tag.
+4. Bump consumers opportunistically.
+
+See [`/docs/conventions.md §11`](../docs/conventions.md#11-schema-first-via-shared-types)
+for the full pattern + common pitfalls.

package/node_modules/@farther-shore/shared-types/dist/admin.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Plan template — the editable scaffold an admin starts a Plan from.
+ *
+ * Returned by:
+ *   GET  /internal/admin/plan-templates           → { data: PlanTemplate[] }
+ *   GET  /internal/admin/plan-templates/:id       → PlanTemplate
+ *
+ * `_count.plans` is a relation aggregate (hydrated when the API joins the
+ * plans table). Other endpoints may omit it.
+ */
+export type PlanTemplate = {
+    id: string;
+    slug: string;
+    name: string;
+    description: string | null;
+    sortOrder: number;
+    published: boolean;
+    defaultConfig: Record<string, unknown>;
+    exposedFields: string[];
+    createdAt: string;
+    updatedAt: string;
+    _count?: {
+        plans: number;
+    };
+};
+//# sourceMappingURL=admin.d.ts.map

package/node_modules/@farther-shore/shared-types/dist/admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../src/admin.ts"],"names":[],"mappings":"AASA;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5B,CAAC"}

package/node_modules/@farther-shore/shared-types/dist/admin.js

@@ -0,0 +1,10 @@
+// ---------------------------------------------------------------------------
+// Admin types — internal-admin (fs-admin) DTOs served by core's
+// /internal/admin/* endpoints.
+//
+// Keep this surface narrow: only types that genuinely cross the
+// fs-admin ⇄ core boundary belong here. Internal helpers / view-model
+// shapes belong in the consuming repo.
+// ---------------------------------------------------------------------------
+export {};
+//# sourceMappingURL=admin.js.map

package/node_modules/@farther-shore/shared-types/dist/admin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.js","sourceRoot":"","sources":["../src/admin.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,gEAAgE;AAChE,+BAA+B;AAC/B,EAAE;AACF,gEAAgE;AAChE,sEAAsE;AACtE,uCAAuC;AACvC,8EAA8E"}