docs: define extension taxonomy and SDK readiness

[apurvvkumaria]

Summary

This PR consolidates the complementary work from #6498 and #6499 into one published decision record for NemoClaw extension terminology and future SDK readiness.
It preserves Julie Yaunches's original authorship, removes conflicting issue classifications, and avoids implying that a public NemoClaw plugin SDK exists today.

Related Issue

Closes #6229.

Changes

• Define lifecycle contribution, managed agent package, agent-native plugin, candidate public seam, and the reserved future NemoClaw plugin SDK terminology.
• Document execution boundaries, a stability and security matrix, measurable readiness gates, and non-overlapping ownership for VoiceClaw integration via existing messaging and provider contracts #5998, refactor(messaging): organize channels into plugin-style modules #6097, Observability plugin support for external telemetry adapters #3915, OpenClaw VoiceClaw support: voice-call plugin boundary and core runtime work #6201, and OpenShell VoiceClaw support: validate sandbox contracts and track networking follow-ons #6207.
• Publish the decision record in the OpenClaw, Hermes, and Deep Agents Code reference navigation.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification: This is a documentation-only architecture decision with no runtime behavior.
• Docs updated for user-facing behavior changes
• Docs not applicable — justification:
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification:
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: Tests are not applicable; npm run docs passed with zero errors.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only) — result: The command passed with zero errors; Fern reported the unauthenticated redirects check and the existing light-theme accent contrast as unrelated warnings.
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Apurv Kumaria akumaria@nvidia.com

Summary by CodeRabbit

• New Features
  • Added a new reference page covering extension and SDK readiness concepts, including terminology, trust boundaries, and readiness criteria.
  • Expanded the documentation navigation so the new reference article appears across all agent variants.
• Documentation
  • Clarified current platform commitments and non-commitments around SDKs, registries, marketplaces, compatibility, and support expectations.
  • Added guidance for naming and describing future extension-related capabilities.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new documentation reference page, extension-taxonomy-sdk-readiness.mdx, defining terminology, execution/trust boundaries, a stability matrix, and public SDK readiness gates. Registers this page in docs/index.yml navigation under Reference for the OpenClaw, Deep Agents, and Hermes tab variants.

Changes

Extension Taxonomy Documentation

Layer / File(s)	Summary
Decision record content docs/reference/extension-taxonomy-sdk-readiness.mdx	New MDX page with frontmatter, a glossary of extension/SDK terminology, execution/trust boundary classes, a stability/security matrix, public SDK readiness gates, issue ownership boundaries, naming guidance, and explicit non-commitments.
Navigation wiring docs/index.yml	Adds an “Extension Taxonomy and SDK Readiness” entry with its MDX path and slug under Reference > Architecture Details for the NemoClaw for OpenClaw, Deep Agents, and Hermes tabs.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately summarizes the new documentation on extension taxonomy and SDK readiness.
Linked Issues check	✅ Passed	The docs add the requested glossary, readiness gates, terminology boundaries, and non-commitments for a future NemoClaw SDK.
Out of Scope Changes check	✅ Passed	The pull request is limited to documentation and navigation updates aligned with the linked architecture decision record.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/6229-extension-sdk-readiness

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

E2E Advisor Recommendation

Required E2E: None
Optional E2E: None

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• None. Docs-only change limited to navigation and a new reference MDX page. No existing E2E job is needed because the change cannot affect NemoClaw runtime/user flows or security-sensitive behavior.

Optional E2E

• None.

New E2E recommendations

• None.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-6508.docs.buildwithfern.com/nemoclaw

[github-actions]

E2E Target Recommendation

Required E2E targets: None
Optional E2E targets: None

Workflow run

Full E2E target advisor summary

E2E Target Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E targets

• None. Docs-only changes cannot affect E2E target behavior.

Optional E2E targets

• None.

Relevant changed files

• None.

[github-actions]

PR Review Advisor — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: No advisor follow-up required beyond maintainer review.
Open items: 0 required · 0 warnings · 0 suggestions · 0 test follow-ups
Top item: No actionable findings

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.

[github-actions]

PR Review Advisor (Nemotron Ultra) — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: No advisor follow-up required beyond maintainer review.
Open items: 0 required · 0 warnings · 0 suggestions · 0 test follow-ups
Since last review: 0 prior items resolved · 0 still apply · 0 new items found

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.

[coderabbitai]

🧹 Nitpick comments (1)

docs/reference/extension-taxonomy-sdk-readiness.mdx (1)

38-44: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Minor naming drift between tables for the "no third-party execution" class.

| Arbitrary NemoClaw executable extension | No. | (Execution and Trust Boundaries table) uses a different name than | Arbitrary third-party NemoClaw executable extension | Reserved and unavailable. | (Stability and Security Matrix). Since this record's purpose is unambiguous terminology, consider aligning the two labels to the same term.

✏️ Suggested alignment

-| Arbitrary NemoClaw executable extension | No. | NemoClaw does not accept third-party code through a host-side or control-path extension point. A later decision would need to define isolation, least privilege, provenance, failure containment, and recovery before enabling this class. |
+| Arbitrary third-party NemoClaw executable extension | No. | NemoClaw does not accept third-party code through a host-side or control-path extension point. A later decision would need to define isolation, least privilege, provenance, failure containment, and recovery before enabling this class. |

Also applies to: 54-63

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/reference/extension-taxonomy-sdk-readiness.mdx` around lines 38 - 44,
The “no third-party execution” row uses inconsistent terminology across the two
tables; align the label in the Execution and trust boundary table with the
matching term used in the Stability and Security Matrix. Update the row in the
taxonomy table that currently says Arbitrary NemoClaw executable extension so it
matches the same canonical name as the other table, keeping the wording
consistent across both references.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/reference/extension-taxonomy-sdk-readiness.mdx`:
- Around line 38-44: The “no third-party execution” row uses inconsistent
terminology across the two tables; align the label in the Execution and trust
boundary table with the matching term used in the Stability and Security Matrix.
Update the row in the taxonomy table that currently says Arbitrary NemoClaw
executable extension so it matches the same canonical name as the other table,
keeping the wording consistent across both references.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 0a0deaa0-4e2e-4936-b020-9c3ce4838545

📥 Commits

Reviewing files that changed from the base of the PR and between 10091a3 and 74f40a8.

📒 Files selected for processing (2)

• docs/index.yml
• docs/reference/extension-taxonomy-sdk-readiness.mdx