diff --git a/.cursor/rules/gitflow.md b/.cursor/rules/gitflow.md
deleted file mode 100644
index 28f9a773..00000000
--- a/.cursor/rules/gitflow.md
+++ /dev/null
@@ -1,167 +0,0 @@
----
-description: Querya Desktop GitFlow, branching, commits, and PR workflow
-alwaysApply: true
----
-
-# Querya Desktop — agent workflow
-
-Desktop SQL/NoSQL client (PostgreSQL, MySQL, Redis, MongoDB).  
-Стек: **Flutter** (Dart 3.5+), **shadcn_flutter** (vendored в `third_party/`), локальный SQLite + OS secure storage для секретов.
-
-Remote: `git@github.com:QueryaHub/Querya-Desktop.git`
-
-## Sync with remote (always)
-
-Before checkout, branch, push, or PR — and **after** merge to `dev`:
-
-```bash
-git fetch --all --prune
-git checkout dev
-git pull --ff-only origin dev
-```
-
-Before push on a feature branch: `git fetch origin`, then rebase or merge remote.
-
-**Full checks** before PR (локально, как в CI):
-
-```bash
-flutter pub get
-flutter analyze
-flutter test
-```
-
-Опционально перед релизом / крупным UI-PR:
-
-```bash
-flutter build linux --release   # или windows / macos
-```
-
-На Linux при `errno = 24` на analyze: `ulimit -n 8192` (см. [CONTRIBUTING.md](CONTRIBUTING.md)).
-
-## Git branches
-
-- **`main`**: production-ready; релизные теги (`X.Y.Z`) ставятся на коммиты, готовые к бинарникам.
-- **`dev`**: интеграция; **все feature PR → `dev`**.
-- **Feature**: `issue/<number>-<short-slug>` или `feat/<short-slug>` от актуального `dev`.
-
-```bash
-git fetch --all --prune && git checkout dev && git pull --ff-only origin dev
-git checkout -b issue/38-querya-workbench-theme-models
-# или: git checkout -b feat/postgres-sql-workspace-toolbar
-```
-
-Долгоживущие ветки по подсистемам (если согласовано с командой): `postgres-ench`, `mongo-ench`, `my_sql`, `design` — не создавать без необходимости; предпочитать короткие `issue/*` / `feat/*`.
-
-**Hotfix** только по явному запросу: `hotfix/<short-slug>` от `main` → PR в `main`, затем back-merge в `dev`.
-
-**Release**: версия в `pubspec.yaml`, тег на нужном коммите, workflow Release — см. [docs/tags-and-releases.md](docs/tags-and-releases.md), [docs/release-checklist.md](docs/release-checklist.md).
-
-## Issue priority & roadmap
-
-Живой roadmap: [docs/roadmap.md](docs/roadmap.md). Крупные темы (пример — epic **#37** theming): дочерние issues #38–#60.
-
-| Область | Фокус |
-|---------|--------|
-| Connections | Tree, new connection, drivers, secure storage |
-| PostgreSQL / MySQL | Browser, SQL workspace, grids, timeouts |
-| Redis / MongoDB | Explorer, keys/collections, document editor |
-| Theme / UI | `lib/core/theme/`, shadcn tokens, SQL editor (#37 epic) |
-| CI / release | `.github/workflows/`, Linux deps, signing (macOS) |
-
-Один issue → одна ветка → один PR. Scope = issue only — без drive-by рефакторинга.
-
-## GitHub labels & milestones
-
-### Milestone: **Theme system**
-
-Epic [#37](https://github.com/QueryaHub/Querya-Desktop/issues/37) и дочерние issues **#38–#60** (кроме закрытого #56) — milestone [Theme system](https://github.com/QueryaHub/Querya-Desktop/milestone/1).
-
-Новые theme-issues: label `theme` → workflow [issue-theme-milestone.yml](.github/workflows/issue-theme-milestone.yml) проставит milestone автоматически. Шаблон: [.github/ISSUE_TEMPLATE/theme_task.yml](.github/ISSUE_TEMPLATE/theme_task.yml).
-
-### PR: labels + milestone (автоматика)
-
-1. Ветка **`issue/<number>-<slug>`** (рекомендуется), например `issue/38-workbench-theme-models`.
-2. В PR body: **`Closes #38`** (или Fixes/Resolves).
-3. В title опционально: `feat(theme): … (#38)`.
-
-Workflow [pr-linked-issue-metadata.yml](.github/workflows/pr-linked-issue-metadata.yml) копирует **все labels** и **milestone** с linked issue на PR при open/edit/sync.
-
-Шаблон PR: [.github/pull_request_template.md](.github/pull_request_template.md).
-
-### Ручное создание PR (если автоматика не сработала)
-
-```bash
-gh pr create --base dev \
-  --milestone "Theme system" \
-  --label "theme,enhancement" \
-  --title "feat(theme): QueryaWorkbenchTheme models (#38)" \
-  --body "$(cat <<'EOF'
-## Summary
-…
-
-Closes #38
-EOF
-)"
-```
-
-Для editor-задач добавь label `editor`: `--label "theme,editor,enhancement"`.
-
-### Issues
-
-```bash
-gh issue edit 38 --milestone "Theme system" --add-label "theme,enhancement"
-```
-
-Labels: `bug`, `enhancement`, `documentation`, `theme`, `editor`, `epic`.
-
-После merge: issue `CLOSED`; `git fetch` + `git pull --ff-only` на `dev`.
-
-## Commits and PRs
-
-- [Conventional Commits](https://www.conventionalcommits.org/): `feat`, `fix`, `perf`, `docs`, `test`, `ci`, `chore`, `refactor` + scope.
-- Scopes (примеры): `postgresql`, `mysql`, `mongodb`, `redis`, `connections`, `theme`, `editor`, `settings`, `ci`, `deps`, `ui`.
-- Атомарные коммиты; не коммитить без явной просьбы пользователя.
-- PR body: `Closes #N` когда применимо.
-- **Не коммитить:** `.env`, ключи, `credentials.json`, экспортированные connection secrets.
-
-Примеры:
-
-```
-feat(theme): add QueryaWorkbenchTheme and editor tokens
-fix(postgresql): pass right-clicked table into Open in SQL
-feat(mysql): SQL workspace statement timeout from settings
-test(connections): panel layout with in-memory secrets
-chore(release): bump version to 0.2.2+4
-```
-
-## Layout & checks
-
-| Area | Path |
-|------|------|
-| Entry | `lib/main.dart`, `lib/app/app.dart` |
-| Theme | `lib/core/theme/` |
-| DB / pools | `lib/core/database/` |
-| Storage / settings | `lib/core/storage/` |
-| Features | `lib/features/<db\|area>/` |
-| Shared UI | `lib/shared/widgets/` |
-| Vendored UI | `third_party/shadcn_flutter/` (override в `pubspec.yaml`) |
-| Tests | `test/` (mirror `lib/` where possible) |
-| Docs | `docs/` |
-| CI / release | `.github/workflows/` |
-
-Зависимости: `pubspec.yaml`; lockfile **не** в git (см. `.gitignore`).
-
-## Flutter conventions
-
-- UI: **shadcn** `Theme.of(context).colorScheme`, не смешивать с Material без нужды (`material.` prefix где уже есть).
-- Патчи shadcn — только в `third_party/shadcn_flutter`, с комментарием в `pubspec.yaml` `dependency_overrides`.
-- Секреты: `flutter_secure_storage` / `connection_secrets_store` — без паролей в SQLite и логах ([docs/security.md](docs/security.md)).
-- SQL editor: пока `TextField` / `QueryEditorTab`; подсветка — по issues #47–#50, не раздувать `TextField` ad hoc.
-- Новый код: `flutter analyze` clean, тесты для нетривиальной логики (парсеры, storage, SQL helpers).
-
-## Out of scope (unless issue says otherwise)
-
-- Backend-сервисы, облачный sync аккаунтов.
-- JDBC-драйверы (только встроенные Dart/native пути).
-- Полная VS Code theme compatibility в одном PR (см. epic #37, поэтапно).
-- Force-push на `main` / `dev` без явного запроса.
diff --git a/.flutter-plugins-dependencies b/.flutter-plugins-dependencies
deleted file mode 100644
index d16280a5..00000000
--- a/.flutter-plugins-dependencies
+++ /dev/null
@@ -1 +0,0 @@
-{"info":"This is a generated file; do not edit or check into version control.","plugins":{"ios":[{"name":"device_info_plus","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/device_info_plus-11.5.0/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"file_selector_ios","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/file_selector_ios-0.5.3+5/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"flutter_secure_storage","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/flutter_secure_storage-9.2.4/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"irondash_engine_context","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/irondash_engine_context-0.5.5/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"path_provider_foundation","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/path_provider_foundation-2.6.0/","native_build":false,"dependencies":[],"dev_dependency":false},{"name":"sqflite_darwin","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/sqflite_darwin-2.4.2/","shared_darwin_source":true,"native_build":true,"dependencies":[],"dev_dependency":false},{"name":"super_native_extensions","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/super_native_extensions-0.9.1/","native_build":true,"dependencies":["irondash_engine_context","device_info_plus"],"dev_dependency":false}],"android":[{"name":"device_info_plus","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/device_info_plus-11.5.0/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"file_selector_android","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/file_selector_android-0.5.2+5/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"flutter_secure_storage","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/flutter_secure_storage-9.2.4/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"irondash_engine_context","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/irondash_engine_context-0.5.5/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"jni","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/jni-1.0.0/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"jni_flutter","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/jni_flutter-1.0.1/","native_build":true,"dependencies":["jni"],"dev_dependency":false},{"name":"path_provider_android","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/path_provider_android-2.3.1/","native_build":false,"dependencies":["jni","jni_flutter"],"dev_dependency":false},{"name":"sqflite_android","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/sqflite_android-2.4.2+3/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"super_native_extensions","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/super_native_extensions-0.9.1/","native_build":true,"dependencies":["irondash_engine_context","device_info_plus"],"dev_dependency":false}],"macos":[{"name":"bitsdojo_window_macos","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/bitsdojo_window_macos-0.1.4/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"device_info_plus","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/device_info_plus-11.5.0/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"file_selector_macos","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/file_selector_macos-0.9.5/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"flutter_secure_storage_macos","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/flutter_secure_storage_macos-3.1.3/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"irondash_engine_context","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/irondash_engine_context-0.5.5/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"path_provider_foundation","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/path_provider_foundation-2.6.0/","native_build":false,"dependencies":[],"dev_dependency":false},{"name":"sqflite_darwin","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/sqflite_darwin-2.4.2/","shared_darwin_source":true,"native_build":true,"dependencies":[],"dev_dependency":false},{"name":"super_native_extensions","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/super_native_extensions-0.9.1/","native_build":true,"dependencies":["irondash_engine_context","device_info_plus"],"dev_dependency":false}],"linux":[{"name":"bitsdojo_window_linux","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/bitsdojo_window_linux-0.1.4/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"device_info_plus","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/device_info_plus-11.5.0/","native_build":false,"dependencies":[],"dev_dependency":false},{"name":"file_selector_linux","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/file_selector_linux-0.9.4/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"flutter_secure_storage_linux","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/flutter_secure_storage_linux-1.2.3/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"irondash_engine_context","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/irondash_engine_context-0.5.5/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"jni","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/jni-1.0.0/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"path_provider_linux","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/path_provider_linux-2.2.1/","native_build":false,"dependencies":[],"dev_dependency":false},{"name":"super_native_extensions","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/super_native_extensions-0.9.1/","native_build":true,"dependencies":["irondash_engine_context","device_info_plus"],"dev_dependency":false}],"windows":[{"name":"bitsdojo_window_windows","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/bitsdojo_window_windows-0.1.6/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"device_info_plus","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/device_info_plus-11.5.0/","native_build":false,"dependencies":[],"dev_dependency":false},{"name":"file_selector_windows","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/file_selector_windows-0.9.3+5/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"flutter_secure_storage_windows","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/flutter_secure_storage_windows-3.1.2/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"irondash_engine_context","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/irondash_engine_context-0.5.5/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"jni","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/jni-1.0.0/","native_build":true,"dependencies":[],"dev_dependency":false},{"name":"path_provider_windows","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/path_provider_windows-2.3.0/","native_build":false,"dependencies":[],"dev_dependency":false},{"name":"super_native_extensions","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/super_native_extensions-0.9.1/","native_build":true,"dependencies":["irondash_engine_context","device_info_plus"],"dev_dependency":false}],"web":[{"name":"device_info_plus","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/device_info_plus-11.5.0/","dependencies":[],"dev_dependency":false},{"name":"file_selector_web","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/file_selector_web-0.9.4+2/","dependencies":[],"dev_dependency":false},{"name":"flutter_secure_storage_web","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/flutter_secure_storage_web-1.2.1/","dependencies":[],"dev_dependency":false},{"name":"super_native_extensions","path":"/home/zhuchka/.pub-cache/hosted/pub.dev/super_native_extensions-0.9.1/","dependencies":["device_info_plus"],"dev_dependency":false}]},"dependencyGraph":[{"name":"bitsdojo_window","dependencies":["bitsdojo_window_windows","bitsdojo_window_macos","bitsdojo_window_linux"]},{"name":"bitsdojo_window_linux","dependencies":[]},{"name":"bitsdojo_window_macos","dependencies":[]},{"name":"bitsdojo_window_windows","dependencies":[]},{"name":"device_info_plus","dependencies":[]},{"name":"file_selector","dependencies":["file_selector_android","file_selector_ios","file_selector_linux","file_selector_macos","file_selector_web","file_selector_windows"]},{"name":"file_selector_android","dependencies":[]},{"name":"file_selector_ios","dependencies":[]},{"name":"file_selector_linux","dependencies":[]},{"name":"file_selector_macos","dependencies":[]},{"name":"file_selector_web","dependencies":[]},{"name":"file_selector_windows","dependencies":[]},{"name":"flutter_secure_storage","dependencies":["flutter_secure_storage_linux","flutter_secure_storage_macos","flutter_secure_storage_web","flutter_secure_storage_windows"]},{"name":"flutter_secure_storage_linux","dependencies":[]},{"name":"flutter_secure_storage_macos","dependencies":[]},{"name":"flutter_secure_storage_web","dependencies":[]},{"name":"flutter_secure_storage_windows","dependencies":["path_provider"]},{"name":"irondash_engine_context","dependencies":[]},{"name":"jni","dependencies":[]},{"name":"jni_flutter","dependencies":["jni"]},{"name":"path_provider","dependencies":["path_provider_android","path_provider_foundation","path_provider_linux","path_provider_windows"]},{"name":"path_provider_android","dependencies":["jni","jni_flutter"]},{"name":"path_provider_foundation","dependencies":[]},{"name":"path_provider_linux","dependencies":[]},{"name":"path_provider_windows","dependencies":[]},{"name":"sqflite","dependencies":["sqflite_android","sqflite_darwin"]},{"name":"sqflite_android","dependencies":[]},{"name":"sqflite_darwin","dependencies":[]},{"name":"super_native_extensions","dependencies":["irondash_engine_context","device_info_plus"]}],"date_created":"2026-06-09 13:00:56.820075","version":"3.41.6","swift_package_manager_enabled":{"ios":false,"macos":false}}
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index 22dd42e8..1960cc1d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,11 +15,9 @@ linux/flutter/generated_*
 windows/flutter/generated_*
 macos/Flutter/ephemeral/
 
-# IDE — track Cursor rules, ignore the rest
+# IDE
 .idea/
-.cursor/*
-!.cursor/rules/
-!.cursor/rules/**
+.cursor/
 
 # OS
 .DS_Store
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 50972bd1..4ca273cc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,7 +16,7 @@ Theme system milestone (epic #37). Git tag **`0.4.0`** — use this release for
 - **Syntax highlighting** — SQL and JSON in `QueryaCodeEditor` via `syntax_highlight`; `tokenColors` mapped to TextMate scopes; isolate highlight for large buffers.
 - **Editor** — `QueryaCodeEditor` abstraction, `SqlEditorChrome` from theme tokens, `QueryaThemeScope` for workbench/editor tokens.
 - **Samples** — `themes/samples/cyberpunk-neon.json` (+ JSONC) for manual import testing.
-- **Docs** — [docs/theme.md](docs/theme.md), [docs/theme-import.md](docs/theme-import.md), [docs/editor-spike-report.md](docs/editor-spike-report.md), [docs/code-forge-evaluation.md](docs/code-forge-evaluation.md).
+- **Docs** — [docs/theme.md](docs/theme.md), [docs/theme-import.md](docs/theme-import.md), [docs/archive/editor-spike-report.md](docs/archive/editor-spike-report.md), [docs/archive/code-forge-evaluation.md](docs/archive/code-forge-evaluation.md).
 
 ### Changed
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index adc18b20..a9b216d4 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,32 +1,94 @@
 # Contributing
 
-## Flutter version
+Thanks for your interest in improving Querya Desktop. This guide covers the
+workflow, branch/commit conventions, and the checks we expect before a PR.
 
-CI pins a **stable** Flutter version in [`.github/workflows/ci.yml`](.github/workflows/ci.yml) and [`.github/workflows/release.yml`](.github/workflows/release.yml). Prefer matching that version locally to avoid “works on my machine” drift. When bumping the pin, run `flutter test` and a release smoke build before merging.
+New to the codebase? Start with [docs/getting-started.md](docs/getting-started.md)
+and [docs/architecture.md](docs/architecture.md).
 
-## Linux: `flutter analyze` and “Too many open files”
+## Workflow
 
-On some Linux setups the Dart analysis server hits the process **open file limit** (`errno = 24`). Try:
+We follow a simple GitFlow: feature work branches off `dev` and merges back into
+`dev` via PR; `main` holds production-ready code and release tags.
 
 ```bash
-ulimit -n 8192
-flutter analyze
+# 1. Sync
+git fetch --all --prune
+git checkout dev
+git pull --ff-only origin dev
+
+# 2. Branch (one issue → one branch → one PR)
+git checkout -b issue/<number>-<short-slug>     # or feat/<short-slug>
+
+# 3. ...make changes, then run the checks below...
+
+# 4. Open a PR into `dev` with "Closes #<number>" in the body
 ```
 
-## Git tags and release commits
+Keep each PR scoped to a single issue — avoid drive-by refactoring.
 
-A **tag points at one commit**. Release artifacts are built from the tree at that commit. If you fix something **after** pushing a release tag, either:
+## Commits
 
-- move the tag to the new commit (only if the team agrees and the release is not yet consumed), or  
-- ship a **new** semver (update `pubspec.yaml` / `CHANGELOG.md`) and push a **new** tag.
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+`feat`, `fix`, `perf`, `docs`, `test`, `ci`, `chore`, `refactor`, with a scope
+where helpful (`postgresql`, `mysql`, `mongodb`, `redis`, `connections`, `theme`,
+`editor`, `settings`, `ui`, `ci`, `deps`).
 
-See [docs/tags-and-releases.md](docs/tags-and-releases.md).
+```
+feat(theme): add QueryaWorkbenchTheme and editor tokens
+fix(postgresql): pass right-clicked table into Open in SQL
+docs: restructure README and docs index
+```
 
-## Tests
+**Never commit** secrets — `.env`, keys, `credentials.json`, or exported
+connection secrets.
+
+## Checks before a PR
+
+Run the same checks CI runs:
 
 ```bash
 flutter pub get
+flutter analyze
 flutter test
 ```
 
-Widget tests that use SQLite or `path_provider` follow patterns in `test/features/connections/connections_panel_layout_test.dart` and `test/flutter_test_config.dart` (in-memory secrets backend).
+For release or large UI PRs, optionally smoke-test a build:
+
+```bash
+flutter build linux --release   # or windows / macos
+```
+
+### Linux: `flutter analyze` and "Too many open files"
+
+On some Linux setups the Dart analysis server hits the process **open file
+limit** (`errno = 24`). Raise it for the session:
+
+```bash
+ulimit -n 8192
+flutter analyze
+```
+
+## Flutter version
+
+CI pins a **stable** Flutter version in
+[`.github/workflows/ci.yml`](.github/workflows/ci.yml) and
+[`.github/workflows/release.yml`](.github/workflows/release.yml). Match that
+version locally to avoid "works on my machine" drift. When bumping the pin, run
+`flutter test` and a release smoke build before merging.
+
+## Tests
+
+Widget tests that use SQLite or `path_provider` follow patterns in
+`test/features/connections/connections_panel_layout_test.dart` and
+`test/flutter_test_config.dart` (in-memory secrets backend). Mirror `lib/` layout
+under `test/` where possible.
+
+## Releases and tags
+
+A **tag points at one commit**, and release artifacts are built from that tree.
+If you fix something **after** pushing a release tag, either move the tag (only if
+the team agrees and the release is not yet consumed) or ship a **new** semver
+(update `pubspec.yaml` / `CHANGELOG.md`) and push a new tag. See
+[docs/tags-and-releases.md](docs/tags-and-releases.md) and
+[docs/release-checklist.md](docs/release-checklist.md).
diff --git a/README.md b/README.md
index e8d34c75..e7f4e94b 100644
--- a/README.md
+++ b/README.md
@@ -1,103 +1,98 @@
-# Querya Desktop
+<div align="center">
 
-A lightweight desktop client for SQL and NoSQL databases. Connect to PostgreSQL, MySQL, Redis, and MongoDB from a single app with a clean, dark UI inspired by tools like pgAdmin.
+# Querya Desktop
 
-## What it is
+**A lightweight, cross-platform desktop client for SQL and NoSQL databases.**
 
-- **Cross-platform:** Windows, Linux, macOS (Flutter desktop).
-- **Multi-database:** PostgreSQL, MySQL, Redis, MongoDB (more can be added).
-- **UI:** Custom window (no system title bar), resizable left panel (connection tree) and bottom split (query editor / results), dark theme, [shadcn_flutter](https://pub.dev/packages/shadcn_flutter) components.
-- **Flow:** Right-click “Servers” → “New connection” (or **Connection → New Database Connection**) → pick database type → configure and save. Metadata is stored in local SQLite; **passwords and connection strings** use the OS secure store (see [docs/security.md](docs/security.md)).
+Connect to PostgreSQL, MySQL/MariaDB, Redis, and MongoDB from a single app with
+a clean, dark UI inspired by tools like pgAdmin.
 
-## Database drivers
+[![CI](https://github.com/QueryaHub/Querya-Desktop/actions/workflows/ci.yml/badge.svg)](https://github.com/QueryaHub/Querya-Desktop/actions/workflows/ci.yml)
+[![Release](https://github.com/QueryaHub/Querya-Desktop/actions/workflows/release.yml/badge.svg)](https://github.com/QueryaHub/Querya-Desktop/actions/workflows/release.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Flutter](https://img.shields.io/badge/Flutter-Desktop-02569B?logo=flutter)](https://flutter.dev)
+[![Platforms](https://img.shields.io/badge/Platforms-Linux%20%7C%20Windows%20%7C%20macOS-555)](#)
 
-- **PostgreSQL** — `postgres` (Dart); browser, SQL workspace, table/view browsing, server stats.
-- **MySQL / MariaDB** — `mysql_client` (Dart); browser (databases, tables, views), SQL workspace with configurable statement timeout, paginated table/view data (read-oriented browse SQL).
-- **Redis** / **MongoDB** — see connection panels and workspace.
+</div>
 
-## Tech stack
+---
 
-- **Flutter** (Dart) with desktop support  
-- **shadcn_flutter** for UI (buttons, inputs, theme)  
-- **bitsdojo_window** for custom frame and window sizing  
+## Highlights
 
-## Prerequisites
+- **Multi-database** — PostgreSQL, MySQL/MariaDB, Redis, and MongoDB, with
+  built-in Dart drivers (no JDBC JARs to download).
+- **Cross-platform** — Linux, Windows, and macOS from one Flutter codebase.
+- **SQL workspace** — query editor with syntax highlighting, configurable
+  statement timeouts, query history, and CSV/JSON export.
+- **Object browsing** — connection tree with databases, tables, views, and
+  server stats.
+- **Themeable** — runtime dark/light/system modes and **VS Code theme import**.
+- **Scalable UI** — global interface scaling for high-DPI and accessibility.
+- **Secure by default** — passwords and connection strings live in the OS secure
+  store, never in plaintext.
 
-- [Flutter SDK](https://docs.flutter.dev/get-started/install) (stable) with desktop enabled:
-  ```bash
-  flutter config --enable-linux-desktop   # or windows, macos
-  ```
-- **Linux builds** also need desktop headers used by Flutter and plugins (GTK, etc.). For `flutter_secure_storage` on Linux you typically need **`libsecret-1-dev`** (Debian/Ubuntu: `sudo apt install libsecret-1-dev`; Fedora: `libsecret-devel`). Match this to your distro’s Flutter desktop docs.
+## Screenshots
 
-## Setup
+> _Add screenshots/GIFs to `docs/assets/` and reference them here._
 
-From the project root:
+## Quick start
 
 ```bash
-flutter pub get
-```
-
-If platform folders are missing:
+# 1. Enable Flutter desktop for your platform
+flutter config --enable-linux-desktop      # or --enable-windows-desktop / --enable-macos-desktop
 
-```bash
-flutter create . --project-name querya_desktop --platforms=linux,windows,macos
+# 2. Fetch dependencies
 flutter pub get
+
+# 3. Run
+flutter run -d linux                        # or windows / macos
 ```
 
-## Run
+Linux builds also need keyring headers (`libsecret-1-dev` on Debian/Ubuntu).
+See **[Getting started](docs/getting-started.md)** for the full setup, including
+prerequisites, release builds, and your first connection.
 
-```bash
-# Linux (on Wayland, use X11 to avoid Gdk warnings when the pointer leaves the window)
-GDK_BACKEND=x11 flutter run -d linux
+## Tech stack
 
-# Or
-flutter run -d linux
+- **[Flutter](https://flutter.dev)** (Dart) with desktop support.
+- **[shadcn_flutter](https://pub.dev/packages/shadcn_flutter)** for UI components and theming.
+- **[bitsdojo_window](https://pub.dev/packages/bitsdojo_window)** for the custom window frame.
+- Built-in Dart drivers: `postgres`, `mysql_client`, `redis`, `mongo_dart`.
 
-# Windows
-flutter run -d windows
+## Project structure
 
-# macOS
-flutter run -d macos
-```
+| Path | Description |
+|------|-------------|
+| `lib/main.dart` | App entry, window setup. |
+| `lib/app/` | App shell and theme wiring. |
+| `lib/core/` | Database clients, storage, theme, layout, editor helpers. |
+| `lib/features/` | Feature modules (main screen, connections, per-engine UI, settings). |
+| `lib/shared/` | Reusable widgets shared across features. |
+| `assets/` | Database type icons and other bundled assets. |
+| `linux/`, `windows/`, `macos/` | Native runners. |
+| `third_party/` | Vendored components (e.g. `shadcn_flutter`), under their own licenses. |
 
-Or use the helper script on Linux:
+For a deeper map of modules and their responsibilities, see
+**[Architecture](docs/architecture.md)**.
 
-```bash
-./run_linux.sh
-```
+## Documentation
 
-## Build release
+Full documentation lives in **[`docs/`](docs/README.md)**:
 
-```bash
-flutter build linux
-flutter build windows
-flutter build macos
-```
+- **[Getting started](docs/getting-started.md)** — install and first run.
+- **[User guide](docs/user-guide.md)** — connections, preferences, drivers.
+- **[Architecture](docs/architecture.md)** — codebase layout.
+- **[Security](docs/security.md)** — local data and secrets.
+- **[Theme system](docs/theme.md)** · **[Theme import](docs/theme-import.md)**.
+- **[Roadmap](docs/roadmap.md)** · **[Releases](docs/tags-and-releases.md)**.
 
-## Project structure
+## Contributing
 
-| Path | Description |
-|------|-------------|
-| `lib/main.dart` | App entry, window setup (bitsdojo_window) |
-| `lib/app/` | App shell and theme |
-| `lib/features/main_screen/` | Main layout, workspace panel, query/results tabs |
-| `lib/features/connections/` | Connection tree, new connection / folder flows, driver manager |
-| `lib/features/postgresql/`, `mysql/`, `redis/`, `mongodb/` | Per-engine workspace and browser UI |
-| `lib/shared/widgets/` | Shared UI (shadcn re-exports, app dialog) |
-| `lib/core/` | Database clients, local storage, theme, editor helpers |
-| `assets/images/` | Database type icons (PostgreSQL, MySQL, Redis, MongoDB) |
-| `linux/`, `windows/`, `macos/` | Native runners (custom frame on Linux/Windows) |
+Contributions are welcome. Please read **[CONTRIBUTING.md](CONTRIBUTING.md)** for
+the workflow, CI expectations, and the pre-PR checklist, and see the
+[Changelog](CHANGELOG.md) for release history.
 
 ## License
 
-[MIT](LICENSE). Third-party components (e.g. vendored UI under `third_party/`) retain their own licenses.
-
-## More documentation
-
-- [Security / local data](docs/security.md)
-- [Theme system](docs/theme.md)
-- [User guide](docs/user-guide.md)
-- [Releases](docs/tags-and-releases.md)
-- [Release checklist](docs/release-checklist.md)
-- [Contributing](CONTRIBUTING.md) (Flutter pin, tags, local analyze)
-- [Roadmap](docs/roadmap.md)
+[MIT](LICENSE). Third-party components (e.g. vendored UI under `third_party/`)
+retain their own licenses.
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..2d38f3ea
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,38 @@
+# Documentation
+
+Index of Querya Desktop documentation, grouped by audience.
+
+## For users
+
+- [Getting started](getting-started.md) — prerequisites, install, first run.
+- [User guide](user-guide.md) — connections, preferences, driver manager.
+- [Security / local data](security.md) — where metadata and secrets are stored.
+
+## For contributors
+
+- [Contributing](../CONTRIBUTING.md) — workflow, CI, pre-PR checklist.
+- [Architecture](architecture.md) — `lib/` layout and module responsibilities.
+- [Theme system](theme.md) — runtime theming and VS Code theme tokens.
+- [Theme import](theme-import.md) — supported `colors` keys and merge behavior.
+- [Performance baseline](perf-baseline.md) — per-milestone DevTools checklist.
+
+## For release managers
+
+- [Tags and releases](tags-and-releases.md) — tag/release policy.
+- [Release checklist](release-checklist.md) — step-by-step release flow.
+- [macOS signing](macos-signing.md) — signing and notarization track.
+
+## Planning
+
+- [Roadmap](roadmap.md) — current direction and follow-ups.
+
+## Archive
+
+Historical design notes and one-off spikes, kept for context but no longer
+maintained — see [`archive/`](archive/):
+
+- [Repository audit (#91)](archive/AUDIT.md)
+- [Editor package spike (#48)](archive/editor-spike-report.md)
+- [`code_forge` + LSP evaluation (#52)](archive/code-forge-evaluation.md)
+- [Theme research (RU)](archive/research_theme.md)
+- [MySQL implementation plan](archive/mysql-implementation-plan.md)
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 00000000..5817736a
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,71 @@
+# Architecture
+
+A high-level map of the codebase for contributors. The app is a Flutter desktop
+client with a custom window frame ([bitsdojo_window](https://pub.dev/packages/bitsdojo_window))
+and [shadcn_flutter](https://pub.dev/packages/shadcn_flutter) UI components.
+
+## Layered layout
+
+```
+lib/
+├── main.dart        App entry: window setup, controller bootstrap
+├── app/             App shell, theme wiring, global scopes
+├── core/            Cross-cutting infrastructure (no feature UI)
+├── features/        Feature modules, one folder per area / engine
+└── shared/          Reusable widgets shared across features
+```
+
+The dependency direction is **features → core/shared**, never the reverse.
+`core/` and `shared/` must not import from `features/`.
+
+## `core/`
+
+| Path | Responsibility |
+|------|----------------|
+| `core/database/` | Engine clients and query execution (PostgreSQL, MySQL, Redis, MongoDB). |
+| `core/storage/` | Local SQLite metadata (`local_db.dart`), app settings, secure secrets store. |
+| `core/theme/` | Theme tokens, VS Code theme import, color resolution. |
+| `core/editor/` | Code editor helpers and syntax highlighting glue. |
+| `core/layout/` | Window/dialog sizing and the global UI-scale system. |
+| `core/csv/`, `core/json/` | Result export helpers (CSV / JSON). |
+
+## `features/`
+
+| Path | Responsibility |
+|------|----------------|
+| `features/main_screen/` | Main layout, workspace panel, query/results tabs, history. |
+| `features/connections/` | Connection tree, new connection / folder flows, driver manager. |
+| `features/postgresql/` | PostgreSQL workspace, object browser, SQL editor dialog. |
+| `features/mysql/` | MySQL / MariaDB workspace, browser, SQL editor dialog. |
+| `features/redis/` | Redis connection form and workspace. |
+| `features/mongodb/` | MongoDB connection form, database dialog, stats view. |
+| `features/settings/` | Preferences dialog, controls, interface scale slider. |
+
+## `shared/`
+
+| Path | Responsibility |
+|------|----------------|
+| `shared/widgets/` | shadcn re-exports, `QueryaDropdown`, app dialog, shared tokens. |
+
+## Cross-cutting systems
+
+- **Theme system** — runtime dark/light/system modes plus VS Code theme import.
+  See [theme.md](theme.md) and [theme-import.md](theme-import.md).
+- **UI scaling** — a global scale factor propagated via an inherited scope and
+  applied to text (`TextScaler`) and dialog dimensions. Lives in `core/layout/`.
+- **Secrets** — passwords and connection strings go to the OS secure store, not
+  SQLite. See [security.md](security.md).
+
+## Data and secrets
+
+- **Connection metadata + preferences**: local SQLite (`querya.db` in the app
+  support directory).
+- **Passwords / connection strings**: OS secure store via `flutter_secure_storage`
+  (Keychain / Credential Manager / libsecret).
+
+## Tests
+
+Widget tests that touch SQLite or `path_provider` follow the patterns in
+`test/features/connections/connections_panel_layout_test.dart` and
+`test/flutter_test_config.dart` (in-memory secrets backend, no desktop keyring
+required). Run them with `flutter test`.
diff --git a/docs/archive/AUDIT.md b/docs/archive/AUDIT.md
new file mode 100644
index 00000000..a65176e0
--- /dev/null
+++ b/docs/archive/AUDIT.md
@@ -0,0 +1,47 @@
+# Repository audit (#91)
+
+Inventory of docs and tracked artifacts with a disposition decision. Goal: keep
+the repository professional and easy to navigate without losing technically
+valuable history.
+
+Legend: **keep** = active, maintained · **archive** = historical, moved to
+`docs/archive/` · **untrack** = remove from git, keep locally · **delete** = removed.
+
+## Documentation
+
+| Path | Disposition | Rationale |
+|------|-------------|-----------|
+| `README.md` | keep (rewritten) | Project front page — restructured with badges, features, quick start, docs index. |
+| `CONTRIBUTING.md` | keep (expanded) | GitFlow, CI expectations, pre-PR checklist. |
+| `CHANGELOG.md` | keep | Release history (Keep a Changelog). Links updated for moved files. |
+| `docs/README.md` | new | Documentation index (User / Developer / Release / Theme / Archive). |
+| `docs/getting-started.md` | new | Install + first run, extracted from README. |
+| `docs/architecture.md` | new | `lib/` layout and module responsibilities for contributors. |
+| `docs/user-guide.md` | keep | End-user guide. Kept current with the shipped UI. |
+| `docs/security.md` | keep | Local-data and secrets model. |
+| `docs/theme.md` | keep | Theme system reference (epic #37). |
+| `docs/theme-import.md` | keep | VS Code theme import details. |
+| `docs/roadmap.md` | keep (synced) | Living roadmap; synced with closed issues. |
+| `docs/perf-baseline.md` | keep | Reusable per-milestone DevTools checklist. |
+| `docs/tags-and-releases.md` | keep | Release/tag policy. |
+| `docs/release-checklist.md` | keep | Release steps. |
+| `docs/macos-signing.md` | keep | Signing/notarize track. |
+| `docs/editor-spike-report.md` | archive | One-off editor package spike (#48); decision shipped in 0.4.0. |
+| `docs/code-forge-evaluation.md` | archive | `code_forge`/LSP go/no-go spike (#52); NO-GO recorded. |
+| `docs/research_theme.md` | archive | Background research (RU) behind the theme epic. |
+| `docs/mysql-implementation-plan.md` | archive | Historical plan; MySQL is implemented (`lib/features/mysql/`). |
+
+## Tracked artifacts
+
+| Path | Disposition | Rationale |
+|------|-------------|-----------|
+| `.flutter-plugins-dependencies` | untrack | Generated per-machine; already in `.gitignore`. Caused recurring "local changes". |
+| `.metadata` | keep | Standard Flutter project metadata. |
+| `third_party/` | keep (untouched) | Vendored `shadcn_flutter`; retains its own license/docs. |
+| `test/`, `.github/workflows/` | keep (untouched) | Behavior and CI unchanged by this cleanup. |
+
+## Not in scope
+
+- Rewriting `third_party/shadcn_flutter` documentation.
+- Full RU+EN localization of docs (separate issue if needed).
+- Marketing site / landing outside the repository.
diff --git a/docs/code-forge-evaluation.md b/docs/archive/code-forge-evaluation.md
similarity index 100%
rename from docs/code-forge-evaluation.md
rename to docs/archive/code-forge-evaluation.md
diff --git a/docs/editor-spike-report.md b/docs/archive/editor-spike-report.md
similarity index 100%
rename from docs/editor-spike-report.md
rename to docs/archive/editor-spike-report.md
diff --git a/docs/mysql-implementation-plan.md b/docs/archive/mysql-implementation-plan.md
similarity index 100%
rename from docs/mysql-implementation-plan.md
rename to docs/archive/mysql-implementation-plan.md
diff --git a/docs/research_theme.md b/docs/archive/research_theme.md
similarity index 100%
rename from docs/research_theme.md
rename to docs/archive/research_theme.md
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 00000000..832767f4
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,75 @@
+# Getting started
+
+How to build and run Querya Desktop from source.
+
+## Prerequisites
+
+- [Flutter SDK](https://docs.flutter.dev/get-started/install) (stable channel)
+  with desktop enabled:
+
+  ```bash
+  flutter config --enable-linux-desktop   # or --enable-windows-desktop / --enable-macos-desktop
+  ```
+
+- **Linux** also needs the desktop headers used by Flutter and its plugins
+  (GTK, etc.). For `flutter_secure_storage` you typically need
+  **`libsecret-1-dev`**:
+
+  ```bash
+  sudo apt install libsecret-1-dev      # Debian / Ubuntu
+  sudo dnf install libsecret-devel      # Fedora
+  ```
+
+  CI pins a specific stable Flutter version; matching it locally avoids
+  "works on my machine" drift (see [Contributing](../CONTRIBUTING.md)).
+
+## Install
+
+From the project root:
+
+```bash
+flutter pub get
+```
+
+If the platform folders are missing:
+
+```bash
+flutter create . --project-name querya_desktop --platforms=linux,windows,macos
+flutter pub get
+```
+
+## Run
+
+```bash
+# Linux
+flutter run -d linux
+# On Wayland, force X11 to avoid Gdk pointer warnings:
+GDK_BACKEND=x11 flutter run -d linux
+# Or use the helper script:
+./run_linux.sh
+
+# Windows
+flutter run -d windows
+
+# macOS
+flutter run -d macos
+```
+
+## Build release
+
+```bash
+flutter build linux
+flutter build windows
+flutter build macos
+```
+
+## First connection
+
+1. Launch the app.
+2. **Connection → New Database Connection** (or right-click **Servers** in the tree).
+3. Pick **PostgreSQL**, **MySQL**, **Redis**, or **MongoDB** and fill in host,
+   port, and credentials.
+4. Saved connections appear in the left tree.
+
+See the [User guide](user-guide.md) for preferences, the driver manager, and
+day-to-day usage, and [Security](security.md) for how credentials are stored.
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 30a36187..491c5d92 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -8,7 +8,7 @@ Living document for planned work. Not a commitment order; adjust as priorities c
   highlighting, P0 workbench migration, Preferences, tests, docs — [theme.md](theme.md).
 - **Optional:** Preferences → **Animate theme changes** (off by default).
 - **Later:** P2 Mongo/Redis token colors; `re_editor` if perf gap; LSP epic per
-  [code-forge-evaluation.md](code-forge-evaluation.md) (**NO-GO** on `code_forge` for 0.3).
+  [archive/code-forge-evaluation.md](archive/code-forge-evaluation.md) (**NO-GO** on `code_forge` for 0.3).
 
 ## Query history and favorites
 
diff --git a/docs/theme.md b/docs/theme.md
index f310fbf5..4fbb4550 100644
--- a/docs/theme.md
+++ b/docs/theme.md
@@ -13,7 +13,7 @@ import (#43–45), `tokenColors` → syntax highlight (#46–47, #49–50), P0 w
 animation (#57), editor package spikes (#48, #52).
 
 **Follow-up (not blocking):** P2 surfaces (Mongo/Redis explorer semantic hues), `re_editor`
-if large-buffer benchmarks fail — see [code-forge-evaluation.md](code-forge-evaluation.md).
+if large-buffer benchmarks fail — see [archive/code-forge-evaluation.md](archive/code-forge-evaluation.md).
 
 ## Architecture
 
@@ -180,11 +180,11 @@ Manual QA (with animation enabled):
 | SQL/JSON syntax highlighting | Done |
 | `tokenColors` → highlighter | Done |
 | Theme transition animation | Preferences → **Animate theme changes** (default off) |
-| `code_forge` / LSP editor | **NO-GO** for 0.3 — [code-forge-evaluation.md](code-forge-evaluation.md) |
+| `code_forge` / LSP editor | **NO-GO** for 0.3 — [archive/code-forge-evaluation.md](archive/code-forge-evaluation.md) |
 
 ## Related docs
 
 - [theme-import.md](theme-import.md) — supported `colors` keys and merge behavior
-- [research_theme.md](research_theme.md) — background research (RU)
-- [editor-spike-report.md](editor-spike-report.md) — code editor package evaluation (#48)
-- [code-forge-evaluation.md](code-forge-evaluation.md) — `code_forge` + LSP go/no-go (#52)
+- [archive/research_theme.md](archive/research_theme.md) — background research (RU)
+- [archive/editor-spike-report.md](archive/editor-spike-report.md) — code editor package evaluation (#48)
+- [archive/code-forge-evaluation.md](archive/code-forge-evaluation.md) — `code_forge` + LSP go/no-go (#52)