[AAASM-4558] ✨ (python-sdk-docs): Convert troubleshooting pip/uv alternative to tabs

[Chisanan232]

Description

docs/troubleshooting.md's "The native extension isn't loading" section showed
the pip-install and uv tool run maturin develop alternatives as one plain
bash block, which reads as "run both" rather than "pick one." Converted to
mkdocs-material content tabs (=== "pip" / === "uv"), mirroring the exact
tab pattern already used in docs/quick-start.md (pymdownx.tabbed with
alternate_style: true is already enabled in mkdocs.yml).

Type of Change

• ✨ New feature
• 🔧 Bug fix
• ♻️ Refactoring
• 🍀 Performance improvement
• 📚 Documentation update
• 🚀 Release

Breaking Changes

• No
• Yes (please describe below)

Related Issues

• Related JIRA ticket: AAASM-4558

Testing

• Unit tests added/updated
• Integration tests added/updated
• Manual testing performed
• No tests required (explain why)

Validated with uv sync --group docs + .venv/bin/python -m mkdocs build --strict
(exit 0) and confirmed the rendered site/troubleshooting/index.html contains
the expected tabbed-set with "pip" / "uv" labels.

Checklist

• Code follows project style guidelines
• Self-review completed
• Comments added for complex logic
• Documentation updated if needed
• All tests passing

Note: this repo's CI paths allow-list excludes docs/**, so no CI workflow
runs on this docs-only PR (expected per repo convention — review-required,
not a CI failure).

[Chisanan232]

Review: AAASM-4558 — troubleshooting pip/uv tabs

CI: 2/5 checks passed, 0 failed. The 3 missing checks are expected — this repo's ci.yaml pull_request.paths allow-list excludes docs/**, so no CI runs on docs-only PRs (per repo convention, not a failure). Nothing to fix here.

Scope: gh pr diff shows exactly one hunk in docs/troubleshooting.md (lines ~50-59), converting the plain bash block under "The native extension isn't loading" into === "pip" / === "uv" content tabs. Indentation (4-space, blank line after the === "tab" line, fenced code block inside) matches the working docs/quick-start.md:14-25 pattern exactly. No other file or section touched.

Regression check: Both commands are preserved verbatim:

• pip: pip install --pre 'agent-assembly[runtime]'
• uv: uv tool run maturin develop --manifest-path native/aa-ffi-python/Cargo.toml --release # build locally (needs Rust)

One small, intentional-looking edit: the pip line's trailing comment changed from # bundled platform wheel, or → # bundled platform wheel (dropping the dangling "or" that only made sense when both commands were shown as one sequential block). The command itself is unchanged; this is a sensible copyedit for the tab format, not a content regression. Rest of troubleshooting.md is untouched (confirmed via full-file diff).

Playwright validation: Built the PR branch with uv sync --group docs && uv run mkdocs build --strict — exit 0, only the pre-existing orphaned release/RUNBOOK.md nav-exclusion notice (known, unrelated to this PR). Served locally and drove it with Playwright:

• Page loads with a tabbed-set containing "pip" (checked/active by default) and "uv" labels.
• Default view shows the pip command in the visible tab panel.
• Clicking "uv" switches the visible panel to the uv/maturin command; pip panel hides correctly.
• Screenshots confirm both states render as expected, matching quick-start.md's tab styling.

This repo has a verification-reports/ convention, but it's used for Story-level QA sign-off (Epic/Story-scoped acceptance reports), not per-subtask docs review — findings are reported here instead, per that scoping.

Verdict: READY

No blocking issues. CI is clean (modulo the expected docs-path skip), the diff is scoped exactly to the ticket, both commands are preserved verbatim, and the tabs render/switch correctly in a live build.

— Claude Code

[Chisanan232]

Claude Code review — AAASM-4558

1. CI: Green. Analyze (python) pass, Build documentation (PR, no deploy) pass; the three Deploy … jobs correctly skipping on a PR (deploy is push-to-master only). No failures. (quickstart-tabs-check not applicable — this PR doesn't touch docs/quick-start.md.)

2. Scope vs subtask: Delivers the AC exactly — the plain bash block at docs/troubleshooting.md:50-56 is converted to === "pip" / === "uv" content tabs, mirroring the docs/quick-start.md pattern. Bonus correctness: the misleading trailing # … , or join is dropped, so the two options no longer read as "run both." Ready.

3. Side effects: Docs-only — one file, docs/troubleshooting.md (+11/-4). No agent_assembly/ runtime code touched. mkdocs build --strict on a fresh uv sync --group docs build (all three Epic PRs merged onto master) exits 0, no strict warnings.

4. FE (rendered tabs → headless Chromium): Built the combined site and drove it. Tab labels render as [pip, uv]; switching to uv flips the radio state to [false, true] and reveals the maturin develop command; pip shows the pip install --pre command. Switch works. Screenshots: design/validation/AAASM-4548-python/troubleshooting-pip-tab.png + troubleshooting-uv-tab.png.

Overall: ✅ Ready to merge. Meets AC, docs-only, CI green, tabs render + switch correctly.

— Claude Code