diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..f20aab1
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,20 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Added
+- Initialized `CHANGELOG.md` with Keep a Changelog structure for ongoing release-note tracking.
+
+### Changed
+- Refreshed `README.md` with current stack details, runtime services, setup commands, configuration notes, and manual validation guidance.
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
diff --git a/README.md b/README.md
index a9bab21..93ab711 100644
--- a/README.md
+++ b/README.md
@@ -1,121 +1,154 @@
 # DMS
 
-DMS is a single-user document management system for ingesting, processing, organizing, and searching files.
+DMS is a self-hosted document management system for ingesting, processing, organizing, and searching files.
 
-Core capabilities:
-- drag-and-drop upload from anywhere in the UI
-- file and folder upload with path preservation
-- asynchronous processing with OCR and extraction for PDF, images, DOCX, XLSX, TXT, and ZIP
-- metadata and full-text search
-- routing suggestions based on learned decisions
-- original file download and extracted markdown export
+## Core Capabilities
 
-## Stack
+- Drag and drop upload from anywhere in the UI
+- File and folder upload with path preservation
+- Asynchronous extraction and OCR for PDF, images, DOCX, XLSX, TXT, and ZIP
+- Metadata and full-text search
+- Routing suggestions based on previous decisions
+- Original file download and extracted markdown export
 
-- Backend: FastAPI + SQLAlchemy + RQ worker (`backend/`)
-- Frontend: React + Vite + TypeScript (`frontend/`)
-- Infrastructure: Postgres, Redis, Typesense (`docker-compose.yml`)
+## Technology Stack
+
+- Backend: FastAPI, SQLAlchemy, RQ worker (`backend/`)
+- Frontend: React, Vite, TypeScript (`frontend/`)
+- Infrastructure: PostgreSQL, Redis, Typesense (`docker-compose.yml`)
+
+## Runtime Services
+
+The default `docker compose` stack includes:
+
+- `frontend` - React UI (`http://localhost:5173`)
+- `api` - FastAPI backend (`http://localhost:8000`, docs at `/docs`)
+- `worker` - background processing jobs
+- `db` - PostgreSQL (`localhost:5432`)
+- `redis` - queue backend (`localhost:6379`)
+- `typesense` - search index (`localhost:8108`)
 
 ## Requirements
 
 - Docker Engine
 - Docker Compose plugin
-- Internet access for the first image build
+- Internet access for first-time image build
 
 ## Quick Start
 
-1. Start the full stack from repository root:
+From repository root:
 
 ```bash
 docker compose up --build -d
 ```
 
-2. Open services:
+Open:
+
 - Frontend: `http://localhost:5173`
-- Backend OpenAPI docs: `http://localhost:8000/docs`
-- Health endpoint: `http://localhost:8000/api/v1/health`
+- API docs: `http://localhost:8000/docs`
+- Health: `http://localhost:8000/api/v1/health`
 
-3. Stop when done:
+Stop the stack:
 
 ```bash
 docker compose down
 ```
 
-## Common Commands
+## Common Operations
 
-Start services:
+Start or rebuild:
 
 ```bash
 docker compose up --build -d
 ```
 
-Stop services:
+Stop:
 
 ```bash
 docker compose down
 ```
 
-Stream logs:
+Tail logs:
 
 ```bash
 docker compose logs -f
 ```
 
-Rebuild services:
+Tail API and worker logs only:
 
 ```bash
-docker compose down
-docker compose up --build -d
+docker compose logs -f api worker
 ```
 
-Reset runtime data (destructive, removes named volumes):
+Reset all runtime data (destructive):
 
 ```bash
 docker compose down -v
 ```
 
+## Frontend-Only Local Workflow
+
+If backend services are already running, you can run frontend tooling locally:
+
+```bash
+cd frontend && npm run dev
+cd frontend && npm run build
+cd frontend && npm run preview
+```
+
+`npm run preview` serves the built app on port `4173`.
+
+## Configuration
+
+Main runtime variables are defined in `docker-compose.yml`:
+
+- API and worker: `DATABASE_URL`, `REDIS_URL`, `STORAGE_ROOT`, `PUBLIC_BASE_URL`, `CORS_ORIGINS`, `TYPESENSE_*`
+- Frontend: `VITE_API_BASE`
+
+Application settings saved from the UI persist at:
+
+- `<STORAGE_ROOT>/settings.json` (inside the storage volume)
+
+Settings endpoints:
+
+- `GET/PUT /api/v1/settings`
+- `POST /api/v1/settings/reset`
+- `POST /api/v1/settings/handwriting`
+- `POST /api/v1/processing/logs/trim`
+
+Note: the compose file currently includes host-specific URL values (for example `PUBLIC_BASE_URL` and `VITE_API_BASE`). Adjust these for your environment when needed.
+
 ## Data Persistence
 
-Runtime state is persisted in Docker named volumes declared in `docker-compose.yml`:
+Docker named volumes used by the stack:
+
 - `db-data`
 - `redis-data`
 - `dcm-storage`
 - `typesense-data`
 
-The application settings file is stored under the storage volume at `/data/storage/settings.json` inside containers.
+## Validation Checklist
 
-## Configuration Notes
+After setup or config changes, verify:
 
-- API and worker runtime environment values are configured in `docker-compose.yml` (`DATABASE_URL`, `REDIS_URL`, `STORAGE_ROOT`, `PUBLIC_BASE_URL`, `CORS_ORIGINS`, `TYPESENSE_*`).
-- Frontend API target is controlled by `VITE_API_BASE` in the `frontend` service.
-- Handwriting, provider, routing, summary, display, and upload defaults are managed through the settings UI and persisted by the backend settings service.
-
-## Manual Validation Checklist
-
-After changes, verify:
 - `GET /api/v1/health` returns `{"status":"ok"}`
-- upload and processing complete successfully
-- search returns expected results
-- preview or download works for uploaded documents
-- `docker compose logs -f` shows no API or worker failures
+- Upload and processing complete successfully
+- Search returns expected results
+- Preview and download work for uploaded documents
+- `docker compose logs -f api worker` has no failures
 
-## API Surface Summary
+## Repository Layout
 
-Base prefix: `/api/v1`
+- `backend/` - FastAPI API, services, models, worker
+- `frontend/` - React application
+- `doc/` - technical documentation for architecture, API, data model, and operations
+- `docker-compose.yml` - local runtime topology
 
-- Health: `/health`
-- Documents: `/documents` (listing, upload, metadata update, lifecycle actions, download and preview, markdown export)
-- Search: `/search`
-- Processing logs: `/processing/logs`
-- Settings: `/settings` and `/settings/handwriting`
+## Documentation Index
 
-See `doc/api-contract.md` for the complete endpoint contract.
-
-## Technical Documentation
-
-- `doc/README.md` - technical documentation index
+- `doc/README.md` - technical documentation entrypoint
 - `doc/architecture-overview.md` - service and runtime architecture
-- `doc/api-contract.md` - HTTP endpoint contract and payload model map
-- `doc/data-model-reference.md` - database model reference
-- `doc/operations-and-configuration.md` - operations runbook and configuration reference
-- `doc/frontend-design-foundation.md` - frontend design system and UI rules
+- `doc/api-contract.md` - endpoint and payload contract
+- `doc/data-model-reference.md` - persistence model reference
+- `doc/operations-and-configuration.md` - runtime operations and configuration
+- `doc/frontend-design-foundation.md` - frontend design rules