Summary

Describe the problem and fix in 2–5 bullets:

• Problem: the repo had strong boundary rules scattered across docs and code, but not enough local AGENTS.md guidance at the boundary directories where Codex is likely to make the wrong reach-in.
• Why it matters: recent follow-up work in #56048 showed concrete failure modes from weak boundary guidance, including core deep-importing bundled plugin internals, plugin-owned config leaking into unrelated core paths, and extension-only helper/test seams getting consumed without a stable facade.
• What changed: I added a top-level architecture-boundary section to AGENTS.md and added focused AGENTS.md files in extensions/, src/plugin-sdk/, src/channels/, src/plugins/, and src/gateway/protocol/ that point to the existing contract docs and source-of-truth files.
• What changed: I tightened the guidance with explicit guardrails from #56048, including "no deep-imports from bundled plugin internals into core", "keep vendor-owned tools/config/secrets in the owning plugin", "avoid ad hoc plugins.entries.<id>.config reads in unrelated core code", and "use public facades for bundled plugin helpers and tests".
• What did NOT change (scope boundary): I did not change runtime behavior, plugin loading logic, protocol schemas, config schemas, or tests. This PR only updates repo guidance.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #
• Related fix(xai): move bundled provider to Responses and add x_search #56048
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

For bug fixes or regressions, explain why this happened, not just what changed. Otherwise write N/A. If the cause is unclear, write Unknown.

• Root cause: N/A
• Missing detection / guardrail: N/A
• Prior context (git blame, prior PR, issue, or refactor if known): N/A
• Why this regressed now: N/A
• If unknown, what was ruled out: N/A

Regression Test Plan (if applicable)

For bug fixes or regressions, name the smallest reliable test coverage that should have caught this. Otherwise write N/A.

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: N/A
• Scenario the test should lock in: N/A
• Why this is the smallest reliable guardrail: N/A
• Existing test that already covers this (if any): N/A
• If no new test is added, why not: this PR is guidance-only and does not change executable behavior.

User-visible / Behavior Changes

None for end users. For contributors and agents, the repo now has explicit local guidance at the main architecture boundaries.

Diagram (if applicable)

Before:
[core or test] -> [private extension/internal file] -> [incidental dependency]

After:
[core or test] -> [documented facade / Plugin SDK / local AGENTS guidance] -> [supported boundary]

Security Impact (required)

• New permissions/capabilities? (Yes/No): No
• Secrets/tokens handling changed? (Yes/No): No
• New/changed network calls? (Yes/No): No
• Command/tool execution surface changed? (Yes/No): No
• Data access scope changed? (Yes/No): No
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: local git branch on origin/main
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted): N/A

Steps

1. Inspect the existing plugin/protocol boundary docs and contract definition files.
2. Review the follow-up fixes in #56048 and extract the concrete boundary mistakes that were corrected later.
3. Add root and boundary-local AGENTS.md guidance that links to the right docs and source files.
4. Rebase the branch onto current origin/main and verify the tree is clean.

Expected

• The repo should document the supported cross-boundary seams where agents are likely to work.
• The PR-informed mistakes from #56048 should be encoded as explicit guardrails.

Actual

• The new guidance is present in the root and boundary directories, the branch rebases cleanly on origin/main, and the worktree is clean.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

I reviewed the local commit range and the follow-up commit history from #56048, including fixes such as:

• xAI: route x_search through public api seam
• fix(xai): restore config-backed auth discovery
• refactor(xai): move code_execution into plugin
• fix(xai): wire plugin-owned codeExecution config
• fix(plugins): stabilize provider contract loading
• refactor(plugins): expose bundled onboard helpers

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: I verified the new guidance exists in AGENTS.md, extensions/AGENTS.md, src/plugin-sdk/AGENTS.md, src/channels/AGENTS.md, src/plugins/AGENTS.md, and src/gateway/protocol/AGENTS.md. I also verified the branch rebases cleanly on current origin/main and the worktree is clean after the two commits on this branch.
• Edge cases checked: I confirmed .local/ is ignored before writing this PR body there, and I removed the unsupported CLAUDE.md symlinks before landing the branch commits.
• What you did not verify: I did not run repo-wide gates because the changes are guidance-only and the normal pre-commit path is currently blocked by unrelated existing TypeScript errors outside this diff.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No): Yes
• Config/env changes? (Yes/No): No
• Migration needed? (Yes/No): No
• If yes, exact upgrade steps:

Risks and Mitigations

List only real risks for this PR. Add/remove entries as needed. If none, write None.

• Risk: the guidance could overfit #56048 and become too prescriptive in spots where a generic seam is still evolving.
  • Mitigation: I linked the guidance back to the existing docs and source-of-truth files instead of inventing new policy surfaces.