feat(onboarding): complete v0.8 onboarding coverage

CHANGELOG.md

@@ -18,6 +18,7 @@ The format is intentionally lightweight and human-readable. Group entries by rel
 - Added matching provider `.env` starter files for cloud, local-worker, and image-provider onboarding flows
 - Added provider env placeholder checks to `foundrygate-doctor` so missing `.env` values are surfaced before rollout
 - Added `--markdown` output to `foundrygate-onboarding-report` so onboarding state can be pasted into issues, PRs, or hand-off notes
+- Added delegated OpenClaw request and generic AI-native app profile starters to round out the `v0.8.x` onboarding path
 
 ## v0.7.0 - 2026-03-12
 

README.md

@@ -858,6 +858,11 @@ If you want to paste the current onboarding state into a ticket or PR, run:
 ```bash
 ./scripts/foundrygate-onboarding-report --markdown
 ```
+
+For delegated OpenClaw traffic and future AI-native app profiles, the new starters live here as well:
+
+- [openclaw-delegated-request.json](./docs/examples/openclaw-delegated-request.json)
+- [client-ai-native-app-profile.yaml](./docs/examples/client-ai-native-app-profile.yaml)
 | `foundrygate-install` | Installs the unit file, creates `/var/lib/foundrygate`, creates helper symlinks, reloads `systemd`, and starts the service |
 | `foundrygate-start` | Runs `systemctl start foundrygate.service` |
 | `foundrygate-stop` | Runs `systemctl stop foundrygate.service` |

docs/FOUNDRYGATE-ROADMAP.md

@@ -19,7 +19,7 @@ The foundation that used to be the near-term buildout is largely in place:
 
 This roadmap now shifts from "rename and foundation" to "deepen the gateway plane without bloating it".
 
-`v0.5.0` is the current operator-distribution release line: modality-aware image paths, publish workflows, onboarding helpers, community baselines, and release update checks are now in place on top of the `v0.4.x` routing foundation.
+`v0.8.x` is the current release line: many-provider and many-client onboarding is being tightened with validation helpers, starter templates, delegated-traffic examples, and shareable onboarding output on top of the already-shipped routing, modality, and ops foundation.
 
 ## Big Picture
 
@@ -230,6 +230,18 @@ Primary goals:
 
 The target is faster adoption without custom glue for every client.
 
+Current `v0.8.x` baseline already includes:
+
+- onboarding report plus validation helpers
+- staged provider rollout reporting
+- client matrix reporting
+- starter templates for OpenClaw, n8n, CLI, cloud providers, local workers, and image providers
+- matching provider `.env` starter files
+- delegated OpenClaw request examples
+- starter custom-profile examples for future AI-native applications
+- doctor checks for missing provider env placeholders
+- JSON and Markdown onboarding exports
+
 ### `v0.9.x`: pre-1.0 hardening
 
 Primary goals:

docs/INTEGRATIONS.md

@@ -34,6 +34,8 @@ Minimal direction:
 
 For a smaller starter snippet without the full alias block, use [examples/openclaw-foundrygate.jsonc](./examples/openclaw-foundrygate.jsonc).
 
+For delegated or many-agent traffic, start from [examples/openclaw-delegated-request.json](./examples/openclaw-delegated-request.json) and keep `x-openclaw-source` stable across sub-agents so traces stay attributable.
+
 ## n8n
 
 n8n can use FoundryGate as a stable local model gateway.
@@ -91,6 +93,20 @@ export OPENAI_API_KEY=local
 
 For a reusable shell starter, use [examples/cli-foundrygate-env.sh](./examples/cli-foundrygate-env.sh).
 
+## AI-native app clients
+
+For future app-specific clients, keep the same OpenAI-compatible base URL and add one stable app header before creating multiple custom profiles.
+
+Recommended pattern:
+
+- set `X-FoundryGate-Client: your-app`
+- create one explicit app profile
+- only split into `ops`, `private`, or `local-only` profiles when real routing differences emerge
+
+Starter snippet:
+
+- [examples/client-ai-native-app-profile.yaml](./examples/client-ai-native-app-profile.yaml)
+
 ## Provider onboarding
 
 When onboarding a new provider:

docs/ONBOARDING.md

@@ -124,6 +124,10 @@ OpenClaw:
 
 Starter file: [examples/openclaw-foundrygate.jsonc](./examples/openclaw-foundrygate.jsonc)
 
+Delegated / many-agent example:
+
+- [examples/openclaw-delegated-request.json](./examples/openclaw-delegated-request.json)
+
 n8n:
 
 ```text
@@ -143,6 +147,7 @@ Starter files:
 
 - [examples/n8n-foundrygate-http-request.json](./examples/n8n-foundrygate-http-request.json)
 - [examples/cli-foundrygate-env.sh](./examples/cli-foundrygate-env.sh)
+- [examples/client-ai-native-app-profile.yaml](./examples/client-ai-native-app-profile.yaml)
 
 ### 4. Add request hooks only if needed
 

docs/examples/client-ai-native-app-profile.yaml

@@ -0,0 +1,21 @@
+client_profiles:
+  enabled: true
+  default: generic
+  profiles:
+    generic: {}
+    app-ops:
+      prefer_tiers: ["default", "cheap"]
+      capability_values:
+        local: false
+    app-private:
+      capability_values:
+        local: true
+  rules:
+    - profile: app-ops
+      match:
+        header_contains:
+          x-foundrygate-client: ["elementify", "ops-app"]
+    - profile: app-private
+      match:
+        header_contains:
+          x-foundrygate-profile: ["private", "local-only"]

docs/examples/openclaw-delegated-request.json

@@ -0,0 +1,15 @@
+{
+  "headers": {
+    "x-openclaw-source": "delegate:planner",
+    "x-foundrygate-client": "openclaw"
+  },
+  "body": {
+    "model": "auto",
+    "messages": [
+      {
+        "role": "user",
+        "content": "Break this task into sub-steps and assign the first one."
+      }
+    ]
+  }
+}

foundrygate/onboarding.py

@@ -303,6 +303,22 @@ def build_onboarding_report(
                 "Use x-openclaw-source when you want sub-agent traffic to resolve differently.",
             ],
         },
+        "ai-native-app": {
+            "recommended": any(
+                name not in {"generic", "openclaw", "n8n", "cli", "local-only"}
+                for name in profile_names
+            ),
+            "header": "X-FoundryGate-Client: your-app",
+            "profile": "custom app profile",
+            "snippet": [
+                "client_profiles.rules -> match on X-FoundryGate-Client",
+                "client_profiles.profiles -> define app-specific prefer_tiers or locality",
+            ],
+            "notes": [
+                "Start with one stable client header before adding more than one app profile.",
+                "Keep app-private traffic on a dedicated profile instead of ad hoc hooks.",
+            ],
+        },
         "n8n": {
             "recommended": "n8n" in enabled_presets or "n8n" in profile_names,
             "header": "X-FoundryGate-Client: n8n",