Skip to content

docs: link every setup guide from AGENTS.md and document omp on Bedrock - #171

Merged
aarora79 merged 1 commit into
mainfrom
docs/link-setup-guides-in-agents
Sep 7, 2026
Merged

aarora79 merged 1 commit into
mainfrom
docs/link-setup-guides-in-agents

Conversation

@aarora79

@aarora79 aarora79 commented Sep 7, 2026

Copy link
Copy Markdown
Owner

Why

AGENTS.md tells agents to "read the doc that covers what you are about to do rather than rediscovering it", but its Setup and reference docs section listed only two of the five setup guides in the repo. The other three were reachable through a script reference or not at all. This came up while wiring codex and omp to Amazon Bedrock on a fresh p5en.48xlarge: docs/omp-setup.md had to be found through a string constant in gen_agent_report.py.

What changed

AGENTS.md -- three guides added to the Machine setup list:

  • docs/omp-setup.md, the harness behind the headline results, and the three ways it differs from pi.
  • .claude/skills/vllm-setup/p5en-h200-cuda-fixes.md, which setup-machine.sh already points at when it detects an 8-GPU NVSwitch node. Without those fixes vLLM dies at KV-cache init.
  • docs/getting-started.md, the narrative path from a fresh checkout to a first run.

The agent-cli-bedrock-setup.md entry now names omp alongside codex and claude, matching what that doc covers.

benchmarks/docs/agent-cli-bedrock-setup.md -- adds the omp section the doc's own intro already promised:

  • omp needs no config file for Bedrock. It ships an amazon-bedrock provider and resolves the credential chain itself, an EC2 instance role included, so a region is all it needs.
  • The stdin redirect a manual invocation needs, cross-referencing omp-setup.md.
  • Ubuntu's stock ~/.bashrc returns early for non-interactive shells, so an appended export reaches interactive shells only. ~/.profile needs it too, or a script and a systemd --user unit both start without it.
  • The harness pins AWS_REGION per run from the runner config, so --provider bedrock runs never depend on the developer's shell.

It also records a gotcha found during that setup: aws bedrock list-foundation-models --region us-west-2 reports openai.gpt-5.6-sol, while the bedrock-mantle endpoint in the same region returns 404 for that id. The two surfaces disagree, so the listing cannot be used as evidence the judge can reach a model. Only the codex exec check settles it. This follows the section's own closing instruction to write down a setup problem that was not already documented.

Verification

Both CLIs were wired and confirmed with real calls on a p5en.48xlarge before the docs were written:

  • codex exec --skip-git-repo-check returned JUDGE OK from us-east-2 (us-west-2 produced the 404 described above).
  • omp -p --mode json returned OMP OK from us-west-2, reporting "provider":"amazon-bedrock" and "api":"bedrock-converse-stream".

Documentation only; no code paths change. Every added link target was checked to resolve from its containing file.

The "Setup and reference docs" section listed the Bedrock and kiro-cli
guides but not three others, so an agent had to find them through a
script reference or not at all. Add them:

- docs/omp-setup.md, for the harness behind the headline results
- .claude/skills/vllm-setup/p5en-h200-cuda-fixes.md, which setup-machine.sh
  already points at when it detects an 8-GPU NVSwitch node
- docs/getting-started.md

Also give agent-cli-bedrock-setup.md the omp section its own intro
promised, covering the built-in amazon-bedrock provider, the stdin
redirect omp needs, and the ~/.bashrc non-interactive guard that drops
an appended export.

Record one gotcha found while wiring a us-west-2 box: list-foundation-models
reports openai.gpt-5.6-sol in that region while the bedrock-mantle endpoint
404s on it, so the listing cannot be used to prove the judge can reach a
model. Only the codex exec call settles it.
@aarora79 aarora79 added the documentation Improvements or additions to documentation label Sep 7, 2026
@aarora79
aarora79 merged commit 1fe4ffa into main Sep 7, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant