Artsen · Artsen · Jul 25, 2026 · Jul 25, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,79 +1,110 @@
 # Contributing to ColorCraft
 
-Thank you for your interest in contributing to ColorCraft! This document provides guidelines for contributing to the project.
+## Before you start
 
-## Getting Started
+- Install Python 3.11.
+- Install Node.js 20 or newer.
+- Enable Corepack.
+- Read [ColorCraft Technical English](./docs/writing-style.md) before you change
+  documentation.
 
-1. Fork the repository
-2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/ColorCraft.git`
-3. Create a new branch: `git checkout -b feature/your-feature-name`
-4. Make your changes
-5. Test your changes thoroughly
-6. Commit your changes: `git commit -m "Add your feature"`
-7. Push to your fork: `git push origin feature/your-feature-name`
-8. Create a Pull Request
+## Set up the repository
 
-## Development Setup
+### Windows
 
-### Backend
-```bash
-cd backend
-pip install -r requirements.txt
-python main.py
+```powershell
+py -3.11 -m venv backend\.venv311
+.\backend\.venv311\Scripts\python.exe -m pip install --upgrade pip
+.\backend\.venv311\Scripts\python.exe -m pip install -r backend\requirements-dev.txt
+cd frontend
+corepack pnpm@9.15.9 install
+cd ..
 ```
 
-### Frontend
+### macOS and Linux
+
 ```bash
+python3.11 -m venv backend/.venv
+backend/.venv/bin/python -m pip install --upgrade pip
+backend/.venv/bin/python -m pip install -r backend/requirements-dev.txt
 cd frontend
-pnpm install
-pnpm dev
+corepack pnpm@9.15.9 install
+cd ..
 ```
 
-## Code Style
-
-### Python
-- Follow PEP 8 guidelines
-- Use type hints where appropriate
-- Add docstrings to functions and classes
-
-### TypeScript/React
-- Use TypeScript for type safety
-- Follow React best practices
-- Use functional components with hooks
-
-## Testing
+## Start ColorCraft
 
-Before submitting a PR, ensure:
-- All existing tests pass
-- New features include appropriate tests
-- The application builds without errors
-- No console errors or warnings
+Use the one-terminal launcher:
 
-## Pull Request Guidelines
-
-- Provide a clear description of the changes
-- Reference any related issues
-- Include screenshots for UI changes
-- Ensure your code is well-documented
-- Keep PRs focused on a single feature or fix
+```powershell
+.\backend\.venv311\Scripts\python.exe dev.py
+```
 
-## Feature Requests
+On macOS or Linux, run `backend/.venv/bin/python dev.py`. See
+[Getting started](./docs/getting-started.md) for manual startup and runtime
+configuration.
 
-Feature requests are welcome! Please:
-- Check if the feature has already been requested
-- Provide a clear use case
-- Explain how it aligns with the project goals
+## Validate a change
 
-## Bug Reports
+Install Playwright Chromium once:
 
-When reporting bugs, please include:
-- Steps to reproduce
-- Expected behavior
-- Actual behavior
-- Screenshots if applicable
-- Environment details (OS, browser, etc.)
+```powershell
+cd frontend
+corepack pnpm@9.15.9 exec playwright install chromium
+cd ..
+```
 
-## Questions?
+Run the complete gate before you open a pull request:
 
-Feel free to open an issue for any questions or clarifications.
+```powershell
+.\backend\.venv311\Scripts\python.exe check.py
+git diff --check
+```
 
+On macOS or Linux, use `backend/.venv/bin/python check.py`.
+
+The gate runs Prettier, ESLint, TypeScript, Vitest with coverage, the frontend
+production build, Ruff, mypy, pytest with coverage, Playwright, and axe
+accessibility checks. Use `python check.py --skip-e2e` only for a fast local
+iteration. Do not use the reduced gate as the final pull request validation.
+
+## Code requirements
+
+- Keep a change focused.
+- Add or update tests for changed behavior.
+- Preserve the Pydantic and Zod contract boundary.
+- Use semantic style tokens for application chrome.
+- Do not describe relationship fit as aesthetic quality.
+- Do not describe a passing contrast pair as proof of complete accessibility.
+
+## Documentation requirements
+
+- Follow [ColorCraft Technical English](./docs/writing-style.md).
+- Use the preferred ColorCraft terminology.
+- Preserve exact UI labels and technical strings.
+- Add a glossary entry for a new stable concept.
+- Update the canonical document instead of copying a large section into the
+  README.
+- Verify algorithm claims against current code and tests.
+- Keep measured relationships separate from aesthetic judgment.
+
+## Pull request requirements
+
+- Explain what changed and why.
+- Reference related issues.
+- List the validation commands and results.
+- Include current screenshots for an intentional UI change.
+- State changes to API contracts, persistence, runtime configuration, or
+  privacy boundaries.
+- Do not commit virtual environments, `node_modules`, build output, temporary
+  screenshots, uploaded test images, credentials, or local configuration.
+
+## Report a bug
+
+Include:
+
+- Reproduction steps
+- Expected result
+- Actual result
+- Operating system and browser
+- Relevant terminal output with secrets and local private data removed
diff --git a/README.md b/README.md
@@ -4,21 +4,41 @@
   <img src="./frontend/public/colorcraft-mark.svg" width="72" alt="ColorCraft mark">
 </p>
 
