Keep public documentation developer-focused

.github/CODEOWNERS

@@ -1,6 +1,3 @@
 # Replace @raph with your GitHub username/team before pushing.
 * @raph
-/docs/architecture/ @raph
-/docs/adr/ @raph
 /.github/ @raph
-/AGENTS.md @raph

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,23 +1,24 @@
-## Linked issue
+## What changed
 
-Closes #
+Describe the developer problem and the change that solves it.
 
-## Summary
+## User impact
 
-## Scope control
+Describe any API, behavior, compatibility, performance, or documentation change.
 
-- [ ] I modified only this repo.
-- [ ] I respected the repo phase gate.
-- [ ] I did not edit architecture docs unless explicitly assigned.
-- [ ] I did not add dependencies without approval.
-
-## Tests run
+## Validation
 
 ```bash
 
 ```
 
 ## Risks
 
-## Reviewer focus
+List known limits, follow-up work, or deployment considerations.
+
+## Checklist
 
+- [ ] Tests cover the behavior I changed.
+- [ ] Public behavior is documented.
+- [ ] Logs, examples, and fixtures contain no credentials or personal data.
+- [ ] Breaking changes and migration steps are clearly identified.

.gitignore

@@ -24,3 +24,14 @@ venv/
 .mypy_cache/
 .ruff_cache/
 .claude/
+
+# Local agent and engineering records
+/AGENTS.md
+/PHASE*_PROGRESS.md
+/docs/REPO_CONTRACT.md
+/docs/PYTHON_CAPABILITY_MATRIX.md
+/docs/PYTHON_SDK_CORE_PARITY_REFERENCE.md
+/docs/PYTHON_SDK_DESIGN.md
+/docs/adr/
+/docs/architecture/
+/docs/standards/

README.md

@@ -1,12 +1,28 @@
-# sdk-python
+# PocketStation Python SDK
 
-**Organization:** `pocketstation-io`  
-**Repository:** `pocketstation-io/sdk-python`  
-**v2.3 tier:** Tier 2 — Client SDKs  
-**Activation phase:** Phase 5  
-**Language/package:** Python/PyPI  
-**Release strategy:** PyPI pocketstation
+Use Python to connect to a PocketStation control plane and Relay, receive PCM
+audio, and send application-owned PCM back over the same session.
 
-This is an independently releasable PocketStation v2.3 repository folder. It is not meant to be merged permanently into a monorepo.
+> **Status: preview.** This repository does not have a PyPI release. The API in
+> `main` may change while the native PocketStation Session binding is completed.
 
-Agents must respect the phase gate in `docs/REPO_CONTRACT.md`.
+## Develop locally
+
+You need Python 3.11 or newer.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[dev]'
+python -m pytest
+```
+
+The current package uses HTTP for session creation and a WebSocket for binary
+PCM. Configure the control-plane and Relay URLs in your application; the SDK
+does not start hidden infrastructure or select a hosted service for you.
+
+## Related projects
+
+- [PocketStation Core](https://github.com/pocketstation-io/pocketstation)
+- [PocketStation Relay](https://github.com/pocketstation-io/relay)
+- [PocketStation Control Plane](https://github.com/pocketstation-io/control-plane)