Artsen · Artsen · Jul 25, 2026 · Jul 25, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -57,6 +57,14 @@ If you changed UI presentation, run `npm run review:ui-screens` and review the i
 - Add or update tests close to the behavior being changed.
 - Avoid changing encoding defaults, API contracts, or routing behavior inside unrelated refactors.
 
+## Documentation Expectations
+
+- Use the controlled terminology in [WVO Technical English](docs/writing-style.md).
+- Preserve exact UI labels, commands, routes, filenames, environment variables, API fields, codec names, and error codes.
+- Check terminology when you add a new user-facing concept.
+- Add a glossary entry to `docs/writing-style.md` when a new concept needs a stable preferred term.
+- Do not claim formal ASD-STE100 compliance.
+
 ## Do Not Commit
 
 - `node_modules`

diff --git a/PRIVACY.md b/PRIVACY.md
@@ -5,7 +5,7 @@ Web Video Optimizer is designed for local media processing.
 ## What Stays Local
 
 - Uploaded source videos are stored under the configured local `STORAGE_ROOT` or Docker volume.
-- Optimized outputs, posters, captions, packages, temporary files, and `manifest.json` stay in managed local storage.
+- Optimized outputs, posters, captions, website packages, temporary files, and `manifest.json` stay in managed local storage.
 - FFmpeg, FFprobe, and whisper.cpp processing runs on your machine when those tools are installed locally.
 - The app does not include analytics, telemetry, accounts, hosted storage, or remote video processing services.
 
@@ -17,7 +17,7 @@ The browser talks to the local API base URL you configure with `VITE_API_BASE_UR
 
 ## Local Storage And Deletion
 
-The Library and Results views can delete sources, jobs, and generated artifacts from managed storage. Storage cleanup removes stale temporary files. Docker users should remember that media persists in the `video_data` volume until it is deleted from the app or the volume is removed.
+The Library and Results views can delete sources, jobs, and outputs from managed storage. Storage cleanup removes stale temporary files. Docker users should remember that media persists in the `video_data` volume until the user deletes it from the app or removes the volume.
 
 ## Logs And Metadata
 

diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@
 
 Web Video Optimizer is a local-first browser workspace for turning source videos into website-ready media packages. It runs FFmpeg on your computer, creates compatible and modern video outputs, lets you compare visual quality, and packages video, poster, caption, transcript, embed, and structured-data assets for deployment.
 
-It is intended for web developers, content teams, marketers, and creators who need deployable web video assets without sending source media to a hosted conversion service. In the default local configuration, the browser sends media to the local WVO API process and the API keeps sources and generated files on your machine.
+It is intended for web developers, content teams, marketers, and creators who need deployable web video assets without sending source videos to a hosted conversion service. In the default local configuration, the browser sends media to the local WVO API process and the API keeps sources and generated files on your machine.
 
 <picture>
   <source media="(prefers-color-scheme: light)" srcset="docs/assets/screenshots/results-light.webp">
@@ -374,15 +374,15 @@ See [Privacy](PRIVACY.md) and [Security](SECURITY.md).
 
 ## Current Limitations
 
-WVO is still a developer beta for trusted local or trusted LAN use. It has no accounts or cloud sync. FFmpeg and FFprobe are required for core media work; caption generation requires optional whisper.cpp and a local model; URL import requires optional yt-dlp and contacts the source service. Processing speed depends on source media, codec, settings, and hardware. Browser playback support may differ from encoding support. Docker Compose startup is validated in GitHub Actions on Ubuntu, but local platform behavior can still vary.
+WVO is still a developer beta for trusted local or trusted LAN use. It has no accounts or cloud sync. FFmpeg and FFprobe are required for core media work; caption generation requires optional whisper.cpp and a local model; URL import requires optional yt-dlp and contacts the source service. Processing speed depends on the source video, codec, settings, and hardware. Browser playback support may differ from encoding support. Docker Compose startup is validated in GitHub Actions on Ubuntu, but local platform behavior can still vary.
 
 ## Documentation Map
 
 **Users:** [Getting Started](docs/getting-started.md), [User Guide](docs/user-guide.md), and [Troubleshooting](docs/troubleshooting.md).
 
 **Operators:** [Configuration](docs/configuration.md), [Privacy](PRIVACY.md), and [Security](SECURITY.md).
 
-**Developers:** [Architecture](docs/architecture.md), [API Reference](docs/api.md), and [Testing](docs/testing.md).
+**Developers:** [Architecture](docs/architecture.md), [API Reference](docs/api.md), [Testing](docs/testing.md), and [WVO Technical English](docs/writing-style.md).
 
 **Project governance:** [Contributing](CONTRIBUTING.md), [Code of Conduct](CODE_OF_CONDUCT.md), [Changelog](CHANGELOG.md), and [Support](SUPPORT.md).
 

diff --git a/SECURITY.md b/SECURITY.md
@@ -24,6 +24,6 @@ Include:
 
 ## Scope
 
-Useful reports include path traversal, unsafe file serving, upload admission bypasses, command execution issues, unsafe archive contents, CORS mistakes, dependency vulnerabilities with a working impact, and denial-of-service cases that bypass configured limits.
+Useful reports include path traversal, unsafe file serving, upload admission bypasses, command execution issues, unsafe ZIP contents, CORS mistakes, dependency vulnerabilities with a working impact, and denial-of-service cases that bypass configured limits.
 
 Reports about optional third-party tools such as FFmpeg, yt-dlp, or whisper.cpp may need to be reported upstream unless the issue is caused by how this app invokes them.
diff --git a/SUPPORT.md b/SUPPORT.md
@@ -4,13 +4,13 @@ Web Video Optimizer is a developer-beta local tool. The fastest path to help is
 
 ## Before Opening An Issue
 
-Check:
+Before you open an issue, check:
 
 - [Getting Started](docs/getting-started.md)
 - [Configuration](docs/configuration.md)
 - [Troubleshooting](docs/troubleshooting.md)
 
-Also confirm:
+Then confirm these commands:
 
 ```powershell
 node --version
