diff --git a/webclient-vue/docs/README.md b/webclient-vue/docs/README.md
new file mode 100644
index 0000000..41073a9
--- /dev/null
+++ b/webclient-vue/docs/README.md
@@ -0,0 +1,29 @@
+# SHServ Vue Client Specification
+
+This directory contains the technical specification for a new SHServ web client.
+
+The current `webclient/` implementation is the reference implementation. The new
+client should preserve its functional behavior while moving to Vue and the
+`gnexus-ui-kit` design system.
+
+## Documents
+
+- `overview.md` - goals, boundaries, architecture direction.
+- `current-client-map.md` - current routes, screens, modules, and UI behavior.
+- `api-contract.md` - API endpoints used by the client and expected response handling.
+- `screens.md` - target screen-by-screen functional specification.
+- `state-and-components.md` - current global helpers mapped to Vue stores/components.
+- `scaffold.md` - recommended Vue/Vite project scaffold and first milestone.
+- `coding-conventions.md` - code organization, state, API, and UI rules.
+- `ui-kit-integration.md` - planned `gnexus-ui-kit` adapter strategy.
+- `migration-plan.md` - phased plan for building the new client in parallel.
+
+## Working Rules
+
+- Keep the current `webclient/` operational until the new client covers the main flows.
+- Treat backend API behavior as a contract; document gaps before changing endpoints.
+- New UI code should be JavaScript, not TypeScript.
+- New UI code should not depend on old global objects such as `Helper`, `Screens`,
+  `DataProvider`, `Toasts`, or `Modals`.
+- Generated build artifacts for the new client should stay inside the new client
+  directory.
diff --git a/webclient-vue/docs/api-contract.md b/webclient-vue/docs/api-contract.md
new file mode 100644
index 0000000..ed72228
--- /dev/null
+++ b/webclient-vue/docs/api-contract.md
@@ -0,0 +1,123 @@
+# API Contract
+
+The new client should wrap all backend calls in a dedicated API layer. UI
+components should not call `fetch` directly.
+
+## Transport
+
+Current dev transport:
+
+```text
+GET|POST {baseUrl}/proxy.php?path=/api/v1/...
+```
+
+Current backend base from `webclient/config.php`:
+
+```text
+http://smart-home-serv.local
+```
+
+## Common Response Shape
+
+Success:
+
+```json
+{
+  "status": true,
+  "data": {}
+}
+```
+
+Error:
+
+```json
+{
+  "status": false,
+  "error_alias": "device_request_fail",
+  "failed_fields": [],
+  "msg": "Устройство не отвечает"
+}
+```
+
+The new API layer should normalize responses into one result shape:
+
+```js
+// success
+{ ok: true, data, meta }
+
+// failure
+{ ok: false, error, meta }
+```
+
+## Devices
+
+| Method | Path | Current Use |
+| --- | --- | --- |
+| GET | `/api/v1/devices/list` | Devices list. |
+| GET | `/api/v1/devices/id/{id}` | Device DB info. |
+| GET | `/api/v1/devices/id/{id}/info` | Device DB info plus live `/about`. |
+| GET | `/api/v1/devices/id/{id}/status` | Live device state. |
+| GET | `/api/v1/devices/scanning/all` | Scan all devices in local network range. |
+| GET | `/api/v1/devices/scanning/setup` | Scan setup-mode devices. |
+| POST | `/api/v1/devices/setup/new-device` | Register a setup-mode device. |
+| GET | `/api/v1/devices/id/{id}/reboot` | Reboot one device. |
+| POST | `/api/v1/devices/resetup` | Reset/rebind device token. |
+| POST | `/api/v1/devices/reset` | Reset device. |
+| POST | `/api/v1/devices/update-name` | Update device name. |
+| POST | `/api/v1/devices/update-description` | Update device description. |
+| POST | `/api/v1/devices/update-alias` | Update device alias. |
+| POST | `/api/v1/devices/place-in-area` | Assign device to area. |
+| GET | `/api/v1/devices/id/{id}/unassign-from-area` | Remove device from area. |
+
+Device state rendering depends on `device_type`:
+
+- `relay` expects `channels[]` with `id` and `state`.
+- `button` expects `channels[]` with `id` and `indicator`.
+- `sensor` expects `sensors.light`, `temperature`, `pressure`, `humidity`,
+  `radar`, and `microphone`.
+- `hatch` expects `hatch.state` and `hatch.position_pct`.
+
+## Scripts
+
+| Method | Path | Current Use |
+| --- | --- | --- |
+| GET | `/api/v1/scripts/actions/list` | Action script cards. |
+| POST | `/api/v1/scripts/actions/run` | Run action script by alias. |
+| GET | `/api/v1/scripts/regular/list` | Regular scripts table. |
+| GET | `/api/v1/scripts/regular/alias/{alias}/enable` | Enable regular script. |
+| GET | `/api/v1/scripts/regular/alias/{alias}/disable` | Disable regular script. |
+| GET | `/api/v1/scripts/scopes/list` | Scopes table. |
+| GET | `/api/v1/scripts/scopes/name/{name}/enable` | Enable scope. |
+| GET | `/api/v1/scripts/scopes/name/{name}/disable` | Disable scope. |
+| GET | `/api/v1/scripts/scopes/name/{name}/remove` | Remove scope. |
+| GET | `/api/v1/scripts/scopes/name/{filename}` | Get scope source by filename/name. |
+| POST | `/api/v1/scripts/scopes/new` | Create scope. |
+| POST | `/api/v1/scripts/scopes/update` | Update scope. |
+| POST | `/api/v1/scripts/place-in-area` | Assign script to area. |
+| GET | `/api/v1/scripts/id/{id}/unassign-from-area` | Remove script from area. |
+
+## Areas
+
+| Method | Path | Current Use |
+| --- | --- | --- |
+| GET | `/api/v1/areas/list` | Areas tree and favorites. |
+| GET | `/api/v1/areas/id/{area_id}/list` | Area inner list. |
+| POST | `/api/v1/areas/new-area` | Create area. |
+| GET | `/api/v1/areas/id/{area_id}/remove` | Remove area. |
+| POST | `/api/v1/areas/place-in-area` | Move area under another area. |
+| POST | `/api/v1/areas/update-display-name` | Rename area display name. |
+| POST | `/api/v1/areas/update-alias` | Update area alias. |
+| GET | `/api/v1/areas/id/{area_id}/devices` | Devices in area. |
+| GET | `/api/v1/areas/id/{area_id}/scripts` | Scripts in area. |
+| GET | `/api/v1/areas/id/{id}/unassign-from-area` | Remove area from parent. |
+| GET | `/api/v1/areas/types/list` | Allowed area types. |
+| GET | `/api/v1/areas/reboot_devices` | Reboot all devices. |
+| GET | `/api/v1/areas/id/{area_id}/reboot_devices` | Reboot devices in area. |
+
+## Reliability Requirements
+
+- Device status loading must be isolated per device.
+- A failed device status request must not break the full screen.
+- Device status requests should have a concurrency limit.
+- The UI should distinguish backend error, network/proxy error, and device offline.
+- API callback/consumer errors must not be treated as transport failures.
diff --git a/webclient-vue/docs/coding-conventions.md b/webclient-vue/docs/coding-conventions.md
new file mode 100644
index 0000000..1d8a8a3
--- /dev/null
+++ b/webclient-vue/docs/coding-conventions.md
@@ -0,0 +1,113 @@
+# Coding Conventions
+
+## Source Language
+
+Use JavaScript for the new client.
+
+Rules:
+
+- Backend response validation lives in `src/api/schemas`.
+- UI-facing normalized models are produced by mapper functions.
+- Avoid passing raw backend envelopes deep into UI components.
+- If a response shape is uncertain, validate it at the API/module boundary and
+  return `invalid_response` on mismatch.
+
+## File Naming
+
+- Vue components: `PascalCase.vue`.
+- Stores: `useXStore` exported from `stores/x.js`.
+- Composables: `useThing.js`.
+- API modules: lowercase domain names, e.g. `devices.js`.
+- Runtime schemas: domain names, e.g. `devices.js`, `areas.js`.
+
+## Component Rules
+
+- Keep route components thin.
+- Put reusable domain UI in `features/{domain}/components`.
+- Put generic reusable UI in `components`.
+- Do not pass raw backend DTO-like objects directly into deep UI components unless
+  the component is API-specific by design.
+- Use props/events for reusable components.
+- Use stores for screen-level data and cross-component state.
+
+## Store Rules
+
+- Stores own fetch/mutation orchestration.
+- Stores call API modules.
+- Stores expose loading/error states.
+- Stores should not know about toasts or router navigation.
+- Components or page-level actions decide how to show feedback.
+
+## API Rules
+
+- All API methods return normalized `{ ok, data?, error?, meta }` results.
+- API modules do not show UI feedback.
+- API modules do not mutate stores directly.
+- API mappers should be pure functions.
+- Request cancellation should use `AbortController`.
+
+## Error Handling
+
+Use this UI policy:
+
+- Route-level fetch failure: show route error state with retry.
+- Per-row device status failure: show row-level error/offline state.
+- Mutation failure: keep the modal/page open and show toast plus inline field
+  errors when available.
+- Validation failure: show field-level errors before submitting.
+
+Do not:
+
+- Treat component render errors as network errors.
+- Hide backend `msg` when present.
+- Swallow failed mutations silently.
+
+## Formatting And Style
+
+- Use tabs or spaces consistently after scaffold decision.
+- Keep components small enough that template, script, and styles are easy to scan.
+- Prefer explicit names over abbreviations.
+- Avoid direct DOM manipulation except for integration boundaries.
+- Avoid global singletons unless they are intentional app-level services.
+
+## Icons
+
+Current client uses Phosphor Icons.
+
+New client options:
+
+- Continue using Phosphor if `gnexus-ui-kit` supports it or does not provide an
+  icon system.
+- Prefer UI-kit icon primitives if they exist.
+
+Do not mix several icon systems in the same screen.
+
+## Dates And Formatting
+
+Centralize formatting in `src/utils/format.js` and `src/utils/dates.js`.
+
+Required helpers:
+
+- `formatDate`
+- `formatDateTime`
+- `formatTimeAgo`
+- `formatDeviceConnectionStatus`
+- `formatScriptState`
+
+## CSS And Styling
+
+- Prefer UI-kit tokens/classes.
+- Put app-specific layout styles in `src/styles`.
+- Avoid copying old SCSS wholesale.
+- If old styles are needed temporarily, isolate them under a legacy namespace.
+- Do not override UI-kit internals with brittle selectors.
+- Keep UI-kit compatibility wrappers thin enough that design updates from
+  `gnexus-ui-kit` are visible without rewriting feature components.
+
+## Accessibility Baseline
+
+- Buttons must use real `<button>` elements.
+- Modals must trap focus or rely on UI-kit dialog behavior.
+- Inputs must have labels.
+- Loading states must not remove context.
+- Danger actions require confirmation.
diff --git a/webclient-vue/docs/current-client-map.md b/webclient-vue/docs/current-client-map.md
new file mode 100644
index 0000000..cd0a0e1
--- /dev/null
+++ b/webclient-vue/docs/current-client-map.md
@@ -0,0 +1,87 @@
+# Current Client Map
+
+Reference implementation: `webclient/`.
+
+## Entry Points
+
+- `webclient/index.php` - page shell.
+- `webclient/ui.php` - UI component preview/demo shell.
+- `webclient/src/js/index.js` - initializes globals, API client, HUD, routing.
+- `webclient/src/js/routes.js` - hash routes.
+- `webclient/src/js/sh/SmartHomeApi.js` - callback-style API client.
+- `webclient/proxy.php` - local proxy to backend API.
+
+## Build
+
+- `npm start` runs Gulp.
+- SCSS entry: `webclient/src/scss/main.scss`.
+- JS entry: `webclient/src/js/index.js`.
+- JS output: `webclient/dist/js/main.js`.
+- CSS output: `webclient/dist/css/main.css`.
+
+## Global Runtime Objects
+
+The current client relies on global mutable objects:
+
+- `DataProvider`
+- `FavoritesStore`
+- `Toasts`
+- `Helper`
+- `Modals`
+- `confirmPopup`
+- `advancedSelect`
+- `editableString`
+- `Screens`
+
+The new Vue client should replace these with explicit imports, stores,
+composables, and component-local state.
+
+## Routes
+
+| Route | Current Module | Purpose |
+| --- | --- | --- |
+| `/` | `routes.js` | Redirects to `/areas/favorites`. |
+| `/devices` | `devices-list-screen.js` | Registered devices list with live state. |
+| `/devices/scanning` | `devices-scanning-screen.js` | Network scan and setup entry point. |
+| `/scripts/scopes` | `scripts-scopes-screen.js` | Control script scopes list and enable/disable. |
+| `/scripts/regular` | `scripts-regular-screen.js` | Regular scripts list and enable/disable. |
+| `/scripts/actions` | `scripts-actions-screen.js` | Action scripts grid and run buttons. |
+| `/areas/tree` | `areas-tree-screen.js` | Areas tree with details/devices/actions/favorites. |
+| `/areas/favorites` | `areas-favorites-screen.js` | Favorite areas dashboard. |
+| fallback | `routes.js` | 404 screen. |
+
+## Navigation Groups
+
+Devices:
+
+- Devices
+- Scanning
+
+Scripts:
+
+- Scopes
+- Actions
+- Regular
+
+Areas:
+
+- Favorites
+- Tree
+
+## Important Existing Behavior
+
+- Device state is loaded per row through `GET /api/v1/devices/id/{id}/status`.
+- Offline/lost devices should not block the whole list.
+- Action script cards run scripts on click and show toast result.
+- Area tree supports local favorite toggling through `FavoritesStore`.
+- Area device modal can reboot individual devices and reboot all devices in an area.
+- Screen reload is often done through `Screens.reinit()` after mutations.
+
+## Known Current-Client Limitations
+
+- Callback-based API layer.
+- Manual DOM rendering and event binding.
+- Many global dependencies.
+- Weak type guarantees for backend responses.
+- Some modals duplicate table/device-state behavior.
+- API errors are mostly surfaced as generic UI errors.
diff --git a/webclient-vue/docs/migration-plan.md b/webclient-vue/docs/migration-plan.md
new file mode 100644
index 0000000..6a81947
--- /dev/null
+++ b/webclient-vue/docs/migration-plan.md
@@ -0,0 +1,120 @@
+# Migration Plan
+
+## Phase 1 - Specification And Contracts
+
+- Document current routes and workflows.
+- Document API calls and response shapes.
+- Identify backend gaps that block a clean Vue client.
+- Confirm JavaScript-only implementation.
+- Decide exact `gnexus-ui-kit` installation method.
+
+Deliverable:
+
+- Complete docs in `webclient-vue/docs/`.
+
+## Phase 2 - Project Scaffold
+
+- Create Vue app under `webclient-vue/`.
+- Configure build tooling.
+- Add `gnexus-ui-kit`.
+- Add router.
+- Add API client wrapper.
+- Add app shell, layout, navigation, toast, modal, and error state primitives.
+
+Deliverable:
+
+- New client opens locally and can call `GET /api/v1/areas/list`.
+
+### Phase 2.1 - Minimal Vertical Slice
+
+Build the smallest complete app slice:
+
+- App shell.
+- Hash router.
+- API client.
+- Areas API module.
+- Favorites localStorage store with key `sh_fav_areas`.
+- `/areas/favorites` page.
+- Loading, empty, and error state components.
+
+Acceptance criteria:
+
+- Running the dev server opens the Vue client.
+- `/` redirects to `/areas/favorites`.
+- `/areas/favorites` calls the backend areas list endpoint.
+- Existing favorite ids from localStorage are respected.
+- Empty favorites state is rendered correctly.
+- No old `webclient/src/js` code is imported.
+- UI-kit access is isolated behind local adapter components, even if adapters are
+  initially minimal.
+
+## Phase 3 - Read-Only Screens
+
+Implement without mutations first:
+
+- Areas favorites.
+- Areas tree.
+- Devices list.
+- Devices scanning list.
+- Scripts actions list.
+- Scripts regular list.
+- Scripts scopes list.
+
+Deliverable:
+
+- New client can display the same operational data as the current client.
+
+## Phase 4 - Mutations And Modals
+
+Implement user actions:
+
+- Run action script.
+- Enable/disable regular scripts.
+- Enable/disable scopes.
+- Device details.
+- Device reboot.
+- Device setup.
+- Area details.
+- Area create/edit.
+- Area devices modal.
+- Area actions modal.
+
+Deliverable:
+
+- New client covers daily operational workflows.
+
+## Phase 5 - Hardening
+
+- Add concurrency limits to device live-state loading.
+- Add request cancellation on route leave/modal close.
+- Add normalized error handling.
+- Add stale data and retry states.
+- Add smoke checklist.
+
+Deliverable:
+
+- New client is safe to use as primary UI.
+
+## Phase 6 - Switch-Over
+
+- Keep old `webclient/` available as fallback.
+- Serve new client on the chosen route/domain.
+- Monitor backend logs and user-reported issues.
+- Remove or archive old client only after a stable period.
+
+## Open Decisions
+
+- Vue state library: Pinia or lightweight composables only.
+- Router mode: hash mode for compatibility or history mode with server config.
+- How to consume `gnexus-ui-kit` as an updatable dependency: package/git dependency preferred, submodule only if necessary.
+- Whether to keep `proxy.php` or use direct backend API from the new dev server.
+
+## Current Recommendations
+
+- Use JavaScript.
+- Use Pinia.
+- Use hash router for the first production-capable version.
+- Keep `proxy.php` compatibility in the API client, but allow direct backend URL
+  through environment variables.
+- Integrate `gnexus-ui-kit` through local adapter components, not direct imports
+  across feature code.
diff --git a/webclient-vue/docs/overview.md b/webclient-vue/docs/overview.md
new file mode 100644
index 0000000..bd4371d
--- /dev/null
+++ b/webclient-vue/docs/overview.md
@@ -0,0 +1,70 @@
+# Overview
+
+## Goal
+
+Build a new SHServ web client in parallel with the existing vanilla JS client.
+The new client should use Vue and `gnexus-ui-kit`, while preserving the current
+smart-home workflows:
+
+- Monitor devices and their live states.
+- Scan and set up new devices.
+- Run action scripts.
+- Enable/disable regular scripts and scopes.
+- Browse areas as a tree.
+- Manage favorite areas.
+- Open area-specific devices and actions.
+
+## Non-Goals For The First Phase
+
+- Rewriting the PHP backend.
+- Changing device firmware contracts.
+- Removing the current `webclient/`.
+- Implementing server-side auth unless backend work is explicitly scheduled.
+- Replacing automation logic in `ControlScripts`.
+
+## Target Architecture
+
+The new client should be a separate frontend application under `webclient-vue/`.
+It should communicate with the existing backend through the same HTTP API used by
+the current client.
+
+Recommended high-level structure:
+
+```text
+webclient-vue/
+  docs/
+  src/
+    app/
+    api/
+    components/
+    features/
+      areas/
+      devices/
+      scripts/
+    router/
+    stores/
+    styles/
+```
+
+## Design Direction
+
+Use `gnexus-ui-kit` as the primary UI foundation and keep it as a live,
+updatable design dependency. The first implementation pass should prioritize
+compatibility with UI-kit updates, consistency, state clarity, and operational
+reliability over visual experimentation.
+
+Important UI states:
+
+- Loading
+- Empty
+- Error
+- Offline device
+- Action in progress
+- Action success
+- Action failure
+
+## Compatibility Boundary
+
+The current client uses `proxy.php` with a `path=/api/v1/...` query parameter.
+The new client may use the same proxy in local development, but API access should
+be wrapped behind a dedicated API client so the transport can be changed later.
diff --git a/webclient-vue/docs/scaffold.md b/webclient-vue/docs/scaffold.md
new file mode 100644
index 0000000..7389c41
--- /dev/null
+++ b/webclient-vue/docs/scaffold.md
@@ -0,0 +1,234 @@
+# Vue Client Scaffold Specification
+
+## Recommended Stack
+
+- Vue 3
+- Vite
+- Vue Router
+- Pinia
+- JavaScript
+- `gnexus-ui-kit` for UI primitives and design system
+
+Project decision: do not use TypeScript. Reliability should come from a small
+API normalization layer, explicit mappers, and runtime response validation where
+backend shapes are uncertain.
+
+## Directory Layout
+
+```text
+webclient-vue/
+  docs/
+  public/
+  src/
+    app/
+      App.vue
+      main.js
+      providers.js
+    api/
+      client.js
+      errors.js
+      http.js
+      mappers.js
+      modules/
+        areas.js
+        devices.js
+        scripts.js
+      schemas/
+        areas.js
+        common.js
+        devices.js
+        scripts.js
+    assets/
+    components/
+      app/
+      data/
+      feedback/
+      forms/
+      layout/
+      overlays/
+    features/
+      areas/
+      devices/
+      scripts/
+    router/
+      index.js
+      routes.js
+    stores/
+      areas.js
+      devices.js
+      favorites.js
+      scripts.js
+      ui.js
+    styles/
+      main.scss
+      tokens.scss
+    utils/
+      concurrency.js
+      dates.js
+      format.js
+      storage.js
+  index.html
+  package.json
+  vite.config.js
+```
+
+## Route Mode
+
+Use hash mode first.
+
+Reason:
+
+- Current client uses `#!/...`.
+- Hash mode does not require web server rewrite configuration.
+- It reduces deployment risk while the old and new clients coexist.
+
+Target route mapping:
+
+| Route | Component |
+| --- | --- |
+| `/` | Redirect to `/areas/favorites`. |
+| `/devices` | `features/devices/pages/DevicesListPage.vue` |
+| `/devices/scanning` | `features/devices/pages/DevicesScanningPage.vue` |
+| `/scripts/actions` | `features/scripts/pages/ScriptActionsPage.vue` |
+| `/scripts/regular` | `features/scripts/pages/ScriptRegularPage.vue` |
+| `/scripts/scopes` | `features/scripts/pages/ScriptScopesPage.vue` |
+| `/areas/favorites` | `features/areas/pages/AreaFavoritesPage.vue` |
+| `/areas/tree` | `features/areas/pages/AreaTreePage.vue` |
+| fallback | `features/system/NotFoundPage.vue` |
+
+Future option:
+
+- Switch to history mode after nginx/apache routing is explicitly configured.
+
+## Environment Variables
+
+Use Vite environment variables:
+
+```text
+VITE_API_BASE_URL=http://smart-home-serv.local
+VITE_API_PROXY_PATH=/proxy.php
+VITE_API_TIMEOUT_MS=10000
+```
+
+For local development with Vite dev server:
+
+```text
+VITE_API_BASE_URL=http://localhost:5173
+VITE_API_PROXY_PATH=/proxy.php
+```
+
+If `proxy.php` remains in the old `webclient/` directory during development,
+either:
+
+- copy/adapt it into `webclient-vue/public/proxy.php` for PHP-served deployment;
+- or configure Vite dev proxy and call backend directly in dev.
+
+## API Client Requirements
+
+The API client should be promise-based:
+
+```ts
+const result = await devicesApi.list();
+
+if (!result.ok) {
+  // normalized error
+  return;
+}
+
+const devices = result.data.devices;
+```
+
+No UI component should parse raw backend envelopes directly.
+
+Layering:
+
+- `http.js` - low-level fetch, timeout, abort, proxy path wrapping.
+- `client.js` - common request helpers and response normalization.
+- `modules/*.js` - domain-specific methods.
+- `mappers.js` - response field unification currently done by `Helper`.
+- `schemas/*.js` - lightweight runtime validators for uncertain response shapes.
+
+## UI Kit Integration Contract
+
+The `gnexus-ui-kit` repository was not available from this environment, so exact
+package exports are intentionally not assumed in this spec.
+
+Acceptable integration options, in preferred order:
+
+1. Install as package/git dependency if it exposes Vue components or CSS assets.
+2. Use a git dependency pinned by commit/tag in the lockfile.
+3. Add as git submodule only if package/git dependency is not viable.
+4. Avoid copying a versioned release into the project because the UI-kit updates
+   often and should remain a live design dependency.
+
+Whichever option is chosen, create one local compatibility layer:
+
+```text
+src/components/ui/
+  UiButton.vue
+  UiBadge.vue
+  UiCard.vue
+  UiDialog.vue
+  UiInput.vue
+  UiSelect.vue
+  UiTable.vue
+  UiToast.vue
+```
+
+Application code should prefer local compatibility components for app-specific
+behavior, but these components must remain thin and track UI-kit public APIs.
+The goal is full UI-kit update compatibility, not a forked component library.
+
+## Initial Dependencies
+
+Expected package dependencies:
+
+```json
+{
+  "dependencies": {
+    "@vitejs/plugin-vue": "latest",
+    "vite": "latest",
+    "vue": "latest",
+    "vue-router": "latest",
+    "pinia": "latest"
+  },
+  "devDependencies": {
+  }
+}
+```
+
+Add exact `gnexus-ui-kit` dependency only after its packaging format is known.
+
+## Build Scripts
+
+Recommended scripts:
+
+```json
+{
+  "scripts": {
+    "dev": "vite --host 0.0.0.0",
+    "build": "vite build",
+    "preview": "vite preview --host 0.0.0.0"
+  }
+}
+```
+
+## First Milestone Scaffold
+
+Minimum files for the first working milestone:
+
+- `src/app/main.js`
+- `src/app/App.vue`
+- `src/router/index.js`
+- `src/router/routes.js`
+- `src/api/client.js`
+- `src/api/modules/areas.js`
+- `src/stores/areas.js`
+- `src/features/areas/pages/AreaFavoritesPage.vue`
+- `src/components/layout/AppShell.vue`
+- `src/components/feedback/AppErrorState.vue`
+- `src/components/feedback/AppLoadingState.vue`
+
+The first milestone is complete when `/areas/favorites` can call
+`GET /api/v1/areas/list`, render favorite areas from localStorage, and show an
+empty state without using any code from the old client.
diff --git a/webclient-vue/docs/screens.md b/webclient-vue/docs/screens.md
new file mode 100644
index 0000000..5b132c8
--- /dev/null
+++ b/webclient-vue/docs/screens.md
@@ -0,0 +1,461 @@
+# Screens Specification
+
+## App Shell
+
+The new client should provide:
+
+- Persistent top header with app name and global actions.
+- Section navigation for Devices, Scripts, and Areas.
+- Route-level loading, error, and empty states.
+- Toast notifications.
+- Confirmation dialogs.
+- Reusable modal/dialog system.
+
+Initial route:
+
+- `/` redirects to `/areas/favorites`.
+
+## Devices List
+
+Route:
+
+- `/devices`
+
+Data:
+
+- `GET /api/v1/devices/list`
+- Per active row: `GET /api/v1/devices/id/{id}/status`
+
+Table columns:
+
+- Device name
+- Connection status
+- Live state
+- IP
+- Actions
+
+Required behavior:
+
+- Render DB list first.
+- Load live state independently per device.
+- Skip live status request for devices with `connection_status = lost`.
+- Limit concurrent status requests.
+- Show per-row loading.
+- Show per-row offline/error state.
+- Provide Details action.
+- Provide Reboot action with confirmation or clear feedback.
+
+## Devices Scanning
+
+Route:
+
+- `/devices/scanning`
+
+Data:
+
+- `GET /api/v1/devices/scanning/all`
+
+Table columns:
+
+- Device ID
+- Device name
+- Type
+- Status
+- IP
+- MAC
+- WiFi signal
+- Actions
+
+Required behavior:
+
+- Show setup button only for devices in `setup` status.
+- Setup flow should collect alias, name, and description.
+- On successful setup, refresh list and show success toast.
+
+### Device Setup Modal
+
+Opened from:
+
+- Devices Scanning screen.
+
+Source data:
+
+- Scanned device object from `/api/v1/devices/scanning/all`.
+
+Read-only device fields:
+
+- All public fields returned by `/about` after current field unification.
+- Typical fields: `device_id`, `name`, `type`, `status`, `ip`, `mac`,
+  `wifi_signal`, firmware/core fields.
+
+Form fields:
+
+- `alias` - required.
+- `name` - required.
+- `description` - optional textarea.
+
+Submit endpoint:
+
+- `POST /api/v1/devices/setup/new-device`
+
+Payload:
+
+```json
+{
+  "device_ip": "192.168.2.42",
+  "alias": "kitchen_relay",
+  "name": "Kitchen relay",
+  "description": "Optional description"
+}
+```
+
+Validation:
+
+- Client-side required validation for `alias` and `name`.
+- Server-side `failed_fields` should mark matching form fields.
+- Server-side `msg` should be shown in an inline alert.
+
+Success behavior:
+
+- Close modal.
+- Refresh current screen data.
+- Show success toast.
+
+## Scripts Actions
+
+Route:
+
+- `/scripts/actions`
+
+Data:
+
+- `GET /api/v1/scripts/actions/list`
+- `POST /api/v1/scripts/actions/run`
+
+Required behavior:
+
+- Render scripts as action cards.
+- Card shows icon, name, description, and enabled/disabled visual state.
+- Clicking card content runs script.
+- Details action opens script details.
+- Show in-progress state per card.
+- Show success/failure toast.
+- Refresh after successful run if current backend behavior requires it.
+
+## Scripts Regular
+
+Route:
+
+- `/scripts/regular`
+
+Data:
+
+- `GET /api/v1/scripts/regular/list`
+- `GET /api/v1/scripts/regular/alias/{alias}/enable`
+- `GET /api/v1/scripts/regular/alias/{alias}/disable`
+
+Required behavior:
+
+- Table with alias, name, filename/path, state, actions.
+- Enable/disable button based on current state.
+- Show in-progress state per button.
+- Refresh after state mutation.
+
+## Scripts Scopes
+
+Route:
+
+- `/scripts/scopes`
+
+Data:
+
+- `GET /api/v1/scripts/scopes/list`
+- `GET /api/v1/scripts/scopes/name/{name}/enable`
+- `GET /api/v1/scripts/scopes/name/{name}/disable`
+
+Required behavior:
+
+- Table with scope name, filename/path, state, actions.
+- Enable/disable button based on current state.
+- Show in-progress state per button.
+- Refresh after state mutation.
+
+## Areas Tree
+
+Route:
+
+- `/areas/tree`
+
+Data:
+
+- `GET /api/v1/areas/list`
+
+Required behavior:
+
+- Build tree from flat list using `parent_id`.
+- Protect against self-reference and cycles.
+- Root nodes are areas without valid parent.
+- Render children collapsible by branch.
+- Area row actions:
+  - Actions
+  - Devices
+  - Details
+  - Favorite toggle
+- Create area button opens create modal.
+
+## Areas Favorites
+
+Route:
+
+- `/areas/favorites`
+
+Data:
+
+- `GET /api/v1/areas/list`
+- Local favorites store.
+
+Required behavior:
+
+- Render only favorite areas.
+- Empty state when no favorites.
+- Area row actions:
+  - Actions
+  - Devices
+  - Remove from favorites
+
+Favorite persistence:
+
+- Current client uses local storage through `FavoritesStore`.
+- New client should preserve local-only favorite behavior unless backend support is added.
+
+## Area Devices Modal
+
+Opened from:
+
+- Areas tree.
+- Areas favorites.
+
+Data:
+
+- `GET /api/v1/areas/id/{area_id}/devices`
+- Device status endpoints per device.
+- `GET /api/v1/devices/id/{id}/reboot`
+- `GET /api/v1/areas/id/{area_id}/reboot_devices`
+
+Required behavior:
+
+- Table with device, connection status, live state, actions.
+- Reuse the same robust state-loading behavior as Devices List.
+- Reboot one device.
+- Reboot all devices in the area.
+- Hide reboot-all if area has no devices.
+- Details action opens Device Details Modal.
+
+## Device Details Modal
+
+Opened from:
+
+- Devices List.
+- Area Devices Modal.
+
+Source data:
+
+- Device object from list or area-device response.
+
+Displayed fields:
+
+- All available device fields as key/value rows.
+- Format `ip`, `mac`, and `device_id` as code values.
+- Format `status` and `connection_status` as badges.
+- Format `last_contact`, `create_at`, and `update_at` as human-readable dates.
+- Render live state through the shared Device State component.
+
+Editable fields:
+
+- `name` through `POST /api/v1/devices/update-name`
+- `description` through `POST /api/v1/devices/update-description`
+- `alias` through `POST /api/v1/devices/update-alias`
+
+Edit behavior:
+
+- Use inline editable text controls.
+- On successful edit, invalidate cached device data and refresh affected views.
+- On failure, restore the original value and show an error toast.
+
+Actions:
+
+- Close.
+- ReSetup through `POST /api/v1/devices/resetup`.
+- Reboot through `GET /api/v1/devices/id/{id}/reboot`.
+- Reset through `POST /api/v1/devices/reset`.
+- Remove through `GET /api/v1/devices/id/{id}/remove`.
+
+Dangerous actions:
+
+- ReSetup, Reset, and Remove require confirmation.
+- Remove should close modal, refresh current screen, and show success/error toast.
+
+Placement:
+
+- Include Place In Area component for device area assignment.
+
+## Area Actions Modal
+
+Opened from:
+
+- Areas tree.
+- Areas favorites.
+
+Data:
+
+- `GET /api/v1/areas/id/{area_id}/scripts`
+- Script action run endpoint.
+
+Required behavior:
+
+- Show scripts/actions assigned to the area.
+- Allow running action scripts.
+- Show empty state when no scripts exist.
+
+## Area Details Modal
+
+Opened from:
+
+- Areas tree.
+
+Required behavior:
+
+- Show area id, display name, alias, type, parent.
+- Allow editing fields covered by backend endpoints.
+- Allow unassigning/moving where current backend supports it.
+
+Displayed fields:
+
+- All available area fields as key/value rows.
+- Format `alias` with link icon.
+- Format `create_at` and `update_at`.
+- Render unsupported `schema` as muted placeholder.
+
+Editable fields:
+
+- `display_name` through `POST /api/v1/areas/update-display-name`
+- `alias` through `POST /api/v1/areas/update-alias`
+
+Actions:
+
+- Close.
+- Remove through `GET /api/v1/areas/id/{area_id}/remove`.
+
+Dangerous actions:
+
+- Remove requires confirmation.
+- On success, invalidate area data, close modal, refresh current screen, and show
+  success toast.
+
+Placement:
+
+- Include Place In Area component for changing `parent_id`.
+
+## Create Area Modal
+
+Opened from:
+
+- Areas Tree.
+
+Form fields:
+
+- `type` - required.
+- `alias` - required.
+- `display_name` - required.
+
+Supporting data:
+
+- `GET /api/v1/areas/types/list`
+
+Submit endpoint:
+
+- `POST /api/v1/areas/new-area`
+
+Payload:
+
+```json
+{
+  "type": "room",
+  "alias": "office",
+  "display_name": "Office"
+}
+```
+
+Required behavior:
+
+- Load area types and provide searchable/selectable type input.
+- Validate all fields as non-empty.
+- Mark fields listed in server `failed_fields`.
+- Show server `msg` in inline alert.
+- On success, close modal, invalidate areas list, refresh screen, and show toast.
+
+## Action Script Details Modal
+
+Opened from:
+
+- Scripts Actions screen.
+- Area Actions Modal where script details are available.
+
+Displayed fields:
+
+- Alias.
+- Description.
+- State badge.
+- Filename.
+- Author.
+- PHP code block with syntax highlighting.
+
+Actions:
+
+- Close.
+- Enable/disable action script through `action_enable` or `action_disable`.
+- Run action script through `POST /api/v1/scripts/actions/run`.
+
+Placement:
+
+- If script has `area_id`, include Place In Area component with type `action`.
+
+Success behavior:
+
+- Enable/disable closes modal, refreshes screen, and shows toast.
+- Run shows button loading state; on success, closes modal and shows toast.
+
+## Place In Area Component
+
+Used by:
+
+- Device Details Modal.
+- Area Details Modal.
+- Action Script Details Modal.
+
+Target types:
+
+- `device` uses `/api/v1/devices/place-in-area` and
+  `/api/v1/devices/id/{id}/unassign-from-area`.
+- `area` uses `/api/v1/areas/place-in-area` and
+  `/api/v1/areas/id/{id}/unassign-from-area`.
+- `action` uses `/api/v1/scripts/place-in-area` and
+  `/api/v1/scripts/id/{id}/unassign-from-area`.
+
+Required behavior:
+
+- Load areas list.
+- Show current parent area display name, or `Area ID {id}` fallback.
+- Hide unassign button when current parent id is `0`.
+- Show searchable area selector.
+- Exclude self from candidate list when target type is `area`.
+- On assignment success, update current parent, invalidate areas data, refresh
+  relevant views, and show success toast.
+- On unassign success, set current parent to `0`, invalidate areas data, refresh
+  relevant views, and show success toast.
+
+Implementation note:
+
+- Current client stores component state in module-level variables, so multiple
+  instances can conflict. The Vue implementation must keep each Place In Area
+  instance state-isolated.
diff --git a/webclient-vue/docs/state-and-components.md b/webclient-vue/docs/state-and-components.md
new file mode 100644
index 0000000..5527e49
--- /dev/null
+++ b/webclient-vue/docs/state-and-components.md
@@ -0,0 +1,208 @@
+# State And Component Model
+
+This document translates current global helpers into target Vue concepts.
+
+## Current Global To Target Mapping
+
+| Current Global | Current Role | Target Vue Concept |
+| --- | --- | --- |
+| `Screens` | Hash routing, route loading/error state, reinit. | Vue Router plus route-level components and query invalidation. |
+| `SmartHomeApi` | Callback API wrapper. | Promise-based API client with normalized result shape. |
+| `DataProvider` | Simple raw data cache. | Pinia stores or composable query cache. |
+| `FavoritesStore` | LocalStorage favorite area ids. | `useFavoritesStore` backed by localStorage. |
+| `Helper.template` | HTML string factories. | Vue components and slots. |
+| `Helper.states` | Button/card loading mutations. | Component props/state. |
+| `Helper.unification` | Field and date normalization. | API mappers and formatting utilities. |
+| `Modals` | Global modal factory. | Dialog/modal components managed by store or local state. |
+| `Toasts` | Global toast factory. | Toast service/store from UI kit or app shell. |
+| `confirmPopup` | Confirmation dialog. | Reusable confirm dialog service. |
+| `advancedSelect` | Searchable select. | UI kit select/autocomplete component. |
+| `editableString` | Inline editing. | Reusable `InlineEditableText` component. |
+
+## Suggested Stores
+
+### `useAreasStore`
+
+Responsibilities:
+
+- Load areas list.
+- Build area tree.
+- Cache area records by id.
+- Invalidate area list after create/update/remove/place operations.
+
+State:
+
+- `areas`
+- `areasById`
+- `isLoading`
+- `error`
+
+### `useDevicesStore`
+
+Responsibilities:
+
+- Load devices list.
+- Load live device status with per-device state.
+- Mark device as offline/lost based on API response.
+- Reboot/reset/remove/setup/update devices.
+
+State:
+
+- `devices`
+- `devicesById`
+- `deviceStatusById`
+- `deviceStatusLoadingById`
+- `deviceStatusErrorById`
+
+### `useScriptsStore`
+
+Responsibilities:
+
+- Load action scripts.
+- Load regular scripts.
+- Load scopes.
+- Run scripts.
+- Enable/disable scripts and scopes.
+
+State:
+
+- `actions`
+- `regular`
+- `scopes`
+- mutation loading state by alias/name.
+
+### `useFavoritesStore`
+
+Responsibilities:
+
+- Persist favorite area ids to localStorage key `sh_fav_areas`.
+- Provide `has`, `add`, `remove`, `toggle`, `getAll`.
+
+Compatibility:
+
+- Preserve current storage key to keep existing user favorites.
+
+## Core Components
+
+### `AppShell`
+
+Owns:
+
+- Header.
+- Main layout.
+- Global navigation.
+- Toast outlet.
+- Modal outlet if a global modal service is used.
+
+### `SectionSidebar`
+
+Props:
+
+- `items`
+- `activeRoute`
+
+Used by:
+
+- Devices section.
+- Scripts section.
+- Areas section.
+
+### `DataTable`
+
+Required features:
+
+- Caption/title.
+- Empty state.
+- Footer/meta area.
+- Cell slots.
+
+### `DeviceState`
+
+Props:
+
+- `deviceId`
+- `deviceType`
+- `initialConnectionStatus`
+
+Required behavior:
+
+- If initial connection status is `lost`, show offline state and do not request
+  live status.
+- Otherwise load status through devices store/API.
+- Show loading, error, and rendered state.
+- Support manual retry.
+
+### `ActionScriptCard`
+
+Props:
+
+- Script action object.
+
+Events:
+
+- `run`
+- `details`
+
+Required behavior:
+
+- Loading state while running.
+- Success flash when run succeeds.
+- Disabled/ warning visual state when script is disabled.
+
+### `InlineEditableText`
+
+Props:
+
+- `modelValue`
+- `multiline`
+- `validate`
+
+Events:
+
+- `save`
+- `cancel`
+
+Required behavior:
+
+- Restore previous value on failed save.
+- Expose loading and error state.
+
+### `PlaceInArea`
+
+Props:
+
+- `targetType`: `area | device | action`
+- `targetId`
+- `currentAreaId`
+
+Required behavior:
+
+- Instance-local state only.
+- Load/select areas.
+- Assign and unassign target.
+- Exclude self when `targetType = area`.
+
+## Request Concurrency
+
+Device status loading should use an explicit concurrency limiter.
+
+Default:
+
+- `4` concurrent live status requests.
+
+Requirements:
+
+- Failed requests must resolve their queue slot.
+- Requests should be cancellable when route or modal is closed.
+- UI should not start live status requests for known `lost` devices.
+
+## Error Taxonomy
+
+The API layer should classify errors as:
+
+- `http_error` - non-2xx response.
+- `api_error` - backend returned `status: false`.
+- `timeout` - client timeout or aborted request due to timeout.
+- `network_error` - fetch/proxy/network failure.
+- `invalid_response` - response shape does not match expected contract.
+- `consumer_error` - UI/component bug; log it, but never report it as network failure.
diff --git a/webclient-vue/docs/ui-kit-integration.md b/webclient-vue/docs/ui-kit-integration.md
new file mode 100644
index 0000000..ce6fa8b
--- /dev/null
+++ b/webclient-vue/docs/ui-kit-integration.md
@@ -0,0 +1,179 @@
+# gnexus-ui-kit Integration Notes
+
+Repository:
+
+```text
+https://git.gnexus.space/root/gnexus-ui-kit
+```
+
+The repository content was not available during this documentation pass, so this
+document defines the expected integration strategy rather than exact import
+paths.
+
+## Integration Principles
+
+- `gnexus-ui-kit` is a live design dependency and may update often.
+- The new client should stay compatible with current UI-kit releases.
+- Prefer consuming UI-kit directly as an updatable dependency, not as a copied
+  snapshot.
+- Domain components should remain independent from visual implementation details.
+- Local adapters should be thin compatibility boundaries, not a forked design
+  system.
+- Do not mirror UI-kit CSS variables/design tokens unless there is no other
+  stable integration path.
+
+## Adapter Components
+
+Create thin wrappers for the primitives the smart-home client needs:
+
+| Adapter | Required Capability |
+| --- | --- |
+| `UiButton` | variants, size, icon slot, loading, disabled. |
+| `UiBadge` | variants for success/warning/error/info/neutral. |
+| `UiCard` | clickable action-card layout. |
+| `UiDialog` | title, body, footer/actions, close behavior. |
+| `UiInput` | text input with label, error, hint. |
+| `UiTextarea` | multiline input with label, error, hint. |
+| `UiSelect` | searchable select/autocomplete. |
+| `UiTable` | caption, header, body slots, empty state, footer/meta. |
+| `UiToast` | success/error/warning/info notifications. |
+| `UiConfirmDialog` | confirmation for dangerous actions. |
+
+## Variant Mapping From Current Client
+
+Current button classes:
+
+- `btn-primary`
+- `btn-secondary`
+- `btn-accent`
+- `btn-info`
+- `btn-danger`
+- `btn-warning`
+- `btn-success`
+
+Target semantic variants:
+
+| Current | Target Variant |
+| --- | --- |
+| `primary` | `primary` |
+| `secondary` | `secondary` |
+| `accent` | `accent` |
+| `info` | `info` |
+| `danger` | `danger` |
+| `warning` | `warning` |
+| `success` | `success` |
+
+Current badge classes:
+
+- `badge-success`
+- `badge-warning`
+- `badge-error`
+- `badge-primary`
+- `badge-primary-outline`
+
+Target semantic variants:
+
+| Current | Target Variant |
+| --- | --- |
+| `badge-success` | `success` |
+| `badge-warning` | `warning` |
+| `badge-error` | `danger` |
+| `badge-primary` | `primary` |
+| `badge-primary-outline` | `primary-outline` |
+
+## Smart-Home Specific Wrappers
+
+Build domain wrappers on top of UI adapters:
+
+- `DeviceConnectionBadge`
+- `DeviceStateBadges`
+- `ScriptStateBadge`
+- `ActionScriptCard`
+- `AreaTreeNode`
+- `PlaceInArea`
+
+These wrappers should hide backend-specific state names from low-level UI
+components. They should preserve UI-kit semantics and props as much as possible.
+
+## Dependency Strategy
+
+Acceptable integration options, in preferred order:
+
+1. Install as package/git dependency if it exposes Vue components or CSS assets.
+2. Use a git dependency pinned by commit/tag in the lockfile.
+3. Add as git submodule only if package/git dependency is not viable.
+4. Copying a release into the project is a last resort and should be avoided
+   because it breaks live design updates.
+
+Application code should usually import local adapters, not UI-kit internals
+directly. The adapters exist for app-specific defaults and compatibility.
+
+Allowed exception:
+
+- If UI-kit provides stable Vue components with a clear public API, feature code
+  may import those components directly for simple cases. Complex domain
+  components should still use local wrappers to centralize smart-home behavior.
+
+## Update Compatibility Policy
+
+The client should support routine UI-kit updates.
+
+Requirements:
+
+- Keep UI-kit as a dependency with a lockfile.
+- Do not copy UI-kit source files into app components.
+- Do not override UI-kit internals by selector unless explicitly documented.
+- Prefer documented CSS variables, component props, and public classes.
+- Keep app-specific styles in a narrow namespace.
+- Add a smoke checklist for UI-kit updates.
+- Avoid local wrappers that permanently freeze old UI-kit markup.
+
+Update workflow:
+
+1. Update `gnexus-ui-kit` dependency.
+2. Run build.
+3. Run UI smoke checklist.
+4. Fix adapter compatibility if public API changed.
+5. Commit dependency lockfile and adapter changes together.
+
+Smoke checklist:
+
+- App shell and navigation.
+- Buttons and loading states.
+- Badges for device/script states.
+- Tables.
+- Dialogs/modals.
+- Toasts.
+- Inputs and validation errors.
+- Select/autocomplete.
+- Action cards.
+- Area tree layout.
+
+## Evaluation Checklist
+
+Before committing to the UI-kit integration method, verify:
+
+- Does it provide Vue components or only CSS/assets?
+- Does it require a build step?
+- Does it expose CSS variables or SCSS sources?
+- Does it include icons?
+- Does it include modal/toast/select/table primitives?
+- Does it support tree-shaking?
+- Is it installable through npm/git URL?
+
+## Fallback Plan
+
+If the UI-kit is CSS-only:
+
+- Use it for tokens, base classes, and layout primitives.
+- Implement Vue components locally in `src/components/ui`.
+- Keep adapter names the same so future migration to UI-kit Vue components is
+  possible.
+- Keep wrappers thin and class-driven, so UI-kit CSS updates apply automatically.
+
+If the UI-kit is not immediately usable:
+
+- Scaffold with local adapters using minimal styles.
+- Keep visual implementation intentionally thin.
+- Replace adapter internals when UI-kit access/API is clarified.
+- Do not build a parallel permanent design system in `webclient-vue`.