feat(api, web): enhance agent management and linting capabilities

- Added a new linting command for OpenAPI specifications in the package.json, improving code quality checks.
- Updated frontend documentation to clarify component usage and structure, including detailed descriptions for `SettingsShell` and `Auth callback`.
- Refactored agent-related API routes to streamline control-plane functionalities, consolidating multiple routes for better organization.
- Improved error handling in the API to provide more informative responses for validation errors, enhancing user feedback during interactions.

These changes enhance the overall development experience and improve the management of agents within the application.

docs/README.md

@@ -5,4 +5,9 @@
 - [EvoBGP](integrate-evobgp.md)
 - [Agents](agents.md)
 - [UI design contract](ui-design-contract.md)
-- [OpenAPI](openapi.yaml)
+- [OpenAPI](openapi.yaml) — **HTTP SoT** (пути/операции). Живая валидация request bodies — Zod в `@evofw/shared`.
+
+```bash
+# Lint OpenAPI (requires npx)
+npx --yes @redocly/cli lint docs/openapi.yaml
+```

docs/openapi.yaml

@@ -1,58 +1,418 @@
 openapi: 3.0.3
 info:
   title: EvoFirewall API
-  version: 0.1.0
-  description: Centralized firewall control plane
+  version: 0.2.0
+  description: |
+    Centralized firewall control plane.
+
+    **HTTP SoT:** this OpenAPI document.
+    **Runtime validation:** Zod schemas in `@evofw/shared` (authoritative for request bodies).
+servers:
+  - url: http://localhost:8080
+    description: Local API
+security: []
 paths:
   /health:
     get:
       summary: Liveness
+      tags: [system]
       responses:
         '200':
           description: OK
+
   /api/v1/dashboard:
     get:
       summary: Dashboard KPI
+      tags: [ops]
       security: [{ bearerAuth: [] }]
       responses:
         '200':
           description: Stats
+
+  /api/v1/install-context:
+    get:
+      summary: Public install base URL + enroll seed hint
+      tags: [ops]
+      security: [{ bearerAuth: [] }]
+      responses:
+        '200':
+          description: Install context
+
+  /api/v1/install-links:
+    get:
+      summary: List install links
+      tags: [agents]
+      security: [{ bearerAuth: [] }]
+      responses:
+        '200':
+          description: Links
+    post:
+      summary: Create install link + invited agent
+      tags: [agents]
+      security: [{ bearerAuth: [] }]
+      responses:
+        '201':
+          description: Created
+
+  /api/v1/install-links/{id}:
+    delete:
+      summary: Revoke install link
+      tags: [agents]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: Revoked
+
   /api/v1/agents:
     get:
       summary: List agents
+      tags: [agents]
       security: [{ bearerAuth: [] }]
       responses:
         '200':
           description: Agents
+
+  /api/v1/agents/{id}:
+    get:
+      summary: Get agent
+      tags: [agents]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: Agent
+    patch:
+      summary: Update agent
+      tags: [agents]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: Updated
+    delete:
+      summary: Delete agent
+      tags: [agents]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: Deleted
+
+  /api/v1/agents/{id}/approve:
+    post:
+      summary: Approve pending/invited agent
+      tags: [agents]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: Approved
+
+  /api/v1/agents/{id}/revoke:
+    post:
+      summary: Revoke agent
+      tags: [agents]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: Revoked
+
+  /api/v1/agents/{id}/preview:
+    get:
+      summary: Policy preview (truncated CIDRs)
+      tags: [agents]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+        - name: limit_cidrs
+          in: query
+          schema: { type: integer, default: 50, maximum: 5000 }
+      responses:
+        '200':
+          description: Preview
+
+  /api/v1/agents/{id}/policy-sets:
+    get:
+      summary: Assigned policy sets
+      tags: [agents]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: Sets
+    put:
+      summary: Replace assigned policy sets (order = sort)
+      tags: [agents]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: Updated
+
+  /api/v1/agents/{id}/overrides:
+    get:
+      summary: List IP overrides
+      tags: [agents]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: Overrides
+    post:
+      summary: Create override
+      tags: [agents]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: Created
+
+  /api/v1/agents/{id}/overrides/{overrideId}:
+    delete:
+      summary: Delete override
+      tags: [agents]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+        - name: overrideId
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        '200':
+          description: Deleted
+
   /api/v1/lists:
     get:
       summary: List IP lists
+      tags: [lists]
       security: [{ bearerAuth: [] }]
       responses:
         '200':
           description: Lists
     post:
       summary: Create IP list
+      tags: [lists]
       security: [{ bearerAuth: [] }]
       responses:
         '200':
           description: Created