@@ -23,21 +23,22 @@ ffprobe -version
 
 Include:
 
-- operating system
-- Node.js version
-- whether you are using Docker or local Node
-- whether FFmpeg/FFprobe are on PATH
-- relevant environment variables with private paths redacted
-- steps to reproduce
-- expected and actual behavior
-- browser console errors or API terminal output
-- whether the issue happens with a small test video
+- Operating system.
+- Node.js version.
+- Whether you use Docker or local Node.
+- Whether FFmpeg and FFprobe are on PATH.
+- Relevant environment variables with private paths redacted.
+- Steps to reproduce.
+- Expected result.
+- Actual result.
+- Browser console errors or API terminal output.
+- Whether the issue happens with a small test source video.
 
-Do not attach private media unless you are comfortable sharing it publicly.
+Do not attach a private source video unless you are comfortable sharing the source video publicly.
 
 ## Feature Requests
 
-Describe the workflow you are trying to improve, the current workaround, and what success would look like.
+Describe the workflow you want to improve, the current workaround, and the result that would make the workflow better.
 
 ## Security
 

diff --git a/docs/README.md b/docs/README.md
@@ -20,4 +20,5 @@ Start here when you want the app to run, understand it, change it, or debug it.
 - [API Reference](api.md): local API endpoints and response behavior.
 - [Testing](testing.md): unit, coverage, browser E2E, real-media integration, and screenshot review commands.
 - [Brand System](brand-system.md): visual identity, palette, logo rules, interaction states, and screenshot asset guidance.
+- [WVO Technical English](writing-style.md): controlled terminology and procedural-writing standard for documentation.
 - [Contributing](../CONTRIBUTING.md): branch hygiene, review expectations, and files that must not be committed.
diff --git a/docs/api.md b/docs/api.md
@@ -18,7 +18,7 @@ http://localhost:4000
 
 `/health` is intentionally lightweight liveness. `/ready` reports required startup checks such as managed storage, manifest load state, FFmpeg/FFprobe availability, core encoding capabilities, and storage pressure without exposing local paths, executable paths, filenames, raw commands, or manifest content. Required failures return `503` with `state: "not_ready"`. Warnings such as low storage return `200` with `state: "degraded"`. Optional tools such as yt-dlp and whisper.cpp are reported separately and are not required for core readiness.
 
