docs(pp-58): define deployable runtime image contract

README.md

@@ -9,6 +9,17 @@ A full-stack application for managing Plex playlists with a FastAPI backend and
 - **Database**: PostgreSQL 16
 - **Containerization**: Docker + Docker Compose
 
+## Deployable Runtime Contract
+
+Deployable image requirements are defined in:
+
+- [docs/DEPLOYABLE_RUNTIME_CONTRACT.md](docs/DEPLOYABLE_RUNTIME_CONTRACT.md)
+- [docs/adr/ADR003-deployable_runtime_image_contract.md](docs/adr/ADR003-deployable_runtime_image_contract.md)
+
+These documents define backend/frontend runtime boundaries, startup and health
+behavior expectations, environment contracts, and disallowed non-runtime
+tooling classes in deployable artifacts.
+
 ## Development Setup
 
 ### Prerequisites
@@ -22,20 +33,24 @@ A full-stack application for managing Plex playlists with a FastAPI backend and
 This project uses comprehensive linting and formatting:
 
 **Backend (Python):**
+
 - `ruff` - Fast Python linter and formatter
 - `pyright` - Type checking
 - `pydoclint` - Docstring linting (Google style)
 
 **Frontend (TypeScript/Vue):**
+
 - `eslint` - Linting with Vue and TypeScript support
 - `prettier` - Code formatting
 - `vue-tsc` - Vue TypeScript checking
 - `eslint-plugin-tsdoc` - TSDoc documentation linting
 
 **Task Runner:**
+
 - `poethepoet` - Unified task runner for development workflows
 
 **General:**
+
 - `pre-commit` - Git hooks for automated quality checks
 - TOML formatting and validation
 
@@ -66,45 +81,49 @@ pre-commit install
 
 ### Quick Start
 
-1. **Clone the repository**
+Clone the repository, then choose one of these startup paths.
 
-2. **Unified Development (Recommended):**
-   ```bash
-   # Complete setup and start development environment
-   poe setup
+#### Unified Development
 
-   # Or manually:
-   cd backend
-   pip install -e .
-   poe dev-env-start
-   ```
+```bash
+# Complete setup and start development environment
+poe setup
 
-3. **Traditional Setup:**
-   ```bash
-   # Backend development
-   cd backend
-   pip install -e .
+# Or manually:
+cd backend
+pip install -e .
+poe dev-env-start
+```
 
-   # Frontend development
-   cd frontend
-   npm install
-   npm run dev
-   ```
+#### Traditional Setup
 
-4. **Docker Development:**
-   ```bash
-   # Using Poe (recommended)
-   poe docker-dev-up
+```bash
+# Backend development
+cd backend
+pip install -e .
 
-   # Or directly
-   docker compose -f compose.dev.yml up --build
-   ```
+# Frontend development
+cd frontend
+npm install
+npm run dev
+```
 
-5. **Production Build:**
-   ```bash
-   poe docker-prod-up
-   # Or: docker compose up --build
-   ```
+#### Docker Development
+
+```bash
+# Using Poe (recommended)
+poe docker-dev-up
+
+# Or directly
+docker compose -f compose.dev.yml up --build
+```
+
+#### Production Build
+
+```bash
+poe docker-prod-up
+# Or: docker compose up --build
+```
 
 ### Running in Production Mode
 
@@ -113,13 +132,14 @@ docker compose up --build -d
 ```
 
 This will start:
+
 - PostgreSQL database on port 5432
 - FastAPI backend on port 8000
 - Vue.js frontend on port 80
 
 ## Project Structure
 
-```
+```text
 plex-playlist/
 ├── backend/                 # FastAPI backend
 ├── frontend/               # Vue.js frontend
@@ -144,16 +164,20 @@ For full troubleshooting context, see `docs/GITEA_ACTIONS_TROUBLESHOOTING.md`.
 ## Environment Variables
 
 ### Backend
+
 - `DATABASE_URL`: PostgreSQL connection string
+- `BACKEND_REQUIRED_PYTHON`: Runtime policy baseline (`3.14` default)
 - `ENVIRONMENT`: `development` or `production`
 - `RELOAD`: Enable uvicorn auto-reload (development only)
 
 ### Frontend
-- `NODE_ENV`: `development` or `production`
+
+- No required runtime environment variables for production nginx serving
 
 ## Database
 
 The PostgreSQL database is configured with:
+
 - Database: `plex_playlist`
 - User: `plex_user`
 - Password: `plex_password`
@@ -168,12 +192,13 @@ The PostgreSQL database is configured with:
 ## API Documentation
 
 When running, the FastAPI automatic documentation is available at:
-- Development: http://localhost:8001/docs
-- Production: http://localhost:8000/docs
+
+- Development: <http://localhost:8001/docs>
+- Production: <http://localhost:8000/docs>
 
 ---
 
-# Manual Setup (if not using Docker)
+## Manual Setup (if not using Docker)
 
 ## Backend Setup (FastAPI, Python 3.14, uv, ruff, pyright)
 
@@ -227,6 +252,7 @@ npm install
 ### 2. Recommended: Enable strictest TypeScript settings
 
 Edit `tsconfig.json` and set:
+
 ```json
 {
   "compilerOptions": {
@@ -255,8 +281,11 @@ npm run dev
 ## Documentation
 
 ### Development & Workflow
+
 - **[Development Environment Setup](docs/DEVELOPMENT.md)** - Comprehensive guide for setting up your development environment, git workflow, pre-commit hooks, manual tool usage, and CI/CD pipeline understanding
 - **[Poe Task Reference](docs/POE_TASK_REFERENCE.md)** - Complete guide to unified development tasks and workflows using Poe the Poet
+- **[Deployable Runtime Contract](docs/DEPLOYABLE_RUNTIME_CONTRACT.md)** - Canonical backend/frontend deployable runtime image requirements and exclusions
+- **[ADR003: Deployable Runtime Image Contract Boundaries](docs/adr/ADR003-deployable_runtime_image_contract.md)** - Architectural decision that locks deployable image boundary policy
 
 ### Architecture & CI/CD
 
@@ -267,7 +296,6 @@ npm run dev
 ### Dependency Management & Automation
 
 - **[Renovate Bot Setup](docs/RENOVATE_SETUP_GUIDE.md)** - Automated dependency updates with Renovate for Python, Node.js, and Docker dependencies
-- **[Gitea API Token Setup](docs/GITEA_TOKEN_SETUP.md)** - Step-by-step guide for creating organization API tokens with proper permissions
 
 ### Operations & Troubleshooting