From 26989506d4da9b3d2a18e397cb62e2af865e8c29 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andre=CC=81=20Lange?= Date: Sun, 15 Mar 2026 03:33:20 +0100 Subject: [PATCH] feat(onboarding): complete v0.8 onboarding coverage --- CHANGELOG.md | 1 + README.md | 5 +++++ docs/FOUNDRYGATE-ROADMAP.md | 14 ++++++++++++- docs/INTEGRATIONS.md | 16 ++++++++++++++ docs/ONBOARDING.md | 5 +++++ .../client-ai-native-app-profile.yaml | 21 +++++++++++++++++++ docs/examples/openclaw-delegated-request.json | 15 +++++++++++++ foundrygate/onboarding.py | 16 ++++++++++++++ 8 files changed, 92 insertions(+), 1 deletion(-) create mode 100644 docs/examples/client-ai-native-app-profile.yaml create mode 100644 docs/examples/openclaw-delegated-request.json diff --git a/CHANGELOG.md b/CHANGELOG.md index 4b34318..bb71229 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index b42e0df..996b587 100644 --- a/README.md +++ b/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` | diff --git a/docs/FOUNDRYGATE-ROADMAP.md b/docs/FOUNDRYGATE-ROADMAP.md index 6b333a2..6baab70 100644 --- a/docs/FOUNDRYGATE-ROADMAP.md +++ b/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: diff --git a/docs/INTEGRATIONS.md b/docs/INTEGRATIONS.md index 151b961..81bcd69 100644 --- a/docs/INTEGRATIONS.md +++ b/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: diff --git a/docs/ONBOARDING.md b/docs/ONBOARDING.md index 632cf26..a861aba 100644 --- a/docs/ONBOARDING.md +++ b/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 diff --git a/docs/examples/client-ai-native-app-profile.yaml b/docs/examples/client-ai-native-app-profile.yaml new file mode 100644 index 0000000..b36bd52 --- /dev/null +++ b/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"] diff --git a/docs/examples/openclaw-delegated-request.json b/docs/examples/openclaw-delegated-request.json new file mode 100644 index 0000000..719865f --- /dev/null +++ b/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." + } + ] + } +} diff --git a/foundrygate/onboarding.py b/foundrygate/onboarding.py index 161370f..5da9102 100644 --- a/foundrygate/onboarding.py +++ b/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",