-## Sources
+## Source Videos
 
 | Method   | Path                       | Purpose                                                                     |
 | -------- | -------------------------- | --------------------------------------------------------------------------- |
@@ -27,7 +27,7 @@ http://localhost:4000
 | `GET`    | `/api/videos/:id/source`   | Stream the source video inline.                                             |
 | `GET`    | `/api/videos/:id/download` | Download the original source video.                                         |
 | `PATCH`  | `/api/videos/:id`          | Rename the source display filename. Body: `{ "originalName": "name.mp4" }`. |
-| `DELETE` | `/api/videos/:id`          | Delete a source and its associated managed files.                           |
+| `DELETE` | `/api/videos/:id`          | Delete a source video and its associated managed files.                     |
 
 ## Jobs
 
@@ -56,12 +56,12 @@ Preview endpoints support valid `Range` headers, including suffix ranges used by
 
 ## Captions
 
-| Method | Path                          | Purpose                                                                 |
-| ------ | ----------------------------- | ----------------------------------------------------------------------- |
-| `POST` | `/api/videos/:id/subtitles`   | Create a subtitle-generation job when whisper.cpp is configured.        |
-| `GET`  | `/api/jobs/:id/captions`      | Read generated caption text.                                            |
-| `PUT`  | `/api/jobs/:id/captions`      | Replace generated VTT captions. Body: `{ "vtt": "WEBVTT..." }`.         |
-| `POST` | `/api/jobs/:id/mux-subtitles` | Create a remux job that embeds subtitles into a completed video output. |
+| Method | Path                          | Purpose                                                                |
+| ------ | ----------------------------- | ---------------------------------------------------------------------- |
+| `POST` | `/api/videos/:id/subtitles`   | Create a caption-generation job when whisper.cpp is configured.        |
+| `GET`  | `/api/jobs/:id/captions`      | Read generated caption text.                                           |
+| `PUT`  | `/api/jobs/:id/captions`      | Replace generated VTT captions. Body: `{ "vtt": "WEBVTT..." }`.        |
+| `POST` | `/api/jobs/:id/mux-subtitles` | Create a remux job that embeds captions into a completed video output. |
 
 ## Packages
 
