Skip to content

docs: fix outdated content and document missing commands#2600

Merged
dgageot merged 1 commit intomainfrom
docs/fix-outdated-and-missing-content
Apr 30, 2026
Merged

docs: fix outdated content and document missing commands#2600
dgageot merged 1 commit intomainfrom
docs/fix-outdated-and-missing-content

Conversation

@dgageot
Copy link
Copy Markdown
Member

@dgageot dgageot commented Apr 30, 2026

Spotted while auditing the published documentation against the source.

Wrong / outdated information

  • Azure provider env var — the azure alias defaults to AZURE_API_KEY (see pkg/model/provider/aliases.go), not AZURE_OPENAI_API_KEY. Updated the providers overview, the models concept page, and the troubleshooting cheat sheet.
  • GitHub Copilot env var — the alias reads GITHUB_TOKEN (a PAT with the copilot scope), not "GitHub CLI auth (gh auth login)". The dedicated providers/github-copilot page already documents this correctly; the overview tables now match.
  • Broken internal linkdocs/providers/openai/index.md linked to /examples/websocket_transport/, which doesn't exist as a docs page. Linked the YAML on GitHub instead.
  • Troubleshooting nits — fixed a stray extra column delimiter in the Log Analysis table that was rendering as a malformed header, and a missing word in the Port conflicts section ("When docker-agent as an API server" → "When running docker-agent as an API server").

Missing content

  • SidebarTasks (/tools/tasks/) and Model Picker (/tools/model-picker/) pages exist but were never linked from the Built-in Tools navigation. Added them.
  • docker agent serve chat — this command (an OpenAI-compatible Chat Completions server at /v1/chat/completions and /v1/models) was not documented anywhere despite being a real, shipped command. Added a section in the CLI reference with the full flag table and a curl example.
  • docker agent version — added a short section in the CLI reference.
  • Missing docker agent run flags — surfaced from cmd/root/run.go and cmd/root/flags.go: --remote, --working-dir, --env-from-file, --code-mode-tools, --models-gateway, --fake, --record.
  • Global flags — added --cache-dir, --config-dir, --data-dir (from cmd/root/root.go) to the Global Flags table.
  • Troubleshooting API-key cheat sheet — rounded it out with Nebius, MiniMax, Requesty, GitHub Copilot, and Azure entries, and noted that GOOGLE_API_KEY and GEMINI_API_KEY are both honored.

Files changed

docs/_data/nav.yml                      |  4 ++
docs/community/troubleshooting/index.md | 27 ++++++++------
docs/concepts/models/index.md           |  4 +-
docs/features/cli/index.md              | 68 +++++++++++++++++++++++++++++++---
docs/providers/openai/index.md          |  2 +-
docs/providers/overview/index.md        |  4 +-
6 files changed, 87 insertions(+), 22 deletions(-)

Docs-only — no Go changes, no behavior changes.

Spotted while auditing the published documentation against the source.

Wrong / outdated information:

- Fix the Azure provider env var: the `azure` alias defaults to
  `AZURE_API_KEY` (see pkg/model/provider/aliases.go), not
  `AZURE_OPENAI_API_KEY`. Updated the providers overview, models
  concept page, and troubleshooting cheat sheet.
- Fix the GitHub Copilot env var: the alias reads `GITHUB_TOKEN` (a
  PAT with the `copilot` scope), not `gh auth login`-managed creds.
- Fix a broken internal link in providers/openai (`/examples/
  websocket_transport/` does not exist as a docs page) — point at the
  YAML on GitHub instead.
- Fix a stray extra column delimiter in the Log Analysis table and a
  missing word in the Port conflicts section of the troubleshooting
  page.

Missing content:

- Add Tasks and Model Picker tools to the navigation; both pages
  already exist under /tools/ but were not linked from the sidebar.
- Document `docker agent serve chat` (OpenAI-compatible Chat
  Completions server) — the command exists but had no public docs.
- Document `docker agent version`.
- Document the missing `docker agent run` flags surfaced by
  cmd/root/run.go and cmd/root/flags.go: `--remote`, `--working-dir`,
  `--env-from-file`, `--code-mode-tools`, `--models-gateway`,
  `--fake`, `--record`.
- Document the global `--cache-dir`, `--config-dir`, `--data-dir`
  flags from cmd/root/root.go.
- Round out the API-key cheat sheet in the troubleshooting page with
  Nebius, MiniMax, Requesty, GitHub Copilot, and Azure entries (and
  note that `GOOGLE_API_KEY` and `GEMINI_API_KEY` are both honored).

Assisted-By: docker-agent
Signed-off-by: David Gageot <david@gageot.net>
@dgageot dgageot requested a review from a team as a code owner April 30, 2026 08:59
Copy link
Copy Markdown

@docker-agent docker-agent Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Assessment: 🟡 NEEDS ATTENTION

This PR fixes several documentation inaccuracies (Azure/GitHub Copilot env vars, broken link, table formatting) and adds missing documentation for new commands and nav entries. The changes are accurate and well-structured. One minor issue found in the newly added content.


```bash
$ docker agent version
docker agent version v1.54.0
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] Hardcoded version number in example will become stale

The docker agent version example uses a specific real version number (v1.54.0) and commit hash (1737035c). These will be outdated as soon as the next release ships, and users may be confused when their actual output differs from the docs.

Consider using placeholder values instead:

$ docker agent version
docker agent version vX.Y.Z
Commit: <commit-hash>

@dgageot dgageot merged commit decb050 into main Apr 30, 2026
11 checks passed
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.

2 participants