docs: participant guide + symptom-indexed troubleshooting

[Robobc]

What

Two docs a workshop participant needs and the repo didn't have — grepping for "troubleshoot" previously returned nothing.

• docs/PARTICIPANT_GUIDE.md — the path through the workshop: prerequisites as required/optional (with the things that actually bite: python3.13 by that exact name, bash 4+, Docker not needed), profile chooser, the module table with real timings from live runs, verification by hand, framework selection, platform.yaml, teardown.
• docs/TROUBLESHOOTING.md — symptom → cause → fix with a symptom index. Every entry is a failure we actually hit: bash 3.2, the npx probe hang, credentials expiring mid-deploy, env creds silently beating AWS_PROFILE, ORG_ID, model IDs aging out, image-tag caching, Unauthorized, HTTP 424, Authorization method mismatch, missing gateway tools, no traces, the 1% X-Ray sample, export-in-use on destroy, the agentic_ai ENI drain.

It leads with the two rules that save the most time: read the container logs first, and CREATE_COMPLETE proves nothing about behaviour.

Product defects found by fact-checking the drafts

I checked every claim against the code before committing. Two turned out to be the wizard overstating what it builds:

• MODULE_EXPLAIN[A] claimed Memory deploys "semantic + user-preference strategies". The semantic strategy is added only when USE_LONG_TERM_MEMORY=true, which no profile sets — so every guided run was told it got something it didn't.
• MODULE_EXPLAIN[4] claimed module 4 federates your enterprise IdP and creates 3LO + M2M providers. By default it creates only the gateway M2M provider: federation needs IDP_TYPE set to a non-cognito value (the prompt defaults to cognito), and each 3LO provider needs its client id supplied.
• README listed Docker as required local tooling, while check_prereqs treats it as optional (images build in CodeBuild). Corrected, and added bash 4+ and the python3.13 name, which it omitted.

Draft errors caught before they shipped

deploy --profile runs cdk deploy --all, not the profile's module sequence · invoke.py --tools asks the gateway, not the agent — and the default orchestrator has no tools, so "what tools do you have?" was a misleading first prompt · security-focused requires ORG_ID · A2A runtimes report protocol A2A, not HTTP · the JWT-verification section applies per-pattern and never to the orchestrator · missing gateway tools are silent in only two conditions, while an AccessDenied on the vault secret fails the invoke outright · test_memory.py uses local credentials so it cannot verify the runtime role.

Verified

• check-workshop-flow.sh passes — the narration is sed-extracted, so the MODULE_EXPLAIN edits had to stay one physical line each; confirmed the dry run prints the new module 4 and A text.
• check-deploy-config.sh passes; pytest 99 passed; shellcheck unchanged (2 pre-existing findings).
• Every relative link and quick-index anchor resolves (checked with GitHub's slug rules); every command checked against the scripts and flags that actually exist.

[github-actions]

Commit: 2f0e6ec | Updated: 2026-08-19 16:12:04 UTC

Security Scan Results

Scanner	S	C	H	M	L	I	Time	Action	Result	Thresh
bandit	0	0	0	0	0	0	808ms	0	PASSED	MED (g)
cdk-nag	0	0	0	0	0	0	7.4s	0	PASSED	MED (g)
cfn-nag	0	0	0	0	0	0	7ms	0	PASSED	MED (g)
checkov	0	0	0	0	0	0	5.5s	0	PASSED	MED (g)
detect-secrets	0	0	0	0	0	0	688ms	0	PASSED	MED (g)
grype	0	0	0	0	0	0	1m 2s	0	PASSED	MED (g)
npm-audit	0	0	0	0	0	0	169ms	0	PASSED	MED (g)
opengrep	0	0	0	0	0	0	17.5s	0	PASSED	MED (g)
semgrep	0	0	0	0	0	0	<1ms	0	MISSING	MED (g)
syft	0	0	0	0	0	0	2.5s	0	PASSED	MED (g)