feat(adr-006): Phase 1 — Python SDK + scaffolder + self-serve webhook install

[lilyshen0722]

Summary

Three artifacts in one PR per ADR-006 §Migration path Phase 1. The whole point: `commonly agent init --language python --name research-bot --pod ` produces a running custom Commonly agent in 60 seconds. No publish step, no admin involvement, no framework adoption — just the four CAP verbs.

What's in

1. Backend self-serve webhook install (touches kernel — needs deploy)

• `backend/models/AgentRegistry.ts` — added `ephemeral?: boolean`. `search()` filters `ephemeral: { $ne: true }` so the marketplace catalog never surfaces self-serve rows. Direct `getByName()` still resolves them so install/uninstall flows work.
• `backend/routes/registry/install.ts` — when the lookup returns null AND `config.runtime.runtimeType === 'webhook'`, synthesize an ephemeral registry row owned by the installing user. Pod-membership check fronts everything; non-webhook installs without manifest still 404; `podId` required (ADR-006 invariant 7); `agentName` regex-validated (returns 400 instead of Mongoose 500); structured `[cap self-serve-install] user=… pod=… agent=… runtime=webhook` log on every synthesis.
• `backend/routes/registry/pod-agents.ts` — comment in the uninstall route flagging the ephemeral GC gap (ADR-006 OQ Add basic unit tests for backend functions #1) for the day someone wires a janitor.
• `backend/tests/integration/self-serve-install.test.js` — 5 cases: happy path (token works), non-webhook 404, malformed name 400, non-member 403, catalog excludes ephemeral.

2. Python SDK (in-repo reference, no published package per ADR-006 §invariant 5)

• `examples/sdk/python/commonly.py` — ~150 LOC, stdlib only (`urllib.request`). Class `Commonly` with the four CAP verbs (`poll_events` / `ack` / `post_message` / `get_memory` / `sync_memory`) + a `run()` convenience loop. `CommonlyError` carries `.status` + `.body` so callers branch on 401/404. ADR-003 invariant Fix GitHub workflow to test frontend with coverage #9 documented in `sync_memory`'s docstring (server-stamps `byteSize`/`updatedAt`/`schemaVersion`). `run()` docstring now matches the actual no-ack-on-handler-error semantics (kernel re-delivers, per ADR-005 §Spawning semantics).
• `examples/hello-world-python/bot.py` — ~50 LOC echo template; reads token from `COMMONLY_TOKEN` env or KEY=VALUE-formatted `.commonly-env` file.

3. CLI scaffolder

• `cli/src/commands/agent.js` — `init --language python --name --pod ` subcommand and an exported `performInit` core. Refuses to clobber any of the 3 output files (`commonly.py`, `.py`, `.commonly-env`) AND aborts before issuing the install POST if any clobber is detected. Writes `.commonly-env` with mode 0600 in `COMMONLY_TOKEN=cm_agent_…` format (sourceable + dotenv-friendly). Reads SDK + template from the repo via `import.meta.url`-relative paths; works from any cwd.
• `cli/tests/agent-init.test.mjs` — 4 cases: full happy path with byte-for-byte SDK/template equality assertions vs the canonical examples, `/runtime-tokens` fallback, clobber refusal (asserts `client.post` was never called), unknown-language reject.

Reviewer pass (code-reviewer agent, grounded in REVIEW.md + ADR-006)

1 Critical + 4 Important + several nits, all addressed before commit:

• `run()` docstring contradicted code (claimed always-ack; code skips ack on handler error). Doc fixed.
• `agentName` regex pre-validation (avoid Mongoose 500 → return 400).
• Explicit `podId` guard on the self-serve branch (defense in depth for ADR-006 invariant 7).
• Test for malformed agentName added.
• Added `COMMONLY_TOKEN=`-prefixed `.commonly-env` for sourceable / dotenv compatibility.
• `repoFile()` documented with ADR-006 §Phase 4 removal condition (publish on npm).
• Catalog test fixture cleanup widened so test order can't leak.
• Comment in uninstall route pointing to ephemeral GC gap (OQ Add basic unit tests for backend functions #1).

What's NOT in (deferred)

• Node SDK + `init --language node` — Phase 2 of ADR-006. Mirror PR.
• `docs/webhook-sdk.md` quickstart — Phase 3.
• Published `pip install commonly` — Phase 4 (gated on CAP freeze + 2+ external authors using the in-repo reference).
• Per-user install cap / janitor for ephemeral rows — open questions in ADR; tracked.

Test plan

• `cd cli && npm test` — 57/57 passing (6 suites)
• `cd backend && npx jest tests/integration/self-serve-install` — 5/5 passing
• Backend type-check clean
• Both Python files compile
• Live smoke against api-dev once deployed — will run `commonly agent init … && python .py` end-to-end and verify pod post

🤖 Generated with Claude Code

[lilyshen0722]

Merged via local squash+push → db7a223