docs: command and query cheat sheet, context injection (open-feature#1839)

Adds a "cheat sheet" with a a bunch of simple, easily searchable
examples for:

- starting flagd
  - docker and binary
  - with file source
  - with http source
  - with multiple sources
  - with header and static context injection
- calling OFREP with curl
  - evaluating multiple flags
  - evaluating one flag
  - using the `flagd-selector` header
- calling proto API
  - streaming and evaluation
  - flagd-selector
 

... and more

[DIRECT
PREVIEW](https://deploy-preview-1839--polite-licorice-3db33c.netlify.app/reference/cheat-sheet/)
:play_or_pause_button:

The idea is this is a searchable reference. Concepts are not explained
we have lots of that elsewhere. This is just for quick reference for
useful commands.

---------

Signed-off-by: Todd Baert <[email protected]>
Co-authored-by: Michael Beemer <[email protected]>

Author: toddbaert

Dockerfile

@@ -1,2 +1,2 @@
-FROM squidfunk/mkdocs-material:9.5
+FROM squidfunk/mkdocs-material:9.7.1
 RUN pip install mkdocs-include-markdown-plugin

docs/assets/cheat-sheet-flags-payments.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://flagd.dev/schema/v0/flags.json",
+  "flags": {
+    "payment-provider": {
+      "state": "ENABLED",
+      "variants": {
+        "slash": "slash",
+        "billbuddy": "billbuddy",
+        "cube": "cube"
+      },
+      "defaultVariant": "slash"
+    },
+    "max-transaction-amount": {
+      "state": "ENABLED",
+      "variants": {
+        "standard": 1000,
+        "elevated": 5000,
+        "unlimited": 999999
+      },
+      "defaultVariant": "standard",
+      "targeting": {
+        "if": [
+          { "===": [{ "var": "account-verified" }, true] },
+          "elevated",
+          "standard"
+        ]
+      }
+    },
+    "enable-crypto-payments": {
+      "state": "ENABLED",
+      "variants": {
+        "on": true,
+        "off": false
+      },
+      "defaultVariant": "off",
+      "targeting": {
+        "if": [
+          { "in": [{ "var": "country" }, ["us", "ca", "uk", "de"]] },
+          "on",
+          "off"
+        ]
+      }
+    }
+  },
+  "metadata": {
+    "flagSetId": "payment-flags"
+  }
+}

docs/assets/cheat-sheet-flags.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://flagd.dev/schema/v0/flags.json",
+  "flags": {
+    "simple-boolean": {
+      "state": "ENABLED",
+      "variants": {
+        "on": true,
+        "off": false
+      },
+      "defaultVariant": "on"
+    },
+    "simple-string": {
+      "state": "ENABLED",
+      "variants": {
+        "greeting": "Hello, World!",
+        "farewell": "Goodbye, World!"
+      },
+      "defaultVariant": "greeting"
+    },
+    "simple-number": {
+      "state": "ENABLED",
+      "variants": {
+        "low": 10,
+        "medium": 50,
+        "high": 100
+      },
+      "defaultVariant": "medium"
+    },
+    "simple-object": {
+      "state": "ENABLED",
+      "variants": {
+        "config-a": {
+          "theme": "light",
+          "maxItems": 10
+        },
+        "config-b": {
+          "theme": "dark",
+          "maxItems": 25
+        }
+      },
+      "defaultVariant": "config-a"
+    },
+    "user-tier-flag": {
+      "state": "ENABLED",
+      "variants": {
+        "basic": "basic-features",
+        "premium": "premium-features",
+        "enterprise": "enterprise-features"
+      },
+      "defaultVariant": "basic",
+      "targeting": {
+        "if": [
+          { "===": [{ "var": "tier" }, "enterprise"] },
+          "enterprise",
+          { "if": [
+            { "===": [{ "var": "tier" }, "premium"] },
+            "premium",
+            null
+          ]}
+        ]
+      }
+    },
+    "email-based-feature": {
+      "state": "ENABLED",
+      "variants": {
+        "on": true,
+        "off": false
+      },
+      "defaultVariant": "off",
+      "targeting": {
+        "if": [
+          { "ends_with": [{ "var": "email" }, "@example.com"] },
+          "on",
+          null
+        ]
+      }
+    },
+    "region-config": {
+      "state": "ENABLED",
+      "variants": {
+        "us": { "currency": "USD", "dateFormat": "MM/DD/YYYY" },
+        "eu": { "currency": "EUR", "dateFormat": "DD/MM/YYYY" },
+        "default": { "currency": "USD", "dateFormat": "YYYY-MM-DD" }
+      },
+      "defaultVariant": "default",
+      "targeting": {
+        "if": [
+          { "in": [{ "var": "region" }, ["us", "usa", "united-states"]] },
+          "us",
+          { "if": [
+            { "in": [{ "var": "region" }, ["eu", "europe", "uk", "de", "fr"]] },
+            "eu",
+            null
+          ]}
+        ]
+      }
+    }
+  },
+  "metadata": {
+    "flagSetId": "app-flags"
+  }
+}

docs/concepts/selectors.md

@@ -13,6 +13,8 @@ In flagd, **selectors** provide a way to query flags based on different criteria
 - **Selector**: A query expression that filters flags by source, flag set, or other criteria
 - **Flag Set Metadata**: The selector information is "reflected" back in response metadata for transparency
 
+See the [cheat sheet](../reference/cheat-sheet.md#using-the-selector-header) for practical examples of using selectors.
+
 !!! tip
 
     The `flagSetId` + `key` combination represents the unique identifier for a flag.

docs/concepts/syncs.md

@@ -2,6 +2,7 @@
 
 Syncs are a core part of flagd; they are the abstraction that enables different sources for feature flag definitions.
 flagd can connect to one or more sync sources.
+See the [cheat sheet](../reference/cheat-sheet.md#running-flagd) for quick startup examples with different sync sources.
 
 ## Available syncs
 

docs/faq.md

@@ -30,6 +30,7 @@ flagd is sub-project of OpenFeature and aims to be fully [OpenFeature-compliant]
 
 You can run flagd as a standalone application, accessible over HTTP or gRPC, or you can embed it into your application.
 Please see [architecture](./architecture.md) and [installation](./installation.md) for more information.
+For quick command examples, see the [cheat sheet](./reference/cheat-sheet.md).
 
 ---