Bring the Rust SDK to documentation parity with Python and TypeScript

[ron-42]

Fixes #141

The gap

sdk/rust is feature-complete and published on crates.io as inkbox v0.5.14, but it is invisible from everywhere except its own directory:

• README.md — the install table lists Python, TypeScript, and the CLI. No Rust row, no crates.io badge, and sdk/rust/ missing from "What's in this repo" — even though RELEASING.md already documents publishing to crates.io.
• skills/ — ships inkbox-python and inkbox-ts. A coding agent asked to add Inkbox to a Rust project has no skill to load, so it guesses at the API or falls back to a Python/TS idiom that does not compile.
• examples/ — every other SDK has runnable examples. sdk/rust/examples/ holds two low-level smoke checks, not agent examples. use-inkbox-signup/ and use-inkbox-vault/ are polyglot (.py + .ts) and Rust is conspicuously absent from both.

Net effect: a Rust user landing on the repo README has no signal the SDK exists.

Full evidence — the per-SDK example coverage table and the seven ways the Rust API actually diverges from Python/TS — is in #141.

What this PR adds

Docs, skills, and examples only. No change to sdk/rust's implementation.

1. README.md

• Rust row in the install table — cargo add inkbox, linking ./sdk/rust/ and crates.io.
• crates.io version badge alongside the existing PyPI and npm badges.
• sdk/rust/, skills/inkbox-rust/, and examples/use-inkbox-rust/ rows in "What's in this repo", so the two new directories are reachable.

2. skills/inkbox-rust/

A new SKILL.md mirroring skills/inkbox-ts/SKILL.md section for section — same headings, same order, same tone and capability coverage (signup, identities, mail + imports + storage caps, mail clients, phone, text/SMS, iMessage, SMS opt-ins, A2A, vault, TOTP, admin resources, contact rules, contacts, notes, whoami, tunnels, webhooks, error handling, key conventions).

Adapted to Rust idioms rather than transliterated:

• Arc<Inkbox>, inkbox::Result<T> / InkboxError, ? propagation.
• Positional arguments instead of kwargs, with the Unset<T> and Option<Option<T>> tri-state sentinels called out explicitly — the single biggest porting trap.
• Enum variants (MailRuleAction::Allow, CallOrigin::DedicatedNumber, SecretPayload::Login(..)) rather than string literals.
• match on typed InkboxError variants instead of exception subclasses.
• The tunnels-runtime cargo feature gate.

It also documents where Rust genuinely differs from the other SDKs, so the skill does not promise things the crate cannot do:

• iter_emails drains every page eagerly into a Vec<Message> — not a lazy generator.
• A2A receiver configuration and the standard outbound protocol client are Python/TS only; Rust exposes history, directories, and invitations.
• Tunnels forward to a URL only — no in-process Fetch/ASGI handler equivalent.
• The API is blocking; call it from spawn_blocking in an async context.
• UnlockedVault mutators take &mut self.

skills/README.md gains the inkbox-rust row, a cargo add inkbox prerequisite, the manual-install cp line, and a "six skills" → "seven skills" correction.

skills/inkbox-all/SKILL.md — the index-of-skills skill — gains inkbox-rust under Core Skills, use-inkbox-rust under Related Examples, and a "How To Choose" bullet. Its Rust entry names the deltas above so an agent picking a skill knows what Rust does not do before it commits.

3. examples/use-inkbox-rust/

Four runnable examples as numbered binaries in one crate, deliberately mirroring the numbered scripts in use-inkbox-cli so the two sets line up:

Binary	Mirrors	What it does
01-identity-and-email	01-identity-and-email.sh + 03-phone-call.sh	Create an identity (mailbox + tunnel atomic), send and read an email, place a call, clean up
02-vault-totp	02-vault-totp.sh	Login credential with TOTP, generate codes, remove TOTP, clean up
04-inbox-monitor	04-inbox-monitor.sh	Poll unread in a loop, read bodies, batch mark-read
07-signup	use-inkbox-signup/agent_signup.py	Self-register with no API key, verify, status, welcome email, cleanup

