Upstream Capability Discovery (UCD)¶

Platform law. Alias: Smallest Stable Owner.

UCD is not OpenClaw-specific. It applies whenever an engineer or agent integrates, extends, or replaces a capability owned by an upstream platform or OSS project.

Related doctrine: Capability Convergence Framework (ownership gravity). This file is the only binding process law for discovery and the Capability Audit gate. Do not create sibling essays, Cursor rules, or repo docs/runtime/* copies of this law.

Binding SHALL¶

When a Business Requirement implies software work against an upstream surface, engineers and agents SHALL:

Run a Capability Audit for that requirement before writing Bluefly code.
Answer from current upstream evidence (docs, CLI, OpenAPI, package registries, source, capability index), not remembered expertise.
Prefer the smallest stable owner that already provides the capability.
Treat Bluefly custom code as LAST — thin adapter / domain glue only after upstream ownership is exhausted with recorded evidence.

Absence of memory is not absence of capability. “Couldn’t find a plugin” without a recorded search is a policy violation.

Universal algorithm¶

Business Requirement
        |
        v
Can upstream already do it?  (native / built-in / CLI / config)
        | no
        v
Official extension?  (plugin, provider, hook, middleware, module)
        | no
        v
Official SDK / API?  (SDK, OpenAPI, MCP, documented protocol)
        | no
        v
Maintained upstream package / delegated ecosystem owner?
        | no
        v
Smallest Bluefly adapter (LAST) — domain glue only; never replace the owner

Stop at the first level that satisfies the requirement with equivalent governance, security, observability, and operational behavior.

Applies to (non-exhaustive)¶

OpenClaw · Gas City · Gas Town · Beads · Drupal · GitLab · Tailscale · DDEV · Cloudflare · Docker · Kubernetes · Keycloak · Dolt · 1Password · Synology DSM · Oracle deploy substrates · any other upstream OSS or platform with a published contract.

Mandatory gate¶

First prompt before implementation: Capability Audit: <X>

Do not open an implementation branch, write custom code, or invent a Bluefly service until every row for the scoped capability is filled with evidence links (or an explicit NOT FOUND with query + corpus recorded).

Capability Audit table¶

Column	Meaning
Capability	Named requirement under audit
Native?	Built-in / CLI / runtime already owns it
Config?	Expressible as upstream desired-state config
Plugin?	Official or catalog plugin / module
Extension?	Hook, provider, middleware, extension point
Official SDK?	First-party SDK package
Official API?	Documented HTTP/RPC/OpenAPI/MCP/protocol
Recommended upstream approach?	What current docs prescribe
Community standard?	Maintained ecosystem pattern (cite source)
Bluefly code actually required?	`None` \| `thin adapter` + justification
Evidence	Docs URL(s), CLI receipt, registry hit, source path — or `NOT FOUND` + exact query

Capability	Native?	Config?	Plugin?	Extension?	Official SDK?	Official API?	Recommended upstream approach?	Community standard?	Bluefly code actually required?	Evidence
(name)									None \| thin adapter

Forbidden¶

Forbidden	Why
Implementation-first	Skips ownership resolution; creates permanent Bluefly liability
Memory-driven claims (“I know OpenClaw can’t…”)	Upstream moves; memory is not evidence
“No plugin exists” without search evidence	Must record query + corpus + result
Narrative expertise dumps as substitute for an index	Searchable capability indexes beat essay corpora
Replacing the upstream owner when upstream owns it	Violates Smallest Stable Owner
Treating Bluefly OpenAPI / projections as upstream contract without labeling them	Projection ≠ authority
New platform-law siblings (Cursor rules, repo docs trees, ES Integration essays) that restate this file	One law, many pointers

Evidence-driven, not memory-driven¶

Do	Do not
Query a capability index / docs corpus / `qmd` / registry	Rely on prior chat “expertise”
Refresh live docs when versions may have changed	Assume last year’s mental model
Record `NOT FOUND` with exact search	Equate “I don’t remember” with “doesn’t exist”
Re-run Capability Audit per feature	Reuse an old audit for a different requirement
When the deployed binary and its own upstream docs disagree, probe the binary directly (`--help`, error text, `--json-schema`, `version -m`) and trust that over the doc for this specific host	Assume the doc is current for the exact build actually running, or invent a local substitute to reconcile the disagreement

Index convention¶

Each upstream platform may publish a machine-readable capability index (JSON) plus optional markdown shards for qmd. Reuse the same schema; do not invent parallel essay corpora.

Artifact	Path
Schema	`/Volumes/AgentPlatform/Scratch/openclaw-capability-index/schema.yaml`
OpenClaw index (example)	`/Volumes/AgentPlatform/Scratch/openclaw-capability-index/capabilities.json`
`qmd` shards	`/Volumes/AgentPlatform/Scratch/openclaw-capability-index/md/`

jq -r '.capabilities[] | select(.keywords | index("health")) | "\(.title)\t\(.docs_urls[0])"' \
  /Volumes/AgentPlatform/Scratch/openclaw-capability-index/capabilities.json
rg -n -i 'healthz|readyz' /Volumes/AgentPlatform/Scratch/openclaw-capability-index/md/
qmd search -c openclaw-capability-index 'gateway health'

Worked example: OpenClaw (Scratch only)¶

Disposable evidence — not a second Engineering-Standard:

Role	Path
Working Capability Audit (one file)	`/Volumes/AgentPlatform/Scratch/OpenClaw-Integration-Contract-Capability-Audit.md`
Docs crawl synthesis (evidence, do not duplicate into ES)	`/Volumes/AgentPlatform/Scratch/OpenClaw-Docs-Expertise-2026-07-21.md`
Crawl extracts	`/Volumes/AgentPlatform/Scratch/openclaw-docs-crawl-2026-07-21/`
Searchable index	`/Volumes/AgentPlatform/Scratch/openclaw-capability-index/`

Locked operator decisions for Oracle OpenClaw edge (re-audit only with new evidence):

Serve / ingress owner: host Tailscale (not Compose; not OpenClaw gateway.tailscale.mode: "serve").
Target: Tailscale Services → set-config → Git → Deployment.
Today: classic Serve until a Service resource exists; never hand-author Services JSON (generate from get-config only).
OpenClaw owns gateway runtime (mode: "off" for Tailscale Serve automation). Health roles per upstream docs: /healthz liveness, /readyz readiness, GET /health uptime SaaS — /health ≡ /healthz remains UNKNOWN in docs.

Repo deploy identity (Current / Target / Blocker only): agent-docker → deployments/oracle/configs/README.md. Architecture and law stay here + Scratch.

Relationship to Capability Convergence¶

UCD is the discovery and audit process. Capability Convergence is the ownership gravity doctrine. Both agree: responsibility falls to the smallest stable owner; Level 6 (local custom) is last and must be evidenced.