docs(plugin): document experimental.chat.{system,messages}.transform and their in-place mutation requirement (Closes #25754)

[ken-jo]

Issue for this PR

Closes #25754

Type of change

• Documentation

What does this PR do?

The two experimental.chat.{system,messages}.transform hooks aren't documented on the Plugins page at all — they're not in the ### Events list, and packages/web/src/content/docs/plugins.mdx never mentions output.system / output.messages. The one mutation gotcha that bites everyone is also undocumented: you have to mutate the array in place (splice/push). Reassigning the whole array (output.system = [...]) is a silent no-op — the runtime keeps the original array reference and never reads the replacement. That's the bug already reported in #25754, whose fix-option #2 explicitly asks to "document the in-place requirement."

What makes this easy to get wrong: the nearby Compaction example sets output.prompt = "..." and that does work (it's a scalar), so a reader naturally assumes output.system = [...] works too. It doesn't.

This PR adds a short subsection under ## Examples documenting both hooks plus a callout about in-place mutation, mirroring the existing ### Compaction hooks example style. Concretely:

import type { Plugin } from "@opencode-ai/plugin"

export const SystemContextPlugin: Plugin = async (ctx) => {
  return {
    "experimental.chat.system.transform": async (input, output) => {
      // Mutate output.system IN PLACE. Insert after the first block so the
      // cached system-prompt prefix stays stable for prompt caching.
      output.system.splice(1, 0, "Extra session context")
      // output.system = [...]  // ⚠️ silently ignored — keeps the original array
    },
  }
}

And the analogous note for experimental.chat.messages.transform: use output.messages.splice(0, output.messages.length, ...next) rather than output.messages = next.

I'd add a :::caution callout: "These hooks hand you an output object whose array property is the live payload. Mutate the array in place (push/splice). Reassigning the whole array is a no-op — see #25754." I'll also cross-reference the related (but separate) guidance in #23660 (prefer merging into the primary system block over pushing extra entries for OpenAI-compatible backends) and the ordering note in #19960.

I hit this building a cross-platform MCP/hook adapter: our generated bridge has to output.system.splice(...) exactly because reassignment is dropped — so I can confirm the contract on a real integration.

How did you verify your code works?

• Confirmed on current dev: packages/web/src/content/docs/plugins.mdx (389 lines) has zero mentions of experimental.chat.system.transform, messages.transform, splice, in-place, output.system, or output.messages; the hooks aren't even in the ### Events list.
• Confirmed the type surface in packages/plugin/src/index.ts:282-296: both transform hooks are declared with no JSDoc, while the sibling experimental.session.compacting (:298-308) has a JSDoc block.
• Verified the in-place requirement matches bug: experimental.chat.messages.transform plugin contract is ambiguous — reassigning output.messages is a silent no-op (requires in-place splice) #25754's repro and the community magic-context plugin, which uses messages.splice(0, messages.length, ...) rather than reassignment.

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

[github-actions]

This issue doesn't fully meet our contributing guidelines.

What needs to be fixed:

• This submission uses a Pull Request template instead of one of the required issue templates (Bug Report, Feature Request, or Question). Please reopen using the correct template.
• The content reads as AI-generated — long, highly detailed walls of text with precise internal cross-references, line numbers, and polished prose are not acceptable for issue submissions.
• If you want to propose documentation improvements, please file a proper Feature Request (title starting with [FEATURE]:) or a Bug Report explaining the missing/incorrect documentation concisely in your own words.

Please edit this issue to address the above within 2 hours, or it will be automatically closed.

---

This issue might be a duplicate of existing issues. Please check:

• bug: experimental.chat.messages.transform plugin contract is ambiguous — reassigning output.messages is a silent no-op (requires in-place splice) #25754: Same topic — experimental.chat.messages.transform in-place mutation requirement is undocumented (the issue this PR claims to close)
• Clarify plugin guidance for experimental.chat.system.transform to avoid extra system messages #23660: Related guidance on experimental.chat.system.transform
• system.transform fires after messages.transform — plugins can't coordinate system+message mutations #19960: Related ordering concern for system.transform / messages.transform

If you believe this was flagged incorrectly, please let a maintainer know.

[github-actions]

This issue has been automatically closed because it was not updated to meet our contributing guidelines within the 2-hour window.

Feel free to open a new issue that follows our issue templates.