Repository navigation
docs: codex setup guide, FAQ folder, and the 0.2.0 notes addendum - #187
Merged
Merged
Conversation
…0 notes The 0.2.0 notes described the release as it stood when they were written, but #186 merged eleven seconds earlier and carried two things they never mentioned: Qwen3-Coder-30B priced on Bedrock, and a new benchmarked model. The notes now cover both, and record the pricing fix under config changes and bug fixes. codex had no setup page. omp and kiro-cli each have one; codex's wiring lived scattered across the harness reference, the benchmark skill and a run-swe-headless docstring, so anyone pointing it at a model had to rediscover it. Two new documents, split so no fact lives in both: - docs/codex-setup.md installs codex, wires it to Bedrock, states the constraint that decides everything else (it speaks only the Responses API, which Bedrock serves for openai.* models alone), and tabulates the failure modes that cost real debugging time: the stdin hang, the ignored OPENAI_BASE_URL, the tool parsers that abort on Responses-shaped tools, the null cost of an unpriced model. - docs/faq/ holds one file per question with an index. Its first entry answers how to wire codex to an open-weight model on Bedrock (the LiteLLM Responses-to-Converse bridge, and why the committed litellm-mantle.yaml cannot serve that path), to an open-weight model on vLLM (the provider block, the Responses-safe parsers, the context window), and to an OpenAI model on Bedrock (nothing to bridge). Both are linked from the README documentation map, the AGENTS.md setup list and the harness reference's agent entry. Also commits the Hello-World smoke run that validated the codex-to-Bedrock route. Its metrics.json carries total_cost_usd: null because it ran before the Qwen price row existed; the 21-task run committed in #186 has real per-task costs. The pre-commit whitespace hooks trimmed trailing spaces in three of its generated markdown artifacts and added a final newline to run-summary.md; the content is otherwise the model's output as written. Every relative link in the touched documents resolves, and every file in docs/faq/ appears in its index.
aarora79
added a commit
that referenced
this pull request
Sep 11, 2026
) docs/faq/ landed in #187 but AGENTS.md never mentioned it, so an agent reading the canonical guide would not know it exists and would answer the same question again somewhere else. Three additions: - The repository-structure tree now lists docs/faq/ beside docs/release-notes/. - Documentation conventions gain the rule: a question someone will ask again gets its own file in docs/faq/ plus a row in the index. Phrase the heading as the question a reader types, not as the name the code uses, and do not restate a setup or reference page. Where a fact could sit in both, pick one owner -- docs/codex-setup.md owns installing and configuring codex, the FAQ owns the per-path recipes. - The reference-doc list points at docs/faq/, and the write-it-down rule at the end of that section now names the FAQ as a destination alongside the model guide and the setup doc. Every relative link in AGENTS.md resolves.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three things, all documentation plus one committed smoke run.
1. The 0.2.0 notes were incomplete
#186 merged eleven seconds before #185, so the release notes never mentioned what it carried: Qwen3-Coder-30B priced on Bedrock, and a new benchmarked model. Added:
bedrock_pricing.py2. codex had no setup page
ompandkiro-clieach have one. codex's wiring lived scattered acrossharness-reference.md, the benchmark skill, and arun-swe-headless.pydocstring, so anyone pointing it at a model had to rediscover it. Two documents, split so no fact lives in both:docs/codex-setup.md installs codex, wires it to Bedrock, proves the judge with one call, states the constraint that decides everything else (it speaks only the Responses API, which Bedrock serves for
openai.*models alone), and tabulates the failure modes that cost real debugging time:codex execblocks on an open, empty stdin404 The model '<name>' does not existOPENAI_BASE_URL(issue #183)Model metadata not founddoes not support the '/openai/v1/responses' APItotal_cost_usdis nullbedrock_pricing.py3. New FAQ folder
docs/faq/ holds one file per question with an index, as requested. First entry, wiring-codex-to-models.md, answers three questions with working commands:
bedrock/provider, why the committedlitellm-mantle.yamlcannot serve that path, why LiteLLM>=1.72,<1.84fails it, and why prompt caching does not happen (Bedrock rejects acachePointfor Qwen;claude-haiku-4-5accepts one on the identical request)qwen3_coderandhermeswork; seven others break), the context-window flagBoth are linked from the README documentation map, the AGENTS.md setup list, and the harness reference's agent entry.
Also
The Hello-World smoke run that validated the codex-to-Bedrock route. Its
metrics.jsoncarriestotal_cost_usd: nullbecause it predates the Qwen price row; the 21-task run in #186 has real per-task costs. Pre-commit trimmed trailing whitespace in three of its generated markdown artifacts and added a final newline torun-summary.md.Verification
Every relative link in every touched document resolves (checked programmatically), and every file in
docs/faq/appears in its index.After this merges, the
0.2.0tag moves to the new merge commit so the tag matches the notes.