[AAASM-4332] 📝 (readme): Document --pre for pre-release install; fix [cli] extra

[Chisanan232]

Description

pip install agent-assembly (no --pre) currently fails for a first-time user with
"No matching distribution found for agent-assembly". Every live PyPI release is a
pre-release (latest is 0.0.1rc3) and the only final release (0.0.2) is yanked, so
pip — which skips pre-releases unless --pre is passed — resolves to nothing. Verified
against the live PyPI JSON: zero non-yanked final releases.

This PR documents --pre on the Python install commands (README + docs) and, in the same
install-hint area, fixes a non-existent [cli] extra referenced by the auto-start error
hint.

--pre docs (README + docs):

• README.md — the two install lines, the Quick Start framework-composed line, plus a
  short note that --pre can be dropped once a stable release exists.
• docs_macros.py — the macro source (install_pip, install_pip_runtime) that
  drives quick-start.md, compatibility/release-process.md, and
  examples/preparing-the-runtime-environment.md; fixed the source rather than the
  templated call sites.
• Literal (non-macro) install lines in docs/compatibility/frameworks.md,
  docs/examples/framework-support.md, docs/guides/type-checking.md,
  docs/troubleshooting.md, and the illustrative line in docs/development/docs-macros.md.
• A --pre note admonition in docs/quick-start.md.

[cli] extra fix (LOW, bundled):

• agent_assembly/core/gateway_resolver.py auto-start hint told users to run
  pip install agent-assembly[cli], but no cli extra exists (pyproject.toml
  defines only runtime and all); pip warns and installs nothing. The aasm
  binary ships via the runtime extra (the aasm console script itself is an
  always-installed [project.scripts] entry). Now points at agent-assembly[runtime].
  (This was the sole [cli] occurrence — line 186; the reporter's :156 no longer
  applies at base HEAD 27997cd.) Pre-commit's pinned black also joined a pre-existing
  split string literal on line 73 when the file was staged.

Grep-sweep result (pip install agent-assembly without --pre, whole repo):

• Changed: the 9 files above.
• Left (intentional): README.md git+https source install (--pre N/A);
  .claude/skills/* release runbooks and docs/release/RUNBOOK.md (version-pinned
  ==<X> / release-process lines); verification-reports/* (historical, version-pinned).
• Out of scope (noted): uv add agent-assembly (README/install_uv) has the same
  pre-release gotcha for uv users but the ticket is pip-scoped; the runtime-hint strings
  in agent_assembly/_install.py / runtime.py use the valid [runtime] extra but lack
  --pre — candidate follow-up.

Type of Change

• 🔧 Bug fix
• 📚 Documentation update

Breaking Changes

• No

Related Issues

• Related JIRA ticket: AAASM-4332

Testing

• Manual testing performed
• Confirmed live PyPI has zero non-yanked final releases (0.0.2 yanked, latest 0.0.1rc3).
• ruff check on the changed .py files: clean. pre-commit (black/isort/mypy) passed.
• Full suite: 771 passed, 17 skipped — the only red, test_init_assembly_coldstart_latency,
  is a pre-existing cold-start latency flake (passes in isolation; unrelated to string/doc
  edits). No test asserts the auto-start extra string.

Checklist

• Code follows project style guidelines
• Self-review completed
• Documentation updated if needed
• All tests passing (modulo the pre-existing latency flake noted above)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Chisanan232]

Claude Code review — COMMENT (not an approval)

Verdict: approve-ready. Scope, correctness, and side-effects all check out against AAASM-4332.

CI: Green — 19/19 checks passing (Codecov/Sonar are advisory only).

Scope vs ticket (verified at branch HEAD):

• --pre is now on every genuine first-install command: the two README install lines + the Quick Start framework-composed line, and the docs-macro source (install_pip, install_pip_runtime in docs_macros.py) that drives the templated quick-start.md / release-process.md / preparing-the-runtime-environment.md call sites — fixing the source rather than the rendered output is the right call. Literal lines in frameworks.md, framework-support.md, type-checking.md, troubleshooting.md, docs-macros.md all updated, plus a --pre note admonition in README and quick-start.md with a clear "drop once stable" caveat.
• Full-repo grep for pip install agent-assembly without --pre leaves only intentional/version-pinned lines: .claude/skills/* release runbooks, docs/release/RUNBOOK.md, and verification-reports/* — all ==<X> historical/release-process contexts. Correctly left untouched.
• [cli] → [runtime] fix confirmed: [runtime] is a real extra (pyproject.toml L40; all alias L42; aasm ships as an always-installed [project.scripts] entry L45). No [cli] occurrence remains. This turns a fail-silent install hint into a working one.

Side-effects: Doc/manifest-only plus the single one-line hint fix. The docs-macro edit only changes string values under existing keys — rendering path unaffected. The incidental black re-join of the split log-string on gateway_resolver.py:73 is cosmetic, no behavior change.

Non-blocking follow-up (already noted in PR desc): the runtime-hint strings in agent_assembly/runtime.py:40 and _install.py:33 use the valid [runtime] extra but still lack --pre, so they carry the same pre-release gotcha; and uv add agent-assembly has the uv-equivalent. Both are legitimately outside this pip-doc-scoped ticket — good candidates for a separate follow-up, not a blocker here.

— Claude Code review

[Chisanan232]

Code Review by Claude Code 🤖

CI Status: ✅ All Green

All CI checks pass including:

• Unit tests & Integration tests ✅
• Dependency advisory audit (pip-audit) ✅
• Documentation build ✅
• CodeQL, SonarCloud, codecov ✅
• CI Success ✅

Ticket Coverage: ✅ Complete

Verified against AAASM-4332:

• ✅ --pre documented: Added to README install lines, Quick Start, and all relevant docs
• ✅ [cli] extra fixed: Changed from non-existent [cli] to valid [runtime] in gateway_resolver.py
• ✅ Note about stable release: Documented that --pre can be dropped once a stable release exists
• ✅ 9 files changed covering README.md, docs_macros.py, and literal install lines in various docs

Side Effect Analysis: ✅ Safe

• No breaking changes
• Documentation-only changes plus one string fix in error message
• No functional code changes

Recommendation: ✅ Ready to Merge

This is a straightforward documentation fix that helps new users successfully install the package.

---

Review performed by Claude Code - automated code review assistant