docs: document server settings API and add API test writing skill

Move the server settings roadmap to implemented/ rewritten per
the documentation standard (architecture and PUT flow diagrams,
endpoint table, design notes). Add a skill covering the pytest
conftest fixture model and the shared-client order-dependency
trap hit while writing the settings tests.

docs/gns3-copilot/implemented/server-settings-api.md

@@ -0,0 +1,103 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+See LICENSE file for licensing information.
+-->
+
+# Server Settings API
+
+## Overview
+
+REST API for reading and updating `gns3_server.conf` at runtime, enabling a server settings page in the Web UI. Updates are persisted with a read-modify-write strategy (unknown options in the file are preserved), validated before anything touches disk, and hot-reloaded into the running server; the response tells the caller which changes require a restart.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    U["Web UI / Client"] -->|"GET /v3/settings"| R["routes/controller/settings.py"]
+    U -->|"PUT /v3/settings"| R
+    R -->|"Server.Audit / Server.Modify"| RBAC["privilege check"]
+    R --> RS["SettingsResponse / SettingsUpdate schemas<br/>(extra=forbid, secret masking)"]
+    RS --> UC["Config.update_config()<br/>read-modify-write"]
+    UC --> FILE["gns3_server.conf<br/>(atomic replace, mode 0600)"]
+    UC --> RN["reload_and_notify()"]
+    RN --> CB["file-watch callbacks<br/>(runtime hot reload)"]
+    R --> NOTIF["notification stream:<br/>settings.updated"]
+```
+
+- **Exposure** — all sections except the deprecated `VirtualBox`/`VMware`: `Server`, `Controller`, `VPCS`, `Dynamips`, `IOU`, `Qemu`, `WebWireshark`. `Controller.jwt_secret_key` is excluded entirely: it is loaded from `<secrets_dir>/gns3_jwt_secret_key` and writing it to the configuration file is a no-op.
+- **Write strategy** — `Config.update_config()` re-reads the configuration files with `configparser`, applies only the submitted options, and atomically rewrites the main configuration file. Comments and formatting are lost (accepted trade-off); options unknown to the schema are preserved.
+- **Validate before write** — the merged view of all configuration files is validated as `ServerConfig` *before* any disk write. A validation error must never reach disk: the `FileWatcher` reload callback would raise and permanently stop polling that file.
+
+## Business Process (PUT)
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant R as PUT /v3/settings
+    participant U as Config.update_config()
+    participant D as gns3_server.conf
+    C->>R: PUT {"Section": {"option": value | null}}
+    R->>R: schema validation (unknown key/section → 422)
+    R->>U: changes (masked/empty secrets skipped)
+    U->>U: locate owning file per option (later file wins)
+    alt option owned by a non-main configuration file
+        U-->>R: ConfigConflictError → 409 (nothing written)
+    else
+        U->>U: set / remove option (null removes, value falls back to default)
+        U->>U: validate merged ServerConfig (failure → 400, file untouched)
+        U->>D: atomic write (.tmp + os.replace, mode 0600)
+        U->>U: reload_and_notify() → runtime hot reload
+        R-->>C: 200 — new values + restart_required
+        R->>C: notification settings.updated (option names only, no values)
+    end
+```
+
+## API Endpoints
+
+| Method | Path | Description | Privilege |
+|--------|------|-------------|-----------|
+| GET | `/v3/settings` | Return all current server settings | `Server.Audit` |
+| PUT | `/v3/settings` | Update and persist server settings | `Server.Modify` |
+
+Request example:
+
+```json
+{
+    "Server": {
+        "report_errors": true,
+        "allowed_interfaces": ["eth0", "lo"],
+        "compute_password": "**********"
+    },
+    "Qemu": {
+        "enable_monitor": false
+    }
+}
+```
+
+Response example (abbreviated):
+
+```json
+{
+    "Server": { "report_errors": true, "allowed_interfaces": ["eth0", "lo"], "...": "..." },
+    "Qemu": { "enable_monitor": false },
+    "restart_required": ["Server.port"]
+}
+```
+
+## Notes
+
+- **Secrets** — `SecretStr` fields are masked in responses. An empty secret (e.g. `compute_password` before the server generates one) serializes as `""` rather than the mask. On PUT, the mask or an empty string means "leave unchanged"; only an explicit new value is written, in clear text like a hand-edited file.
+- **`restart_required`** — options that only take effect after a server restart (bind host/port, protocol, TLS and certificates, port ranges, image/symbol/config paths, GNS3 VM credentials, skills paths, …). Everything else hot-reloads via `Config.instance().settings`.
+- **GET reflects runtime values** — in-memory settings may differ from disk (e.g. the generated `compute_password`, the resolved `secrets_dir`); the mask/empty skip rule guarantees PUT never writes echoed values back.
+- **Privileges** — `Server.Audit`/`Server.Modify` are seeded into the `Administrator` role at table creation only; existing databases need a manual grant. Superadmins bypass RBAC.
+- **Hardening** — the file watcher callback is exception-guarded (`utils/file_watcher.py`): a callback failure is logged instead of silently killing the polling loop.
+
+### Related Files
+
+| File | Role |
+|------|------|
+| `gns3server/config.py` | `Config.update_config()` (read-modify-write, validate-before-write), `reload_and_notify()` |
+| `gns3server/utils/file_watcher.py` | callback exception hardening |
+| `gns3server/schemas/controller/settings.py` | response/update models, `SECRET_MASK` |
+| `gns3server/api/routes/controller/settings.py` | GET/PUT endpoints, `restart_required`, notification |
+| `gns3server/db/models/privileges.py` | `Server.Audit` / `Server.Modify` privilege seeds |

