docs: add sdk project guidance

Author: Si40Code

CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing
+
+This SDK is the Python server SDK for the CALL-E Developer API. It is meant for
+trusted backend services, workers, and automation systems.
+
+## Development setup
+
+```bash
+uv sync --all-groups
+uv run pytest -q
+uv run ruff check .
+uv run mypy src/calle
+uv run python -m py_compile examples/create_and_wait.py examples/webhook_server.py
+uv build
+uvx twine check dist/*
+```
+
+## Local examples
+
+```bash
+export CALLE_API_KEY="calle_test_key"
+export CALLE_BASE_URL="https://api.example.com"
+export CALLE_EXAMPLE_PHONE="+14155550100"
+uv run python examples/create_and_wait.py
+
+export CALLE_WEBHOOK_SECRET="whsec_test_key"
+uv run python examples/webhook_server.py
+```
+
+The webhook example listens on `POST /calle/webhook` and verifies
+`CALL-E-Timestamp` plus `CALL-E-Signature` against the raw request body.
+
+## Phase 1 scope
+
+In scope:
+
+- Create a call.
+- Read a call.
+- Poll until a terminal call result.
+- List call events.
+- Verify and unwrap signed webhook events.
+
+Out of scope for Phase 1:
+
+- Async client support.
+- Batch calls.
+- Cancel calls.
+- Recurring or scheduled calls.
+- Project-level webhook management.
+- Pydantic result schema helpers.
+
+## API contract changes
+
+The SDK is generated and wrapped from `openapi/calle.openapi.yaml`.
+
+When the OpenAPI contract changes:
+
+1. Update `openapi/calle.openapi.yaml`.
+2. Regenerate generated client code if the generated package is in use.
+3. Update wrappers and tests for any changed behavior.
+4. Run the full development check list above.
+
+## Pull requests
+
+Keep changes small and focused. Include tests for wrapper behavior, error
+handling, webhook signature verification, and any changed API contract surface.
+
+Do not add browser examples or patterns that expose CALL-E API keys to client
+code.

README.md

@@ -89,6 +89,9 @@ event = client.webhooks.unwrap(
 This repository publishes the Python distribution `calle-ai`. Application code
 imports it as `calle`.
 
+See [RELEASE.md](./RELEASE.md) for the release checklist, GitHub Actions
+workflow, and post-publish install smoke test.
+
 Prerequisites:
 
 - Create a TestPyPI API token and add it as the GitHub Actions secret
@@ -114,3 +117,9 @@ python -c 'from calle import CalleClient; print(CalleClient)'
 
 Use repository `pypi` only after the TestPyPI package has been installed and
 tested.
+
+## Project Documents
+
+- [CONTRIBUTING.md](./CONTRIBUTING.md)
+- [SECURITY.md](./SECURITY.md)
+- [RELEASE.md](./RELEASE.md)

RELEASE.md

@@ -0,0 +1,75 @@
+# Release
+
+This repository publishes the Python distribution `calle-ai`. Application code
+imports it as `calle`.
+
+## Current status
+
+The package source, CI, and publish workflow are ready. The first registry
+publish still requires one of these release identities:
+
+- GitHub Actions secret `TEST_PYPI_API_TOKEN` for TestPyPI,
+- GitHub Actions secret `PYPI_API_TOKEN` for PyPI, or
+- PyPI/TestPyPI Trusted Publishing configured for this repository and workflow.
+
+Until the first beta is published, use a local checkout for examples and
+integration testing.
+
+## Release gates
+
+Run these checks before publishing:
+
+```bash
+uv sync --all-groups
+uv run pytest -q
+uv run ruff check .
+uv run mypy src/calle
+uv run python -m py_compile examples/create_and_wait.py examples/webhook_server.py
+uv build
+uvx twine check dist/*
+```
+
+The CI workflow also installs the built wheel in a fresh virtual environment and
+imports `CalleClient`.
+
+## TestPyPI rehearsal
+
+1. Confirm `pyproject.toml` has a unique beta version, for example `0.1.0b1`.
+2. Confirm GitHub Actions secret `TEST_PYPI_API_TOKEN` is configured, unless the
+   package has been moved to TestPyPI Trusted Publishing.
+3. Open the `Publish Python package` workflow in GitHub Actions.
+4. Run the workflow from `main` with repository `testpypi`.
+5. Confirm the workflow completes the post-publish install smoke test.
+
+Manual verification:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple \
+  calle-ai==0.1.0b1
+python -c 'from calle import CalleClient; print(CalleClient)'
+```
+
+## PyPI publish
+
+Use PyPI only after the TestPyPI package has been installed and tested in at
+least one backend integration.
+
+1. Increment the version in `pyproject.toml`. PyPI package versions are
+   immutable.
+2. Confirm GitHub Actions secret `PYPI_API_TOKEN` is configured, unless the
+   package has been moved to PyPI Trusted Publishing.
+3. Run the `Publish Python package` workflow from `main` with repository `pypi`.
+4. Confirm the workflow completes the post-publish install smoke test.
+
+## Registry identity notes
+
+PyPI Trusted Publishing is preferred once the repository is ready for public
+release. Configure a pending publisher for:
+
+- Owner: `CALLE-AI`
+- Repository: `server-sdk-python`
+- Workflow filename: `publish-python.yml`
+- Project name: `calle-ai`

SECURITY.md

@@ -0,0 +1,28 @@
+# Security
+
+## Supported versions
+
+The SDK is in Phase 1 beta preparation. Security fixes are applied to the
+current beta line.
+
+## Reporting a vulnerability
+
+Do not open a public issue for suspected vulnerabilities. Use GitHub private
+vulnerability reporting if it is enabled for this repository; otherwise contact
+the CALL-E maintainers directly.
+
+Send a private report to the CALL-E maintainers with:
+
+- Affected package and version.
+- Reproduction steps or proof of concept.
+- Expected impact.
+- Any relevant logs with secrets removed.
+
+## Secret handling
+
+This SDK is for trusted server environments only. Do not expose CALL-E API keys
+or webhook secrets in browser code, mobile apps, public logs, or client-side
+bundles.
+
+Webhook handlers must verify `CALL-E-Timestamp` and `CALL-E-Signature` against
+the raw request body before parsing or trusting an event.