Summary

Describe the problem and fix in 2–5 bullets:

• Problem: there was no repo-local plan or reference scaffold for Mintlify-native generated Plugin SDK docs.
• Why it matters: the Plugin SDK surface is large and partly transitional, so the docs rollout needs stable navigation, stability policy, and a reviewed starting set before generator work begins.
• What changed: synced main to current upstream/main, added experiments/plugin-sdk-docs-implementation-plan.md, added the Phase 1 docs/reference/plugin-sdk/ scaffold, added scripts/lib/plugin-sdk-doc-metadata.ts, added docs/docs.json nav entries, and linked the current plugin guides to the new reference area.
• What did NOT change (scope boundary): this PR still does not add the generator, TypeDoc config, or generated per-module SDK pages.

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 #

User-visible / Behavior Changes

• Adds a new Phase 1 Plugin SDK reference section in the docs nav under Reference.
• Adds a curated stability/category scaffold for the first reviewed Plugin SDK subpaths.
• Existing plugin guide pages now point readers at the new reference area.

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: Linux
• Runtime/container: Node 22.22.0 for repo commands; git + gh CLI
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted): N/A

Steps

1. Sync local main to current upstream/main.
2. Add the implementation plan under experiments/.
3. Finish Phase 1 by adding the Plugin SDK reference scaffold, nav entries, metadata file, and guide links.
4. Run docs-only validation.
5. Push fork main and update the existing PR.

Expected

• main is rebased to current upstream.
• The repo contains a concrete staged plan for generated Plugin SDK docs.
• The docs nav includes a new Plugin SDK reference group.
• Phase 1 docs pages exist and docs-only validation passes.

Actual

• Completed.
• pnpm check:docs passed.
• Note: latest synced upstream still fails later full pnpm check lint stages unrelated to this docs work (extensions/openai/media-understanding-provider.ts and extensions/openai/openai-codex-provider.ts import-boundary drift). I did not broaden this PR into that unrelated cleanup.

Evidence

Attach at least one:

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

Human Verification (required)

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

• Verified scenarios: synced main to upstream/main, created the plan file, created the Phase 1 reference scaffold, added nav entries and guide links, ran pnpm check:docs, pushed origin/main, and updated this PR.
• Edge cases checked: validated docs/docs.json parses, kept the visible nav small, and kept generated module pages explicitly deferred to the next phase.
• What you did not verify: I did not implement or run a Plugin SDK docs generator in this PR.

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:

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: revert commits f8b5d25192, 57ab43a31f, and 88e896e350
• Files/config to restore: docs/reference/plugin-sdk/*, scripts/lib/plugin-sdk-doc-metadata.ts, docs/docs.json, docs/plugins/building-plugins.md, docs/plugins/sdk-migration.md, experiments/plugin-sdk-docs-implementation-plan.md, src/memory/embeddings-openai.ts, src/tts/tts.ts
• Known bad symptoms reviewers should watch for: missing docs nav pages, broken internal docs links, or disagreement on the initial stability/category split

Risks and Mitigations

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

• Risk: the Phase 1 scaffold could make the reviewed subset look more complete than it is.
  • Mitigation: every new reference page calls out that generated per-module pages land in the next phase.
• Risk: the initial stability/category split might need adjustment before generator work.
  • Mitigation: the metadata file is explicit and reviewable before any generator consumes it.