docs/gns3-copilot/roadmap/server-settings-api-roadmap.md

@@ -1,67 +0,0 @@
-<!--
-SPDX-License-Identifier: CC-BY-SA-4.0
-See LICENSE file for licensing information.
--->
-
-> This document is a roadmap/planning document. The described features have not been implemented yet.
-
-
-# Server Settings REST API — Roadmap
-
-## Problem
-
-Currently, `gns3_server.conf` can only be modified by directly editing the file on disk. There is no REST API endpoint to read or write server configuration, which prevents the Web UI from offering a settings page for server parameters.
-
-## Proposed API
-
-```
-GET  /v3/settings  →  Return all current server settings
-PUT  /v3/settings  →  Update and persist server settings
-```
-
-### Implementation Plan
-
-**1. Add `save_config()` to `Config` class** (`gns3server/config.py`)
-
-The `Config` class currently only reads configuration (via `read_config()` / `reload()`). A `save_config()` method is needed to serialize the in-memory `ServerConfig` pydantic model back to INI format and write it to disk.
-
-Serialization details:
-- `bool` → `"True"` / `"False"` (configparser convention)
-- `SecretStr` → `get_secret_value()`
-- `Enum` → `.value`
-- `List[str]` → semi-colon for `additional_images_paths`, comma for `allowed_interfaces`
-- `None` → skip
-
-**2. Add a settings getter/setter** to `Config` to allow programmatic updates to the in-memory settings.
-
-**3. New route file** (`gns3server/api/routes/controller/settings.py`):
-
-- `GET /v3/settings` — returns the full `ServerConfig` as JSON (pydantic automatically masks `SecretStr` fields as `"********"`)
-- `PUT /v3/settings` — accepts `ServerConfig`, merges existing secrets when placeholder values (`"********"`) are submitted, calls `save_config()`, and triggers runtime config update callbacks
-
-Both endpoints require `get_current_active_user` for authentication.
-
-**4. Register the new router** in `gns3server/api/routes/controller/__init__.py` under the `/settings` prefix.
-
-### Security
-
-- All settings endpoints require admin authentication (`get_current_active_user`)
-- `SecretStr` fields (`compute_password`, `default_admin_password`, `jwt_secret_key`) are masked in responses
-- On write, unchanged secrets are preserved via placeholder detection
-
-### Related Files
-
-| File | Role |
-|------|------|
-| `gns3server/config.py` | Config singleton with `read_config()` / `reload()` |
-| `gns3server/schemas/config.py` | `ServerConfig` pydantic model with all 9 sub-models |
-| `gns3server/api/routes/controller/__init__.py` | Controller router mounting |
-| `gns3server/controller/__init__.py` | `Controller._update_config()` for runtime credential sync |
-
-## Status
-
-- [ ] gns3server/config.py: add `save_config()` method
-- [ ] gns3server/config.py: add settings getter/setter
-- [ ] gns3server/api/routes/controller/settings.py: new route file with GET and PUT endpoints
-- [ ] gns3server/api/routes/controller/__init__.py: register settings router under `/settings`
-- [ ] gns3server/api/routes/controller/controller.py: add notification emission on config change