Skip to content

docs: add missing warnings for key ADK footguns and workflow gaps#86

Merged
AaronForinton merged 3 commits intomainfrom
claude/docs-gap-fixes
Apr 17, 2026
Merged

docs: add missing warnings for key ADK footguns and workflow gaps#86
AaronForinton merged 3 commits intomainfrom
claude/docs-gap-fixes

Conversation

@AaronForinton
Copy link
Copy Markdown
Contributor

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

  • N/A (docs, config, or trivial change)

Checklist

  • ruff check . and ruff format --check . pass
  • pytest passes
  • No breaking changes to the poly CLI interface (or migration path documented)
  • Commit messages follow conventional commits

Note: prerequisites.md is also touched by #85 (tab rename). Whichever merges second will need a quick rebase.

Addresses gaps identified from a real end-to-end AI-agent build that caused
significant lost time due to missing or unclear documentation.

Gap 1 — No local runtime:
- testing.md: add prominent warning that there is no poly serve or local simulator
- 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: add warning that poly init lists all projects visible to the key;
  if you see the wrong projects, you likely have the wrong key
- also removes a garbled duplicate "Local requirements" section left over from an
  earlier edit

Gap 3 — Platform-provisioned resources cannot be created via ADK:
- voice_settings.md, chat_settings.md, agent_settings.md, speech_recognition.md:
  add note that greeting, style prompt, disclaimer, personality, role, and ASR settings
  are created by Agent Studio on project init and can only be updated, not created;
  push will fail with NotImplementedError if the file exists locally without a
  matching .agent_studio_config entry

Gap 4 — Don't copy project directories:
- anti-patterns.md: add new section explaining why copying a project directory to a
  different project causes push failures; correct approach is poly init + poly pull

Gap 6 — No poly merge command:
- tutorials/build-an-agent.md: add note at Steps 10 and Workflow 2 Step 7 that
  merging requires the Agent Studio web UI; there is no poly merge 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

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@AaronForinton AaronForinton requested review from a team as code owners April 17, 2026 13:35
AaronForinton and others added 2 commits April 17, 2026 14:36
…ording

American English:
- tutorials/build-an-agent.md: Initialise → Initialize (heading + table),
  Customise → Customize (heading), Dialogue → Dialog (card)
- reference/topics.md: dialogue → dialog
- reference/experimental_config.md: Behaviour → Behavior

Platform-provisioned notes accuracy:
- voice_settings.md, chat_settings.md, agent_settings.md, speech_recognition.md,
  anti-patterns.md: replace "initialised in Agent Studio" / "an initialised project"
  with "created by the platform" / "any Agent Studio project"

The original wording implied the project had to be set up via the Agent Studio
browser UI. In practice these resources are provisioned server-side at project
creation time regardless of how the project is created, so the notes are accurate
for pure ADK / Claude Code workflows that start from an API key alone.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@AaronForinton AaronForinton merged commit 4391333 into main Apr 17, 2026
3 checks passed
@AaronForinton AaronForinton deleted the claude/docs-gap-fixes branch April 17, 2026 13:42
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