docs: rename API Keys tab, add key-gen image to get-started, remove orphaned docs workflow page#85
Merged
AaronForinton merged 2 commits intomainfrom Apr 17, 2026
Merged
Conversation
…docs workflow page
- prerequisites.md, installation.md: rename "Data Access" tab to "API Keys"
and update image alt text to match
- get-started.md: add Step 5 (Generate an API key) with the API key screenshot,
renumber old Steps 5–6 to 6–7, fix "Next step" card to point to Installation
instead of back to Prerequisites
- development/docs.md: delete — the AI-agent workflow content is fully covered
by tutorials/build-an-agent.md (Workflow 2); keeping a separate partial copy
under a mismatched nav label ("Docs workflow") caused confusion
- mkdocs.yml: remove the now-empty Development nav section
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
5 tasks
AaronForinton
added a commit
that referenced
this pull request
Apr 17, 2026
## Summary Addresses the documentation gaps identified from a real end-to-end AI-agent workflow build (Bella Vista reservation assistant) that caused significant lost time. Each change adds a targeted note or warning where the docs were silent on a real failure mode. ## Motivation A systematic audit against a live implementation identified six gaps where the docs' silence or vagueness caused actual blockers — not theoretical ones. Several required digging through source code to resolve. ## Changes **Gap 1 — No local runtime** - `testing.md`: prominent warning that there is no `poly serve` or local simulator; all execution is in Agent Studio Sandbox - `what-is-the-adk.md`: clarify the ADK manages config files and does not execute agents **Gap 2 — API keys are workspace-scoped** - `prerequisites.md`: warning that `poly init` lists all projects visible to the key; seeing unexpected projects means the wrong key is in use; also removes a garbled duplicate section from a previous edit **Gap 3 — Platform-provisioned resources cannot be created via ADK** - `voice_settings.md`, `chat_settings.md`, `agent_settings.md`, `speech_recognition.md`: note on each page that greeting/style prompt/disclaimer/personality/role/ASR settings are provisioned by Agent Studio on project init and can only be _updated_, not created; pushing them into a project without a matching `.agent_studio_config` entry fails with `NotImplementedError: Create operation not supported` **Gap 4 — Don't copy project directories** - `anti-patterns.md`: new section explaining why copying a project directory to a different project causes push failures (`.agent_studio_config` IDs, platform-provisioned resources); correct approach is `poly init` + `poly pull` **Gap 6 — No `poly merge` command** - `tutorials/build-an-agent.md`: note at Workflow 1 Step 10 and Workflow 2 Step 7 that merging requires the Agent Studio web UI; there is no CLI command **Minor gaps** - `tutorials/build-an-agent.md`: mark `chat/` as optional in the project structure diagram - `tutorials/build-an-agent.md`: add tip in AI-agent Workflow 2 Step 3 to run `poly docs --all` immediately after `poly pull`, before generating any files — without it, a coding agent has no schema context and will hallucinate resource structure ## What was not addressed - `poly merge` CLI command — this is a code change, not a doc change; documented as a known gap - Gap 5 (branch `--environment` 404) — `cli.md` already partially covers branch environment behavior; the failure mode may be platform-specific and is not clearly reproducible ## Test strategy - [x] N/A (docs, config, or trivial change) ## Checklist - [x] `ruff check .` and `ruff format --check .` pass - [x] `pytest` passes - [x] No breaking changes to the `poly` CLI interface (or migration path documented) - [x] Commit messages follow [conventional commits](https://www.conventionalcommits.org/) > **Note:** `prerequisites.md` is also touched by #85 (tab rename). Whichever merges second will need a quick rebase. --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
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
1 participant
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.
Summary
Three clean-up fixes to the get-started docs: correct a stale UI label, fill a missing screenshot in the new-user flow, and remove a stranded duplicate page.
Motivation
poly pullto work.development/docs.md(nav label: "Docs workflow") was an older, partial version of the AI-agent workflow thattutorials/build-an-agent.mdcovers fully. Keeping it as a lone page under a "Development" section with a mismatched title caused confusion.Changes
prerequisites.md: "Data Access" tab → "API Keys", button label → "+ API key", image alt text updatedinstallation.md: image alt text updated to matchget-started.md: add Step 5 — Generate an API key (with screenshot andPOLY_ADK_KEYexport), renumber old Steps 5–6 to 6–7, fix the bottom "Next step" card to point forward to Installation rather than back to Prerequisitesdevelopment/docs.md: deleted — content fully covered by Workflow 2 intutorials/build-an-agent.mdmkdocs.yml: remove the now-empty Development nav sectionTest strategy
Checklist
ruff check .andruff format --check .passpytestpassespolyCLI interface (or migration path documented)