Skip to content

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

Description

@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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions