diff --git a/.gitignore b/.gitignore
index a30ddc4..64c1fdb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -117,3 +117,6 @@ CLAUDE.local.md
 
 # TYPO3 auto-generated public assets
 /public/_assets_install/
+
+# local developer scratch notes
+.dev-notes.md
diff --git a/README.md b/README.md
index 8624cbb..a01a4a0 100644
--- a/README.md
+++ b/README.md
@@ -1,26 +1,170 @@
-## Site Sets
+<div align="center">
 
-// Site Sets
-<f:if condition="{site.settings.vitec.debugMode}">
-    <div class="debug-info">
-        Debug mode is enabled
-        {f:debug(data)}
-    </div>
-</f:if>
+# VITEC Platform
 
-<?php
-$debugMode = $request->getAttribute('site')->getSettings()->get('vitec.debugMode');
+### Headless TYPO3 v14 + React — the VITEC website
 
+TYPO3 runs the editorial backend and serves content as **JSON**; a decoupled
+**React** front end renders it. This repository is the TYPO3 Composer distribution.
 
+<br>
 
-# Custom Frames:
-/usr/home/vitecevo/public_html/live/packages/vitec/Configuration/TCA/Overrides/sys_category.php
+![TYPO3](https://img.shields.io/badge/TYPO3-14.3-FF8700?logo=typo3&logoColor=white)
+![PHP](https://img.shields.io/badge/PHP-8.4-777BB4?logo=php&logoColor=white)
+![Mode](https://img.shields.io/badge/mode-headless_JSON-0A3D62)
+![Frontend](https://img.shields.io/badge/frontend-React_(Vite)-61DAFB?logo=react&logoColor=black)
+![Composer](https://img.shields.io/badge/Composer-distribution-885630?logo=composer&logoColor=white)
+![License](https://img.shields.io/badge/license-GPL--2.0--or--later-blue)
 
+</div>
 
+---
 
-https://www.figma.com/design/0EZHIXmmRoIRk0BljKzhXq/VITEC?node-id=61-220&p=f
+> **Overview**
+> This is a TYPO3 CMS base distribution configured for **headless** operation. Editors
+> work in the TYPO3 backend; every page is exposed as a JSON document (no server‑side
+> HTML). The compiled React application in [`public/_frontend/`](public/_frontend/)
+> consumes that JSON. All custom domain logic — content elements, plugins, layout
+> containers and the JSON renderers — lives in the **[`evomedien/vitec`](packages/vitec/)**
+> extension.
 
+## Table of contents
 
+- [How it fits together](#how-it-fits-together)
+- [Tech stack](#tech-stack)
+- [Repository layout](#repository-layout)
+- [Requirements](#requirements)
+- [Getting started](#getting-started)
+- [Configuration](#configuration)
+- [Everyday commands](#everyday-commands)
+- [Deployment notes](#deployment-notes)
+- [Documentation](#documentation)
+- [License](#license)
 
-vitecdev
-17ZJfy75sJoU68J6
\ No newline at end of file
+## How it fits together
+
+```
+┌────────────┐     edits      ┌─────────────────────┐   JSON per page   ┌────────────────┐
+│  Editors   │ ─────────────▶ │  TYPO3 v14 backend  │ ────────────────▶ │  React (Vite)  │
+│  (backend) │                │  headless: 1        │   /page → { … }   │  public/_front │
+└────────────┘                └─────────────────────┘                   └────────────────┘
+                                        │
+                                        ▼
+                              evomedien/vitec extension
+                        (content elements · plugins · JSON-LD)
+```
+
+The heavy lifting — the JSON envelope, per‑plugin renderers, layout containers and
+schema.org structured data — is documented in the extension’s architecture spec:
+**[`packages/vitec/Documentation/Headless-JSON-Architecture.md`](packages/vitec/Documentation/Headless-JSON-Architecture.md)**.
+
+## Tech stack
+
+| Layer | Technology |
+|---|---|
+| CMS / backend | TYPO3 CMS `^14.3` (headless) |
+| Language / runtime | PHP `8.4` |
+| Dependency management | Composer (base distribution) |
+| Headless rendering | `friendsoftypo3/headless`, `nb-headless-content-blocks` |
+| Content modelling | `friendsoftypo3/content-blocks`, `b13/container` |
+| News | `georgringer/news` |
+| Custom logic | `evomedien/vitec` (see [`packages/vitec/`](packages/vitec/)) |
+| Front end | React, built with Vite → `public/_frontend/` |
+
+## Repository layout
+
+```
+live/
+├── config/
+│   ├── sites/vitec/config.yaml     # site config (headless: 1, Sets, routing)
+│   └── system/settings.php         # TYPO3 system config (git-ignored — secrets)
+├── packages/
+│   └── vitec/                      # the custom extension (see its own README)
+├── public/
+│   ├── index.php                   # TYPO3 front controller
+│   ├── _frontend/                  # compiled React app (Vite build)
+│   ├── _assets/                    # published extension assets
+│   ├── fileadmin/  typo3/  …
+├── var/                            # caches, logs (git-ignored)
+├── vendor/                         # Composer dependencies (git-ignored)
+├── Documentation/                  # project-level docs
+├── composer.json / composer.lock
+├── auth.json                       # Composer auth for private repos (git-ignored)
+└── fix-asset-perms.sh              # deploy helper — fixes asset file permissions
+```
+
+## Requirements
+
+- **PHP 8.4**
+- **Composer 2**
+- **MySQL / MariaDB** (database)
+- **Node.js** (only to build the front end)
+- Access to the private `t3planet` Composer repository (via `auth.json`)
+
+## Getting started
+
+```bash
+# 1. Install PHP dependencies (requires a valid auth.json for the private repo)
+composer install
+
+# 2. Configure the system (database, encryption key, …)
+#    config/system/settings.php is git-ignored; create it via the Install Tool
+#    or copy it from a secure source.
+
+# 3. Apply the database schema
+vendor/bin/typo3 database:updateschema "*.add,*.change"
+
+# 4. Warm up
+vendor/bin/typo3 cache:flush
+```
+
+The document root is **`public/`**. Point the web server there; `public/index.php` is
+the TYPO3 entry point.
+
+## Configuration
+
+- **Headless mode & routing** — `config/sites/vitec/config.yaml`:
+  ```yaml
+  base: /
+  headless: 1
+  dependencies:
+    - friendsoftypo3/headless
+    - friendsoftypo3/headless-mixed
+    - nb-headless-content-blocks/headless-content-blocks
+    - georgringer/news
+  ```
+- **System settings & secrets** — `config/system/settings.php` and `auth.json` are
+  **git-ignored**. Never commit database credentials or Composer tokens.
+
+## Everyday commands
+
+```bash
+vendor/bin/typo3 cache:flush                              # clear all caches
+vendor/bin/typo3 database:updateschema "*.add,*.change"   # apply schema changes
+bash fix-asset-perms.sh                                   # fix asset permissions (see below)
+```
+
+## Deployment notes
+
+- **Document root:** `public/`.
+- **Asset permissions:** when files are deployed over an SSHFS/Windows mount they can
+  land with a too‑restrictive mode (no “other” read), which makes the web server return
+  **403** for backend icons/CSS/JS. Run [`fix-asset-perms.sh`](fix-asset-perms.sh) on the
+  server after deploying assets (it sets files to `644` / directories to `755` under
+  `public/_assets` and the extension’s `Resources/Public`, then flushes caches).
+- **Never commit** `config/system/settings.php` or `auth.json` (already git-ignored).
+
+## Documentation
+
+| Document | Purpose |
+|---|---|
+| [`packages/vitec/README.md`](packages/vitec/README.md) | The custom extension — features & content elements |
+| [`packages/vitec/Documentation/Headless-JSON-Architecture.md`](packages/vitec/Documentation/Headless-JSON-Architecture.md) | Authoritative headless architecture & JSON interface spec |
+| [`Documentation/CustomFrameClasses.md`](Documentation/CustomFrameClasses.md) | Custom frame classes |
+| [`VITEC-ContentBlocks-Setup.md`](VITEC-ContentBlocks-Setup.md) | Content Blocks setup notes |
+
+## License
+
+[GPL‑2.0‑or‑later](LICENSE) — © evomedien.
+
+<div align="center"><sub>VITEC · TYPO3 headless backend + React front end</sub></div>