docs(use-cases): correct any-OpenClaw flow + add roadmap scenario + surface in README#47
Merged
Merged
Conversation
Scenario 2 (any-OpenClaw → AzureClaw cloud offload) was hallucinated:
it documented a fictional 'azureclaw mesh auth --registry --provider
github' command run on the laptop. The defining property of this
scenario is that the laptop user does NOT install the azureclaw CLI
at all — they install only the azureclaw-mesh OpenClaw plugin. The
real flow is:
1. Operator runs 'azureclaw mesh promote --port-forward' (or
LoadBalancer / future managed edge) so the cluster's relay +
registry are reachable from off-cluster.
2. Operator runs 'azureclaw pair generate --name <name> --slots N'
to mint a one-time, expiring, slot/budget/capability-bounded
'azc_pair_v1_<base64url>' token containing controller AMID,
relay/registry URLs and a sealed pairing secret.
3. Token is sent to the user via any secure channel (secret-share,
SMS, encrypted email, managed-provider portal).
4. User pastes the token once into chat, or sets it as an env var.
The plugin's azureclaw_pair tool handshakes with the registry,
claims a slot, exchanges X3DH prekeys, and the host is a
registered mesh peer. Token is single-use and auto-zeroized.
Other corrections in use-cases.md:
- Add explicit 'How the laptop reaches the AKS mesh edge' subsection
documenting the four edge modes today vs roadmap (port-forward,
LoadBalancer + IP allowlist, public managed mesh edge, managed
AzureClaw provider edge).
- Add scenario 4 (roadmap): any agentic runtime → AzureClaw via
MCP / A2A 1.0.0 / AP2, with explicit 'mounted in Phase 2 once
reconcilers ship signing keys via K8s Secrets' caveat to avoid a
default-keys / no-auth path.
- Update 'What's NOT a use case' to include not being a SaaS agent
author (M365 Agent Framework / Copilot Studio territory).
- Replace duplicated body that survived the rewrite.
README.md:
- Surface a one-line link to docs/use-cases.md right after 'What
problems does it solve?' (the user asked for a prominent reference
near the top of the main page, not just in the Roadmap and Docs
table further down).
- Update Roadmap blurb to say 'four end-to-end scenarios — three
shipping today, plus a roadmap track for non-OpenClaw runtimes'.
Refs: docs/use-cases.md, mesh-plugin/src/, controller/src/pairing.rs,
cli/src/commands/{pair.ts,mesh.ts}
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
… flow diagrams Use cases describe what AzureClaw does. Blueprints describe how to run it for a given audience. The two are complementary; a single AzureClaw deployment can serve multiple blueprints simultaneously. Adds docs/blueprints/: 00-index.md Catalogue + reading guide 01-developer-inner-loop.md Laptop / kind, single-node 02-enterprise-self-hosted.md Customer-owned AKS, single tenant 03-managed-public-offload.md Provider-owned AKS, multi-tenant 04-cross-org-federation.md Two AKS clusters meshed E2E 05-sovereign-airgapped.md Isolated network island Each blueprint has the same shape: - Persona & intent - Topology Mermaid diagram - Trust boundary Mermaid diagram - Primary-flow sequence diagram - Concrete CLI invocations - 'What's unique vs. what this blueprint is NOT' - Code / CRD / ADR references Cross-cutting properties (egress isolation, Foundry-side Content Safety, AGT governance, tamper-evident audit chain, Signal-Protocol mesh, CRD-driven control plane) are documented once in 00-index.md and referenced from each blueprint. The blueprint set is surfaced from: - README.md prominent link (right after 'What problems does it solve?') - docs/use-cases.md callout at the top Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
pallakatos
added a commit
that referenced
this pull request
May 12, 2026
…urface in README (#47) * docs(use-cases): correct any-OpenClaw flow + add roadmap scenario Scenario 2 (any-OpenClaw → AzureClaw cloud offload) was hallucinated: it documented a fictional 'azureclaw mesh auth --registry --provider github' command run on the laptop. The defining property of this scenario is that the laptop user does NOT install the azureclaw CLI at all — they install only the azureclaw-mesh OpenClaw plugin. The real flow is: 1. Operator runs 'azureclaw mesh promote --port-forward' (or LoadBalancer / future managed edge) so the cluster's relay + registry are reachable from off-cluster. 2. Operator runs 'azureclaw pair generate --name <name> --slots N' to mint a one-time, expiring, slot/budget/capability-bounded 'azc_pair_v1_<base64url>' token containing controller AMID, relay/registry URLs and a sealed pairing secret. 3. Token is sent to the user via any secure channel (secret-share, SMS, encrypted email, managed-provider portal). 4. User pastes the token once into chat, or sets it as an env var. The plugin's azureclaw_pair tool handshakes with the registry, claims a slot, exchanges X3DH prekeys, and the host is a registered mesh peer. Token is single-use and auto-zeroized. Other corrections in use-cases.md: - Add explicit 'How the laptop reaches the AKS mesh edge' subsection documenting the four edge modes today vs roadmap (port-forward, LoadBalancer + IP allowlist, public managed mesh edge, managed AzureClaw provider edge). - Add scenario 4 (roadmap): any agentic runtime → AzureClaw via MCP / A2A 1.0.0 / AP2, with explicit 'mounted in Phase 2 once reconcilers ship signing keys via K8s Secrets' caveat to avoid a default-keys / no-auth path. - Update 'What's NOT a use case' to include not being a SaaS agent author (M365 Agent Framework / Copilot Studio territory). - Replace duplicated body that survived the rewrite. README.md: - Surface a one-line link to docs/use-cases.md right after 'What problems does it solve?' (the user asked for a prominent reference near the top of the main page, not just in the Roadmap and Docs table further down). - Update Roadmap blurb to say 'four end-to-end scenarios — three shipping today, plus a roadmap track for non-OpenClaw runtimes'. Refs: docs/use-cases.md, mesh-plugin/src/, controller/src/pairing.rs, cli/src/commands/{pair.ts,mesh.ts} Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(blueprints): add 5 deployment blueprints with Mermaid topology + flow diagrams Use cases describe what AzureClaw does. Blueprints describe how to run it for a given audience. The two are complementary; a single AzureClaw deployment can serve multiple blueprints simultaneously. Adds docs/blueprints/: 00-index.md Catalogue + reading guide 01-developer-inner-loop.md Laptop / kind, single-node 02-enterprise-self-hosted.md Customer-owned AKS, single tenant 03-managed-public-offload.md Provider-owned AKS, multi-tenant 04-cross-org-federation.md Two AKS clusters meshed E2E 05-sovereign-airgapped.md Isolated network island Each blueprint has the same shape: - Persona & intent - Topology Mermaid diagram - Trust boundary Mermaid diagram - Primary-flow sequence diagram - Concrete CLI invocations - 'What's unique vs. what this blueprint is NOT' - Code / CRD / ADR references Cross-cutting properties (egress isolation, Foundry-side Content Safety, AGT governance, tamper-evident audit chain, Signal-Protocol mesh, CRD-driven control plane) are documented once in 00-index.md and referenced from each blueprint. The blueprint set is surfaced from: - README.md prominent link (right after 'What problems does it solve?') - docs/use-cases.md callout at the top Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Pal Lakatos-Toth <pallakatos@microsoft.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes hallucinated content in
docs/use-cases.mdScenario 2 (any-OpenClaw → AzureClaw cloud offload) and adds the missing context the user flagged after PR #44 landed:What was wrong
Old Scenario 2 documented a fictional
azureclaw mesh auth --registry --provider githubcommand run on the laptop. The laptop user does not install the azureclaw CLI at all — they install only theazureclaw-meshOpenClaw plugin.azureclaw mesh authis a real command, but it lives on the operator side for cluster-to-cluster federation identity, not on the user's laptop.What the rewrite says
Operator side (one-time per user):
azureclaw mesh promote --port-forward # expose registry + relay so off-cluster hosts can reach them azureclaw pair generate --name alice-laptop --slots 3 --expires 90d \ --capabilities offload,handoffProduces a one-time, expiring, slot/budget/capability-bounded
azc_pair_v1_<base64url>token containing controller AMID, relay/registry URLs, and a sealed pairing secret. Sent via any secure channel.Plugin user side:
azureclaw-meshplugin (today bundled into NemoClaw images; goal: upstream into OpenClaw)AZURECLAW_PAIRING_TOKENenv var or paste the token once into chatazureclaw_pairtool — X3DH + Double Ratchet handshake, single-use token, auto-zeroizedEdge exposure modes documented
mesh promote --port-forwardmesh promote --allow-ip <cidr>(LoadBalancer)Other changes
docs/use-cases.mdright after "What problems does it solve?" (the user asked for a reference "at the beginning of mainpage where it fits", not just buried in Roadmap line 217 + Docs table line 492).Validation
Docs-only PR; no code paths touched. CI gates that apply: markdown lint, link check.
Refs:
mesh-plugin/src/,controller/src/pairing.rs,cli/src/commands/{pair.ts,mesh.ts}