[pimlock]

Summary

The README currently focuses on development and repository migration. Lead with SDK installation, gateway prerequisites, and usage examples so users can connect to a gateway and run commands. Update package metadata to describe the Python client and remove the Alpha classifier.

Related Issue

No issue required: documentation and package metadata maintenance with no runtime or API changes.

Changes

• Add the OpenShell banner, license/PyPI/security/docs badges, and uv and pip installation commands.
• Add examples for sandbox creation and cleanup, SDK and gateway versions, pagination, commands in existing sandboxes, and OIDC service authentication.
• Move developer and end-to-end test setup into CONTRIBUTING.md and keep migration details in one history section.
• Remove the Alpha classifier, clarify the package description and keywords, and link package metadata directly to the Python SDK docs. Supported Python versions and public APIs are unchanged.

Testing

• mise run ci: formatting, lint, type checking, proto and fixture drift checks, 240 unit tests, package build verification, and clean installation smoke checks.
• Manually exercised the non-OIDC README workflows against a temporary Docker gateway running core v0.1.7, including command output, version output, listing, automatic deletion, and retaining an existing sandbox.
• Validated all remaining PyPI classifiers and rendered the README with PyPI's Markdown renderer, including the banner.
• Checked README links, image URLs, example syntax, and git diff --check.
• Unit/E2E test additions are not applicable. OIDC was not exercised against an identity provider.
• This repository has no pre-commit task; its full mise run ci pipeline passed instead.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• README or CONTRIBUTING.md updated