+
+  /api/v1/lists/{id}:
+    get:
+      summary: List detail + entries
+      tags: [lists]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: Detail
+    delete:
+      summary: Delete list
+      tags: [lists]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: Deleted
+
+  /api/v1/lists/{id}/refresh:
+    post:
+      summary: Refresh remote/json/evobgp list
+      tags: [lists]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: Refreshed
+
+  /api/v1/lists/{id}/entries:
+    post:
+      summary: Add manual entries
+      tags: [lists]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: Updated
+    delete:
+      summary: Delete entry
+      tags: [lists]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: Deleted
+
+  /api/v1/policy-sets:
+    get:
+      summary: List policy sets
+      tags: [policies]
+      security: [{ bearerAuth: [] }]
+      responses:
+        '200':
+          description: Sets
+    post:
+      summary: Create policy set
+      tags: [policies]
+      security: [{ bearerAuth: [] }]
+      responses:
+        '200':
+          description: Created
+
+  /api/v1/policy-sets/{id}:
+    get:
+      summary: Get policy set
+      tags: [policies]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: Set
+    patch:
+      summary: Patch policy set
+      tags: [policies]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: Updated
+    delete:
+      summary: Delete policy set
+      tags: [policies]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: Deleted
+
+  /api/v1/policy-sets/{id}/rules:
+    get:
+      summary: Rules in set
+      tags: [policies]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: Rules
+
+  /api/v1/policy-sets/{id}/rules/reorder:
+    put:
+      summary: Reorder rules in a set
+      tags: [policies]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: Reordered
+
   /api/v1/rules:
     get:
-      summary: List policy rules
+      summary: List policy rules (optional set filter)
+      tags: [policies]
       security: [{ bearerAuth: [] }]
       responses:
         '200':
           description: Rules
     post:
       summary: Create policy rule
+      tags: [policies]
       security: [{ bearerAuth: [] }]
       responses:
         '200':
           description: Created
+
+  /api/v1/rules/{id}:
+    patch:
+      summary: Patch rule
+      tags: [policies]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: Updated
+    delete:
+      summary: Delete rule
+      tags: [policies]
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: Deleted
+
+  /api/v1/stats/recent:
+    get:
+      summary: Recent apply samples
+      tags: [ops]
+      security: [{ bearerAuth: [] }]
+      responses:
+        '200':
+          description: Samples
+
+  /api/v1/integrations/evobgp/communities:
+    get:
+      summary: Proxy EvoBGP communities
+      tags: [integrations]
+      security: [{ bearerAuth: [] }]
+      responses:
+        '200':
+          description: Communities
+
+  /api/v1/settings:
+    get:
+      summary: Settings map (token masked)
+      tags: [settings]
+      security: [{ bearerAuth: [] }]
+      responses:
+        '200':
+          description: Settings
+    put:
+      summary: Update whitelisted settings keys
+      tags: [settings]
+      security: [{ bearerAuth: [] }]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties:
+                type: string
+              description: Keys — enroll_seed, evobgp_api_url, evobgp_api_token, agent_sync_interval_sec, show_quick_actions
+      responses:
+        '200':
+          description: Saved
+        '400':
+          description: Unknown key / validation
+
   /api/v1/audit:
     get:
-      summary: Local audit log (dual-write source fw)
+      summary: Local audit log
+      tags: [ops]
       security: [{ bearerAuth: [] }]
       parameters:
         - name: action
@@ -67,31 +427,83 @@ paths:
       responses:
         '200':
           description: Audit entries
+
+  /v1/agent/install.sh:
+    get:
+      summary: Agent install script
+      tags: [agent-public]
+      responses:
+        '200':
+          description: Shell script
+
   /v1/agent/enroll:
     post:
-      summary: Enroll agent (public + seed)
+      summary: Enroll agent (X-EvoFW-Seed)
+      tags: [agent-public]
       responses:
         '201':
           description: Pending agent
+
   /v1/agent/policy:
     get:
       summary: Evaluated policy for agent
+      tags: [agent]
       security: [{ agentToken: [] }]
       responses:
         '200':
           description: Policy
-  /v1/agent/apply-report:
+
+  /v1/agent/policy.rsc:
+    get:
+      summary: MikroTik RSC policy
+      tags: [agent]
+      security: [{ agentToken: [] }]
+      responses:
+        '200':
+          description: RSC text
+
+  /v1/agent/heartbeat:
     post:
-      summary: Apply report + packet stats
+      summary: Agent heartbeat
+      tags: [agent]
       security: [{ agentToken: [] }]
       responses:
         '200':
           description: OK
+
+  /v1/agent/apply-report:
+    post:
+      summary: Apply report + packet stats
+      tags: [agent]
+      security: [{ agentToken: [] }]
+      responses:
+        '200':
+          description: OK
+
 components:
+  parameters:
+    Id:
+      name: id
+      in: path
+      required: true
+      schema: { type: string }
   securitySchemes:
     bearerAuth:
       type: http
       scheme: bearer
+      description: Portal JWT (app id fw)
     agentToken:
       type: http
       scheme: bearer
+      description: Agent enroll token
+
+tags:
+  - name: system
+  - name: ops
+  - name: agents
+  - name: lists
+  - name: policies
+  - name: settings
+  - name: integrations
+  - name: agent-public
+  - name: agent