-<p align="center"><strong>A local-first workspace for extracting, refining, reviewing, saving, and exporting color palettes.</strong></p>
+<p align="center"><strong>A local workspace for extracting, editing, reviewing, saving, and exporting color palettes.</strong></p>
 
 <p align="center">
   <a href="https://github.com/Artsen/ColorCraft/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Artsen/ColorCraft/actions/workflows/ci.yml/badge.svg"></a>
   <a href="./LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-725fd6"></a>
   <img alt="Local-first" src="https://img.shields.io/badge/storage-local--first-41a37a">
 </p>
 
-![ColorCraft review workspace](./docs/assets/screenshots/review-dark.png)
+ColorCraft creates a palette from a source image or from colors that you enter
+manually. It detects geometric hue relationships, evaluates contrast, proposes
+optional colors, and generates browser-side exports.
 
-ColorCraft turns an image or a hand-built set of colors into practical design evidence. It extracts representative colors, detects geometric harmony relationships, checks WCAG contrast, suggests additions, and exports reusable values. Saved palettes stay in the current browser. Uploaded source images are processed for the active session and are not placed in persistent browser storage.
+![ColorCraft Review workspace](./docs/assets/screenshots/review-dark.png)
+
+## Current workflow
+
+1. Create a palette from a JPG, PNG, or WebP source image, or select **Start manually**.
+2. Edit, add, duplicate, remove, or sample palette colors.
+3. Select **Analyze palette**.
+4. Use **Overview**, **Harmony**, **Contrast**, and **Suggestions** in Review.
+5. Assign color roles and evaluate the applicable contrast pairs.
+6. Use Export to generate **CSS custom properties**, **JSON**, **Tailwind theme colors**, or an **SVG swatch sheet**.
+7. Select **Copy** or **Download**.
+
+Relationship fit measures geometric agreement with documented hue structures, not aesthetic quality. Contrast checks measure one accessibility requirement; they do not prove complete WCAG conformance.
+
+The API accepts a source image up to 10 MB and 40 million decoded pixels. Extraction returns 3–10 requested colors, or fewer for a limited processing sample. **Save palette** stores a versioned record in IndexedDB. The Library can open, search, rename, duplicate, and delete saved palettes.
+
+ColorCraft has no accounts or cloud synchronization. Source-image bytes and unsaved changes remain session-only. Browser history stores the active view and Review tab, not palette data. Export generation runs in the browser.
+
+![ColorCraft Palette Library](./docs/assets/screenshots/library-dark.png)
 
 ## Quick start
 
-Use Python 3.11 and Node.js 20 or newer. From the repository root:
+Use Python 3.11 and Node.js 20 or newer:
 
 ```powershell
 py -3.11 -m venv backend\.venv311
@@ -29,58 +49,24 @@ cd ..
 .\backend\.venv311\Scripts\python.exe dev.py
 ```
 
-On macOS or Linux, create `backend/.venv`, install the same requirements, then run `backend/.venv/bin/python dev.py`. One launcher starts both services and opens the app:
-
-- Web: `http://127.0.0.1:5174`
-- API: `http://127.0.0.1:4100`
-- Runtime metadata: `http://127.0.0.1:4100/metadata`
-
-See [Getting started](./docs/getting-started.md) for setup and recovery details.
+The web application starts at `http://127.0.0.1:5174`; the API starts at `http://127.0.0.1:4100`. The default configuration accepts loopback traffic only. Trusted LAN access expands the security boundary and requires opt-in.
 
-## Product workflow
-
-```mermaid
-flowchart LR
-    Start[Upload image or start manually] --> Edit[Refine palette]
-    Edit --> Save[Save locally]
-    Save --> Review[Review harmony and contrast]
-    Review --> Export[Copy or download exports]
-    Save --> Library[Search, reopen, rename, duplicate, or delete]
-```
+Read [Getting started](./docs/getting-started.md) for Windows, macOS, Linux, manual startup, configuration, shutdown, and recovery procedures.
 
-The application makes state explicit: **Unsaved** means no local record exists, **Saved** means the open palette matches its record, and **Modified** means local edits need **Save changes**. Starting another palette or opening a saved palette prompts before meaningful unsaved work is discarded.
-
-## Capabilities
+## Documentation
 
