Lightweight coding agent that runs in your terminal
Rust
Update OpenAI Docs skill guidance for GPT-6 Astra (#42931)
Konstantine Kahadze12fe9f822c0b
diff --git a/codex-rs/skills/src/assets/samples/openai-docs/SKILL.md b/codex-rs/skills/src/assets/samples/openai-docs/SKILL.mdindex f74454101e..a872d0cb9b 100644--- a/codex-rs/skills/src/assets/samples/openai-docs/SKILL.md+++ b/codex-rs/skills/src/assets/samples/openai-docs/SKILL.md@@ -33,6 +33,6 @@ Read at most one primary reference. Do not open every route, bundled model guide- Search, open, fetch, and cite only `developers.openai.com`, `platform.openai.com`, and `learn.chatgpt.com`. Cite the page that supports the claim. State uncertainty when official sources do not establish pricing, availability, account access, limits, or behavior.- Preserve an explicitly requested model for selection, migration, and prompting. Resolve an unspecified latest or current migration target only after searching and fetching current official guidance.-- Use `references/latest-model.md` only as a disclosed fallback after current official model guidance does not answer the question. Read `references/upgrading-to-gpt-5p6-sol.md` only for an actual, requested GPT-5.6-family migration; read `references/prompting-guide.md` only for requested prompting work.+- Use `references/latest-model.md` only as a disclosed fallback after current official model guidance does not answer the question. Read `references/upgrading-to-gpt-6-astra.md` only for an actual, requested GPT-6 migration; read `references/prompting-guide.md` only for requested prompting work.- Before building, running, editing, debugging, or testing an API-backed app or tool, use `openai-platform-api-key` first when available. Documentation, conceptual examples, model selection, and read-only guidance do not require an API key.- Say "OpenAI Docs" or "official OpenAI documentation" in user-facing answers. Keep exact official citations and examples concise.diff --git a/codex-rs/skills/src/assets/samples/openai-docs/references/latest-model.md b/codex-rs/skills/src/assets/samples/openai-docs/references/latest-model.mdindex 27d46ffd05..d4fca8c4f0 100644--- a/codex-rs/skills/src/assets/samples/openai-docs/references/latest-model.md+++ b/codex-rs/skills/src/assets/samples/openai-docs/references/latest-model.md@@ -2,16 +2,16 @@This is a compact, non-authoritative fallback, not a source for current availability, prices, aliases, or defaults. First search for and fetch current official model guidance at `https://developers.openai.com/api/docs/guides/latest-model` and the relevant official model page. The fetched official documentation wins if this snapshot has drifted. Disclose any use of this fallback.-## GPT-5.6 family+## Model roles| Model ID | Documented workload to verify against the current model page || --- | --- |-| `gpt-5.6` | GPT-5.6 family alias; verify its currently documented routing and availability. |-| `gpt-5.6-sol` | Quality-first flagship, reasoning, and difficult coding work. |+| `gpt-6` | GPT-6 family alias; verify its currently documented routing and availability. |+| `gpt-6-astra` | Quality-first flagship, reasoning, and difficult coding work. || `gpt-5.6-terra` | Balanced quality, latency, and cost. |-| `gpt-5.6-luna` | High-throughput, lower-latency work. |+| `gpt-5.6-luna` | Primary choice for faster or cheaper workloads. |-Use `https://developers.openai.com/api/docs/guides/upgrading-to-gpt-5p6-sol` for an actual GPT-5.6 migration and `https://developers.openai.com/api/docs/guides/prompt-guidance-gpt-5p6` for requested GPT-5.6 prompting. Open and read the relevant page before recommending a request shape, reasoning setting, endpoint, tool behavior, or migration.+Use `https://developers.openai.com/api/docs/guides/latest-model/gpt-6-astra.md#migration-quickstart` for an actual GPT-6 migration and `https://developers.openai.com/api/docs/guides/latest-model/gpt-6-astra.md#prompting-best-practices` for requested GPT-6 prompting. Open and read the relevant page before recommending a request shape, reasoning setting, endpoint, tool behavior, or migration.## Explicitly requested existing models@@ -20,6 +20,6 @@ Use `https://developers.openai.com/api/docs/guides/upgrading-to-gpt-5p6-sol` for| `gpt-4.1` | Preserve only when the user explicitly requests this model or existing migration target; search and fetch its own current official guide. || `gpt-5.4` | Preserve only when the user explicitly requests this model or existing migration target; search and fetch its own current official guide. |-Do not promote a legacy model as the current default, substitute it into an unrelated task, or replace an explicitly requested legacy target with GPT-5.6. Recommend a specialized image, audio, realtime, coding, moderation, or embedding model only after verifying the requested modality against current official documentation.+Do not promote a legacy model as the current default, substitute it into an unrelated task, or replace an explicitly requested legacy target with GPT-6 Astra. Recommend a specialized image, audio, realtime, coding, moderation, or embedding model only after verifying the requested modality against current official documentation.-Verify GPT-5.6 Pro against current official Responses and model documentation before describing model IDs, reasoning modes, request parameters, or account availability; do not invent a separate `gpt-5.6-pro` model slug.+Verify GPT-6 Pro against current official Responses and model documentation before describing model IDs, reasoning modes, request parameters, or account availability; do not invent a separate `gpt-6-pro` model slug.diff --git a/codex-rs/skills/src/assets/samples/openai-docs/references/model-migration.md b/codex-rs/skills/src/assets/samples/openai-docs/references/model-migration.mdindex 895fca9328..934c5c1ec3 100644--- a/codex-rs/skills/src/assets/samples/openai-docs/references/model-migration.md+++ b/codex-rs/skills/src/assets/samples/openai-docs/references/model-migration.md@@ -4,7 +4,7 @@ Use this route for model upgrades, migration planning, model-specific prompting,## Choose the target before loading more context-- **Explicit model target:** Preserve the user's exact requested target, including an explicitly requested GPT-4.1 or GPT-5.4 migration. Do not run the latest-model resolver and do not substitute a newer model. Search for and fetch current guidance for that exact model. A GPT-5.4 migration must not load GPT-5.6 guidance or references.+- **Explicit model target:** Preserve the user's exact requested target, including an explicitly requested GPT-5.5 or GPT-5.6 migration. Do not run the latest-model resolver and do not substitute a newer model. Search for and fetch current guidance for that exact model. A GPT-5.6 migration must not load GPT-6 guidance or references.- **Unspecified, latest, current, or default target:** Search for and fetch `https://developers.openai.com/api/docs/guides/latest-model` first. Use the corresponding `latest-model.md` metadata only when dynamic migration resolution is needed, then run the platform-specific resolver below and preserve its returned model and exact guide URLs.- **Latest/current/default prompting:** Follow the dynamic-target route, then use the returned prompting guide. Do not run the resolver for explicitly named-model prompting.- **Pure model selection:** Use `references/model-selection.md` instead. Do not run the resolver.@@ -30,9 +30,9 @@ Do not suppress or redirect resolver stdout. Success requires JSON with nonemptyTreat returned guide URLs as opaque: fetch those exact URLs without deriving, substituting, or appending a model query. Use an available official documentation or first-party-domain capability to open and read the relevant official page. Retry the exact guide URL when its response contains only a title or no substantive body.- Fetch `migrationGuideUrl` for a requested migration or upgrade plan.-- Fetch `promptingGuideUrl` only when the user asks for prompting guidance or the migration requires a prompt change. Extract only `## Prompting Best Practices` through the next H2 heading.-- For explicitly named-model prompting, fetch that model's official prompting guidance and extract only `## Prompting Best Practices` through the next H2 heading. Do not load a migration reference or run the resolver.-- For an actual GPT-5.6-family migration or implementation plan, fetch `https://developers.openai.com/api/docs/guides/upgrading-to-gpt-5p6-sol`. For specifically requested GPT-5.6 prompting, fetch `https://developers.openai.com/api/docs/guides/prompt-guidance-gpt-5p6`. Read `references/upgrading-to-gpt-5p6-sol.md` only when fetched official guidance does not resolve needed compatibility gates, scoped code changes, tier-aware routing, validation, or other migration-specific judgment. Never load it for documentation-only questions about model tiers, the family alias, Pro mode, reasoning effort, or current guidance when the fetched official documentation already answers them.+- Fetch `promptingGuideUrl` only when the user asks for prompting guidance or the migration requires a prompt change. Extract only `## Prompting best practices` through the next H2 heading.+- For explicitly named-model prompting, fetch that model's official prompting guidance and extract only `## Prompting best practices` through the next H2 heading. Do not load a migration reference or run the resolver.+- For an actual GPT-6 migration or implementation plan, fetch `https://developers.openai.com/api/docs/guides/latest-model/gpt-6-astra.md#migration-quickstart`. For specifically requested GPT-6 prompting, fetch `https://developers.openai.com/api/docs/guides/latest-model/gpt-6-astra.md#prompting-best-practices`. Read `references/upgrading-to-gpt-6-astra.md` only when fetched official guidance does not resolve needed compatibility gates, scoped code changes, tier-aware routing, validation, or other migration-specific judgment. Never load it for documentation-only questions about model tiers, the family alias, Pro mode, reasoning effort, or current guidance when the fetched official documentation already answers them.- Read `references/prompting-guide.md` only when prompting guidance or prompt changes are actually needed and current official guidance is unavailable.- Read `references/upgrade-guide.md` only when current official migration guidance is unavailable. Disclose when a bundled fallback was used.diff --git a/codex-rs/skills/src/assets/samples/openai-docs/references/prompting-guide.md b/codex-rs/skills/src/assets/samples/openai-docs/references/prompting-guide.mdindex 221a6d1133..2370a8a1ab 100644--- a/codex-rs/skills/src/assets/samples/openai-docs/references/prompting-guide.md+++ b/codex-rs/skills/src/assets/samples/openai-docs/references/prompting-guide.md@@ -1,287 +1,115 @@-## Retrieve the live GPT-5.6 prompting guidance+## Retrieve the live GPT-6 prompting guidance-Use already-callable official documentation search and fetch, or immediately use official-domain web search and fetch, to retrieve the live GPT-5.6 prompting guidance from:+Use already-callable official documentation search and fetch, or immediately use official-domain web search and fetch, to retrieve the live GPT-6 prompting guidance from:-https://developers.openai.com/api/docs/guides/model-guidance?model=gpt-5.6#prompting-best-practices+https://developers.openai.com/api/docs/guides/latest-model/gpt-6-astra.md#prompting-best-practices-Read only the `## Prompting Best Practices` section, stopping at the next H2 heading. The URL anchor points to the section visually, but a documentation fetch may return the full page, so explicitly extract only that section.+Read only the `## Prompting best practices` section, stopping at the next H2 heading. The URL anchor points to the section visually, but a documentation fetch may return the full page, so explicitly extract only that section.-Treat the live section as the canonical model-specific prompting guidance. Use the local guidance below only for skill-specific migration judgment: deciding what to preserve, remove, rewrite, or test when adapting an existing prompt stack to GPT-5.6.+Treat the live section as the canonical model-specific prompting guidance. Use the local copy below only when live guidance is unavailable. Keep it identical to the page's `## Prompting best practices` section when refreshing this reference.-## Skill-specific migration judgment+## Prompting best practices-GPT-5.6 works best when prompts define the outcome, important constraints, available evidence, and completion bar, then leave room for the model to choose an efficient path. Compared with earlier GPT-5 models, many applications can use shorter prompts and smaller tool sets without losing quality.+GPT-6 Astra is more intelligent and capable than prior models like GPT-5.6 Sol, and also exhibits behavior patterns that can be optimized through prompting the model for your use case.-Do not carry over every instruction from an older prompt stack. Legacy prompts often repeat rules, prescribe unnecessary steps, expose irrelevant tools, or include examples that no longer change behavior. With GPT-5.6, this can encourage extra exploration, repeated validation, and larger accumulated context.+### GPT-6 Astra behavior-Start with the smallest prompt and tool set that passes your evals. Add an instruction, example, or tool only when it fixes a measured failure mode.+- [Initiative and follow-through](#initiative-and-follow-through) – The model is designed to be a more effective collaborator and is thus more likely to ask the user a question when additional input could materially change the result. This can cause it to stop when the user may expect it to make reasonable assumptions and persist.+- [Instruction following](#instruction-following) – GPT-6 Astra is stronger at general instruction following than our previous models, giving you greater control over its behavior. It can be more sensitive to instructions contained in skills and other files, such as `AGENTS.md`. We **strongly recommend** auditing skills and other files accessible to your model for instructions that could influence its behavior.+- [Personality and writing style](#personality-and-writing-style) – The model tends toward detailed, formatted responses and may use recurring phrases across sessions. Specify the writing style and structure your application needs.+- [Subagent delegation](#subagent-delegation) – The model may delegate less often than desired for your workflow. Specify when and how much it should use subagents for parallel work.+- [Testing and verification](#testing-and-verification) – For coding tasks, the model tends to be thorough in testing before considering a task complete. For smaller tasks, this can result in broader tests than the task requires.-## Simplify prompts first+### Initiative and follow-through-When migrating an existing prompt, remove redundant scaffolding before adding new GPT-5.6-specific instructions.+GPT-6 Astra is generally better than GPT-5.6 Sol and earlier models at staying coherent during long tasks. It is also more likely to ask for clarification where earlier models would make assumptions.-Trim:+To encourage more autonomous work, start with this prompt:-- repeated statements of the same rule;-- generic “be thorough,” “be concise,” or “think step by step” language;-- examples that do not change behavior;-- process instructions for behavior the model already performs reliably;-- tools and tool descriptions unrelated to the task.+```text+You should infer the user's intent and task scope from the instructions and prior conversation context. Your job is to bias towards action and carry the user's intended task to completion.-Keep:+When the user expresses intent to perform new work or fix an existing issue, persist until the user's intended goal is complete. Progress autonomously towards the user's goal (e.g. creating isolated worktrees / checkouts if needed, resolving merge conflicts, read-only actions, creating draft PRs etc.) unless they are clearly destructive or irreversible.+```-- the user-visible outcome;-- success criteria and stopping conditions;-- safety, business, evidence, and permission constraints;-- tool-routing rules when the correct route is not obvious;-- required output shape and validation requirements.+When the user’s intent is unclear, the model is more likely to ask the user for clarification to proceed. Prompt the model to follow through if the user’s prompt implies authorization:-Review the remaining instructions for contradictions. GPT-5-class models follow prompt contracts closely, so conflicting rules can create more instability than missing detail.+```text+When the user's prompt indicates a request for action, such as "can you...", "I want to...", "help me..." and similar expressions, treat these as instructions to do the work and take action. Do not stop at acknowledging capability (e.g. "Yes…"), proposing a plan, or offering to continue. Do not settle for a partial or "helpful enough" solution that does not fully satisfy the user's task to save time, effort or tokens. If a task requires sustained work, complete all the necessary work until the intended outcome is fulfilled.+```-## Outcome-first prompts and stopping conditions+Prompt the model to ask for approval only after preparing a concrete, reviewable result. This avoids blocking the task before the model has done the work it can, and often leads to quicker task completion.-Describe the destination rather than prescribing every step. GPT-5.6 can usually choose an efficient search, tool, or reasoning path when the prompt states what good looks like.+```text+Before asking the user clarifying questions, you should complete the work that is already authorized from context and necessary to make the proposed action concrete and reviewable. The user should be approving a concrete, reviewable result. For example, before deploying a change, writing to an external application, merging a PR or publishing a site, do all the required work first so that user approval is the final step. You don't need user permission for reversible tasks, read-only actions, reviews or fixes, or anything for which authorization is provided earlier in the session or strongly implied from the task instruction.-Prefer:+Do not introduce unsolicited warnings, disclaimers, approval flows, or safety/compliance checklists due to hypothetical risk.+```- Resolve the customer's issue end to end.+The model also likes to ask non-blocking questions as it’s working by default, so adjust these prompts to match the level of autonomy your application needs.- Success means:- - make the eligibility decision from available policy and account evidence- - complete any allowed action before responding- - return completed_actions, customer_message, and blockers- - if required evidence is missing, ask for the smallest missing field+### Instruction following-Avoid unnecessary absolute rules. Use ALWAYS, NEVER, must, and only for true invariants such as safety rules, required fields, or actions that should never happen. For judgment calls, such as when to search, ask, use a tool, or keep iterating, prefer decision rules.+GPT-6 Astra is better able to follow longer instructions, but can also be more sensitive to information in context. For example, unclear or conflicting guidance in a skill file may cause the model to pause and block work early. Make the priority of user instructions and skills explicit.-Preserve explicit user values. When the correct value is implicit, provide decision criteria and let the model reason from context or schema. Avoid universal defaults, keyword maps, and broad semantic shortcuts.+```text+The user's instructions take precedence over guidelines provided in a skill. If explicit user instructions conflict with a skill's instructions, prioritize the user's instructions.+```-Add stopping conditions:+Asking the model to identify the skill and instruction that caused it to pause or change direction can also be effective in providing transparency into model behavior.- Resolve the request in the fewest useful tool loops, but do not let loop- minimization outrank correctness, required evidence, calculations, or- required citations.+```text+If a skill causes you to ask for permission or confirmation, pause, leave requested work unfinished, or diverge from the user's intent, name and link to the exact SKILL.md file you read, quote the relevant instruction, and briefly explain how it applies. Distinguish explicit skill requirements from your interpretation of guidelines.+```- After each result, ask whether the core request can now be answered with- useful evidence. If yes, answer. If required evidence is still missing,- name the missing fact and use the smallest useful fallback.+Use this prompt to find silent and conflicting guidance when your application loads many skills and instruction files such as `AGENTS.md`.-## Personality, collaboration, and response length+### Personality and writing style-GPT-5.6 is efficient, direct, and more compressed than recent models. For customer-facing assistants and collaborative products, define both personality and collaboration style.+GPT-6 Astra tends to use lists, tables and Markdown to make responses scannable. If your application needs prose with less formatting, specify that preference.-- Personality controls tone, warmth, directness, formality, humor, empathy, and polish.-- Collaboration style controls when the model asks questions, makes assumptions, takes initiative, explains tradeoffs, checks work, and handles uncertainty.+```text+Default to using clear, concise paragraphs, each developing one main idea. Use lists only when the information is genuinely parallel, sequential, or easier to compare, and avoid nested lists unless the hierarchy cannot be expressed clearly in prose. Use plain, simple language: familiar words, concrete examples, and precise verbs. Prefer active voice and direct statements.-Keep both short. Personality should shape the user experience; collaboration instructions should shape task behavior. Neither should replace clear goals, success criteria, tool rules, or stopping conditions.+Make sure to state the main point clearly and early, then develop it with the explanation and detail the reader needs. Let each sentence build on what came before. Develop the points that matter and provide enough support to be useful.+```-Use concrete writing controls:+For technical communication, the following prompt helps strike a balance between using clear, coherent language while remaining domain appropriate:- Lead with the conclusion. Include the evidence needed to support it, any- material caveat, and the next action. Keep all required facts, decisions,- caveats, and next steps. Trim introductions, repetition, generic reassurance,- and optional background first.+```text+Use plain language over jargon, and reference technical details only to the degree that it helps illustrate an idea or your work to the user. Communicate complex concepts in a clear and cohesive manner, and calibrate your writing to the level of background knowledge assumed from the user's prompt and context.+```-Avoid generic “be brief,” “keep it short,” or “use minimal text” instructions. GPT-5.6 is already biased toward compression, and generic brevity can make it omit required evidence or parts of an artifact.+To reduce jargon and stock phrases in writing, start with this prompt:-For customer-facing tone, prefer concrete guidance:+```text+Avoid using slop words or phrases like "Bottom Line:" in conclusions, "delve," "foster," "leverage," "it's worth noting," "importantly," "Question? Answer." or "This isn't about X. It's about Y.", "genuinely" or hyphenated compound descriptions and adjectives. Do not use concluding summary statements such as "In short:..", "The simplest mental model is:...".- Be direct and tactful. Acknowledge friction specifically when relevant.- Avoid canned reassurance and unnecessary sign-offs.+State the intended action directly. Avoid adding what you won't do, what will remain unchanged, or how you'll separate or categorize results. Do not use contrastive framing such as "X, not Y" or "X—not Y" that introduces an unprompted alternative that the user didn't ask about. Avoid invented compound labels like "exact-head checks" and "editorial-row layouts", vague qualifiers, and canned transitions; use plain verbs and prepositions to state the actual relationship directly.+```-Avoid blanket language rules such as “always respond in the user's language” unless that is truly the product requirement. Specify the intended output language and when it should change.+### Subagent delegation-For editing, rewriting, summaries, and customer-facing drafts, tell the model what to preserve:+GPT-6 Astra is trained to be able to divide and delegate work to subagents that work in parallel. If you are implementing a multi-agent system in your harness, use the following prompt to tune how much GPT-6 Astra should delegate work:- Preserve the requested artifact, length, structure, genre, and factual claims- first. Improve clarity, flow, and correctness without adding new claims,- sections, or a more promotional tone unless requested.+```text+If at any point you can parallelize work by delegating tasks to another agent (no matter if you are the root or subagent), you should do so using collaboration tools if it could save time or improve quality.+```-## Autonomy and permissions+Messages between agents may contain grammar or spacing errors. Use this prompt to make inter-agent messages easier to read:-GPT-5.6 can be proactive and persistent. Define which level of action each request authorizes.+```text+Messages that you send to other agents and your final answer may be read by a human, so ensure they are legible. Always put proper spaces between words and/or numbers.+```- For requests to answer, explain, review, diagnose, or plan, inspect the- relevant materials and report the result. Do not implement changes unless- the request also asks for them.+The model tends to respond well to prompting for how and when it should delegate work to subagents, so tune this behavior to fit with your harness and multi-agent implementation.- For requests to change, build, or fix, make the requested in-scope local- changes and run relevant non-destructive validation without asking first.+### Testing and verification- Require confirmation for external writes, destructive actions, purchases,- or a material expansion of scope.+For coding tasks, calibrate how much testing and verification a change requires. This can help avoid unnecessary tests or repeated checks for small changes.-Specify which local actions are safe without approval, such as reading files, inspecting logs, searching, editing in-scope code, and running non-destructive tests.+```text+Do not write tests for reversible, low-impact changes that mirror the implementation. If you do choose to verify your work with tests, make sure that the tests are meaningful and necessary to verify implementation.-Avoid repeating “ask first” throughout the prompt. Repetition can cause unnecessary permission checks even for safe, expected actions.--For long-running work, define the current layer of work. Distinguish research, design, implementation, review, and external coordination so the model does not silently move from one layer to another.--## Tool routing--Expose only task-relevant tools. Tool descriptions should state what the tool does, when to use it, important return fields, and error behavior.--When correctness depends on prerequisite retrieval or lookup, say so:-- Before taking an action, resolve required discovery, retrieval, and- validation steps. Do not skip a prerequisite because the intended final- state seems obvious.--When several reads are independent, parallelize them. When one result determines the next action, keep the work sequential. After parallel retrieval, synthesize before acting.--If a tool returns empty, partial, or suspiciously narrow results, try one or two meaningful fallbacks before concluding that no result exists.--## Programmatic Tool Calling--Programmatic Tool Calling is useful when code can reduce large, structured intermediate results before they return to model context.--Use it for:--- filtering, joining, sorting, ranking, deduplication, and aggregation;-- batching across many similar records;-- repeated deterministic validation;-- large structured results that can be reduced to a compact schema.--Prefer direct tool calls when:--- one call is sufficient;-- intermediate outputs are already small;-- each result may change the next decision;-- an action requires approval;-- the final answer must preserve citations or native artifacts;-- the workflow requires semantic judgment between calls.--Do not rely on generic instructions such as “use Programmatic Tool Calling efficiently.” State the bounded stage, eligible tools, output schema, retry limit, stop condition, and handoff back to direct model judgment.-- Use Programmatic Tool Calling only for the bounded record-reduction stage.- Call only the documented read-only tools. Filter and deduplicate the- intermediate results, then emit exactly the required compact schema with- evidence fields. Retry transient failures at most twice. Use direct tool- calls for approval, semantic judgment, citations, and final validation.--Evaluate the final user-visible answer, not only the program result. Lower tokens, latency, calls, or turns are improvements only when the final answer still meets the required quality bar.--## Grounding, citations, and retrieval budgets--For grounded answers, citation behavior should be part of the prompt. Define what needs support, what counts as enough evidence, and how to behave when evidence is missing. Absence of evidence should not automatically become a factual “no.”-- For ordinary Q&A, start with one broad search using short, discriminative- keywords. If the top results contain enough support for the core request,- answer from those results.-- Make another retrieval call only when a required fact, owner, date, ID, or- source is missing; the user asked for exhaustive coverage or comparison; a- specific artifact must be read; or an important claim would otherwise be- unsupported.-- Do not search again only to improve phrasing, add examples, or support- nonessential detail.--For research and synthesis:--- cite only retrieved sources;-- attach citations to the claims they support;-- label inference separately from directly supported facts;-- state conflicts between sources;-- narrow the answer or report missing evidence instead of guessing.--For creative drafting, distinguish source-backed facts from creative wording. Do not invent names, metrics, dates, roadmap status, customer outcomes, or product capabilities to make a draft sound stronger.--## Long-running workflows and state--For multi-step or tool-heavy tasks, prompt for a short visible preamble before the first tool call, then sparse outcome-based updates at major phase changes. Do not ask the model to narrate routine tool calls.-- Before tool calls for a multi-step task, send a one- or two-sentence- user-visible update that states the first step. During the task, update only- when a major phase begins or a finding changes the plan. Each update should- state one concrete outcome and the next step.--Preserve assistant phase values when replaying history so the model can distinguish commentary from the final answer. If using previous_response_id, prior assistant state is preserved automatically. If replaying history manually, preserve each original phase value unchanged.--Compact after major milestones rather than every turn. Keep the prompt functionally consistent after compaction and treat compacted items as opaque state.--Persisted reasoning is useful when the objective, assumptions, and priorities remain stable across turns. Use current-turn behavior when earlier reasoning is no longer relevant. Do not treat persisted reasoning as an always-on optimization: stale reasoning can add tokens, increase latency, and anchor the model to an outdated approach.--Prompt caching also affects prompt construction. Keep reusable prefixes stable and avoid unnecessary churn in large system prompts. Use explicit cache breakpoints only when they improve measured cache behavior and cost for the workload.--## Reasoning effort--Treat reasoning effort as a last-mile tuning knob, not the first response to a weak result.--- Preserve the current GPT-5.5 or GPT-5.4 reasoning effort as the baseline.-- Test the same setting and one level lower on representative tasks.-- Use low for latency-sensitive work when it preserves quality.-- Use medium as a balanced starting point.-- Use high or xhigh only when evals show a meaningful gain.-- Reserve max for the hardest quality-first workloads; do not recommend it globally.--Before increasing reasoning effort, check whether the prompt is missing a success criterion, dependency rule, tool-routing rule, or verification loop.--## Frontend and visual tasks--GPT-5.6 has stronger layout, visual hierarchy, and design judgment. Still provide product context, preserve the existing design system, and name the states and constraints that matter.--For incremental frontend changes:--- inspect and preserve existing design tokens, components, and patterns;-- do not add extra features or decorative UI unless requested;-- preserve responsive behavior and expected states;-- render and inspect the result before finalizing.--For vision, computer use, localization, or OCR tasks where spatial precision matters, choose image detail intentionally. Use original detail for large, dense, or coordinate-sensitive images when the extra input cost and latency are justified.--## Check work before finishing--Give GPT-5.6 access to tools that can validate the output, and state what validation matters.--For coding:-- After making changes, run the most relevant validation available:- - targeted tests for changed behavior- - type checks or lint checks when applicable- - build checks for affected packages- - a minimal smoke test when full validation is too expensive-- If validation cannot be run, explain why and describe the next best check.--For visual artifacts:-- Render the artifact before finalizing. Inspect layout, clipping, spacing,- missing content, and visual consistency. Revise until the rendered output- matches the requirements.--For implementation plans, include requirements, named resources or files, state transitions or data flow, validation checks, failure behavior, privacy or security considerations, and open questions that materially affect implementation.--## Suggested prompt structure--Use this structure as a starting point for complex prompts. Keep each section short. Add detail only where it changes behavior.-- Role: [the model's function and context]-- Personality: [tone and collaboration style]-- Goal: [user-visible outcome]-- Success criteria: [what must be true before the final answer]-- Constraints: [policy, safety, business, evidence, and side-effect limits]-- Tools: [which tools to use, when, and what not to use]-- Output: [sections, length, format, and tone]-- Stop rules: [when to retry, fallback, abstain, ask, or stop]--## Prompt migration workflow--When moving an existing application to GPT-5.6:--1. Switch the model and preserve the current reasoning effort.-2. Run representative evals before changing the prompt.-3. Remove obsolete scaffolding, repeated instructions, and irrelevant tools.-4. Add only the smallest targeted instruction that fixes a measured regression.-5. Re-run evals after each prompt or reasoning change.--Do not rewrite a working prompt stack all at once. Otherwise you cannot tell whether a behavior change came from the model, reasoning setting, prompt, tool set, or runtime.--When a prompt regresses, debug it with a small set of real traces. Identify the failure mode, find the instruction or contradiction that likely caused it, make a surgical edit, and rerun the same cases.+Run tests appropriate to the change and complete required checks. Once those pass, broaden or repeat testing only when new changes, failures, or unresolved concerns justify it; otherwise, continue toward completing the task.+```diff --git a/codex-rs/skills/src/assets/samples/openai-docs/references/upgrade-guide.md b/codex-rs/skills/src/assets/samples/openai-docs/references/upgrade-guide.mdindex 8134bc6d55..c367ee4d52 100644--- a/codex-rs/skills/src/assets/samples/openai-docs/references/upgrade-guide.md+++ b/codex-rs/skills/src/assets/samples/openai-docs/references/upgrade-guide.md@@ -9,14 +9,14 @@ For latest, current, default, or unspecified-model upgrades:3. Treat the live guides as canonical.4. If remote retrieval fails, disclose that bundled fallback guidance is being used.-For an explicit GPT-5.6 Sol or GPT-5.6-family migration:+For an explicit GPT-6 Astra migration:1. Preserve the user's explicit target; do not run the latest-model resolver.-2. Fetch the live GPT-5.6 model guidance:+2. Fetch the live GPT-6 model guidance:- https://developers.openai.com/api/docs/guides/model-guidance?model=gpt-5.6+ https://developers.openai.com/api/docs/guides/latest-model/gpt-6-astra.md-3. Read `references/upgrading-to-gpt-5p6-sol.md` for skill-specific migration judgment.+3. Read `references/upgrading-to-gpt-6-astra.md` for skill-specific migration judgment.4. Read `references/prompting-guide.md` only when prompt changes are needed.-For another explicit model target, preserve that target and fetch its current official guidance. Do not reuse GPT-5.6-specific defaults, API shapes, or compatibility rules for a different model.+For another explicit model target, preserve that target and fetch its current official guidance. Do not reuse GPT-6-specific defaults, API shapes, or compatibility rules for a different model.diff --git a/codex-rs/skills/src/assets/samples/openai-docs/references/upgrading-to-gpt-5p6-sol.md b/codex-rs/skills/src/assets/samples/openai-docs/references/upgrading-to-gpt-5p6-sol.mddeleted file mode 100644index 43f506fce6..0000000000--- a/codex-rs/skills/src/assets/samples/openai-docs/references/upgrading-to-gpt-5p6-sol.md+++ /dev/null@@ -1,448 +0,0 @@-# Upgrading to GPT-5.6 Sol--Use this guide when the user asks to migrate an existing OpenAI API integration, repository, prompt stack, agent, model router, or model picker to GPT-5.6 Sol or the GPT-5.6 family.--The default explicit target is `gpt-5.6-sol`. The alias `gpt-5.6` routes to Sol; use it only when the repository intentionally prefers family aliases. Do not treat every old model usage as a Sol candidate: GPT-5.6 is a family with different cost, latency, context, and quality roles.--Before changing code, retrieve the current live GPT-5.6 model guidance using already-callable official documentation search and fetch, or immediately use official-domain web search and fetch:--https://developers.openai.com/api/docs/guides/model-guidance?model=gpt-5.6--For prompt changes, also read only the `## Prompting Best Practices` section from:--https://developers.openai.com/api/docs/guides/model-guidance?model=gpt-5.6#prompting-best-practices--Treat live docs as canonical for current model IDs, parameters, limits, pricing, and feature availability. This file supplies migration judgment: where to look, what can break, what to preserve, what not to adopt automatically, and how to validate the result.--## Core principle--Do not perform a blind model-string replacement.--First preserve the behavior, latency class, cost class, reasoning level, endpoint contract, tool semantics, cache behavior, and output contract of each usage site. Then make the smallest safe migration. Adopt new GPT-5.6 capabilities only when they solve a measured problem or the user explicitly asks for them.--A model upgrade alone does not authorize adding reasoning fields, changing request schemas, or rewriting tests. Only add explicit reasoning when the old effective behavior is established and omission would change behavior on GPT-5.6.--The main 5.6 migration hazards are:--- choosing Sol for workloads that were intentionally mini, nano, low-cost, or latency-sensitive;-- inheriting 5.6's default `medium` reasoning where the old effective effort was `none`;-- using Chat Completions with function tools without explicitly setting effective reasoning to `none`;-- losing prompt-cache hits when a stable prefix is followed by a changing suffix;-- increasing image or PDF input tokens because omitted or `auto` detail behaves differently;-- applying new cache, persisted-reasoning, Pro, Programmatic Tool Calling, or multi-agent fields to routes that do not support them;-- updating model strings but forgetting registries, allowlists, pricing metadata, capability flags, tests, and UI model pickers.--## Migration posture--Classify every usage site before editing:--1. `simple Sol migration`- - One flagship model usage.- - Same endpoint and request shape can remain.- - Reasoning effort is explicit or its old effective value is known.- - No cache, vision, file, tool, or parser behavior needs implementation changes.-2. `tier-aware family migration`- - The repository exposes multiple model roles, model choices, fallbacks, routers, pricing data, or capability metadata.- - Map each role to Sol, Terra, or Luna instead of replacing everything with Sol.-3. `compatibility migration`- - The safe move requires parameter, endpoint, cache, state, tool-loop, or multimodal-detail changes.- - Make these changes only when implementation work is inside the user's requested scope. Otherwise report the exact blocker and smallest follow-up.-4. `prompt migration`- - The API shape can remain, but representative traces show a prompt-specific regression.- - Make a surgical prompt edit tied to that failure; do not rewrite a working prompt stack wholesale.- - When the task is to update prompting guidance, edit the directly tied prompt surface only. Do not modify runtime request code, model schemas, or tests unless the prompt change requires it.-5. `optional feature adoption`- - Pro mode, persisted reasoning, explicit caching, Programmatic Tool Calling, or multi-agent behavior is being added deliberately.- - Keep this separate from the baseline migration so its effect can be measured.-6. `leave unchanged`- - Historical examples, documentation about old models, snapshots, fixtures, eval baselines, comparison code, intentionally pinned fallbacks, unsupported providers, or ambiguous usages.--When intent is unclear, prefer leaving a usage unchanged and list it for confirmation over silently changing its role.--## Inventory before editing--Search for more than literal model IDs. Inventory:--- model strings, aliases, environment variables, CLI flags, config defaults, and deployment settings;-- SDK calls to Responses, Chat Completions, Batch, or provider adapters;-- reasoning settings, token budgets, sampling settings, and latency timeouts;-- function tools, hosted tools, structured outputs, response parsers, and replay logic;-- system, developer, user, and tool-description prompts tied to each usage;-- routers, fallbacks, model allowlists, enums, regexes, validation schemas, and capability maps;-- model picker UI, display labels, descriptions, context limits, pricing metadata, and provider catalogs;-- prompt-cache keys, retention options, stable-prefix construction, and cache metrics;-- image, PDF, file, OCR, and computer-use inputs;-- tests, fixtures, snapshots, evals, analytics labels, billing tables, and docs.--When changing a default model, search every active default surface: runtime config, environment/config files, setup docs, tests, CLI defaults, and deployment examples. Update them together.--For each usage site, record:--- source model and why it appears to be used;-- endpoint and SDK/client surface;-- prompt surface;-- effective reasoning effort, including defaults;-- latency, cost, context, and quality role;-- tools, structured outputs, caching, state replay, and multimodal inputs;-- downstream parsers or user-visible contracts;-- migration class and validation plan.--## Choose the target model by role--Use this as a starting map, then validate against the repository's workload:--| Existing role | Starting GPT-5.6 target | Reason |-| --- | --- | --- |-| Unsuffixed GPT-5 flagship, GPT-5.5, or GPT-5.4 flagship | `gpt-5.6-sol` | Sol is the flagship-equivalent tier. |-| Mini model, balanced lower-cost route, or medium-throughput worker | `gpt-5.6-terra` | Terra is the mini-like tier. |-| Nano model, classification, extraction, routing, high-volume, or strict-latency route | `gpt-5.6-luna` | Luna is the nano-like tier. |-| GPT-4.1 or GPT-4o latency-sensitive flow | Evaluate Luna and Terra first; use Sol only if quality requires it | A flagship replacement can change latency and cost materially. |-| Reasoning-heavy or hardest quality-first flow | Start with Sol at the old effective effort | Preserve the reasoning contract before tuning. |-| Old Pro usage | Sol plus `reasoning.mode: "pro"`, only if the user wants Pro behavior | GPT-5.6 Pro is a mode, not a separate model slug. |-| Router, fallback, or model picker | Add the family by role | Do not collapse a multi-model design into Sol. |-| Third-party or provider-specific model | Leave unchanged unless the user explicitly requests provider migration | Model-name similarity is not a safe mapping. |--Important limits to check in live docs:--- Sol and Terra have roughly 1.05M context and 128K maximum output.-- Luna has a smaller 400K context and 128K maximum output.-- Sol and Terra long-context requests above 272K input tokens can change pricing for the full request.--Do not invent prices, limits, or capability flags. Fetch them from current docs before updating a registry or UI.--For model pickers and registries, preserve existing model entries by default. Add GPT-5.6 Sol, Terra, and Luna as new options unless the user explicitly asks to replace or remove older models. Do not invent pricing, context limits, capabilities, or metadata unless confirmed from canonical docs.--If using the `gpt-5.6` alias, record the returned `response.model` during validation. Do not assume an alias and an explicit Sol slug appear identically in dashboards, rate-limit configuration, analytics, or billing metadata.--## Preserve effective reasoning before tuning--GPT-5.6 supports `none`, `low`, `medium`, `high`, `xhigh`, and `max`. If omitted, GPT-5.6 defaults to `medium`.--This is a behavioral migration hazard:--- GPT-5.5 commonly defaulted to `medium`.-- GPT-5.4, mini, and nano usages commonly defaulted to `none`.-- A previously omitted setting can therefore become slower, more expensive, and incompatible with Chat Completions function tools after the model swap.--For each usage:--1. If effort is explicit, preserve it for the first 5.6 run when supported.-2. If effort is omitted and the old effective default is known, add it explicitly only when GPT-5.6's omitted default would change behavior. If both old and new omitted defaults are the same, keep it omitted.-3. If the old effective value is unknown, do not guess. Flag it and compare the old behavior with 5.6 at the likely baseline.-4. After the baseline passes, test the same setting and one lower on representative tasks.-5. Use `xhigh` or `max` only for hard quality-first workloads where evals show a meaningful gain.--Do not globally recommend `max`. Before increasing effort, check whether the actual failure is a missing success criterion, dependency rule, tool-routing rule, state-replay bug, or validation loop.--Use the field shape that belongs to the endpoint.--Responses:--```json-{- "model": "gpt-5.6-sol",- "reasoning": { "effort": "none" }-}-```--Chat Completions:--```json-{- "model": "gpt-5.6-sol",- "reasoning_effort": "none"-}-```--## Chat Completions and function tools--This is the most important endpoint-specific check.--For GPT-5.6, function tools in Chat Completions are compatible only with effective reasoning `none`. Reasoning with tools should use the Responses API.--Because GPT-5.6 defaults to `medium`, this combination is unsafe:--```json-{- "model": "gpt-5.6-luna",- "tools": [{ "type": "function", "function": { "...": "..." } }]-}-```--For a latency-sensitive Chat Completions flow that must keep function tools, explicitly preserve `none`:--```json-{- "model": "gpt-5.6-luna",- "reasoning_effort": "none",- "tools": [{ "type": "function", "function": { "...": "..." } }]-}-```--If the application needs both reasoning and tools:--- migrate that flow to Responses when implementation changes are in scope;-- otherwise report it as a compatibility blocker;-- do not hide the incompatibility by removing tools, dropping required reasoning, or changing the workload's behavior without approval.--If the live API rejects the intended `none` path, treat it as a current API compatibility issue and report the exact request and error rather than inventing a workaround.--## Responses API and conversation state--Prefer Responses for reasoning, tools, multi-turn agents, and new 5.6 capabilities.--For ordinary multi-turn Responses calls, preserve the repository's existing state strategy. Do not add persisted reasoning merely because it exists.--If deliberately enabling persisted reasoning:--- use `reasoning.context: "all_turns"` only when the objective and assumptions remain stable;-- prefer `previous_response_id` when the server can carry state;-- when replaying manually, preserve every prior user input and every relevant output item, not only assistant text;-- with `store: false` or ZDR, request and replay `reasoning.encrypted_content`;-- use current-turn behavior when old reasoning may be stale or misleading.--For manual replay, preserve item types, IDs, call IDs, caller metadata, and assistant phase values exactly. Incomplete replay can silently reduce quality or break tool continuation.--## Prompt caching--Do not assume old cache-hit behavior survives the model swap.--GPT-5.6 implicit caching places a managed breakpoint near the latest user or tool message and no longer relies on 128-token rounding. A prompt with a large stable prefix followed by a changing suffix can therefore lose cache hits even when the stable prefix itself has not changed.--Audit:--- large reusable system/developer prompts;-- dynamic suffixes appended to otherwise stable prompts;-- changing timestamps, request IDs, user-specific values, or tool lists in the prefix;-- cache keys, retention settings, and cache dashboards;-- token accounting that assumes reads only and ignores writes.--Migration rules:--- keep reusable prefixes stable;-- do not churn large system prompts unnecessarily;-- compare old and new `cached_tokens`, `cache_write_tokens`, latency, and cost;-- use explicit cache breakpoints only when a measured workload has a stable boundary that implicit caching misses;-- do not globally convert every prompt to explicit caching;-- do not send 5.6-only cache fields to older routes in a mixed-model system.--When old and GPT-5.6 routes share a request builder, isolate GPT-5.6-only fields instead of applying them globally.--The new top-level request shape uses `prompt_cache_options`, for example:--```json-{- "prompt_cache_options": {- "mode": "explicit",- "ttl": "30m"- }-}-```--Place explicit breakpoints at the actual stable rendered boundary using `prompt_cache_breakpoint`. Preserve `prompt_cache_key` when the application already uses it. Treat the older `prompt_cache_retention` shape as deprecated and verify the live docs before rewriting it.--Cache writes cost more than ordinary uncached input, so a lower hit rate can be both slower and more expensive.--## Images, PDFs, files, and long context--GPT-5.6 can change token and latency behavior without any prompt change:--- for image inputs, omitted or `auto` image detail can preserve original dimensions;-- for PDF/file inputs in Responses, omitted or `input_file.detail: "auto"` can use high page-image detail;-- Chat Completions file inputs do not expose the same detail control;-- long-context Sol and Terra requests can cross pricing thresholds;-- Luna's smaller context can break workloads that fit in Sol or Terra.--For multimodal or long-context usages:--1. Measure input tokens and latency before and after.-2. Make detail explicit when cost or latency matters.-3. Resize images or use lower detail when the task does not need original spatial precision.-4. Keep original/high detail for dense, coordinate-sensitive, OCR, localization, or visual-inspection tasks where it materially improves quality.-5. Test worst-case context lengths, not only typical requests.--Do not claim a capability was removed based only on a missing metadata flag. Verify against current docs and a representative request.--## Structured outputs, parsers, and tool contracts--Keep output contracts explicit:--- preserve JSON schemas, required fields, enums, refusal handling, and parser expectations;-- preserve tool names, parameter schemas, call IDs, and retry behavior;-- keep citations, evidence fields, or native artifacts when downstream consumers require them;-- validate that the final answer still satisfies the contract, not merely that a tool call succeeded.--Do not fix a failing migration by weakening a schema, deleting required behavior, removing routes, dropping tools, or changing business logic unless the user explicitly asked for that product change.--## Optional: Pro mode--Do not enable Pro mode during a baseline migration unless the old usage was Pro-like or the user explicitly asks for it.--GPT-5.6 Pro uses the base model with a reasoning mode:--```json-{- "model": "gpt-5.6-sol",- "reasoning": {- "mode": "pro",- "effort": "medium"- }-}-```--Rules:--- use Responses, not Chat Completions;-- do not search for or invent a separate `gpt-5.6-pro` slug;-- supported Pro efforts begin at `medium`;-- mode and effort are separate decisions;-- compare task quality, total latency, and actual billed token usage against standard mode.--If migrating a legacy Pro slug, make the mode change explicit and evaluate it separately from ordinary Sol migration.--## Optional: Programmatic Tool Calling--Programmatic Tool Calling is not a required part of moving to GPT-5.6. Add it only when code can reduce large structured intermediate results before they return to model context.--Good candidates:--- bounded read-only filtering, joining, sorting, ranking, deduplication, and aggregation;-- batching many similar records;-- repeated deterministic validation;-- map-reduce style retrieval with a compact result schema.--Poor candidates:--- one direct tool call;-- adaptive workflows where each result changes the next decision;-- write, approval, or side-effecting flows;-- citation-heavy or native-artifact flows;-- semantic judgment that should remain visible to the model.--Request-shape requirements:--```json-{- "tools": [- { "type": "programmatic_tool_calling" },- {- "type": "function",- "name": "lookup_records",- "allowed_callers": ["programmatic"]- }- ]-}-```--Do not nest `programmatic_tool_calling` under another `tools` property. When enabled, the host must handle `program`, program-issued `function_call`, `function_call_output`, and `program_output` items. Preserve the original `call_id` and `caller` when returning function results.--Constrain the stage, eligible read-only tools, output schema, retry limit, and handoff back to direct judgment. Validate the final user-visible answer; a correct program result can still become an incorrect final answer.--## Optional: multi-agent beta--Do not enable multi-agent behavior during a baseline migration unless the application already has a clear parallelizable workflow and the user asks for it.--Enabling it requires:--- the `OpenAI-Beta: responses_multi_agent=v1` header;-- `multi_agent: { "enabled": true, "max_concurrent_subagents": 3 }`;-- handling `multi_agent_call`, `multi_agent_call_output`, and `agent_message` items;-- executing ordinary developer-defined function calls from any agent and returning all required outputs;-- preserving new items for replay and tracing;-- checking incompatibilities with compaction, reasoning summaries, and tool-call limits in current docs.--Cap concurrency. Do not let a migration task create unbounded subagents, duplicate work, or finish without a final synthesis.--## Prompt migration judgment--After the model and API baseline is working, run representative traces before editing prompts. Change prompts only for measured failures.--For GPT-5.6, prefer:--- shorter, outcome-oriented prompts;-- explicit success criteria, dependencies, stopping conditions, and completion boundaries;-- preserved user-provided values;-- decision criteria for implicit choices instead of universal defaults or keyword maps;-- explicit autonomy and permission boundaries;-- explicit tool routing, resource links, breadcrumbs, and expected tool choice;-- staged plans, current-layer awareness, and concise handoffs for long work;-- real validation before declaring completion.--Avoid:--- generic `be brief`, `be thorough`, or `think step by step` instructions;-- blanket language instructions that can cause unwanted language switching;-- repeating `ask first` until safe local work becomes blocked;-- giant prompt rewrites that make the source of a regression impossible to identify;-- telling the model to minimize tool loops when correctness, evidence, or required validation needs more work.--For coding or agentic migrations, add concrete preservation and verification rules:--```-Preserve existing functionality, routes, outputs, and user-visible behavior.-Do not delete or disable required behavior merely to make the build pass.-Before finishing, run the relevant build, tests, type checks, render or smoke-checks, and report the evidence.-```--For long-running work, define the current layer: research, design, implementation, review, or external coordination. Do not let the model silently move to another layer.--## Upgrade workflow--1. Fetch current live 5.6 docs and the Prompting Best Practices section.-2. Inventory every usage site and its adjacent prompt, config, registry, parser, and test surfaces.-3. Classify each usage by role and migration class.-4. Choose Sol, Terra, or Luna by the existing workload's role.-5. Preserve the old effective reasoning effort explicitly.-6. Run the compatibility gates:- - endpoint and SDK support;- - Chat Completions plus function tools;- - cache topology and cache fields;- - context length and long-context cost;- - image, PDF, and file detail;- - structured outputs and parsers;- - Responses state replay and tool continuation;- - mixed-model routing and unsupported new fields.-7. Apply the smallest safe model, config, registry, and prompt changes.-8. Do not add optional Pro, persisted reasoning, PTC, explicit caching, or multi-agent behavior unless needed and measurable.-9. Run existing tests and representative evals.-10. Report changed, unchanged, blocked, and confirmation-needed sites separately.--## Validation matrix--Prefer a controlled comparison:--1. old model + old prompt + old settings;-2. GPT-5.6 target + same prompt + preserved effective reasoning;-3. GPT-5.6 target + same prompt + one lower effort;-4. GPT-5.6 target + the smallest prompt or API fix required by a measured failure;-5. optional feature treatment, isolated from the baseline.--Measure what matters for the workflow:--- task success and user-visible quality;-- structured-output validity and parser success;-- tool choice, tool arguments, retries, loop count, and completion rate;-- TTFT, end-to-end latency, timeout rate, and concurrency behavior;-- input, output, reasoning, cached, and cache-write tokens;-- cost per successful task;-- long-context, compaction, and replay behavior;-- image/PDF token use and visual/OCR accuracy;-- completeness, preserved behavior, citations, and validation evidence.--For model routers and pickers, test at least one representative workload for each role. Verify that the cheapest or fastest tier is not accidentally used for quality-critical work and that Sol is not accidentally used for every workload.--## Required final report--Return:--- `Current usage inventory`: each model site, endpoint, role, prompt surface, and old effective reasoning.-- `Target mapping`: Sol, Terra, Luna, unchanged, or confirmation-needed, with the reason.-- `Changes made`: model strings, reasoning settings, prompts, registries, metadata, tests, and API-shape changes.-- `Compatibility checks`: Chat Completions/tools, caching, state replay, multimodal detail, context/cost, schemas, and mixed-model routing.-- `Prompt changes`: each surgical edit and the failure mode it addresses.-- `Validation`: commands, evals, traces, before/after measurements, and remaining gaps.-- `Unchanged sites`: historical, pinned, ambiguous, or intentionally role-specific usages.-- `Blockers and open questions`: exact issue, why it is unsafe to guess, and the smallest next step.--Never say the migration is complete merely because model strings changed. It is complete only when the affected behavior and contracts have been validated or the remaining gaps are stated explicitly.diff --git a/codex-rs/skills/src/assets/samples/openai-docs/references/upgrading-to-gpt-6-astra.md b/codex-rs/skills/src/assets/samples/openai-docs/references/upgrading-to-gpt-6-astra.mdnew file mode 100644index 0000000000..49d138ee29--- /dev/null+++ b/codex-rs/skills/src/assets/samples/openai-docs/references/upgrading-to-gpt-6-astra.md@@ -0,0 +1,221 @@+# Upgrading to GPT-6 Astra++Use this guide when the user asks to migrate an existing OpenAI API integration, repository, prompt stack, agent, model router, or model picker to GPT-6 Astra.++The default explicit target is `gpt-6-astra`. Verify the `gpt-6` family alias's currently documented routing and availability before using it. Do not treat every old model usage as an Astra candidate: retain Terra for balanced work and Luna as the primary faster or cheaper model.++Before changing code, retrieve the current live GPT-6 model guidance using already-callable official documentation search and fetch, or immediately use official-domain web search and fetch:++https://developers.openai.com/api/docs/guides/latest-model/gpt-6-astra.md++For prompt changes, also read only the `## Prompting best practices` section from:++https://developers.openai.com/api/docs/guides/latest-model/gpt-6-astra.md#prompting-best-practices++Treat live docs as canonical for current model IDs, parameters, limits, pricing, and feature availability. The skill-specific workflow below covers repository inspection, scope preservation, and validation. The fallback after it includes all non-prompting guidance, including access notices, examples, caveats, and `## Migration quickstart`; the full prompting section is in `references/prompting-guide.md`. When refreshing, preserve all guide content unless it is specific to the website rather than useful to the skill, and record any omission. Remove website metadata and component markup while retaining their readable content. Resolve site-relative links against `https://developers.openai.com` and section-only links against the canonical model-guide URL above.++## Core principle++Do not perform a blind model-string replacement.++First preserve the behavior, latency class, cost class, reasoning level, endpoint contract, tool semantics, cache behavior, and output contract of each usage site. Then make the smallest safe migration. Adopt new GPT-6 capabilities only when they solve a measured problem or the user explicitly asks for them.++A model upgrade alone does not authorize adding reasoning fields, changing request schemas, or rewriting tests. Set a supported reasoning effort explicitly to preserve the source model's effective behavior; verify omitted defaults rather than guessing.++## Migration posture++Classify every usage site before editing:++1. `simple Astra migration`+ - One flagship model usage.+ - Same endpoint and request shape can remain.+ - Reasoning effort is explicit or its old effective value is known.+ - No cache, vision, file, tool, or parser behavior needs implementation changes.+2. `tier-aware family migration`+ - The repository exposes multiple model roles, model choices, fallbacks, routers, pricing data, or capability metadata.+ - Map each role to Astra, Terra, or Luna instead of replacing everything with Astra.+3. `compatibility migration`+ - The safe move requires parameter, endpoint, cache, state, tool-loop, or multimodal-detail changes.+ - Make these changes only when implementation work is inside the user's requested scope. Otherwise report the exact blocker and smallest follow-up.+4. `prompt migration`+ - The API shape can remain, but representative traces show a prompt-specific regression.+ - Make a surgical prompt edit tied to that failure; do not rewrite a working prompt stack wholesale.+ - When the task is to update prompting guidance, edit the directly tied prompt surface only. Do not modify runtime request code, model schemas, or tests unless the prompt change requires it.+5. `optional feature adoption`+ - Pro mode, persisted reasoning, explicit caching, Programmatic Tool Calling, or multi-agent behavior is being added deliberately.+ - Keep this separate from the baseline migration so its effect can be measured.+6. `leave unchanged`+ - Historical examples, documentation about old models, snapshots, fixtures, eval baselines, comparison code, intentionally pinned fallbacks, unsupported providers, or ambiguous usages.++When intent is unclear, prefer leaving a usage unchanged and list it for confirmation over silently changing its role.++## Inventory before editing++Search for more than literal model IDs. Inventory:++- model strings, aliases, environment variables, CLI flags, config defaults, and deployment settings;+- SDK calls to Responses, Chat Completions, Batch, or provider adapters;+- reasoning settings, token budgets, sampling settings, and latency timeouts;+- function tools, hosted tools, structured outputs, response parsers, and replay logic;+- system, developer, user, and tool-description prompts tied to each usage;+- routers, fallbacks, model allowlists, enums, regexes, validation schemas, and capability maps;+- model picker UI, display labels, descriptions, context limits, pricing metadata, and provider catalogs;+- prompt-cache keys, retention options, stable-prefix construction, and cache metrics;+- image, PDF, file, OCR, and computer-use inputs;+- tests, fixtures, snapshots, evals, analytics labels, billing tables, and docs.++When changing a default model, search every active default surface: runtime config, environment/config files, setup docs, tests, CLI defaults, and deployment examples. Update them together.++For each usage site, record:++- source model and why it appears to be used;+- endpoint and SDK/client surface;+- prompt surface;+- effective reasoning effort, including defaults;+- latency, cost, context, and quality role;+- tools, structured outputs, caching, state replay, and multimodal inputs;+- downstream parsers or user-visible contracts;+- migration class and validation plan.++## Choose the target model by role++Use this as a starting map, then validate against the repository's workload:++| Existing role | Starting target | Reason |+| --- | --- | --- |+| GPT-5.6 Sol or an earlier flagship | `gpt-6-astra` | Astra is the flagship-equivalent tier. |+| Balanced quality, latency, and cost | `gpt-5.6-terra` | Terra is the balanced option. |+| Faster or cheaper work, classification, extraction, routing, high-volume, or strict-latency route | `gpt-5.6-luna` | Luna is the primary speed and cost option. |+| GPT-4.1 or GPT-4o latency-sensitive flow | Start with Luna; evaluate Terra or Astra if quality requires it | A flagship replacement can change latency and cost materially. |+| Reasoning-heavy or hardest quality-first flow | Start with Astra at the old effective effort | Preserve the reasoning contract before tuning. |+| Router, fallback, or model picker | Add the family by role | Do not collapse a multi-model design into Astra. |+| Third-party or provider-specific model | Leave unchanged unless the user explicitly requests provider migration | Model-name similarity is not a safe mapping. |++Important limits to check in live docs:++- Each model's context window and maximum output.+- Long-context pricing thresholds for each route.+- Token pricing for GPT-6.++Do not invent prices, limits, or capability flags. Fetch them from current docs before updating a registry or UI.++For model pickers and registries, preserve existing model entries by default. Add GPT-6 Astra and retain the existing Terra and Luna options unless the user explicitly asks to replace or remove them. Do not invent pricing, context limits, capabilities, or metadata unless confirmed from canonical docs.++If using the `gpt-6` alias, record the returned `response.model` during validation. Do not assume an alias and an explicit Astra slug appear identically in dashboards, rate-limit configuration, analytics, or billing metadata.++## Structured outputs, parsers, and tool contracts++Keep output contracts explicit:++- preserve JSON schemas, required fields, enums, refusal handling, and parser expectations;+- preserve tool names, parameter schemas, call IDs, and retry behavior;+- keep citations, evidence fields, or native artifacts when downstream consumers require them;+- validate that the final answer still satisfies the contract, not merely that a tool call succeeded.++Do not fix a failing migration by weakening a schema, deleting required behavior, removing routes, dropping tools, or changing business logic unless the user explicitly asked for that product change.++## Prompt migration judgment++After the model and API baseline is working, run representative traces before editing prompts. Change prompts only for measured failures. Read `references/prompting-guide.md` for the exact canonical prompting section when prompt changes are needed.++## Upgrade workflow++1. Fetch current live GPT-6 docs. Fetch the Prompting Best Practices section only when prompt changes are needed.+2. Inventory every usage site and its adjacent prompt, config, registry, parser, and test surfaces.+3. Classify each usage by role and migration class.+4. Choose Astra, Terra, or Luna by the existing workload's role.+5. Preserve the old effective reasoning effort explicitly when supported; follow the canonical migration guidance for unsupported settings.+6. Run the compatibility gates:+ - endpoint and SDK support;+ - Chat Completions plus function tools;+ - cache topology and cache fields;+ - context length and long-context cost;+ - image, PDF, and file detail;+ - structured outputs and parsers;+ - Responses state replay and tool continuation;+ - mixed-model routing and unsupported new fields.+7. Apply the smallest safe model, config, registry, and prompt changes.+8. Do not add optional Pro, persisted reasoning, PTC, explicit caching, async tools, or multi-agent behavior unless needed and measurable.+9. Run existing tests and representative evals.+10. Report changed, unchanged, blocked, and confirmation-needed sites separately.++## Validation matrix++Prefer a controlled comparison:++1. old model + old prompt + old settings;+2. GPT-6 target + same prompt + preserved effective reasoning;+3. GPT-6 target + same prompt + one lower supported effort;+4. GPT-6 target + the smallest prompt or API fix required by a measured failure;+5. optional feature treatment, isolated from the baseline.++Measure what matters for the workflow:++- task success and user-visible quality;+- structured-output validity and parser success;+- tool choice, tool arguments, retries, loop count, and completion rate;+- TTFT, end-to-end latency, timeout rate, and concurrency behavior;+- input, output, reasoning, cached, and cache-write tokens;+- total cost per successful task;+- long-context, compaction, and replay behavior;+- image/PDF token use and visual/OCR accuracy;+- completeness, preserved behavior, citations, and validation evidence.++For model routers and pickers, test at least one representative workload for each role. Verify that the cheapest or fastest tier is not accidentally used for quality-critical work and that Astra is not accidentally used for every workload.++## Required final report++Return:++- `Current usage inventory`: each model site, endpoint, role, prompt surface, and old effective reasoning.+- `Target mapping`: Astra, Terra, Luna, unchanged, or confirmation-needed, with the reason.+- `Changes made`: model strings, reasoning settings, prompts, registries, metadata, tests, and API-shape changes.+- `Compatibility checks`: Chat Completions/tools, caching, state replay, multimodal detail, context/cost, schemas, and mixed-model routing.+- `Prompt changes`: each surgical edit and the failure mode it addresses.+- `Validation`: commands, evals, traces, before/after measurements, and remaining gaps.+- `Unchanged sites`: historical, pinned, ambiguous, or intentionally role-specific usages.+- `Blockers and open questions`: exact issue, why it is unsafe to guess, and the smallest next step.++Never say the migration is complete merely because model strings changed. It is complete only when the affected behavior and contracts have been validated or the remaining gaps are stated explicitly.++## Introduction++GPT-6 Astra is our most intelligent model yet, with state-of-the-art performance in computer use, browsing, software engineering, science, and professional work. It excels at carrying out multistep workflows across code, browsers, and professional software. In <a href="https://openai.com/index/gpt-6-astra/" target="_blank" rel="noopener noreferrer">several evaluations</a>, Astra achieves stronger results while using substantially fewer output tokens—delivering a lower estimated API cost per task than earlier models despite its higher per-token pricing.++GPT-6 Astra is also our most aligned model yet. It excels at exercising care, respecting task boundaries, and communicating transparently. When instructions leave room for interpretation, it uses the context it has to fill in routine gaps and asks focused questions when the answer could change the outcome. It incorporates new requirements, changes course when asked, and answers side questions without losing track of the broader task.++To build with Astra, set `model` to `gpt-6-astra` in a [Responses API](https://developers.openai.com/api/docs/guides/migrate-to-responses) request.++## What's new++- **Async tool calling:** GPT-6 Astra can continue reasoning, call other tools, or answer independent parts of a request while your application runs a tool. Set `async: true` on a function or custom tool and return its result when ready using the original `call_id`. Your application still executes the tool and manages pending work. See [Async tool calling](https://developers.openai.com/api/docs/guides/async-tool-calling) for basic usage and a developer-defined wait-tool pattern.+- **Mid-turn steering:** Send additional user instructions while GPT-6 Astra is working, such as a correction or a change in requirements. Over a WebSocket connection, the Responses API preserves completed work and includes the update in a continuation. See [Mid-turn steering](https://developers.openai.com/api/docs/guides/steering) for the event flow and tool-result handling.+- **Change reasoning mid-conversation while preserving cache:** Add a `configuration_update` input item to increase reasoning effort for difficult work or reduce it for routine follow-ups without rewriting the original prompt prefix. The updated reasoning effort applies until another `configuration_update` input item overrides it. See [Change reasoning mid-conversation](https://developers.openai.com/api/docs/guides/reasoning#change-reasoning-mid-conversation) for examples and compatibility.+- **Misalignment monitoring:** As part of our <a href="https://openai.com/index/path-to-astra/" target="_blank" rel="noopener noreferrer">strengthened safeguards</a> for GPT-6 Astra, our systems asynchronously monitor for misalignment and trigger alerts when necessary. See [Misalignment monitoring](https://developers.openai.com/api/docs/guides/safety-checks/misalignment-monitoring) for more information.+- **Limitations:** GPT-6 Astra does not support the `none` reasoning effort. [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode) is unavailable for GPT-6 Astra with EU data residency.++GPT-6 Astra also supports the existing API capabilities available with GPT-5.6, including [computer use](https://developers.openai.com/api/docs/guides/tools-computer-use), [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs), [streaming](https://developers.openai.com/api/docs/guides/streaming-responses), [Programmatic Tool Calling](https://developers.openai.com/api/docs/guides/tools-programmatic-tool-calling), [multi-agent orchestration](https://developers.openai.com/api/docs/guides/responses-multi-agent), [prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching), [persisted reasoning](https://developers.openai.com/api/docs/guides/reasoning#preserve-reasoning-across-calls), [compaction](https://developers.openai.com/api/docs/guides/compaction), and [pro mode](https://developers.openai.com/api/docs/guides/reasoning#reasoning-mode).++## Migration quickstart++### Migrate with Codex++Codex can apply the recommended changes in this guide with the <a href="https://github.com/openai/skills/tree/main/skills/.curated/openai-docs" target="_blank" rel="noopener noreferrer">OpenAI Docs skill</a>.++```text+$openai-docs migrate this project to GPT-6 Astra+```++To use this skill in other coding agents, download it from the <a href="https://github.com/openai/skills/tree/main/skills/.curated/openai-docs" target="_blank" rel="noopener noreferrer">OpenAI skills repository</a>.++### Update API and model parameters++Set `model` to `gpt-6-astra`, then check the following:++- **Reasoning effort:** If you currently use `none` or `minimal`, start with `low` and compare results. Otherwise, preserve your current effective [reasoning effort](https://developers.openai.com/api/docs/guides/reasoning#reasoning-effort). Use `reasoning.effort` in Responses or `reasoning_effort` in Chat Completions.+- **Tool calling:** Use the [Responses API](https://developers.openai.com/api/docs/guides/migrate-to-responses#migrating-from-chat-completions). GPT-6 Astra supports Chat Completions, but tool calling requires Responses.+- **Unsupported parameters:** Remove `temperature`, `top_p`, and `top_logprobs`. For Chat Completions, also remove `logprobs`. For Responses, remove `message.output_text.logprobs` from `include`.+- **Fast mode:** For EU data residency, use Standard processing. GPT-6 Astra does not support `service_tier: "fast"` or `service_tier: "priority"` with EU data residency. Fast mode for GPT-6 Astra does not include a latency SLA. See [Fast mode compatibility](https://developers.openai.com/api/docs/guides/fast-mode#is-fast-mode-compatible-with-data-residency-zero-data-retention-and-a-baa).+- **Changing reasoning effort:** If your application changes effort between responses, use `configuration_update` items in standard, single-agent requests. Keep request-level `reasoning.effort` unchanged to preserve the prompt prefix for caching. Check the [compatibility limits](https://developers.openai.com/api/docs/guides/reasoning#change-reasoning-mid-conversation) before adopting this feature.+- **Prompt caching:** When migrating from GPT-5.5 or earlier, replace `prompt_cache_retention` with `prompt_cache_options.ttl` set to `"30m"`. Review the [prompt caching changes](https://developers.openai.com/api/docs/guides/prompt-caching#summary-of-model-differences), including cache boundaries and cache-write billing.+- **Unnecessary approval pauses:** If you run into issues where the model keeps asking for approval before proceeding, use the [initiative and follow-through guidance](https://developers.openai.com/api/docs/guides/latest-model/gpt-6-astra.md#initiative-and-follow-through) to prompt for more autonomous execution. See the rest of [Prompting best practices](https://developers.openai.com/api/docs/guides/latest-model/gpt-6-astra.md#prompting-best-practices) for guidance on instruction following, writing style, subagent delegation, and testing.