docs(getting-started): add Set Up a Model tutorial for API key and local paths#3502
Merged
Conversation
…cal paths Phase 4 of #3442. First contact with docker-agent on a machine without provider credentials had no single page walking from "no API key" to a working model: the quickstart assumed a model was already usable and the credential errors pointed at scattered reference pages. Add a getting-started page "Set Up a Model" covering both paths end to end: cloud provider (get an API key, store it through a secret source, verify with doctor, run) and local model (install Docker Model Runner, pull a model, verify, run), with a comparison table, a pointer to the docker agent setup wizard, and a doctor section. Link the page from the README (install section and documentation list), the quickstart Options A and D, the site navigation, and the Phase 1 error messages: RequiredEnvError (model credential variant), AutoModelFallbackError, and the first_available variant now end with a shared environment.ModelSetupDocsURL line. The troubleshooting page prose is kept in sync.
dgageot
approved these changes
Jul 7, 2026
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.
Phase 4 (docs tutorial) of #3442, the last remaining phase. Closes #3442.
New getting-started page "Set Up a Model" walking both model-setup paths end to end, linked from the README, the quickstart, the site navigation, and the Phase 1 error messages.
Issue expectation mapping
docs/getting-started/set-up-a-model/index.md: comparison table, Path A (get an API key, store it through a secret source, verify withdocker agent doctor, run), Path B (install Docker Model Runner, pull, verify, run), pointer to thedocker agent setupwizard, doctor sectionenvironment.ModelSetupDocsURLconstant, appended toRequiredEnvError(model-credential variant),AutoModelFallbackError, and thefirst_availablevariantChanges
docs/getting-started/set-up-a-model/index.mddocs/data/nav.ymlREADME.mddocs/getting-started/quickstart/index.mddocs/community/troubleshooting/index.mdpkg/environment/errors.goModelSetupDocsURLconstant, link inRequiredEnvErrormodel variantpkg/config/auto.goAutoModelFallbackErrorpkg/config/first_available.gofirst_availablemissing-env errorpkg/{environment,config}/*_test.goMessage rendering after the change (combined with the Phase 3 wizard line):
Validation
go build ./...go test ./pkg/environment/ ./cmd/root/and targetedpkg/configerror testsgolangci-lint run pkg/environment/ pkg/config/ cmd/root/markdownlint-cli2(105 files)scripts/docs-check-canonical.sh(94 pages)refLinksErrorLevel: ERROR)TestURLSource_Read_RejectsLocalAddressesandTestLoadExamplesfail identically on a cleanmainin this environment (sandbox network restrictions, corrupted local DMR blob cache); unrelated to this change.Issue status once merged
docker agent doctor