diff --git a/README.md b/README.md
index 4292b5a..19ad1e2 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Sumeru
 
-**Modular open-source ERP — Go backend, PostgreSQL, and a modern web workspace.**
+**Modular open-source ERP/CRM platform** - Go backend, PostgreSQL, installable apps, and a TypeScript workspace client for enterprise operations.
 
 [![CI](https://github.com/ProjectMeru/sumeru/actions/workflows/ci.yml/badge.svg)](https://github.com/ProjectMeru/sumeru/actions/workflows/ci.yml)
 [![Go](https://img.shields.io/badge/Go-1.26.6+-00ADD8?logo=go&logoColor=white)](https://go.dev/dl/)
@@ -8,199 +8,186 @@
 [![Pre-Alpha](https://img.shields.io/badge/Status-Pre--Alpha-critical)](https://github.com/ProjectMeru/sumeru)
 [![Docs](https://img.shields.io/badge/Docs-projectmeru.github.io-informational)](https://projectmeru.github.io/sumeru/docs/)
 
-![Sumeru settings](core/engine/assets/img/screenshots/hero_img.png)
-![Sumeru apps hub](core/engine/assets/img/screenshots/apps_imgs.png)
+## Table of contents
 
-_Settings hub — configure companies, users, localization, and open installed apps._
+- [Sumeru](#sumeru)
+  - [Table of contents](#table-of-contents)
+  - [Overview](#overview)
+  - [Features](#features)
+  - [Preview](#preview)
+  - [Architecture](#architecture)
+  - [Repository ecosystem](#repository-ecosystem)
+  - [Getting started](#getting-started)
+    - [Prerequisites](#prerequisites)
+    - [Recommended — custom workspace](#recommended--custom-workspace)
+    - [Alternative — core only](#alternative--core-only)
+    - [First run](#first-run)
+  - [Configuration](#configuration)
+  - [Development](#development)
+  - [Documentation](#documentation)
+  - [Community](#community)
+
+## Overview
+
+Sumeru is a **modular ERP and CRM engine** for teams that want a single deployable stack: **PostgreSQL** for data, **XML views** for screens and menus, **Go models** for business logic, and a **SWC** web workspace for list, form, kanban, and analysis work. Install **apps** (addons) from disk; extend behavior through manifests and the **`sumeru/core/sdk`** surface instead of forking core.
+
+This repository (`module sumeru`) is the **kernel**: ORM, HTTP/RPC, rendering shell, and base apps (`base`, `mail`, …). Standard CRM/ERP apps ship in **[sumeru_addons](https://github.com/ProjectMeru/sumeru_addons)**. Most integrators run the server from **[sumeru_custom_addons](https://github.com/ProjectMeru/sumeru_custom_addons)** (paths, config, generated imports).
 
 > [!CAUTION]
 >
-> **Pre-alpha software** — not for production or commercial use.
+> **Pre-alpha software** — not for production or regulated workloads.
 >
-> - Do not deploy live business workloads; stability and data integrity are not guaranteed.
-> - APIs, data models, and behavior may change without notice.
+> - APIs, schemas, and UX may change without notice.
 > - Use for local development, evaluation, and feedback only.
 
-Sumeru is a modular ERP platform built in **Go**. Install **apps** (addons) for CRM, sales, inventory, and more; persist data in **PostgreSQL**; define screens with XML **views**; and run day-to-day work in a **SWC** workspace client with a shared control bar for search, filters, and saved searches across list, form, kanban, graph, pivot, calendar, gantt, map, and cohort views.
-
-This repository is the **core engine** (`module sumeru`). Most teams keep it pull-only and run the server from **[sumeru_custom_addons](https://github.com/ProjectMeru/sumeru_custom_addons)**.
-
-## Key features
+## Features
 
-- **Modular apps** — manifests, XML views/menus, Go models, install and update from disk
-- **PostgreSQL ORM** — model sync on startup, record rules, multi-company support
-- **Collection control bar** — search, filters, multi group-by, custom domain rules, and saved-search favorites on collection and analysis views
-- **Workspace views** — list, form, kanban, graph, pivot, calendar, gantt, map, and cohort
-- **Saved searches** — persist filter/search/group state per user (`swc.saved.search` + favorites API)
-- **SWC client** — TypeScript sources in `core/swc/`; bundles built locally (not committed to git)
-- **JSON-RPC API** — `POST /api/rpc` for integrations (session or API key)
-- **Stable addon SDK** — prefer **`sumeru/core/sdk`** over direct **`sumeru/core/orm`** imports
-- **Plain CSS shell** — design tokens and `sum-*` layout under `core/engine/assets/css/`
+| Area               | Capabilities                                                                       |
+| ------------------ | ---------------------------------------------------------------------------------- |
+| **Apps & modules** | Manifests, dependency order, install/update from `addons_path`; XML data and views |
+| **Data layer**     | PostgreSQL ORM, model sync on startup, record rules, multi-company                 |
+| **Workspace**      | List, form, kanban, graph, pivot, calendar, gantt, map, cohort                     |
+| **Collection UX**  | Search, filters, group-by, custom domains, saved-search favorites                  |
+| **Integrations**   | `POST /api/rpc` (session or API key); mail/chatter; export/import hooks            |
+| **Client**         | TypeScript SWC in `core/swc/`; server-rendered shell + SPA workspace               |
+| **Extensibility**  | Prefer **`sumeru/core/sdk`** for addons; `sum-*` design tokens in CSS              |
 
-## Quick start
+## Preview
 
-**Prerequisites:** [Go 1.26.6+](https://go.dev/dl/), [Node.js](https://nodejs.org/) (npm — builds the SWC UI), [PostgreSQL](https://www.postgresql.org/)
+User flow: **sign in → apps catalog → settings and workspace**.
 
-Clone the three sibling repositories, configure the workspace, and run:
+**Sign-in** — enterprise login shell with optional company logo and tagline on the left panel.
 
-```bash
-mkdir -p ~/sumeru_erp && cd ~/sumeru_erp
-git clone git@github.com:ProjectMeru/sumeru.git
-git clone git@github.com:ProjectMeru/sumeru_addons.git
-git clone git@github.com:ProjectMeru/sumeru_custom_addons.git
+![Enterprise login with branding panel](core/engine/assets/img/screenshots/login_screen.png)
 
-# Create a PostgreSQL database matching db_name in your INI, e.g.:
-#   psql -c "CREATE DATABASE sumeru;"
+**Apps** — browse, install, and open CRM/ERP modules from the catalog.
 
-cd sumeru_custom_addons
-cp sumeru.conf.example sumeru.conf   # edit db_*, http_port, addons_path
-make setup    # go.mod, imports, SWC + login JS bundles
-make run      # regenerate imports; rebuild assets when missing or stale
-```
+![Installed and available apps](core/engine/assets/img/screenshots/apps_imgs.png)
 
-Open **`http://localhost:8080`** (or your `http_port`). `/` redirects to **`/web/apps`**.
+**Settings & workspace** — configure the organization and work in list, form, and analysis views.
 
-**Day-to-day updates:**
+![Settings hub and workspace chrome](core/engine/assets/img/screenshots/hero_img.png)
 
-```bash
-cd ../sumeru && git pull
-cd ../sumeru_addons && git pull
-cd ../sumeru_custom_addons && make run
-```
+## Architecture
 
-After pulling SWC changes in `sumeru`, `make run` rebuilds client bundles automatically when TypeScript sources are newer than the on-disk JS.
+Sumeru runs as a **Go monolith**: HTTP handlers and JSON-RPC call into the ORM; addons register models and actions; the SWC client loads inside an HTML shell from `core/engine/render`.
 
-Full workspace details: **[sumeru_custom_addons README](https://github.com/ProjectMeru/sumeru_custom_addons/blob/main/README.md)**.
+| Layer                | Location                                        |
+| -------------------- | ----------------------------------------------- |
+| UI shell & routes    | `core/server/web`, `core/engine/render`         |
+| Workspace client     | `core/swc`                                      |
+| Business logic & RPC | `core/server/api`, `core/orm`, `core/sdk`       |
+| Modules              | `core/module`, `addons/`, external addon repos  |
+| Security             | Access CSV/XML, record rules, groups, field ACL |
 
-### Core-only (optional)
+Full layer diagram and request flow: **[docs/architecture-layers.md](docs/architecture-layers.md)**.
 
-When you only need kernel apps under `sumeru/addons/`:
+## Repository ecosystem
 
-```bash
-cd sumeru
-cp sumeru.conf.example sumeru.conf
-make setup && make run
-```
+| Repository                                                                      | Role                                                    |
+| ------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| **[sumeru](https://github.com/ProjectMeru/sumeru)**                             | Core engine + kernel apps                               |
+| **[sumeru_addons](https://github.com/ProjectMeru/sumeru_addons)**               | Standard CRM/ERP apps                                   |
+| **[sumeru_custom_addons](https://github.com/ProjectMeru/sumeru_custom_addons)** | Workspace: `sumeru.conf`, generated imports, `make run` |
 
-Install sample data, then serve: `go run ./cmd/sumeru -- -c sumeru.conf -i company,user --stop-after-init` then `make run`.
+## Getting started
 
-## Development workflow
+### Prerequisites
 
-Most development happens in **`sumeru_custom_addons`**. The core repo uses the same Makefile targets when working on kernel addons or SWC directly.
+- [Go 1.26.6+](https://go.dev/dl/)
+- [Node.js](https://nodejs.org/) (npm — builds SWC bundles; not committed to git)
+- [PostgreSQL](https://www.postgresql.org/)
+- Git
+- Optional: Docker for `make test-integration`
 
-### Custom workspace (`sumeru_custom_addons`)
+### Recommended — custom workspace
 
-| Step                | Command                                                   | What it does                                                   |
-| ------------------- | --------------------------------------------------------- | -------------------------------------------------------------- |
-| First time          | `make setup`                                              | Config, go.mod replaces, import generation, SWC + login JS     |
-| Daily dev           | `make run` or `make dev`                                  | Regenerate imports, rebuild assets if stale, start HTTP server |
-| After SWC/CSS edits | `make swc`                                                | Force rebuild workspace bundle + login JS                      |
-| Pull upstream       | `git pull` in `sumeru` / `sumeru_addons`, then `make run` | Rebuilds assets when sources changed                           |
-| Tests               | `make check`                                              | SWC typecheck + Go tests                                       |
-| Binary              | `make build`                                              | Imports + assets + `bin/sumeru-erp`                            |
+Clone the three sibling repositories, create a database matching `db_name`, then run from the workspace repo:
 
-### Core repo (`sumeru`)
+```bash
+mkdir -p ~/sumeru_erp && cd ~/sumeru_erp
+git clone git@github.com:ProjectMeru/sumeru.git
+git clone git@github.com:ProjectMeru/sumeru_addons.git
+git clone git@github.com:ProjectMeru/sumeru_custom_addons.git
 
-| Step                 | Command       | What it does                                        |
-| -------------------- | ------------- | --------------------------------------------------- |
-| First time           | `make setup`  | `sumeru.conf`, SWC assets, `cmd/sumeru/zimports.go` |
-| Daily dev            | `make run`    | `generate` + `assets` + `go run`                    |
-| Force client rebuild | `make swc`    | Always rebuild SWC + login JS                       |
-| Incremental assets   | `make assets` | Build only when bundles missing or sources changed  |
-| Tests                | `make check`  | `swc-check` + `go test ./...`                       |
-| Binary               | `make build`  | `generate` + `assets` + `./sumeru` binary           |
+# psql -c "CREATE DATABASE sumeru;"
 
-```text
-make run  →  generate (Go imports)  →  assets (SWC + login JS)  →  go run server
+cd sumeru_custom_addons
+cp sumeru.conf.example sumeru.conf   # edit db_*, http_port, addons_path
+make setup && make run
 ```
 
-## Client assets
+Open **`http://localhost:8080`** (or your `http_port`). Details: [sumeru_custom_addons README](https://github.com/ProjectMeru/sumeru_custom_addons/blob/main/README.md).
 
-The browser UI is **not stored in git**. Sources live under **`core/swc/src/`** (TypeScript); build outputs are gitignored (see `.gitignore`).
+### Alternative — core only
 
-| Output                                            | Purpose                             |
-| ------------------------------------------------- | ----------------------------------- |
-| `core/engine/assets/swc/swc.js`                   | Workspace UI (`/static/swc/swc.js`) |
-| `core/engine/assets/js/sumeru-password-toggle.js` | Login / setup password visibility   |
-| `core/engine/assets/js/sumeru-password-match.js`  | Setup password confirmation         |
+Kernel apps under `sumeru/addons/`:
 
-Build with **`make swc`** (always rebuild) or let **`make assets`** / **`make run`** build when bundles are missing or SWC sources changed. A fresh clone needs **Node.js** — run **`make setup`** or **`make run`** once before opening the app.
-
-## Architecture
-
-Sumeru splits across three repositories so you can pull engine and standard apps without mixing customer code.
+```bash
+cd sumeru
+cp sumeru.conf.example sumeru.conf   # addons_path = addons
+make setup && make run
+```
 
-In-repo reference: **[docs/architecture-layers.md](docs/architecture-layers.md)** — six-layer stack, request traces, and inheritance catalog (view inherit, model inherit, depends, events).
+Optional sample data:
 
-```text
-sumeru_custom_addons
-  make setup / make run
-    → generate (addonimports/zimports.go)
-    → assets (SWC + login JS → sumeru/core/engine/assets/)
-    → go run HTTP server
-  loads sumeru (core) + sumeru_addons via addons_path in sumeru.conf
+```bash
+go run ./cmd/sumeru -- -c sumeru.conf -i company,user --stop-after-init
+make run
 ```
 
-| Repository                                                                      | Role                                                              |
-| ------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
-| **[sumeru](https://github.com/ProjectMeru/sumeru)**                             | Core engine + kernel apps (`base`, `mail`, …)                     |
-| **[sumeru_addons](https://github.com/ProjectMeru/sumeru_addons)**               | Standard business apps (CRM, Sales, Inventory, …)                 |
-| **[sumeru_custom_addons](https://github.com/ProjectMeru/sumeru_custom_addons)** | Your workspace: custom addons, INI, generated imports, `make run` |
-
-**Entry binary:** `cmd/sumeru/main.go` → `sumeru/core/server`. Library code under `core/` has no `main`.
+### First run
 
-## Tech stack
+| Step        | Behavior                                                                                       |
+| ----------- | ---------------------------------------------------------------------------------------------- |
+| Empty DB    | Browser **`/setup`** wizard (company + admin); see `setup_*` keys in **`sumeru.conf.example`** |
+| After setup | **`/web/login`**; set **`dev_mode = true`** for local UI iteration                             |
+| Signed in   | `/` → **`/web/apps`**                                                                          |
 
-| Layer        | Technology                                               |
-| ------------ | -------------------------------------------------------- |
-| Server       | Go 1.26.6+, structured logging (`log/slog`)              |
-| Database     | PostgreSQL                                               |
-| Modules      | Go addons + XML views/menus + manifest sync              |
-| Workspace UI | SWC (TypeScript) — sources in `core/swc/`                |
-| Client build | Node.js + npm (esbuild); `make assets` / `make swc`      |
-| Styling      | Plain CSS (`core/engine/assets/css/`)                    |
-| API          | JSON-RPC at `POST /api/rpc`, health at `GET /api/health` |
+## Configuration
 
-CLI flags: `-c` config, `-d` database, `-p` port, `-i` install modules, `-u` update modules. See [Tooling docs](https://projectmeru.github.io/sumeru/docs/guides/build/tooling.html).
+Copy **`sumeru.conf.example`** → **`sumeru.conf`** next to `go.mod` (or in `sumeru_custom_addons` for the workspace flow).
 
-## Documentation
+| Setting                      | Required | Notes                             |
+| ---------------------------- | -------- | --------------------------------- |
+| `db_*`, `db_sslmode`         | Yes      | PostgreSQL connection             |
+| `http_port`                  | Yes      | Default `8080`                    |
+| `addons_path`                | Yes      | Comma-separated addon directories |
+| `dev_mode`                   | No       | `true` for local development      |
+| `log_enabled` / `log_stdout` | No       | See example for file logging      |
 
-| Resource                                                                                               | Contents                         |
-| ------------------------------------------------------------------------------------------------------ | -------------------------------- |
-| [Documentation home](https://projectmeru.github.io/sumeru/docs/)                                       | Guides, reference, and tutorials |
-| [Installation](https://projectmeru.github.io/sumeru/docs/guides/start/installation.html)               | First-time setup                 |
-| [Configuration](https://projectmeru.github.io/sumeru/docs/guides/start/configuration.html)             | `sumeru.conf` keys and paths     |
-| [JSON-RPC API](https://projectmeru.github.io/sumeru/docs/reference/json-rpc.html)                      | RPC methods, auth, errors        |
-| [SWC architecture](https://projectmeru.github.io/sumeru/docs/guides/concepts/swc-architecture.html)    | Workspace client                 |
-| [Creating an addon](https://projectmeru.github.io/sumeru/docs/guides/build/creating-an-addon.html)     | Module authoring                 |
-| [Tooling](https://projectmeru.github.io/sumeru/docs/guides/build/tooling.html)                         | Makefile, import-gen, CLI        |
-| [sumeru_addons README](https://github.com/ProjectMeru/sumeru_addons/blob/main/README.md)               | Standard business apps           |
-| [sumeru_custom_addons README](https://github.com/ProjectMeru/sumeru_custom_addons/blob/main/README.md) | Workspace runner                 |
+Reference: [configuration guide](https://projectmeru.github.io/sumeru/docs/guides/start/configuration.html).
 
-Configuration template: **`sumeru.conf.example`** in this repo.
+## Development
 
-## Project layout
+Run **`make`** from **`sumeru/`** (or workspace Makefile in **`sumeru_custom_addons/`**) before opening a PR.
 
-| Path           | Purpose                                  |
-| -------------- | ---------------------------------------- |
-| `core/orm/`    | PostgreSQL models, CRUD, registry        |
-| `core/engine/` | View XML, HTML render, templates, assets |
-| `core/server/` | INI config, HTTP handlers                |
-| `core/module/` | Addon discovery, install/update          |
-| `core/sdk/`    | Stable Go API for addons                 |
-| `core/swc/`    | Workspace UI source (TypeScript)         |
-| `cmd/sumeru/`  | Server binary + generated imports        |
-| `addons/`      | Kernel apps shipped with core            |
-| `test/`        | Unit and integration tests               |
+| Command                 | Purpose                                         |
+| ----------------------- | ----------------------------------------------- |
+| `make setup`            | `sumeru.conf` scaffold; `generate` + SWC assets |
+| `make run` / `make dev` | `go run ./cmd/sumeru -c sumeru.conf`            |
+| `make swc`              | Rebuild workspace + login JS bundles            |
+| `make` / `make check`   | Lint, tests, `go build ./...` (CI parity)       |
+| `make build`            | Production binary `./sumeru`                    |
+| `make help`             | Modules, integration tests, i18n, shell REPL    |
 
-## Contributing
+Extra CLI flags: **`EXTRA_RUN_FLAGS`** (e.g. `make run EXTRA_RUN_FLAGS='-p 9090'`). See [tooling docs](https://projectmeru.github.io/sumeru/docs/guides/build/tooling.html).
 
-See **[CONTRIBUTING.md](CONTRIBUTING.md)** for where to put changes, the generate/test loop, and PR expectations. Please follow the **[Code of Conduct](CODE_OF_CONDUCT.md)**.
+SWC sources live in `core/swc/src/`; bundles land in `core/engine/assets/` when you run `make setup` or `make run`.
 
-## Security
+## Documentation
 
-Report vulnerabilities privately — see **[SECURITY.md](SECURITY.md)**. Do not open public issues for undisclosed security problems.
+| Resource      | Link                                                                                                    |
+| ------------- | ------------------------------------------------------------------------------------------------------- |
+| Site          | [projectmeru.github.io/sumeru/docs/](https://projectmeru.github.io/sumeru/docs/)                        |
+| Architecture  | [docs/architecture-layers.md](docs/architecture-layers.md)                                              |
+| Configuration | [guides/start/configuration](https://projectmeru.github.io/sumeru/docs/guides/start/configuration.html) |
+| Tooling & CLI | [guides/build/tooling](https://projectmeru.github.io/sumeru/docs/guides/build/tooling.html)             |
 
-## License
+## Community
 
-Licensed under the [Apache License, Version 2.0](LICENSE).
+|                  |                                                                             |
+| ---------------- | --------------------------------------------------------------------------- |
+| **Contributing** | [CONTRIBUTING.md](CONTRIBUTING.md) — layout, generate loop, PR expectations |
+| **Security**     | [SECURITY.md](SECURITY.md) — responsible disclosure                         |
+| **License**      | [Apache 2.0](LICENSE)                                                       |
diff --git a/core/engine/assets/img/screenshots/login_screen.png b/core/engine/assets/img/screenshots/login_screen.png
new file mode 100644
index 0000000..1c4e628
Binary files /dev/null and b/core/engine/assets/img/screenshots/login_screen.png differ