Skip to content

docs: codex setup guide, FAQ folder, and the 0.2.0 notes addendum - #187

Merged
aarora79 merged 1 commit into
mainfrom
docs/0.2.0-notes-addendum
Sep 11, 2026
Merged

aarora79 merged 1 commit into
mainfrom
docs/0.2.0-notes-addendum

Conversation

@aarora79

Copy link
Copy Markdown
Owner

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:

  • a New models subsection for Qwen3-Coder-30B-A3B on codex / Bedrock: 42.22 over 19 of 21 tasks at $0.6204 per task, why it reaches no chart, and why all 83,488,690 input tokens were billed fresh
  • a config changes row for bedrock_pricing.py
  • two bug fixes entries for the id normalization and the cacheless-cost guard
  • fix(pricing): price Qwen on Bedrock, and stop a cacheless model costing zero #186 in the pull-requests table
  • the bump line now names all three benchmarked models

2. codex had no setup page

omp and kiro-cli each have one. codex's wiring lived scattered across harness-reference.md, the benchmark skill, and a run-swe-headless.py docstring, 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:

Symptom Cause
Hangs before the first request codex exec blocks on an open, empty stdin
404 The model '<name>' does not exist codex 0.153.4 ignores OPENAI_BASE_URL (issue #183)
Every request retried five times vLLM tool parser aborts on Responses-shaped tools
Model metadata not found codex does not know a self-hosted window
does not support the '/openai/v1/responses' API Open-weight Bedrock model reached without a bridge
total_cost_usd is null Model has no row in bedrock_pricing.py

3. 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:

  • an open-weight model on Bedrock -- the LiteLLM Responses-to-Converse bridge with the native bedrock/ provider, why the committed litellm-mantle.yaml cannot serve that path, why LiteLLM >=1.72,<1.84 fails it, and why prompt caching does not happen (Bedrock rejects a cachePoint for Qwen; claude-haiku-4-5 accepts one on the identical request)
  • an open-weight model on vLLM -- the provider block the harness builds, the Responses-safe parser table (qwen3_coder and hermes work; seven others break), the context-window flag
  • an OpenAI model on Bedrock -- nothing to bridge, the same native provider the judge uses

Both 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.json carries total_cost_usd: null because 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 to run-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.0 tag moves to the new merge commit so the tag matches the notes.

…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
aarora79 merged commit 34871b3 into main Sep 11, 2026
5 checks passed
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant