[AAASM-3781] 📝 (docs): Fix quickstart-saas install commands & non-existent API/CLI refs

[Chisanan232]

Description

Fixes four verified documentation-correctness bugs (2026-06-26 QA re-verification, Epic AAASM-3773). All four touch docs/src/quickstart-saas.md; one also corrects docs/src/security-model.md. Each fix is a separate atomic commit.

• AAASM-3781 — go get github.com/agent-assembly/go-sdk 404s. The published module is github.com/ai-agent-assembly/go-sdk (confirmed in go-sdk/go.mod and every examples/go go.mod). Corrected the org and added @latest.
• AAASM-3782 — pip install agent-assembly fails: PyPI publishes only pre-releases (newest 0.0.1rc1; 0.0.2 yanked) and pip skips pre-releases by default. Added --pre at both install sites.
• AAASM-3783 — pnpm add @agent-assembly/sdk installs a stale alpha because the npm latest dist-tag is 0.0.1-alpha.3; the current pre-release line is beta. Pinned to @beta.
• AAASM-3784 — (A) The Python snippets imported a non-existent AgentAssembly class and used an @aaa.agent(...) decorator that the SDK does not provide (copy-paste raised ImportError). Rewritten against the shipped public API: init_assembly(...) as a governed context manager plus the LangChain AssemblyCallbackHandler, matching the runnable examples. (B) aasm login --sso and aasm secret rotate are not real aa-cli subcommands; reworded the SSO sign-in sequence diagram and the secret-rotation note in security-model.md as SaaS console (control-plane) flows.

Type of Change

• 🐛 Bug fix (correcting inaccurate or missing content)

Related Issues

• Related Jira tickets: AAASM-3781, AAASM-3782, AAASM-3783, AAASM-3784

Closes AAASM-3781
Closes AAASM-3782
Closes AAASM-3783
Closes AAASM-3784

Documentation Checklist

• cd docs && mdbook build passes locally with no warnings (only a harmless mdbook-mermaid version-skew notice; no broken links)
• All internal cross-links verified
• Page registered in docs/src/SUMMARY.md (no new pages added)
• Self-hosted instructions not included (SaaS-only scope)
• "Last reviewed" footer updated with today's date (left as-is; no content-ownership change, only correctness fixes)
• Commits follow GitEmoji convention and are small / atomic

How to verify

1. cd docs && mdbook build — succeeds with no broken references.
2. Source-of-truth checks: go-sdk/go.mod module = github.com/ai-agent-assembly/go-sdk; python-sdk/agent_assembly/__init__.py __all__ exports init_assembly (no AgentAssembly); agent-assembly/aa-cli/src/commands/mod.rs Commands enum has no login/secret.

🤖 Generated with Claude Code

[Chisanan232]

🤖 Claude Code — PR Review (AAASM-3781/82/83/84)

Independent review of the four doc-correctness fixes. All source-of-truth claims were cross-checked against the live repos in this workspace. CI is green (Aggregate all module docs ✅, SonarCloud ✅, Pages deploy skipped on PR as expected).

Verdict per ticket

Ticket	Fix	Source-of-truth check	Verdict
3781 Go module org	go get github.com/ai-agent-assembly/go-sdk@latest	go-sdk/go.mod → module github.com/ai-agent-assembly/go-sdk	✅ Correct
3782 missing --pre	pip install agent-assembly --pre at both sites (Step 1 + Pro-tier)	PyPI publishes only pre-releases; --pre is a position-independent global flag (langchain/-openai/-core still resolve to stable)	✅ Correct
3783 stale npm tag	pnpm add @agent-assembly/sdk@beta	npm latest dist-tag is stale alpha; @beta is current pre-release line	✅ Correct
3784B non-existent CLI	aasm login --sso / aasm secret rotate reworded as SaaS console (control-plane) flows in security-model.md	aa-cli/src/commands/mod.rs Commands enum has no login/secret subcommand	✅ Correct
3784A non-existent Python API	Rewrote to init_assembly(...) + AssemblyCallbackHandler	imports now valid (init_assembly in __all__); but handler is wired to the wrong object	⚠️ Needs change

⚠️ Blocking finding — 3784A: the rewritten handler is a silent no-op

Both rewritten snippets construct the callback handler as:

handler = AssemblyCallbackHandler(interceptor=ctx.client)

ctx.client is a bare GatewayClient (AssemblyContext.client: GatewayClient, core/assembly.py). AssemblyCallbackHandler invokes its interceptor purely via getattr(self._interceptor, "check_tool_start"|"on_tool_end"|"on_llm_start_scan"|"on_llm_end", None) and returns early (no-op) when the attribute is absent (adapters/langchain/callback_handler.py). GatewayClient implements none of those methods (verified: no __getattr__, no check_tool_start/on_tool_end/on_llm_*). So the explicitly-wired handler performs no policy check, no blocking, and no audit emission — directly contradicting the snippet's own prose:

• Run a policy check before each tool/LLM call, blocking it if policy denies.
• Emit an audit event for every call.

The real governance interceptor is the RuntimeQueryInterceptor (which does implement check_tool_start), produced internally by build_governance_interceptor() and applied via LangChainPatch during init_assembly(...). It is not exposed as ctx.client. Note this means the snippet is internally inconsistent: the prose correctly says init_assembly auto-wires the handler, yet the code then hand-rolls a second, broken one and passes it as callbacks=[handler]. At best the manual handler is dead/misleading code (governance silently coming from the patch); at worst a reader who copies just the handler wiring gets an agent that looks governed but isn't — the exact copy-paste-produces-wrong-behavior trap this ticket set out to remove (old code at least failed loudly with ImportError).

No shipped example uses interceptor=ctx.client; the real example (agent-assembly-examples/python/langchain-research-agent/src/main.py) passes a proper interceptor object that implements check_tool_start.

Suggested fix (minimal): drop the manual construction and use the handler init_assembly already auto-wires —

from agent_assembly.adapters.langchain import get_active_callback_handler
...
with init_assembly(..., mode="sdk-only"):
    handler = get_active_callback_handler()   # built on the real RuntimeQueryInterceptor
    executor = AgentExecutor(agent=agent, tools=tools, callbacks=[handler], verbose=False)

(or otherwise pass an object that actually implements the interceptor protocol — not ctx.client).

Side-effects (docs-only) — clean

• No other page references the now-changed commands inconsistently. compatibility.md and README.md already use ai-agent-assembly/go-sdk, --pre, and @beta; after this PR quickstart-saas.md matches them.
• mermaid edits in security-model.md are internally consistent (all CLI→Console participant renames threaded through every message line). Code fences balanced; "Aggregate all module docs" build check is green.

Recommendation

Request changes — 3781/3782/3783/3784B are correct and ready. The single blocker is 3784A's interceptor=ctx.client wiring (silent no-op contradicting the documented governance guarantees). Recommend re-pointing the handler to the real interceptor (get_active_callback_handler()) in both Python snippets, then merge.

Read-only review; not merging.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
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