@quonfig/cli 0.0.4 → 0.0.5

package/README.md

@@ -14,7 +14,7 @@ $ npm install -g @quonfig/cli
 $ qfg COMMAND
 running command...
 $ qfg (--version)
-@quonfig/cli/0.0.4 linux-x64 node-v24.4.1
+@quonfig/cli/0.0.5 linux-x64 node-v24.4.1
 $ qfg --help [COMMAND]
 USAGE
   $ qfg COMMAND
@@ -25,6 +25,7 @@ USAGE
 # Commands
 
 <!-- commands -->
+* [`qfg config-schema`](#qfg-config-schema)
 * [`qfg create NAME`](#qfg-create-name)
 * [`qfg download`](#qfg-download)
 * [`qfg generate`](#qfg-generate)
@@ -43,15 +44,45 @@ USAGE
 * [`qfg schema NAME`](#qfg-schema-name)
 * [`qfg serve DATA-FILE`](#qfg-serve-data-file)
 * [`qfg set-default [NAME]`](#qfg-set-default-name)
+* [`qfg set-rollout [NAME]`](#qfg-set-rollout-name)
 * [`qfg sync`](#qfg-sync)
 * [`qfg verify [PATH]`](#qfg-verify-path)
 * [`qfg whoami`](#qfg-whoami)
 * [`qfg workspace`](#qfg-workspace)
 * [`qfg workspace bootstrap`](#qfg-workspace-bootstrap)
 
+## `qfg config-schema`
+
+Print the config file format reference: rules engine, operators, targeting criteria, segments, and weighted rollouts. Use --json-schema for the machine-readable JSON Schema document.
+
+```
+USAGE
+  $ qfg config-schema [--json] [--interactive] [--no-color] [--verbose] [--json-schema]
+
+FLAGS
+  --json-schema  Output the full JSON Schema document for config files instead of the human-readable reference
+
+GLOBAL FLAGS
+  --[no-]interactive  Force interactive mode
+  --json              Format output as json.
+  --no-color          Do not colorize output
+  --verbose           Verbose output
+
+DESCRIPTION
+  Print the config file format reference: rules engine, operators, targeting criteria, segments, and weighted rollouts.
+  Use --json-schema for the machine-readable JSON Schema document.
+
+EXAMPLES
+  $ qfg config-schema                  # human-readable operator reference + examples
+
+  $ qfg config-schema --json-schema    # full JSON Schema document (copy into your editor)
+```
+
+_See code: [src/commands/config-schema.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/config-schema.ts)_
+
 ## `qfg create NAME`
 
-Create a new item in Quonfig
+Create a new feature flag, config value, or other item.
 
 ```
 USAGE
@@ -80,7 +111,26 @@ GLOBAL FLAGS
       --verbose           Verbose output
 
 DESCRIPTION
-  Create a new item in Quonfig
+  Create a new feature flag, config value, or other item.
+
+  Use --type to specify the kind of item:
+  boolean-flag  On/off feature flag (sendToClientSdk defaults to true; best for gradual rollouts)
+  string        A string configuration value
+  int           An integer configuration value
+  double        A floating-point configuration value
+  string-list   A comma-separated list of strings
+  json          An arbitrary JSON blob
+  boolean       A plain boolean (not a feature flag)
+
+  This sets the global default value. Override per-environment with:
+  qfg set-default my.flag --environment production --value true
+
+  For a percentage rollout (gradual rollout / A/B test / canary deploy), use:
+  qfg set-rollout my.flag --environment production --true-percent 20
+
+  Or edit the JSON config file directly for complex targeting rules:
+  qfg config-schema          # full operator reference + examples
+  qfg pull --dir ./config    # clone workspace, then edit JSON and git push
 
 EXAMPLES
   $ qfg create my.new.flag --type boolean-flag
@@ -94,9 +144,13 @@ EXAMPLES
   $ qfg create my.new.string --type string --env-var=MY_ENV_VAR_NAME
 
   $ qfg create my.new.string --type json --value="{\"key\": \"value\"}"
+
+  # After creating a flag, set a 20% rollout in production:
+
+  $ qfg set-rollout my.new.flag --environment production --true-percent 20
 ```
 
-_See code: [src/commands/create.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/create.ts)_
+_See code: [src/commands/create.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/create.ts)_
 
 ## `qfg download`
 
@@ -129,7 +183,7 @@ EXAMPLES
   $ qfg download --environment=test --sdk-key=YOUR_SDK_KEY
 ```
 
-_See code: [src/commands/download.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/download.ts)_
+_See code: [src/commands/download.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/download.ts)_
 
 ## `qfg generate`
 
@@ -199,7 +253,7 @@ EXAMPLES
   $ qfg generate --targets node-ts -o ./dist # combine with targets
 ```
 
-_See code: [src/commands/generate.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/generate.ts)_
+_See code: [src/commands/generate.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/generate.ts)_
 
 ## `qfg generate-new-hex-key`
 
@@ -222,7 +276,7 @@ EXAMPLES
   $ qfg generate-new-hex-key
 ```
 
-_See code: [src/commands/generate-new-hex-key.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/generate-new-hex-key.ts)_
+_See code: [src/commands/generate-new-hex-key.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/generate-new-hex-key.ts)_
 
 ## `qfg get [NAME]`
 
@@ -254,11 +308,11 @@ EXAMPLES
   $ qfg get my.config.name --environment=production
 ```
 
-_See code: [src/commands/get.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/get.ts)_
+_See code: [src/commands/get.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/get.ts)_
 
 ## `qfg info [NAME]`
 
-Show details about the provided config/feature-flag/etc.
+Show current values, rules, and evaluation stats for a flag or config.
 
 ```
 USAGE
@@ -278,13 +332,27 @@ GLOBAL FLAGS
       --verbose           Verbose output
 
 DESCRIPTION
-  Show details about the provided config/feature-flag/etc.
+  Show current values, rules, and evaluation stats for a flag or config.
+
+  Output shows the value for each environment:
+  - A simple value (true / false / "hello") means a single unconditional rule.
+  - "[see rules]" means the environment has targeting rules or a percentage rollout.
+  - "[inherit]" means the environment falls back to the Default value.
+
+  Percentage rollouts are displayed as "20.0% true, 80.0% false".
+  Evaluation counts for the past 24 hours are included by default.
+
+  Related commands:
+  qfg set-default my.flag --environment production --value true   # set a scalar fallback
+  qfg set-rollout my.flag --environment production --true-percent 20  # set a % rollout
 
 EXAMPLES
   $ qfg info my.config.name
+
+  $ qfg info my.config.name --exclude-evaluations   # skip 24h stats
 ```
 
-_See code: [src/commands/info.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/info.ts)_
+_See code: [src/commands/info.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/info.ts)_
 
 ## `qfg init [DIRECTORY]`
 
@@ -322,7 +390,7 @@ EXAMPLES
   $ qfg init --dry-run
 ```
 
-_See code: [src/commands/init.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/init.ts)_
+_See code: [src/commands/init.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/init.ts)_
 
 ## `qfg interactive`
 
@@ -340,7 +408,7 @@ EXAMPLES
   $ qfg
 ```
 
-_See code: [src/commands/interactive.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/interactive.ts)_
+_See code: [src/commands/interactive.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/interactive.ts)_
 
 ## `qfg list`
 
@@ -377,7 +445,7 @@ EXAMPLES
   $ qfg list --feature-flags
 ```
 
-_See code: [src/commands/list.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/list.ts)_
+_See code: [src/commands/list.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/list.ts)_
 
 ## `qfg login`
 
@@ -405,7 +473,7 @@ EXAMPLES
   $ qfg login --profile myprofile
 ```
 
-_See code: [src/commands/login.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/login.ts)_
+_See code: [src/commands/login.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/login.ts)_
 
 ## `qfg logout`
 
@@ -428,7 +496,7 @@ EXAMPLES
   $ qfg logout
 ```
 
-_See code: [src/commands/logout.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/logout.ts)_
+_See code: [src/commands/logout.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/logout.ts)_
 
 ## `qfg mcp`
 
@@ -461,7 +529,7 @@ EXAMPLES
   $ qfg mcp --url http://local-app.quonfig-staging.com:3003/api/v1/mcp
 ```
 
-_See code: [src/commands/mcp.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/mcp.ts)_
+_See code: [src/commands/mcp.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/mcp.ts)_
 
 ## `qfg override [NAME]`
 
@@ -500,7 +568,7 @@ EXAMPLES
   $ qfg override my.double.config --value=3.14159
 ```
 
-_See code: [src/commands/override.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/override.ts)_
+_See code: [src/commands/override.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/override.ts)_
 
 ## `qfg profile`
 
@@ -523,11 +591,11 @@ EXAMPLES
   $ qfg profile
 ```
 
-_See code: [src/commands/profile.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/profile.ts)_
+_See code: [src/commands/profile.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/profile.ts)_
 
 ## `qfg pull`
 
-Clone or update a local directory from the workspace Gitea repo
+Clone or update a local copy of your workspace config files.
 
 ```
 USAGE
@@ -544,7 +612,22 @@ GLOBAL FLAGS
   --verbose           Verbose output
 
 DESCRIPTION
-  Clone or update a local directory from the workspace Gitea repo
+  Clone or update a local copy of your workspace config files.
+
+  Use this when you need to edit flag JSON directly — for complex targeting rules,
+  multi-rule configs, or anything beyond a single scalar value.
+
+  For the config file format, operator reference, and examples:
+  qfg config-schema              # human-readable reference
+  qfg config-schema --json-schema  # machine-readable JSON Schema
+
+  After editing files:
+  qfg verify <dir>               # validate JSON before pushing
+  git -C <dir> add -A && git -C <dir> commit -m "feat: ..." && git -C <dir> push
+
+  CLI shortcuts (no JSON editing needed for simple cases):
+  qfg set-rollout my.flag --environment production --true-percent 20
+  qfg set-default my.flag --environment production --value true
 
 EXAMPLES
   $ qfg pull --dir ./our-config
@@ -552,7 +635,7 @@ EXAMPLES
   $ qfg pull  # uses QUONFIG_DIR env var
 ```
 
-_See code: [src/commands/pull.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/pull.ts)_
+_See code: [src/commands/pull.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/pull.ts)_
 
 ## `qfg schema NAME`
 
@@ -590,7 +673,7 @@ EXAMPLES
   $ qfg schema my-schema --set-json-schema=@schemas/my-schema.json --protected
 ```
 
-_See code: [src/commands/schema.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/schema.ts)_
+_See code: [src/commands/schema.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/schema.ts)_
 
 ## `qfg serve DATA-FILE`
 
@@ -626,11 +709,11 @@ EXAMPLES
   $ qfg serve ./quonfig.test.588.config.json --port=3099
 ```
 
-_See code: [src/commands/serve.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/serve.ts)_
+_See code: [src/commands/serve.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/serve.ts)_
 
 ## `qfg set-default [NAME]`
 
-Set/update the default value for an environment (other rules still apply)
+Set the unconditional fallback value for a flag or config in a specific environment.
 
 ```
 USAGE
@@ -658,19 +741,116 @@ GLOBAL FLAGS
       --verbose           Verbose output
 
 DESCRIPTION
-  Set/update the default value for an environment (other rules still apply)
+  Set the unconditional fallback value for a flag or config in a specific environment.
+
+  This updates the catch-all rule — the value users receive when NO targeting rule matches.
+  Any targeting rules or percentage rollouts you have configured are NOT affected; they
+  continue to fire before this fallback is evaluated.
+
+  "Other rules still apply" means: if you have rules targeting specific users, segments,
+  or properties, those rules still take priority. This command only changes what everyone
+  else sees.
+
+  To set a percentage rollout (gradual rollout / A/B test / canary deploy) instead:
+  qfg set-rollout my.flag --environment production --true-percent 20
+
+  To see all current values and rules for a flag:
+  qfg info my.flag
 
 EXAMPLES
-  $ qfg set-default my.flag.name # will prompt for value and env
+  $ qfg set-default my.flag.name                                          # prompts for value and env
 
   $ qfg set-default my.flag.name --value=true --environment=staging
 
+  $ qfg set-default my.flag.name --value=false --environment=production   # kill-switch: turn off for everyone
+
   $ qfg set-default my.flag.name --value=true --secret
 
   $ qfg set-default my.config.name --env-var=MY_ENV_VAR_NAME --environment=production
+
+  # For a percentage rollout, use set-rollout instead:
+
+  $ qfg set-rollout my.flag.name --environment production --true-percent 20
+```
+
+_See code: [src/commands/set-default.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/set-default.ts)_
+
+## `qfg set-rollout [NAME]`
+
+Configure a percentage rollout (gradual rollout / A/B test / canary deploy) for a flag.
+
+```
+USAGE
+  $ qfg set-rollout [NAME] [--json] [--interactive] [--no-color] [--verbose] [-p <value>] [--environment <value>]
+    [--hash-by <value>] [--true-percent <value>] [--weights <value>] [--confirm]
+
+ARGUMENTS
+  NAME  config/feature-flag/etc. name
+
+FLAGS
+  --confirm               skip the interactive confirmation prompt (useful for scripts and agents)
+  --environment=<value>   environment to update (e.g. production, staging)
+  --hash-by=<value>       [default: user.key] user property used to assign buckets (default: user.key)
+  --true-percent=<value>  percentage of users that receive true (0–100). Remaining users receive false. Boolean flags
+                          only.
+  --weights=<value>       comma-separated "value:percent" pairs that must sum to 100 (e.g. "true:20,false:80" or
+                          "red:33,green:33,blue:34")
+
+GLOBAL FLAGS
+  -p, --profile=<value>   Profile to use (defaults to ENV var QUONFIG_PROFILE or "default")
+      --[no-]interactive  Force interactive mode
+      --json              Format output as json.
+      --no-color          Do not colorize output
+      --verbose           Verbose output
+
+DESCRIPTION
+  Configure a percentage rollout (gradual rollout / A/B test / canary deploy) for a flag.
+
+  The flag must already exist. Create it first if needed:
+  qfg create my.flag --type boolean-flag
+
+  Weights are specified as whole-number percentages (0–100). They must sum to 100.
+
+  For a boolean flag, use --true-percent to set the percentage of users that receive
+  true (the remainder automatically receive false):
+  qfg set-rollout my.flag --environment production --true-percent 20
+  → 20% of users get true, 80% get false
+
+  For multi-value flags or custom splits, use --weights with a comma-separated list:
+  qfg set-rollout my.flag --environment production --weights "red:33,green:33,blue:34"
+
+  Hashing: users are bucketed by the value of hashByPropertyName (default: "user.key").
+  Use --hash-by to change which property drives the bucket assignment:
+  qfg set-rollout my.flag --environment production --true-percent 10 --hash-by user.id
+
+  For scripted / agent use, add --confirm to skip the interactive confirmation prompt.
+
+  To combine a rollout with segment targeting (e.g. beta ON, holdout OFF, everyone else 50/50),
+  you need to edit the JSON config file directly:
+  qfg config-schema           # operator reference + worked multi-rule example
+  qfg pull --dir ./config     # clone workspace to edit
+
+  To revert to a single value for everyone, use:
+  qfg set-default my.flag --environment production --value false
+
+  To inspect the current rollout:
+  qfg info my.flag
+
+EXAMPLES
+  $ qfg set-rollout my.feature.flag --environment production --true-percent 20
+
+  $ qfg set-rollout my.feature.flag --environment staging --true-percent 50
+
+  $ qfg set-rollout my.feature.flag --environment production --true-percent 100  # full rollout
+
+  $ qfg set-rollout my.feature.flag --environment production --true-percent 0    # kill switch (all false)
+
+  $ qfg set-rollout my.variant.flag --environment production --weights "control:50,treatment:50"
+
+  $ qfg set-rollout my.variant.flag --environment production --weights "a:33,b:33,c:34" --hash-by user.id
 ```
 
-_See code: [src/commands/set-default.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/set-default.ts)_
+_See code: [src/commands/set-rollout.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/set-rollout.ts)_
 
 ## `qfg sync`
 
@@ -702,7 +882,7 @@ EXAMPLES
   $ qfg sync --watch --dir ./our-config --interval 30
 ```
 
-_See code: [src/commands/sync.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/sync.ts)_
+_See code: [src/commands/sync.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/sync.ts)_
 
 ## `qfg verify [PATH]`
 
@@ -735,7 +915,7 @@ EXAMPLES
   $ qfg verify --json
 ```
 
-_See code: [src/commands/verify.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/verify.ts)_
+_See code: [src/commands/verify.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/verify.ts)_
 
 ## `qfg whoami`
 
@@ -758,7 +938,7 @@ EXAMPLES
   $ qfg whoami
 ```
 
-_See code: [src/commands/whoami.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/whoami.ts)_
+_See code: [src/commands/whoami.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/whoami.ts)_
 
 ## `qfg workspace`
 
@@ -781,7 +961,7 @@ EXAMPLES
   $ qfg workspace
 ```
 
-_See code: [src/commands/workspace.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/workspace.ts)_
+_See code: [src/commands/workspace.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/workspace.ts)_
 
 ## `qfg workspace bootstrap`
 
@@ -814,7 +994,7 @@ EXAMPLES
   $ qfg workspace bootstrap --dir ./our-config --skip-validate
 ```
 
-_See code: [src/commands/workspace/bootstrap.ts](https://github.com/quonfig/cli/blob/v0.0.4/src/commands/workspace/bootstrap.ts)_
+_See code: [src/commands/workspace/bootstrap.ts](https://github.com/quonfig/cli/blob/v0.0.5/src/commands/workspace/bootstrap.ts)_
 <!-- commandsstop -->
 
 ## Local Development

package/dist/commands/config-schema.d.ts

@@ -0,0 +1,10 @@
+import { BaseCommand } from '../index.js';
+import { JsonObj } from '../result.js';
+export default class ConfigSchema extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'json-schema': import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+    };
+    run(): Promise<JsonObj | void>;
+}

package/dist/commands/config-schema.js

@@ -0,0 +1,165 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../index.js';
+import { storedConfigJsonSchema } from '../init/schema.js';
+const REFERENCE = `
+────────────────────────────────────────────────────────────
+FILE LAYOUT
+────────────────────────────────────────────────────────────
+Config files live in your workspace (clone with: qfg pull --dir ./my-config):
+
+  feature-flags/   Boolean feature flags (on/off, targeting, percentage rollouts)
+  configs/         Typed config values (string, int, double, json, string-list)
+  segments/        User segments for targeting rules
+  log-levels/      Dynamic log-level configs
+
+────────────────────────────────────────────────────────────
+RULE EVALUATION
+────────────────────────────────────────────────────────────
+Rules are evaluated in ORDER — the FIRST matching rule wins.
+Put specific rules (user lists, segments) BEFORE catch-all rules.
+  criteria: []   means "match everyone" (unconditional / catch-all)
+  criteria: [..] multiple entries in one rule are ANDed together
+
+────────────────────────────────────────────────────────────
+EXAMPLE: complex targeting + rollout in production
+────────────────────────────────────────────────────────────
+Four rules in order:
+  1. Always ON  for users in an allowlist
+  2. Always ON  for users in the "beta" segment
+  3. Always OFF for users in the "holdout" segment
+  4. 50/50 split for everyone else
+
+  {
+    "key": "my.feature.flag",
+    "type": "feature_flag",
+    "valueType": "bool",
+    "default": {
+      "rules": [{ "criteria": [], "value": { "type": "bool", "value": false } }]
+    },
+    "environments": [{
+      "id": "production",
+      "rules": [
+        {
+          "criteria": [{
+            "operator": "PROP_IS_ONE_OF",
+            "propertyName": "user.key",
+            "valueToMatch": { "type": "string_list", "value": ["user-123", "user-456"] }
+          }],
+          "value": { "type": "bool", "value": true }
+        },
+        {
+          "criteria": [{
+            "operator": "IN_SEG",
+            "valueToMatch": { "type": "string", "value": "beta" }
+          }],
+          "value": { "type": "bool", "value": true }
+        },
+        {
+          "criteria": [{
+            "operator": "IN_SEG",
+            "valueToMatch": { "type": "string", "value": "holdout" }
+          }],
+          "value": { "type": "bool", "value": false }
+        },
+        {
+          "criteria": [],
+          "value": {
+            "type": "weighted_values",
+            "value": {
+              "hashByPropertyName": "user.key",
+              "weightedValues": [
+                { "value": { "type": "bool", "value": true },  "weight": 50000 },
+                { "value": { "type": "bool", "value": false }, "weight": 50000 }
+              ]
+            }
+          }
+        }
+      ]
+    }]
+  }
+
+────────────────────────────────────────────────────────────
+CRITERION FIELDS
+────────────────────────────────────────────────────────────
+Each criterion object has:
+  operator        (required) — see operator table below
+  propertyName    (required for PROP_* operators) — user property, e.g. "user.key", "user.plan"
+  valueToMatch    (required for all except ALWAYS_TRUE) — typed value to compare against
+
+────────────────────────────────────────────────────────────
+OPERATOR REFERENCE
+────────────────────────────────────────────────────────────
+  Operator                         valueToMatch type    Notes
+  ────────────────────────────────────────────────────────
+  ALWAYS_TRUE                      (none)               Unconditional match; use for catch-all rules
+  PROP_IS_ONE_OF                   string_list          propertyName value is in the list
+  PROP_IS_NOT_ONE_OF               string_list          propertyName value is NOT in the list
+  PROP_STARTS_WITH_ONE_OF          string_list          string prefix match
+  PROP_DOES_NOT_START_WITH_ONE_OF  string_list
+  PROP_ENDS_WITH_ONE_OF            string_list          string suffix match
+  PROP_DOES_NOT_END_WITH_ONE_OF    string_list
+  PROP_CONTAINS_ONE_OF             string_list          substring match
+  PROP_DOES_NOT_CONTAIN_ONE_OF     string_list
+  PROP_LESS_THAN                   int or double        numeric comparison
+  PROP_LESS_THAN_OR_EQUAL          int or double
+  PROP_GREATER_THAN                int or double
+  PROP_GREATER_THAN_OR_EQUAL       int or double
+  PROP_BEFORE                      string (ISO 8601)    date/time comparison
+  PROP_AFTER                       string (ISO 8601)
+  PROP_MATCHES                     string               regex match
+  PROP_DOES_NOT_MATCH              string
+  IN_SEG                           string               value = segment key (no propertyName needed)
+  NOT_IN_SEG                       string               value = segment key (no propertyName needed)
+  IN_INT_RANGE                     int_range            value = {min, max}
+  LOOKUP_KEY_IN                    string_list          matches if SDK lookup key is in the list
+  LOOKUP_KEY_NOT_IN                string_list
+
+valueToMatch format: { "type": "<type>", "value": <value> }
+  string_list  →  { "type": "string_list", "value": ["a", "b"] }
+  string       →  { "type": "string",      "value": "beta" }
+  int          →  { "type": "int",         "value": 42 }
+  double       →  { "type": "double",      "value": 3.14 }
+
+────────────────────────────────────────────────────────────
+PERCENTAGE ROLLOUT (weighted_values)
+────────────────────────────────────────────────────────────
+Weights are integers out of 100,000 (not percentages):
+  5%=5000  10%=10000  20%=20000  50%=50000  100%=100000
+  All weights in one rule MUST sum to exactly 100,000.
+
+hashByPropertyName controls the bucket assignment property (default: "user.key").
+
+────────────────────────────────────────────────────────────
+RELATED COMMANDS
+────────────────────────────────────────────────────────────
+  qfg create my.flag --type boolean-flag          create a new flag
+  qfg set-default my.flag --environment prod ...  set a scalar fallback value
+  qfg set-rollout my.flag --environment prod ...  set a simple percentage rollout
+  qfg pull --dir ./config                         clone workspace to edit JSON directly
+  qfg verify ./config                             validate all JSON files before pushing
+  qfg info my.flag                                inspect current values and rules
+  qfg config-schema --json-schema                 print the machine-readable JSON Schema
+`.trim();
+export default class ConfigSchema extends BaseCommand {
+    static description = 'Print the config file format reference: rules engine, operators, targeting criteria, segments, and weighted rollouts. ' +
+        'Use --json-schema for the machine-readable JSON Schema document.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>                  # human-readable operator reference + examples',
+        '<%= config.bin %> <%= command.id %> --json-schema    # full JSON Schema document (copy into your editor)',
+    ];
+    static flags = {
+        'json-schema': Flags.boolean({
+            default: false,
+            description: 'Output the full JSON Schema document for config files instead of the human-readable reference',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(ConfigSchema);
+        if (flags['json-schema']) {
+            const schema = storedConfigJsonSchema();
+            this.log(JSON.stringify(schema, null, 2));
+            return schema;
+        }
+        this.log(REFERENCE);
+    }
+}