@@ -75,7 +75,7 @@ Package metadata supports optional `title`, `description`, `language`, and `file
 
 | Method | Path                   | Purpose                                       |
 | ------ | ---------------------- | --------------------------------------------- |
-| `GET`  | `/api/history`         | Return the persisted source/job snapshot.     |
+| `GET`  | `/api/history`         | Return the persisted local library snapshot.  |
 | `POST` | `/api/history/delete`  | Bulk-delete selected `videoIds` and `jobIds`. |
 | `GET`  | `/api/storage`         | Return managed storage status.                |
 | `POST` | `/api/storage/cleanup` | Remove stale temporary managed files.         |

diff --git a/docs/architecture.md b/docs/architecture.md
@@ -1,6 +1,6 @@
 # Architecture
 
-Web Video Optimizer is a local-first web app with a React browser client, an Express API, shared runtime contracts, and FFmpeg-backed media workers. The system is designed around small service boundaries so video processing, storage cleanup, package generation, captions, and UI routing can evolve without changing the public API casually.
+Web Video Optimizer is a local-first web app with a React browser client, an Express API, shared runtime contracts, and FFmpeg-backed media workers. The system is designed around small service boundaries so video processing, storage cleanup, website package generation, captions, and UI routing can evolve without changing the public API casually.
 
 ## System Context
 
@@ -29,11 +29,11 @@ sequenceDiagram
   participant S as Storage
   participant F as FFmpeg/FFprobe
 
-  U->>W: Add source
+  U->>W: Add source video
   W->>A: POST /api/videos
   A->>S: Stage and admit upload
   A->>F: Probe metadata
-  A->>S: Persist source and manifest
+  A->>S: Persist source video and manifest
   A-->>W: Video record
   U->>W: Optimize for website
   W->>A: POST /api/videos/:id/pair
@@ -74,7 +74,7 @@ The `video-core` package holds pure logic that is useful on either side of the b
 - job lifecycle and scheduling services
 - process registry and process runner
 - storage boundary, reservations, capacity checks, and housekeeping
-- cleanup, package, caption, video, and job services
+- cleanup, website package, caption, video, and job services
 
 Routes depend on the runtime interface rather than constructing services directly. This keeps tests fast and lets integration tests run against the compiled API without changing route code.
 
@@ -128,11 +128,11 @@ erDiagram
 Managed storage lives under `STORAGE_ROOT`:
 
 - `uploads` stores admitted source videos.
-- `outputs` stores completed job artifacts and packages.
+- `outputs` stores completed job artifacts and website packages.
 - `tmp` stores temporary work files and upload staging.
 - `manifest.json` stores durable history.
 
-The storage boundary resolves files by managed area, blocks traversal, and opens files through descriptors. Cleanup removes canceled jobs, deleted videos, orphan files, stale temporary files, and partial failed outputs. Capacity checks can reserve bytes before paired website jobs so one output is not admitted unless the pair can be scheduled safely.
+The storage boundary resolves files by managed area, blocks traversal, and opens files through descriptors. Cleanup removes canceled jobs, deleted source videos, orphan files, stale temporary files, and partial failed outputs. Capacity checks can reserve bytes before paired website jobs so one output is not admitted unless the pair can be scheduled safely.
 
 ## Persistence And Recovery
 

diff --git a/docs/brand-system.md b/docs/brand-system.md
@@ -370,6 +370,8 @@ Disallowed examples:
 - `AI-powered optimization engine`
 - `Revolutionary media workflow`
 
+The brand document governs product voice and interface tone. [WVO Technical English](writing-style.md) governs procedural and technical documentation. The two standards are complementary: product and brand writing can explain design rationale, while setup, configuration, troubleshooting, API, and support documentation should use controlled terminology and direct procedures.
+
 ## Accessibility And Review
 
 Normal text should meet at least 4.5:1 contrast and large text at least 3:1. Status must not rely on color alone.

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -1,6 +1,33 @@
 # Configuration
 
-The API reads environment variables at startup. Restart the API after changing them. The web app reads `VITE_API_BASE_URL` when the Vite app starts or builds.
+The API reads environment variables at startup. Restart the API after changing an API variable. The web app reads `VITE_API_BASE_URL` when the Vite app starts or builds.
+
+## Change A Configuration Value
+
+### Purpose
+
+Change WVO runtime configuration for a local development session.
+
+### Before You Start
+
+- Stop the API when you change API variables.
+- Stop the Vite web app when you change `VITE_API_BASE_URL`.
+- Record values that contain private local paths outside public issues and pull requests.
+
+### Procedure
+
+1. Set the environment variable in the terminal that will start the process.
+2. Start or restart the affected process.
+3. Open <http://localhost:5173>.
+4. If the change affects API readiness, open <http://localhost:4000/ready>.
+
+### Result
+
+The affected process starts with the new value.
+
+### Recovery
+
+If WVO does not use the new value, confirm that the variable was set in the same terminal that started the process.
 
 ## Core
 
@@ -24,7 +51,9 @@ The API reads environment variables at startup. Restart the API after changing t
 | `TEMP_FILE_MAX_AGE_MS`         | `86400000`                                  | Age threshold for stale temporary cleanup.                                                         |
 | `HOUSEKEEPING_INTERVAL_MS`     | `3600000`                                   | Interval for background storage housekeeping.                                                      |
 
-Managed areas are `uploads`, `outputs`, `tmp`, and `tmp/upload-staging`. Files outside those areas are not served through the API.
+Managed areas are `uploads`, `outputs`, `tmp`, and `tmp/upload-staging`. The API does not serve files outside those areas.
+
+Important: Do not point `STORAGE_ROOT` at a directory that contains unrelated user files. Delete and cleanup actions operate inside managed storage.
 
 ## Media Jobs
 
@@ -48,6 +77,8 @@ Managed areas are `uploads`, `outputs`, `tmp`, and `tmp/upload-staging`. Files o
 
 FFmpeg and FFprobe are invoked from PATH.
 
+Result: If optional tools are not configured, WVO still supports local upload, probing, optimization, comparison, posters, packages, and downloads. YouTube import and caption generation remain unavailable until their variables are configured.
+
 ## Docker Compose
 
 Docker Compose sets: