feature/pp-58-runtime-image-contract (#68)

## Summary

This PR tightens repository quality enforcement around markdown and documentation. It adds `markdownlint` to the `cicd-checks` workflow, expands pre-commit coverage so markdown files are checked repo-wide, and cleans up the PP-58 documentation set to keep it aligned with the new policy.

## What changed

- Added a `Markdownlint Check` entry to `.gitea/workflows/cicd-checks.yaml`
- Added `markdownlint` to pre-commit and widened prettier coverage to include markdown files across the repo
- Updated `README.md` to satisfy markdownlint line-length rules
- Normalized the PP-58 documentation set:
  - `docs/DEPLOYABLE_RUNTIME_CONTRACT.md`
  - `docs/adr/ADR003-deployable_runtime_image_contract.md`
  - `docs/DEVELOPMENT.md`
  - `docs/CICD_MULTI_STAGE_BUILD.md`
  - `docs/CICD_TROUBLESHOOTING_GUIDE.md`
  - `docs/SECURE_DOCKER_CICD.md`

## Validation

- `pre-commit run markdownlint --files README.md docs/DEPLOYABLE_RUNTIME_CONTRACT.md`
- `pre-commit run prettier --files README.md docs/DEPLOYABLE_RUNTIME_CONTRACT.md`
- Workflow YAML validation returned no errors

## Notes

This change does not alter application runtime behavior. It only strengthens CI and documentation quality enforcement.

Co-authored-by: copilotcoder <copilotcoder@darkhelm.org>
Reviewed-on: #68

docs/DEVELOPMENT.md

@@ -19,6 +19,24 @@ This document outlines how to set up your development environment and work with
 - **[CI/CD Multi-Stage Build Architecture](CICD_MULTI_STAGE_BUILD.md)** - Technical details of the optimized build system
 - **[CI/CD Troubleshooting](GITEA_ACTIONS_TROUBLESHOOTING.md)** - Common issues and solutions
 - **[Secure Docker CI/CD](SECURE_DOCKER_CICD.md)** - Security considerations and practices
+- **[Deployable Runtime Contract](DEPLOYABLE_RUNTIME_CONTRACT.md)** - Canonical backend/frontend runtime artifact contract and exclusion rules
+- **[ADR003: Deployable Runtime Image Contract Boundaries](adr/ADR003-deployable_runtime_image_contract.md)** - Decision record for deployable runtime boundaries
+
+## Deployable Runtime Artifacts
+
+When changing deployment behavior or image composition, treat
+`DEPLOYABLE_RUNTIME_CONTRACT.md` as the source of truth for:
+
+- Runtime entrypoint and exposed ports.
+- Health and startup expectations.
+- Runtime environment contract.
+- Disallowed non-runtime tooling classes in final deployable images.
+
+Scope boundary:
+
+- This repository separates contract definition from enforcement mechanics.
+- CI workflow rewiring and test execution redesign are out of scope for PP-58
+  and belong to follow-up work under epic #66.
 
 ## Quick Start
 
@@ -69,10 +87,10 @@ docker compose -f compose.dev.yml up -d --build
 
 ### Service Access
 
-- **Frontend**: http://localhost:3000
-- **Backend API**: http://localhost:8000
-- **API Documentation**: http://localhost:8000/docs
-- **Database**: localhost:5432 (user: `plex`, password: see `secrets/postgres_password`)
+- **Frontend**: <http://localhost:3000>
+- **Backend API**: <http://localhost:8000>
+- **API Documentation**: <http://localhost:8000/docs>
+- **Database**: `localhost:5432` (user: `plex`, password: see `secrets/postgres_password`)
 
 ## Poe the Poet Task Runner
 
@@ -197,6 +215,7 @@ pre-commit run --all-files
 ### How It Works
 
 Pre-commit automatically runs on every `git commit` and will:
+
 - Format code (Prettier, Ruff)
 - Check syntax (ESLint, Pyright)
 - Validate files (YAML, TOML, trailing whitespace)
@@ -207,6 +226,7 @@ If any hook fails, the commit is blocked until issues are fixed.
 ### Pre-commit is Optional
 
 While strongly recommended, pre-commit is not required because:
+
 - **CI Validation**: All the same checks run in CI
 - **Developer Choice**: Some prefer manual tool usage
 - **Learning**: Developers can run tools individually to understand them
@@ -221,7 +241,8 @@ If you prefer not to use pre-commit, here's how to run each tool manually:
 
 Navigate to the `backend/` directory for all backend commands.
 
-#### Code Formatting
+#### Backend Code Formatting
+
 ```bash
 # Format code with Ruff
 uv run ruff format .
@@ -230,13 +251,15 @@ uv run ruff format .
 uv run ruff check . --fix
 ```
 
-#### Type Checking
+#### Backend Type Checking
+
 ```bash
 # Run Pyright type checker
 uv run pyright
 ```
 
-#### Testing
+#### Backend Testing
+
 ```bash
 # Run unit tests
 uv run pytest
@@ -251,7 +274,8 @@ uv run pytest tests/integration/
 uv run xdoctest src/
 ```
 
-#### Documentation
+#### Backend Documentation
+
 ```bash
 # Check docstring style
 uv run pydoclint --config=pyproject.toml src/
@@ -261,7 +285,8 @@ uv run pydoclint --config=pyproject.toml src/
 
 Navigate to the `frontend/` directory for all frontend commands.
 
-#### Code Formatting
+#### Frontend Code Formatting
+
 ```bash
 # Format code with Prettier
 yarn format
@@ -271,6 +296,7 @@ yarn format:check
 ```
 
 #### Linting
+
 ```bash
 # Run ESLint
 yarn lint
@@ -282,13 +308,15 @@ yarn lint:fix
 yarn lint:tsdoc
 ```
 
-#### Type Checking
+#### Frontend Type Checking
+
 ```bash
 # Run Vue TypeScript compiler
 yarn type-check
 ```
 
-#### Testing
+#### Frontend Testing
+
 ```bash
 # Run unit tests
 yarn test
@@ -341,22 +369,26 @@ The CI/CD pipeline uses a **multi-stage build architecture** for optimal perform
 - **Stage 2**: Build complete image (project code and dependencies) - **rebuilt every time**
 
 Pipeline triggers:
+
 - Push to any branch
 - Pull requests to `main` or `develop`
 
 ### Multi-Stage Build Benefits ✅ **VALIDATED SUCCESSFUL**
 
 **Performance Gains**:
+
 - **85% build time improvement**: 3-5 minutes (down from 15-25 minutes)
 - Base image cached when `Dockerfile.cicd-base` unchanged (~95% of runs)
 - **100% success rate** achieved with optimized dependency management
 - Raspberry Pi 4GB workers handle builds efficiently with resource optimization
 
 **Architecture**:
+
 - `cicd-base:latest` - System dependencies (Python 3.14, Node.js 24, build tools, pre-installed dev packages)
 - `cicd:latest` - Complete environment (project code + optimized dependency installation)
 
 **Recent Optimizations** (November 2025):
+
 - **Dependency-first build pattern** prevents cache invalidation on code changes
 - **Yarn PnP state regeneration** ensures reliable frontend builds
 - **Network-resilient E2E testing** with simplified Docker operations