use-inkbox-signup and use-inkbox-vault are polyglot directories that had no Rust counterpart; those flows are covered here rather than by adding a Cargo.toml to each. Numbering leaves gaps where no Rust counterpart exists yet.

• One dependency: inkbox. No clap, no uuid, no async runtime.
• default-run keeps a bare cargo run working for 01; the rest use cargo run --bin <name>.
• Teardown runs even when a step fails, so a bad run never leaves a live identity — or a billed phone number — behind.
• Billable and outward-facing steps are opt-in: the call needs INKBOX_DEMO_PHONE, signup registration is its own subcommand.
• 02-vault-totp deliberately demonstrates the snapshot semantics of credentials() — it prints the login count before and after re-unlocking, because a freshly created secret is not in the unlock snapshot.

Verification

Every Rust snippet is grounded in sdk/rust/src — no invented methods.

Compile. cargo build, cargo fmt --check, and cargo clippy --all-targets -- -D warnings all pass in examples/use-inkbox-rust against inkbox v0.5.14 from crates.io.

Every code sample in the skill type-checks. All snippets in skills/inkbox-rust/SKILL.md were extracted into a scratch crate and compiled against the published crate — zero errors. The only warnings are the intentional uses of mail_contact_rules(), phone_contact_rules(), and the org-level create_signing_key(), all three of which the skill labels DEPRECATED. This caught four real defects before they shipped:

• ContactImportResult::created_ids is a method, not a field (and the per-card list is results, not errors)
• ContactFactCitation::source_url is Option<String>
• TextWebhookPayload::event_type is a typed enum, not a string
• WebhookSubscriptionCreateResponse serde-flattens its base under .subscription

End-to-end against the live API. Examples 01, 02, and 04 all ran clean against a real organization with an admin-scoped key, plus 07's cleanup and argument-handling paths. A follow-up list confirmed no residue. (07 register was not run — it provisions a new organization and emails a real human. The phone leg of 01 was likewise left off, since it provisions a billable number and dials a real destination.)

=> Creating identity: rust-demo (mailbox + tunnel provisioned atomically)
   rust-demo@inkboxmail.com
   https://rust-demo.inkboxwire.com
=> Sending a test email to rust-demo@inkboxmail.com
   sent 5aa255d4-4ac5-4286-9c5c-7e61e2dab4ef (sent)
=> Polling the inbox for delivery
   [rust-demo@inkboxmail.com] Rust SDK demo
   Hello from the Inkbox Rust SDK!
=> Cleaning up...
   Done.

02-vault-totp live-confirmed the snapshot semantics the skill documents (0 login(s) before re-unlock, 1 after) and produced correctly rotating codes — the same value twice inside one 30-second window, then a new one. 04-inbox-monitor found the unread message, printed the body, marked it read, and came back clean on the next check; its output also incidentally confirmed the Free-plan stored-body footer the skill warns about.

A separate read-only pass exercised the rest of the documented surface live — whoami discriminant, identity facade accessors, mailbox storage fields (storage_limit_bytes came back 1073741824, exactly 1 GiB, confirming the binary-units guidance), iter_emails, the serde-flattened ThreadDetail.thread.folder, list_folders, identity-keyed contact rules, the iMessage triage number, vault info/secrets/credentials, contacts, notes, both A2A directories plus tasks/contexts with next_cursor, signing-key status, webhook subscriptions, phone numbers, tunnels, SMS opt-ins, and domains. Every field name and shape matched what the skill documents.

One finding worth surfacing. Re-running 01 fails with 409 agent_handle_unavailable: handles live in a namespace shared with tunnels and mail and stay reserved after deletion. The SDK ships a typed view for exactly this — HandleUnavailableError::from_error(&e) → blocking_namespace — which the first draft of the skill did not mention, despite this being the most common create_identity failure. Now documented as a "Handle collisions (409)" subsection under Error Handling, with a note in the example README. Type-checking alone would never have caught it.

CI is unaffected: .github/workflows/tests.yml only builds sdk/rust, and the example is a standalone crate outside any workspace.

[dimavrem22]

Two blocking issues:

1. The newly advertised Rust 1.74 minimum does not work with a fresh dependency resolution. cargo +1.74.1 build in examples/use-inkbox-rust fails before compilation because the current transitive graph includes a Rust-2024 manifest and dependencies requiring newer compilers. The successful build on current stable does not verify the documented MSRV. Please either raise the documented minimum consistently or constrain the dependency graph to 1.74-compatible releases, and add a minimum-toolchain CI check.

2. 02-vault-totp does not fulfill the promise that teardown runs when a step fails. Once create_secret succeeds, any later error returns through run; cleanup deletes only the identity, while the vault secret remains unless execution reaches the success-path delete_secret. Please retain the secret ID outside the fallible workflow and best-effort delete it on every exit before deleting the identity.

I verified the current-toolchain build, formatting, and clippy checks pass; these failures are in the advertised compatibility and error-cleanup paths.

[dimavrem22]

One remaining documentation fix is needed.

[dimavrem22]

Please remove this unused import. The skill tells users to depend only on inkbox; uuid is only transitive and is not available to consumer code, so this snippet fails with E0432 unless users separately add uuid.

[ron-42]

Good catch, removed in 82b2ffe.

My snippet check had uuid as its own dependency, so it was not building the way a reader would. Rebuilding it with inkbox alone also caught two spots that genuinely need serde_json (webhook payload, tunnel metadata), now flagged at the call site and in Install.

The skill compiles against inkbox plus serde_json and nothing else.

[ron-42]

Two blocking issues:

1. The newly advertised Rust 1.74 minimum does not work with a fresh dependency resolution. `cargo +1.74.1 build` in `examples/use-inkbox-rust` fails before compilation because the current transitive graph includes a Rust-2024 manifest and dependencies requiring newer compilers. The successful build on current stable does not verify the documented MSRV. Please either raise the documented minimum consistently or constrain the dependency graph to 1.74-compatible releases, and add a minimum-toolchain CI check.

2. `02-vault-totp` does not fulfill the promise that teardown runs when a step fails. Once `create_secret` succeeds, any later error returns through `run`; `cleanup` deletes only the identity, while the vault secret remains unless execution reaches the success-path `delete_secret`. Please retain the secret ID outside the fallible workflow and best-effort delete it on every exit before deleting the identity.

I verified the current-toolchain build, formatting, and clippy checks pass; these failures are in the advertised compatibility and error-cleanup paths.

Both fixed, thanks.

1. MSRV

Raised the minimum instead of pinning deps. Tested it this time:

Toolchain	Result
1.74.1	fails, rand_pcg 0.10.2 is edition 2024
1.85.0	fails, icu_* 2.2 needs 1.86
1.86.0	works

rust-version is now 1.86, and Cargo.lock is committed so it stays reproducible. Every doc says 1.86.

Note that cargo +1.74.1 build still fails. 1.74 is not reachable with this graph, so the fix was to stop claiming it.

sdk/rust/Cargo.toml had the same bug. It failed on 1.74 even with its own lockfile, because base64ct 1.8.3 is edition 2024. A library lockfile does not apply to consumers, so cargo add inkbox always resolves fresh. Bumped it too. Metadata and README only, no source or lockfile. That is published crate metadata though, so it should go out with a release rather than quietly.

New CI jobs:

• rust-msrv: SDK, both feature sets, at the declared minimum
• rust-example: 1.86 and stable, with --locked. Clippy and fmt run on stable only, since lint sets change between releases and the MSRV build has no say over them
• rust-example-fresh-resolution: drops the lockfile to catch future drift

2. Teardown

The secret id now lives outside run, and cleanup deletes it best effort on every exit, before the identity. delete_secret appears once now.

Forced an error right after creation to check:

   Created secret: 23fae02f-...
=> Cleaning up...
   Deleted secret 23fae02f-...
Error: InvalidArgument("INJECTED FAILURE")

I also confirmed vault secrets do survive identity deletion, so this was a real leak.

Also 02 now reads INKBOX_AGENT_HANDLE, since deleted handles stay reserved and re-runs hit a 409.

Commits: bd28d72, e7878ec, ce23ee5. The CI jobs pass locally but have not run on GitHub yet.