-- Deterministic LAB-space image color extraction
-- Manual palette creation and direct HEX editing
-- Harmony visualization and explainable relationship fit
-- WCAG contrast-role review and color suggestions
-- CSS, JSON, Tailwind, and token export
-- IndexedDB palette library with search and recent items
-- Light, dark, and system themes with responsive navigation
-- Dashboard discovery through a static manifest and runtime metadata endpoint
+Use the [documentation index](./docs/README.md) for user, technical, operations, and contribution guides. All documentation follows [ColorCraft Technical English](./docs/writing-style.md).
 
 ## Validation
 
-After installing the development dependencies and Playwright Chromium:
+Run the complete local and CI gate:
 
 ```powershell
-cd frontend
-corepack pnpm@9.15.9 exec playwright install chromium
-cd ..
 .\backend\.venv311\Scripts\python.exe check.py
 ```
 
-`check.py` runs formatting, linting, frontend and backend typing, unit and integration coverage, production build, Playwright workflow coverage, and automated accessibility checks. CI runs the same command. See [Testing](./docs/testing.md).
-
-## Documentation
-
-The [documentation index](./docs/README.md) links setup, workflow, runtime configuration, architecture, API, persistence and privacy, dashboard manifest, brand, testing, screenshot review, and troubleshooting guides.
-
-## Privacy and security
-
-ColorCraft binds to loopback addresses by default. Palette records are stored in the browser's IndexedDB database; theme preference is the only application preference stored in LocalStorage. Source images are sent to the local API for extraction but are not retained by ColorCraft after processing. Clearing site data removes saved palettes. Read [Persistence and privacy](./docs/persistence-and-privacy.md) before enabling LAN access.
+The gate checks formatting, linting, types, tests, coverage, the production
+build, browser workflows, and representative accessibility states.
 
 ## License
 

diff --git a/docs/README.md b/docs/README.md
@@ -1,15 +1,20 @@
 # ColorCraft documentation
 
-Start with [Getting started](./getting-started.md), then use the guide that matches your task:
+| Document | Audience and purpose |
+| --- | --- |
+| [Getting started](./getting-started.md) | Users and contributors who must install, start, stop, or recover ColorCraft. |
+| [User guide](./user-guide.md) | Users who create, review, save, manage, and export palettes. |
+| [Color analysis](./color-analysis.md) | Readers who must interpret extraction, relationship, fit, and contrast results. |
+| [API contracts](./api-contracts.md) | API consumers who need canonical routes, payloads, validation, and errors. |
+| [Architecture](./architecture.md) | Contributors who need component boundaries and data flows. |
+| [Runtime configuration](./runtime-configuration.md) | Operators who configure hosts, ports, CORS, browser launch, or trusted LAN access. |
+| [Persistence and privacy](./persistence-and-privacy.md) | Users and operators who need storage, retention, migration, and security details. |
+| [Dashboard manifest](./dashboard-manifest.md) | Dashboard integrators who discover ColorCraft and resolve runtime endpoints. |
+| [Testing](./testing.md) | Contributors who run local and CI validation. |
+| [Troubleshooting](./troubleshooting.md) | Users and contributors who must recover from known failures. |
+| [Screenshot review](./screenshot-review.md) | Reviewers who generate or curate product screenshots. |
+| [Brand system](./brand-system.md) | Designers and UI contributors who apply the visual identity and product voice. |
+| [ColorCraft Technical English](./writing-style.md) | All documentation contributors who need the controlled writing and terminology standard. |
 
-- [User workflow](./user-workflow.md) — create, save, review, export, and manage palettes.
-- [Runtime configuration](./runtime-configuration.md) — ports, hosts, CORS, LAN opt-in, and launcher behavior.
-- [Architecture](./architecture.md) — application boundaries and data flow.
-- [API](./api.md) — endpoints, request shapes, metadata, readiness, and errors.
-- [Persistence and privacy](./persistence-and-privacy.md) — IndexedDB schema, migration, retention, and deletion.
-- [Dashboard manifest](./dashboard-manifest.md) — static discovery defaults and runtime resolution.
-- [Testing](./testing.md) — local and CI quality gates.
-- [Screenshot review](./screenshot-review.md) — deterministic fixtures, temporary output, and curation.
-- [Troubleshooting](./troubleshooting.md) — common Python, pnpm, port, and browser failures.
-- [Brand system](./brand-system.md) — identity, tokens, themes, and shell conventions.
-- [API contract rationale](./api-contracts.md) — compatibility and validation design notes.
+The application code, API schemas, and tests are the source of truth for
+behavior. Update the relevant canonical document when behavior changes.