test: live E2E smoke test; docs for alpha testers

[PaulAsjes]

Task 7, scoped to the E2E smoke test and docs. No version tag — nothing is released by this PR.

Live E2E smoke test

tests/e2e_smoke.rs runs the whole workflow against a real account: init → add → push → pull → delete. Its core assertion is the one thing unit and wire tests can't reach: a config survives a push/pull round-trip byte-for-byte, which is the guarantee the raw-JSON design exists to provide. It also checks status reports the live id and that the widget snippet embeds it.

Safety — it creates and deletes agents, so:

• Opt-in via ELEVENLABS_E2E_API_KEY, deliberately not ELEVENLABS_API_KEY. A shell with your normal credentials exported cannot mutate a live workspace by running cargo test. There's a test asserting that wiring stays that way.
• Skips with a clear message when unset, so cargo test and CI are unaffected.
• Redirects HOME at a temp dir, so it can't read or write your ~/.elevenlabs residency setting.
• Always deletes the agent it created, including on panic; prints the id if deletion fails.

ELEVENLABS_E2E_API_KEY=xi-... cargo test --test e2e_smoke -- --nocapture

I deliberately did not wire it into CI — it's destructive, so it shouldn't fire automatically on every push.

A bug the pre-flight caught

Before shipping I checked each invocation's arg shape against the real binary, and the cleanup step was wrong: generated API commands take path parameters as flags, so deletion is agents delete --agent-id <id>, not a positional. As written the cleanup would have failed and leaked agents in the test account on every run.

Docs

• "Two surfaces in one namespace" — elevenlabs agents holds both workflow verbs (positional args, operate on local files, progress output) and generated API commands (flag args, one request each, --format-able). Every claim in that table was verified against the built binary.
• v0 migration notes that fall out of it: agents list is now the API's list (use agents status for the local view), agents delete --agent-id <id> (and it no longer cleans up locally), and agents widget <id> → agents widget embed <id>.
• Installation reworked to lead with building from source, with a pre-release banner — the existing curl | sh instructions pointed at releases/latest, which doesn't exist yet and would have failed for alpha testers.
• Development section covering the three test suites (including why the generated crates need separate --manifest-path runs) and the E2E warning.
• Dropped --locked from the install instructions after testing it: the committed Cargo.lock is incomplete, so cargo install --locked errors out.

tests/e2e_smoke.rs is added to .fernignore (its neighbour wire_test.rs is generated and stays regenerable).

Verified

Full suite green: 1752 framework + 47 workflow + 345 wire + 2 e2e (skipped without a key) + doc tests. The E2E test's own compile and skip path confirmed; every documented command checked against the binary.

Note

Cargo.lock is left out of this PR — it has ~30 packages of pre-existing churn that appear on any build, unrelated to these changes. Worth a separate lockfile refresh (and it's what makes --locked fail).

🤖 Generated with Claude Code