Python README Customize Mode omits the `preamble` and `runtime_instructions` sections and the `preserve` action

[examon]

The Python README's "Customize Mode" section documents fewer section IDs and fewer actions than the Python SDK actually ships, so two of its statements are wrong.

python/README.md currently says:

Available section IDs: "identity", "tone", "tool_efficiency", "environment_context", "code_change_rules", "guidelines", "safety", "tool_instructions", "custom_instructions", "last_instructions".

Each section override supports four string actions: "replace", "remove", "append", and "prepend".

The shipped package exposes 12 section IDs and 5 string actions. The two missing section IDs, preamble and runtime_instructions, are both present in SystemMessageSection and carry descriptions in SYSTEM_MESSAGE_SECTIONS; the missing action, preserve, is part of the shipped SectionOverrideAction type. All three work, but a reader following the Python README has no way to discover them.

Reproduction

pip install github-copilot-sdk
python repro.py

repro.py:

import typing

from copilot.session import (
    SYSTEM_MESSAGE_SECTIONS,
    SectionOverrideAction,
    SystemMessageSection,
)

readme_section_ids = {
    "identity", "tone", "tool_efficiency", "environment_context",
    "code_change_rules", "guidelines", "safety", "tool_instructions",
    "custom_instructions", "last_instructions",
}
readme_actions = {"replace", "remove", "append", "prepend"}  # README says "four"

section_ids = set(typing.get_args(SystemMessageSection))
literal_arm = next(
    arg for arg in typing.get_args(SectionOverrideAction)
    if typing.get_origin(arg) is typing.Literal
)
string_actions = set(typing.get_args(literal_arm))

print("section IDs  README:", len(readme_section_ids), " shipped:", len(section_ids))
print("  shipped but undocumented:", sorted(section_ids - readme_section_ids))
print("actions      README:", len(readme_actions), " shipped:", len(string_actions))
print("  shipped but undocumented:", sorted(string_actions - readme_actions))
print("SYSTEM_MESSAGE_SECTIONS keys:", len(SYSTEM_MESSAGE_SECTIONS))

Expected

The README's list matches the shipped SystemMessageSection and SectionOverrideAction, so both differences are empty.

Actual

section IDs  README: 10  shipped: 12
  shipped but undocumented: ['preamble', 'runtime_instructions']
actions      README: 4  shipped: 5
  shipped but undocumented: ['preserve']
SYSTEM_MESSAGE_SECTIONS keys: 12

Why this matters

preserve is not just a missing name. It is the only way to keep an individually-addressable section when its parent group is removed, and preamble is the only way to target the identity preamble without affecting the rest of the identity group. Neither is usable if the README does not mention that they exist.

The other SDKs already document this

nodejs/README.md, go/README.md, dotnet/README.md and docs/getting-started.md all list the same 12 sections and the same 5 actions, and all explain that identity and tool_instructions are section groups. The Python README is the only place that documents this surface and gets it wrong.

[github-actions]

Documentation Gap Confirmed

Summary: The python/README.md "Customize Mode" section is out of sync with the shipped Python SDK — it documents 10 section IDs and 4 actions, while the package exports 12 section IDs and 5 actions.

Affected file: python/README.md — the "Customize Mode" section

Missing items:

• Section IDs: preamble, runtime_instructions
• Action: preserve

What needs to be added/improved:

1. Expand the "Available section IDs" list to include preamble and runtime_instructions (with descriptions matching those in SYSTEM_MESSAGE_SECTIONS).
2. Add "preserve" to the documented actions list and update the count from "four" to "five".
3. Add a note explaining the semantics of preserve — it is the only way to keep an individually-addressable section when its parent group is removed.
4. Clarify that identity and tool_instructions are section groups, consistent with nodejs/README.md, go/README.md, dotnet/README.md, and docs/getting-started.md, which already document all 12 sections and 5 actions correctly.

The other SDK READMEs and docs/getting-started.md can serve as the authoritative reference for the correct content.

Generated by Documentation Handler for #2263 · sonnet46 16.9 AIC · ⌖ 5.04 AIC · ⊞ 5.4K · ◷