Merge pull request #27 from vyos-contrib/feat/architecture-and-quality-improvements

feat: v0.4.0 - Architecture refactor, bug fixes, and quality improvem…

34 files changed, 980 insertions, 328 deletions

diff --git a/docs/Makefile b/docs/Makefile
deleted file mode 100644
index d0c3cbf..0000000
--- a/docs/Makefile
+++ /dev/null
@@ -1,20 +0,0 @@
-# Minimal makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
-BUILDDIR      = build
-
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-.PHONY: help Makefile
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/api-reference.md b/docs/api-reference.md
new file mode 100644
index 0000000..3cd24bb
--- /dev/null
+++ b/docs/api-reference.md
@@ -0,0 +1,88 @@
+# API Reference
+
+Complete reference for all PyVyOS classes and methods.
+
+## VyDevice Class
+
+Main class for interacting with VyOS devices.
+
+### Constructor
+
+```python
+VyDevice(hostname: str, apikey: str, protocol: "http"|"https" = "https",
+         port: int = 443, verify: bool = True, timeout: int = 10)
+```
+
+**Parameters:** `hostname`, `apikey`, `protocol`, `port` (1-65535), `verify`, `timeout`
+
+### Configuration Methods
+
+- `configure_set(path)`: Set configuration values
+- `configure_delete(path)`: Delete configuration values
+- `configure_multiple_op(op_path)`: Execute multiple operations atomically
+
+```python
+device.configure_set(path=["interfaces", "ethernet", "eth0", "address", "192.168.1.1/24"])
+device.configure_delete(path=["interfaces", "dummy", "dum1"])
+device.configure_multiple_op(op_path=[
+    {"op": "set", "path": [...]},
+    {"op": "delete", "path": [...]}
+])
+```
+
+### Retrieval Methods
+
+- `retrieve_show_config(path)`: Get configuration in show format
+- `retrieve_return_values(path)`: Get specific configuration values
+
+```python
+device.retrieve_show_config(path=["system"])
+device.retrieve_return_values(path=["interfaces", "dummy", "dum1", "address"])
+```
+
+### Operational Methods
+
+- `show(path)`: Execute show commands
+- `generate(path)`: Generate configuration elements
+- `reset(path)`: Reset configuration elements
+
+```python
+device.show(path=["system", "image"])
+device.generate(path=["ssh", "client-key", "/tmp/key"])
+device.reset(path=["conntrack-sync", "internal-cache"])
+```
+
+### File Operations
+
+- `config_file_save(file)`: Save configuration to file
+- `config_file_load(file)`: Load configuration from file
+
+```python
+device.config_file_save(file="/config/backup.config")
+device.config_file_load(file="/config/backup.config")
+```
+
+**Note:** The `path` parameter is automatically included as `[]` for config-file operations, as required by the VyOS API.
+
+### System Operations
+
+- `reboot(path=["now"])`: Reboot the device
+- `poweroff(path=["now"])`: Power off the device
+
+### Image Management
+
+- `image_add(url, file, path)`: Add VyOS system image
+- `image_delete(name, url, file, path)`: Delete a system image
+
+## ApiResponse Class
+
+Response object: `status` (int), `request` (dict, API key removed), `result` (dict), `error` (str|bool)
+
+```python
+response = device.show(path=["system"])
+if response.error:
+    print(f"Error {response.status}: {response.error}")
+else:
+    print(response.result)
+```
+
diff --git a/docs/concepts.md b/docs/concepts.md
new file mode 100644
index 0000000..058d20c
--- /dev/null
+++ b/docs/concepts.md
@@ -0,0 +1,88 @@
+# Concepts
+
+Key concepts and architecture of PyVyOS.
+
+## Architecture Overview
+
+PyVyOS is built on a REST client architecture:
+- `RestClient`: Base class handling HTTP communication
+- `VyDevice`: High-level interface for VyOS operations
+- `ApiResponse`: Standardized response structure
+
+## API Command Structure
+
+VyOS API uses a hierarchical command structure:
+- Commands: `configure`, `retrieve`, `show`, `generate`, `reset`
+- Operations: `set`, `delete`, `showConfig`, `returnValues`
+- Paths: Array representing configuration hierarchy
+
+## Path Format
+
+Paths are always arrays representing the configuration tree:
+
+```python
+# Single path
+["interfaces", "ethernet", "eth0", "address", "192.168.1.1/24"]
+
+# Multiple paths (for configure_set)
+[
+    ["interfaces", "ethernet", "eth0", "address", "192.168.1.1/24"],
+    ["interfaces", "ethernet", "eth0", "description", "Management"]
+]
+```
+
+## Response Handling
+
+All methods return `ApiResponse`:
+- Consistent error checking
+- Sanitized request payloads (API keys removed)
+- Structured result data
+
+## Operation Types
+
+### Configuration Operations
+- `set`: Add or modify configuration
+- `delete`: Remove configuration
+- `showConfig`: Get full configuration
+- `returnValues`: Get specific values
+
+### Operational Commands
+- `show`: Execute show commands
+- `generate`: Generate configurations/keys
+- `reset`: Reset state/cache
+
+## Multi-Operation Requests
+
+`configure_multiple_op` allows atomic operations:
+- Multiple set/delete operations in one API call
+- Transaction-like behavior
+- Better performance than individual calls
+
+## Error Handling Strategy
+
+PyVyOS uses defensive error handling:
+- Network errors captured as exceptions
+- API errors returned in response.error
+- HTTP status codes in response.status
+
+## Security Considerations
+
+- API keys never appear in response.request
+- SSL verification configurable per connection
+- Timeout protection prevents hanging connections
+
+## Connection Lifecycle
+
+1. Initialize VyDevice with connection parameters
+2. Parameters validated on initialization
+3. Each method creates new HTTP request
+4. Responses parsed and returned as ApiResponse
+
+## Best Practices
+
+- Use environment variables for credentials
+- Enable SSL verification in production
+- Handle errors explicitly
+- Use configure_multiple_op for bulk changes
+- Set appropriate timeouts for operations
+
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000..b6634d2
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,84 @@
+# Configuration
+
+Guide to configuring PyVyOS for connecting to VyOS devices.
+
+## Environment Variables
+
+The recommended way to configure PyVyOS is using environment variables with a `.env` file.
+
+### Required Variables
+
+- `VYDEVICE_HOSTNAME`: IP address or hostname of your VyOS device
+- `VYDEVICE_APIKEY`: API key for authentication
+
+### Optional Variables
+
+- `VYDEVICE_PORT`: API port (default: 443)
+- `VYDEVICE_PROTOCOL`: Protocol "http" or "https" (default: https)
+- `VYDEVICE_VERIFY_SSL`: "True" or "False" (default: True)
+
+## .env File Setup
+
+Create a `.env` file in your project root:
+
+```bash
+VYDEVICE_HOSTNAME=192.168.1.1
+VYDEVICE_APIKEY=your-secret-api-key
+VYDEVICE_PORT=443
+VYDEVICE_PROTOCOL=https
+VYDEVICE_VERIFY_SSL=False
+```
+
+## Loading Configuration
+
+```python
+from dotenv import load_dotenv
+import os
+from pyvyos import VyDevice
+
+load_dotenv()
+device = VyDevice(
+    hostname=os.getenv('VYDEVICE_HOSTNAME'),
+    apikey=os.getenv('VYDEVICE_APIKEY'),
+    port=int(os.getenv('VYDEVICE_PORT', 443)),
+    protocol=os.getenv('VYDEVICE_PROTOCOL', 'https'),
+    verify=os.getenv('VYDEVICE_VERIFY_SSL', 'True').lower() == 'true'
+)
+```
+
+## Direct Configuration
+
+Pass parameters directly:
+
+```python
+device = VyDevice(hostname="192.168.1.1", apikey="your-api-key",
+                  port=443, protocol="https", verify=False, timeout=30)
+```
+
+## SSL & Timeout
+
+SSL verification enabled by default. To disable (dev only):
+
+```python
+import urllib3
+urllib3.disable_warnings()
+device = VyDevice(..., verify=False, timeout=60)
+```
+
+## Generating API Key on VyOS
+
+1. SSH into your VyOS device
+2. Run: `configure`
+3. Run: `set system api http interface <interface>`
+4. Run: `set system api http port <port>`
+5. Run: `set system api http api-key <key-name> key <key-value>`
+6. Run: `commit` and `save`
+
+## Security Best Practices
+
+- Never commit `.env` files to version control
+- Use strong API keys
+- Enable SSL verification in production
+- Restrict API access to specific interfaces/IPs on VyOS
+- Rotate API keys regularly
+
diff --git a/docs/development/architecture.md b/docs/development/architecture.md
new file mode 100644
index 0000000..aceda08
--- /dev/null
+++ b/docs/development/architecture.md
@@ -0,0 +1,77 @@
+# Development Architecture (Proposed)
+
+## Goals
+- Strong separation of concerns (transport, domain, specs, utils)
+- Backward compatibility for 0.3.0 via shims
+- Clear public API surface and internal boundaries
+- Minimal maintenance burden for a public, official SDK
+
+## Source Layout (file tree)
+```
+pyvyos/
+  __init__.py            # public API exports (VyDevice, ApiResponse)
+  core/                  # internal, stable layers
+    __init__.py
+    rest_client.py       # RestClient, ApiResponse (transport layer)
+    device.py            # VyDevice (domain layer)
+  specs/                 # optional Pydantic models (validation)
+    __init__.py
+    models.py            # base models (ApiRequest/Response)
+    commands/            # split by responsibility
+      __init__.py
+      configure.py       # set, delete, multiple_op
+      retrieve.py        # show_config, return_values
+      config_file.py     # save, load (path: [])
+      show.py            # show
+      generate.py        # generate
+      reset.py           # reset
+      system.py          # reboot, poweroff
+      image.py           # add, delete
+  utils/                 # reusable helpers (no side effects)
+    __init__.py
+    json.py              # safe_json, redact_key
+    http.py              # timeouts, retries (future)
+    paths.py             # path builder helpers
+    ids.py               # request_id helpers
+  exceptions.py          # typed exceptions (SDKError, HttpError, ApiError)
+  types.py               # public typing aliases if needed
+  device.py              # shim re-export (compat)
+  rest.py                # shim re-export (compat)
+  vyos_api/              # JSON specs (docs/reference, optional at runtime)
+```
+
+## Layers & Responsibilities
+- Transport (core.rest_client): HTTP, payload assembly, response validation
+- Domain (core.device): high-level methods (configure, show, reset, etc.)
+- Specs (specs.*): optional Pydantic models to validate requests/answers
+- Utils: pure helpers (formatting, ids, path building)
+- Shims (device.py, rest.py): ensure 0.3.0 compatibility
+
+## Public API Surface
+- `from pyvyos import VyDevice, ApiResponse`
+- Stable imports; internal moves hidden by shims
+
+## Compatibility Strategy
+- Keep shims until 1.0.0
+- Deprecation policy: warn after N minors, remove at next major
+- Document migration path (import from `pyvyos.core` for new code)
+
+## Data Validation Flow (optional)
+- App builds `path` with utils.paths
+- If validation enabled, use `specs.commands.*` models
+- RestClient serializes payload and executes request
+- Response validated (structure: success/data/error)
+
+## Testing Strategy
+- Unit: core.rest_client and core.device isolated via monkeypatch
+- Contract: JSON fixtures mirror VyOS responses
+- E2E (future): optional with test VyOS VM
+
+## Packaging
+- Include `vyos_api/` only if needed at runtime
+- Otherwise treat it as docs/reference, not required by the package
+
+## Naming & Conventions
+- Use underscores `_` in file and module names
+- One responsibility per module (keep files small)
+- Typed public APIs, specific exceptions, no prints (only logging)
diff --git a/docs/development/quality-and-utils.md b/docs/development/quality-and-utils.md
new file mode 100644
index 0000000..ff78ec2
--- /dev/null
+++ b/docs/development/quality-and-utils.md
@@ -0,0 +1,72 @@
+# Quality, Utils, and Pitfalls
+
+## Goals
+- Reduce regressions and supportability burden
+- Consistent error handling and logging
+- Clear utilities to avoid duplication
+
+## Exceptions (typed)
+- `SDKError` (base)
+- `HttpError(status, message)`
+- `ApiError(message, details=None)`  # when success=False
+- `ValidationError(message)`         # client-side validation
+
+## Logging
+- Use `logging.getLogger("pyvyos")`
+- Include: op, command, status, elapsed_ms, request_id
+- Redact secrets (api key) – via `utils.json.redact_key(data, keys=["key"])`
+- Default INFO; DEBUG guarded by env `PYVYOS_DEBUG=1`
+
+## Timeouts & Retries
+- Default timeout: 10s (configurable)
+- No implicit retries by default
+- Future: retry idempotent ops only (exponential backoff)
+
+## Security
+- `verify=True` by default
+- Document `urllib3.disable_warnings()` only for dev
+- Never log secrets or full payloads by default
+
+## Utilities (proposal)
+- `utils.paths.build(*segments) -> list[str]`
+- `utils.ids.request_id() -> str`
+- `utils.json.safe_dumps(obj) -> str` (with redaction)
+- `utils.http.timeout(seconds) -> int` (normalize)
+
+## Validation (optional)
+- `specs.commands.*` Pydantic models validate request structures
+- Enforce path rules (e.g., config-file requires `path=[]`)
+- Gate behind feature flag or optional dependency group
+
+## Testing
+- Unit: small, isolated, no real I/O
+- Contract: success/error fixtures per command
+- Naming: `test_should_<do>_when_<condition>`
+- Use monkeypatch on `_execute_request`
+
+## Documentation
+- Keep developer docs scoped and short (≤100 lines)
+- Update api-reference and path rules on changes
+
+## Style & Types
+- Type hints on public APIs, avoid `Any`
+- Early returns, no deep nesting, no bare `except`
+- Constants for command/operation strings
+
+## Release Hygiene
+- Conventional commits; CHANGELOG generated
+- Tag every release; ensure `git push --tags`
+- Patch bumps for fixes, minor for features
+
+## Potential Pitfalls & Fixes
+- Path handling inconsistencies → centralize in RestClient
+- Logging secrets → redact before logging
+- Tight coupling device↔transport → maintain clean core boundaries
+- Hidden breaking changes → keep shims until 1.0.0
+- Non-deterministic tests → remove sleeps, use fixed seeds
+
+## Next Steps (ordered)
+1. Introduce `exceptions.py` and wire into RestClient
+2. Add `utils/` with `json.py`, `paths.py`, `ids.py`
+3. Add optional `specs/` models for high-value commands
+4. CI: lint+type-check, codecov, test matrix
diff --git a/docs/development/refactor-roadmap.md b/docs/development/refactor-roadmap.md
new file mode 100644
index 0000000..eeee879
--- /dev/null
+++ b/docs/development/refactor-roadmap.md
@@ -0,0 +1,56 @@
+# Refactor Roadmap (Prioritized)
+
+## Priorities
+- P0 (now): safety, compatibility, correctness
+- P1 (next): validation, observability, developer UX
+- P2 (later): performance, async, resiliency
+
+## P0 — Immediate
+- Stabilize transport: keep `_get_payload(include_empty_path)`; special-case `config-file`
+- Keep shims: `pyvyos/device.py` and `pyvyos/rest.py` re-export from `pyvyos/core/*`
+- Typed exceptions: introduce `SDKError`, `HttpError`, `ApiError`, `ValidationError`
+- Timeouts: ensure sane defaults, expose in `VyDevice`
+- Logging: centralize in transport, structured key fields (op, command, status)
+- Tests: payload assertions for `config-file` (path: []), regression for others
+- Docs: architecture and path rules (done)
+
+## P1 — Short Term
+- Specs (optional): Pydantic models in `pyvyos/specs/commands/*`
+- `utils/`: path builders, request_id, safe_json redaction
+- Deprecation policy: note in README; warn on internal imports (future only)
+- CI: test matrix (Python 3.13), codecov, lint (ruff/flake8), type-check (pyright/mypy)
+- Release: conventional commits + CHANGELOG; ensure tags push
+- Docs: contributor guide, release playbook (short)
+
+## P2 — Medium Term
+- Async client: `AsyncRestClient` (aiohttp/httpx), opt-in
+- Retries & backoff: idempotent ops only; circuit-breaker (future)
+- Rate limiting: client-side token bucket (opt-in)
+- Caching: read-only `show/retrieve` (TTL) optional
+- Batch ops: smarter `configure_multiple_op` planning
+
+## Migration & Compatibility
+- Public API: `from pyvyos import VyDevice, ApiResponse` (stable)
+- Internal: prefer `pyvyos.core.*` for new code
+- Shims stay until 1.0.0; removal at next major only
+
+## Testing Plan
+- Unit: transport (errors, timeouts), domain (paths)
+- Contract: sample JSON fixtures per command
+- E2E: optional job against a test VyOS (gated, non-blocking)
+
+## Release Flow (lean)
+- Branch: feature → PR → squash merge
+- Pre-release (optional): `-rcX` tags
+- Tag + publish: GitHub Action (uv build + PyPI publish)
+
+## Risks & Mitigations
+- Hidden breakages → keep shims, add regression tests
+- API drift (VyOS) → specs folder eases updates
+- Logging noise → default INFO; debug gated via env
+- Security → default `verify=True`, redact secrets in logs
+
+## Success Criteria
+- 0.3.x users unaffected
+- New structure adopted by contributors
+- Lower maintenance overhead (fewer regressions)
diff --git a/docs/development/vyos_api/config-file-load.json b/docs/development/vyos_api/config-file-load.json
new file mode 100644
index 0000000..3e1fcef
--- /dev/null
+++ b/docs/development/vyos_api/config-file-load.json
@@ -0,0 +1,2 @@
+{"command":"config-file","operation":"load","description":"Load configuration from a file.","endpoint":"/config-file","method":"POST","request":{"payload":{"data":{"op":"load","path":[],"file":"/config/backup.config"},"key":"your-api-key"},"example":{"op":"load","path":[],"file":"/config/backup.config"}},"response":{"success":{"success":true,"data":null,"error":null},"error":{"success":false,"data":null,"error":"Failed to load configuration file"}},"parameters":{"file":{"type":"string","required":true,"description":"Path to the configuration file to load","example":"/config/backup.config"},"path":{"type":"array","required":false,"description":"Path parameter (required by API, typically empty array)","default":[],"example":[]}},"python_usage":"device.config_file_load(file=\"/config/backup.config\")","notes":"The path parameter is required by the VyOS API even though it's typically empty for load operations."}
+
diff --git a/docs/development/vyos_api/config-file-save.json b/docs/development/vyos_api/config-file-save.json
new file mode 100644
index 0000000..563e0ad
--- /dev/null
+++ b/docs/development/vyos_api/config-file-save.json
@@ -0,0 +1,58 @@
+{
+  "command": "config-file",
+  "operation": "save",
+  "description": "Save the current configuration to a file.",
+  "endpoint": "/config-file",
+  "method": "POST",
+  "request": {
+    "payload": {
+      "data": {
+        "op": "save",
+        "path": [],
+        "file": "/config/backup.config"
+      },
+      "key": "your-api-key"
+    },
+    "example": {
+      "with_file": {
+        "op": "save",
+        "path": [],
+        "file": "/config/backup.config"
+      },
+      "default_location": {
+        "op": "save",
+        "path": []
+      }
+    }
+  },
+  "response": {
+    "success": {
+      "success": true,
+      "data": "",
+      "error": null
+    },
+    "error": {
+      "success": false,
+      "data": null,
+      "error": "Failed to save configuration"
+    }
+  },
+  "parameters": {
+    "file": {
+      "type": "string",
+      "required": false,
+      "description": "Path to the file where configuration will be saved. If not provided, uses default location.",
+      "example": "/config/backup.config"
+    },
+    "path": {
+      "type": "array",
+      "required": false,
+      "description": "Path parameter (required by API, typically empty array)",
+      "default": [],
+      "example": []
+    }
+  },
+  "python_usage": "device.config_file_save(file=\"/config/backup.config\")",
+  "notes": "The path parameter is required by the VyOS API even though it's typically empty for save operations."
+}
+
diff --git a/docs/development/vyos_api/configure-delete.json b/docs/development/vyos_api/configure-delete.json
new file mode 100644
index 0000000..f68c5c8
--- /dev/null
+++ b/docs/development/vyos_api/configure-delete.json
@@ -0,0 +1,2 @@
+{"command":"configure","operation":"delete","description":"Delete configuration values based on a path.","endpoint":"/configure","method":"POST","request":{"payload":{"data":{"op":"delete","path":["interfaces","dummy","dum1"]},"key":"your-api-key"},"example":{"op":"delete","path":["interfaces","dummy","dum1"]}},"response":{"success":{"success":true,"data":{},"error":null},"error":{"success":false,"data":null,"error":"Path does not exist"}},"parameters":{"path":{"type":"array","required":true,"description":"Configuration path to delete as array of strings","example":["interfaces","dummy","dum1"]}},"python_usage":"device.configure_delete(path=[\"interfaces\", \"dummy\", \"dum1\"])"}
+
diff --git a/docs/development/vyos_api/configure-multiple-op.json b/docs/development/vyos_api/configure-multiple-op.json
new file mode 100644
index 0000000..a0d0ab4
--- /dev/null
+++ b/docs/development/vyos_api/configure-multiple-op.json
@@ -0,0 +1,2 @@
+{"command":"configure","operation":"multiple","description":"Execute multiple configuration operations atomically in a single request.","endpoint":"/configure","method":"POST","request":{"payload":{"data":[{"op":"set","path":["interfaces","dummy","dum1","address","192.168.1.1/24"]},{"op":"delete","path":["interfaces","dummy","old1"]}],"key":"your-api-key"},"example":[{"op":"set","path":["interfaces","dummy","dum1","address","192.168.1.1/24"]},{"op":"set","path":["interfaces","dummy","dum1","description","Test interface"]},{"op":"delete","path":["interfaces","dummy","old1"]}]},"response":{"success":{"success":true,"data":null,"error":null},"error":{"success":false,"data":null,"error":"One or more operations failed"}},"parameters":{"op_path":{"type":"array","required":true,"description":"Array of operation objects, each with 'op' and 'path'","items":{"type":"object","required":["op","path"],"properties":{"op":{"type":"string","enum":["set","delete"]},"path":{"type":"array","items":{"type":"string"}}}},"example":[{"op":"set","path":["interfaces","dummy","dum1","address","192.168.1.1/24"]},{"op":"delete","path":["interfaces","dummy","old1"]}]}},"python_usage":"device.configure_multiple_op(op_path=[{\"op\": \"set\", \"path\": [...]}, {\"op\": \"delete\", \"path\": [...]}])"}
+
diff --git a/docs/development/vyos_api/configure-set.json b/docs/development/vyos_api/configure-set.json
new file mode 100644
index 0000000..e99da8c
--- /dev/null
+++ b/docs/development/vyos_api/configure-set.json
@@ -0,0 +1,2 @@
+{"command":"configure","operation":"set","description":"Set configuration values based on a path. Can accept single or multiple configuration paths.","endpoint":"/configure","method":"POST","request":{"payload":{"data":{"op":"set","path":["interfaces","ethernet","eth0","address","192.168.1.1/24"]},"key":"your-api-key"},"example":{"single_path":{"op":"set","path":["interfaces","ethernet","eth0","address","192.168.1.1/24"]},"multiple_paths":{"op":"set","path":[["interfaces","ethernet","eth0","address","192.168.1.1/24"],["interfaces","ethernet","eth0","description","Management"]]}}},"response":{"success":{"success":true,"data":{},"error":null},"error":{"success":false,"data":null,"error":"Configuration validation failed"}},"parameters":{"path":{"type":"array","required":true,"description":"Configuration path(s) as array of strings or array of path arrays for multiple configurations","examples":[["interfaces","ethernet","eth0","address","192.168.1.1/24"],[["interfaces","ethernet","eth0","address","192.168.1.1/24"],["interfaces","ethernet","eth0","description","Management"]]]}},"python_usage":"device.configure_set(path=[\"interfaces\", \"ethernet\", \"eth0\", \"address\", \"192.168.1.1/24\"])"}
+
diff --git a/docs/development/vyos_api/generate.json b/docs/development/vyos_api/generate.json
new file mode 100644
index 0000000..bae9e16
--- /dev/null
+++ b/docs/development/vyos_api/generate.json
@@ -0,0 +1,2 @@
+{"command":"generate","operation":"generate","description":"Generate configuration elements such as SSH keys, certificates, etc.","endpoint":"/generate","method":"POST","request":{"payload":{"data":{"op":"generate","path":["ssh","client-key","/tmp/key_random"]},"key":"your-api-key"},"example":{"op":"generate","path":["ssh","client-key","/tmp/key_random"]}},"response":{"success":{"success":true,"data":"Generating public/private rsa key pair.\nYour identification has been saved in /tmp/key_random\nYour public key has been saved in /tmp/key_random.pub","error":null},"error":{"success":false,"data":null,"error":"Generation failed"}},"parameters":{"path":{"type":"array","required":true,"description":"Path specifying what to generate","example":["ssh","client-key","/tmp/key_random"]}},"python_usage":"device.generate(path=[\"ssh\", \"client-key\", \"/tmp/key_random\"])"}
+
diff --git a/docs/development/vyos_api/image-add.json b/docs/development/vyos_api/image-add.json
new file mode 100644
index 0000000..068adbe
--- /dev/null
+++ b/docs/development/vyos_api/image-add.json
@@ -0,0 +1,2 @@
+{"command":"image","operation":"add","description":"Add a VyOS system image from a URL or file.","endpoint":"/image","method":"POST","request":{"payload":{"data":{"op":"add","url":"https://example.com/vyos-image.iso"},"key":"your-api-key"},"example":{"from_url":{"op":"add","url":"https://example.com/vyos-image.iso"},"from_file":{"op":"add","file":"/path/to/local/image.iso"}}},"response":{"success":{"success":true,"data":{"status":"added","image":"vyos-image.iso"},"error":null},"error":{"success":false,"data":null,"error":"Failed to add image"}},"parameters":{"url":{"type":"string","required":false,"description":"URL of the image to download and add","format":"uri","example":"https://example.com/vyos-image.iso"},"file":{"type":"string","required":false,"description":"Local file path to the image","example":"/path/to/local/image.iso"},"path":{"type":"array","required":false,"description":"Additional path parameters","default":[],"example":[]}},"python_usage":"device.image_add(url=\"https://example.com/vyos-image.iso\")","notes":"Either url or file parameter must be provided."}
+
diff --git a/docs/development/vyos_api/image-delete.json b/docs/development/vyos_api/image-delete.json
new file mode 100644
index 0000000..56ab796
--- /dev/null
+++ b/docs/development/vyos_api/image-delete.json
@@ -0,0 +1,2 @@
+{"command":"image","operation":"delete","description":"Delete a VyOS system image.","endpoint":"/image","method":"POST","request":{"payload":{"data":{"op":"delete","name":"image-name"},"key":"your-api-key"},"example":{"op":"delete","name":"image-name"}},"response":{"success":{"success":true,"data":{"status":"deleted","image":"image-name"},"error":null},"error":{"success":false,"data":null,"error":"Image not found or deletion failed"}},"parameters":{"name":{"type":"string","required":true,"description":"Name of the image to delete","example":"image-name"},"url":{"type":"string","required":false,"description":"Optional URL associated with the image","format":"uri"},"file":{"type":"string","required":false,"description":"Optional file path associated with the image"},"path":{"type":"array","required":false,"description":"Additional path parameters","default":[],"example":[]}},"python_usage":"device.image_delete(name=\"image-name\")"}
+
diff --git a/docs/development/vyos_api/index.json b/docs/development/vyos_api/index.json
new file mode 100644
index 0000000..54a64c7
--- /dev/null
+++ b/docs/development/vyos_api/index.json
@@ -0,0 +1,2 @@
+{"title":"VyOS API Command Index","description":"Complete index of all VyOS REST API commands documented in this directory","version":"1.0.0","schema":"schema.json","commands":[{"file":"configure-set.json","command":"configure","operation":"set","python_method":"configure_set","description":"Set configuration values"},{"file":"configure-delete.json","command":"configure","operation":"delete","python_method":"configure_delete","description":"Delete configuration values"},{"file":"configure-multiple-op.json","command":"configure","operation":"multiple","python_method":"configure_multiple_op","description":"Execute multiple configuration operations atomically"},{"file":"retrieve-show-config.json","command":"retrieve","operation":"showConfig","python_method":"retrieve_show_config","description":"Retrieve configuration in show format"},{"file":"retrieve-return-values.json","command":"retrieve","operation":"returnValues","python_method":"retrieve_return_values","description":"Retrieve specific configuration values"},{"file":"show.json","command":"show","operation":"show","python_method":"show","description":"Execute show commands"},{"file":"generate.json","command":"generate","operation":"generate","python_method":"generate","description":"Generate configuration elements"},{"file":"reset.json","command":"reset","operation":"reset","python_method":"reset","description":"Reset configuration elements"},{"file":"config-file-save.json","command":"config-file","operation":"save","python_method":"config_file_save","description":"Save configuration to file"},{"file":"config-file-load.json","command":"config-file","operation":"load","python_method":"config_file_load","description":"Load configuration from file"},{"file":"reboot.json","command":"reboot","operation":"reboot","python_method":"reboot","description":"Reboot the device"},{"file":"poweroff.json","command":"poweroff","operation":"poweroff","python_method":"poweroff","description":"Power off the device"},{"file":"image-add.json","command":"image","operation":"add","python_method":"image_add","description":"Add VyOS system image"},{"file":"image-delete.json","command":"image","operation":"delete","python_method":"image_delete","description":"Delete VyOS system image"}],"statistics":{"total_commands":14,"command_types":{"configure":3,"retrieve":2,"show":1,"generate":1,"reset":1,"config-file":2,"reboot":1,"poweroff":1,"image":2}}}
+
diff --git a/docs/development/vyos_api/poweroff.json b/docs/development/vyos_api/poweroff.json
new file mode 100644
index 0000000..1950691
--- /dev/null
+++ b/docs/development/vyos_api/poweroff.json
@@ -0,0 +1,2 @@
+{"command":"poweroff","operation":"poweroff","description":"Power off the VyOS device.","endpoint":"/poweroff","method":"POST","request":{"payload":{"data":{"op":"poweroff","path":["now"]},"key":"your-api-key"},"example":{"op":"poweroff","path":["now"]}},"response":{"success":{"success":true,"data":{"status":"powering off"},"error":null},"error":{"success":false,"data":null,"error":"Power off operation failed"}},"parameters":{"path":{"type":"array","required":false,"description":"Power off parameters, typically ['now']","default":["now"],"example":["now"]}},"python_usage":"device.poweroff(path=[\"now\"])","warning":"This operation will immediately power off the device."}
+
diff --git a/docs/development/vyos_api/reboot.json b/docs/development/vyos_api/reboot.json
new file mode 100644
index 0000000..3ca92da
--- /dev/null
+++ b/docs/development/vyos_api/reboot.json
@@ -0,0 +1,2 @@
+{"command":"reboot","operation":"reboot","description":"Reboot the VyOS device.","endpoint":"/reboot","method":"POST","request":{"payload":{"data":{"op":"reboot","path":["now"]},"key":"your-api-key"},"example":{"op":"reboot","path":["now"]}},"response":{"success":{"success":true,"data":{"status":"rebooting"},"error":null},"error":{"success":false,"data":null,"error":"Reboot operation failed"}},"parameters":{"path":{"type":"array","required":false,"description":"Reboot parameters, typically ['now']","default":["now"],"example":["now"]}},"python_usage":"device.reboot(path=[\"now\"])","warning":"This operation will immediately reboot the device."}
+
diff --git a/docs/development/vyos_api/reset.json b/docs/development/vyos_api/reset.json
new file mode 100644
index 0000000..8418456
--- /dev/null
+++ b/docs/development/vyos_api/reset.json
@@ -0,0 +1,2 @@
+{"command":"reset","operation":"reset","description":"Reset configuration elements or system state.","endpoint":"/reset","method":"POST","request":{"payload":{"data":{"op":"reset","path":["conntrack-sync","internal-cache"]},"key":"your-api-key"},"example":{"op":"reset","path":["conntrack-sync","internal-cache"]}},"response":{"success":{"success":true,"data":"conntrack-sync is not configured!","error":null},"error":{"success":false,"data":null,"error":"Reset operation failed"}},"parameters":{"path":{"type":"array","required":false,"description":"Path specifying what to reset","default":[],"example":["conntrack-sync","internal-cache"]}},"python_usage":"device.reset(path=[\"conntrack-sync\", \"internal-cache\"])"}
+
diff --git a/docs/development/vyos_api/retrieve-return-values.json b/docs/development/vyos_api/retrieve-return-values.json
new file mode 100644
index 0000000..c827b5d
--- /dev/null
+++ b/docs/development/vyos_api/retrieve-return-values.json
@@ -0,0 +1,2 @@
+{"command":"retrieve","operation":"returnValues","description":"Retrieve and return specific configuration values for a given path.","endpoint":"/retrieve","method":"POST","request":{"payload":{"data":{"op":"returnValues","path":["interfaces","dummy","dum1","address"]},"key":"your-api-key"},"example":{"op":"returnValues","path":["interfaces","dummy","dum1","address"]}},"response":{"success":{"success":true,"data":["192.168.56.100/24"],"error":null},"error":{"success":false,"data":null,"error":"Path not found"}},"parameters":{"path":{"type":"array","required":true,"description":"Configuration path to retrieve values from","example":["interfaces","dummy","dum1","address"]}},"python_usage":"device.retrieve_return_values(path=[\"interfaces\", \"dummy\", \"dum1\", \"address\"])"}
+
diff --git a/docs/development/vyos_api/retrieve-show-config.json b/docs/development/vyos_api/retrieve-show-config.json
new file mode 100644
index 0000000..bf5231f
--- /dev/null
+++ b/docs/development/vyos_api/retrieve-show-config.json
@@ -0,0 +1,2 @@
+{"command":"retrieve","operation":"showConfig","description":"Retrieve and show the device configuration in show format.","endpoint":"/retrieve","method":"POST","request":{"payload":{"data":{"op":"showConfig","path":["system"]},"key":"your-api-key"},"example":{"op":"showConfig","path":["system"]}},"response":{"success":{"success":true,"data":{"config-management":{"commit-revisions":"100"},"host-name":"vyos-device","name-server":"eth0"},"error":null},"error":{"success":false,"data":null,"error":"Invalid path"}},"parameters":{"path":{"type":"array","required":false,"description":"Configuration path to retrieve, empty array for full config","default":[],"example":["system"]}},"python_usage":"device.retrieve_show_config(path=[\"system\"])"}
+
diff --git a/docs/development/vyos_api/schema.json b/docs/development/vyos_api/schema.json
new file mode 100644
index 0000000..fb125b1
--- /dev/null
+++ b/docs/development/vyos_api/schema.json
@@ -0,0 +1,2 @@
+{"$schema":"http://json-schema.org/draft-07/schema#","$id":"https://github.com/vyos-contrib/pyvyos/docs/vyos-api/schema.json","title":"VyOS API Command Schema","description":"Schema definition for VyOS REST API commands","type":"object","definitions":{"apiRequest":{"type":"object","required":["command","op"],"properties":{"command":{"type":"string","description":"API endpoint command","enum":["configure","retrieve","show","generate","reset","config-file","reboot","poweroff","image"]},"op":{"type":"string","description":"Operation type","enum":["set","delete","showConfig","returnValues","show","generate","reset","save","load","reboot","poweroff","add","delete",""]},"path":{"oneOf":[{"type":"array","description":"Single configuration path","items":{"type":"string"}},{"type":"array","description":"Multiple configuration paths","items":{"type":"array","items":{"type":"string"}}},{"type":"array","description":"Multiple operations with paths","items":{"type":"object","required":["op","path"],"properties":{"op":{"type":"string","enum":["set","delete"]},"path":{"type":"array","items":{"type":"string"}}}]}]},"file":{"type":"string","description":"File path for file operations"},"url":{"type":"string","description":"URL for external resources","format":"uri"},"name":{"type":"string","description":"Resource name identifier"},"method":{"type":"string","description":"HTTP method","enum":["GET","POST","PUT","DELETE"],"default":"POST"}}},"apiResponse":{"type":"object","required":["success","data","error"],"properties":{"success":{"type":"boolean","description":"Whether the operation succeeded"},"data":{"description":"Response data (type varies by operation)","oneOf":[{"type":"object"},{"type":"array"},{"type":"string"},{"type":"null"}]},"error":{"oneOf":[{"type":"null"},{"type":"string"}],"description":"Error message if operation failed"}}}},"properties":{"request":{"$ref":"#/definitions/apiRequest"},"response":{"$ref":"#/definitions/apiResponse"}}}
+
diff --git a/docs/development/vyos_api/show.json b/docs/development/vyos_api/show.json
new file mode 100644
index 0000000..3576e43
--- /dev/null
+++ b/docs/development/vyos_api/show.json
@@ -0,0 +1,2 @@
+{"command":"show","operation":"show","description":"Execute show commands to display system information.","endpoint":"/show","method":"POST","request":{"payload":{"data":{"op":"show","path":["system","image"]},"key":"your-api-key"},"example":{"op":"show","path":["system","image"]}},"response":{"success":{"success":true,"data":"Name                   Default boot    Running\n------------------------  --------------  ---------\n1.5-rolling-202407300021       Yes           Yes","error":null},"error":{"success":false,"data":null,"error":"Command not found"}},"parameters":{"path":{"type":"array","required":false,"description":"Command path for show operation","default":[],"example":["system","image"]}},"python_usage":"device.show(path=[\"system\", \"image\"])"}
+
diff --git a/docs/examples.md b/docs/examples.md
new file mode 100644
index 0000000..6f4cf29
--- /dev/null
+++ b/docs/examples.md
@@ -0,0 +1,91 @@
+# Examples
+
+Common usage patterns and examples for PyVyOS.
+
+## Basic Connection
+
+```python
+from pyvyos import VyDevice
+device = VyDevice(hostname="192.168.1.1", apikey="your-api-key", verify=False)
+```
+
+## Viewing System Information
+
+```python
+response = device.show(path=["system", "image"])
+if not response.error:
+    print(response.result)
+```
+
+## Interface Configuration
+
+Add, view, get, or remove interface configuration:
+
+```python
+# Add address
+device.configure_set(path=["interfaces", "ethernet", "eth0", "address", "192.168.1.1/24"])
+
+# View configuration
+device.retrieve_show_config(path=["interfaces", "ethernet", "eth0"])
+
+# Get address value
+device.retrieve_return_values(path=["interfaces", "ethernet", "eth0", "address"])
+
+# Remove interface
+device.configure_delete(path=["interfaces", "dummy", "dum1"])
+```
+
+## Multiple Operations
+
+Execute multiple configuration changes atomically:
+
+```python
+device.configure_multiple_op(op_path=[
+    {"op": "set", "path": ["interfaces", "dummy", "dum1", "address", "192.168.1.1/24"]},
+    {"op": "set", "path": ["interfaces", "dummy", "dum1", "description", "Test"]},
+    {"op": "delete", "path": ["interfaces", "dummy", "old1"]}
+])
+```
+
+## Configuration Backup
+
+```python
+device.config_file_save(file="/config/backup-2024.config")
+device.config_file_load(file="/config/backup-2024.config")
+```
+
+## SSH Key Generation
+
+```python
+import random, string
+randstring = ''.join(random.choice(string.ascii_letters + string.digits) for _ in range(20))
+device.generate(path=["ssh", "client-key", f'/tmp/key_{randstring}'])
+```
+
+## System Operations
+
+```python
+device.reboot(path=["now"])
+device.poweroff(path=["now"])
+```
+
+## Error Handling
+
+```python
+response = device.configure_set(path=["invalid", "path"])
+if response.error:
+    print(f"Error {response.status}: {response.error}")
+else:
+    print("Success:", response.result)
+```
+
+## Working with Responses
+
+```python
+response = device.show(path=["system"])
+print(f"Status: {response.status}")
+if not response.error:
+    data = response.result  # Process data...
+print(f"Request: {response.request}")  # API key sanitized
+```
+
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 0000000..183c109
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,77 @@
+# Getting Started
+
+This guide will help you set up PyVyOS and make your first API call to a VyOS device.
+
+## Prerequisites
+
+- VyOS device with REST API enabled
+- API key generated on your VyOS device
+- Network access to your VyOS device
+
+## Step 1: Install PyVyOS
+
+See [Installation](installation.md) for detailed instructions.
+
+## Step 2: Configure Environment Variables
+
+Create a `.env` file in your project directory:
+
+```bash
+VYDEVICE_HOSTNAME=192.168.1.1
+VYDEVICE_APIKEY=your-api-key-here
+VYDEVICE_PORT=443
+VYDEVICE_PROTOCOL=https
+VYDEVICE_VERIFY_SSL=False
+```
+
+## Step 3: Create Your First Script
+
+```python
+import os
+from dotenv import load_dotenv
+from pyvyos import VyDevice
+
+load_dotenv()
+
+device = VyDevice(
+    hostname=os.getenv('VYDEVICE_HOSTNAME'),
+    apikey=os.getenv('VYDEVICE_APIKEY'),
+    port=os.getenv('VYDEVICE_PORT'),
+    protocol=os.getenv('VYDEVICE_PROTOCOL'),
+    verify=os.getenv('VYDEVICE_VERIFY_SSL', 'True').lower() == 'true'
+)
+
+response = device.show(path=["system", "image"])
+if not response.error:
+    print(response.result)
+else:
+    print(f"Error: {response.error}")
+```
+
+## Step 4: Disable SSL Warnings (Optional)
+
+If using `verify=False`, disable urllib3 warnings:
+
+```python
+import urllib3
+urllib3.disable_warnings()
+```
+
+## Understanding API Responses
+
+All methods return an `ApiResponse` object with:
+- `status`: HTTP status code
+- `request`: Request payload (API key sanitized)
+- `result`: Response data dictionary
+- `error`: Error message (False if successful)
+
+## Common Operations
+
+See [Examples](examples.md) for more detailed usage patterns.
+
+## Next Steps
+
+- Read [API Reference](api-reference.md) for complete method documentation
+- Explore [Configuration](configuration.md) for advanced setup
+- Check [Concepts](concepts.md) to understand PyVyOS architecture
+
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..1bc9cb7
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,56 @@
+# PyVyOS Documentation
+
+PyVyOS is a Python SDK for interacting with VyOS devices via their REST API. This library provides a simple and intuitive interface to manage VyOS network devices programmatically.
+
+## Overview
+
+PyVyOS enables developers to:
+- Configure VyOS devices remotely
+- Retrieve configuration and operational data
+- Manage system operations (reboot, poweroff)
+- Generate SSH keys and manage images
+- Save and load configuration files
+
+## Documentation Structure
+
+- [Installation](installation.md) - How to install PyVyOS
+- [Getting Started](getting-started.md) - Quick start guide
+- [API Reference](api-reference.md) - Complete API documentation
+- [Configuration](configuration.md) - Device setup and authentication
+- [Examples](examples.md) - Common usage patterns
+- [Concepts](concepts.md) - Key concepts and architecture
+- [Troubleshooting](troubleshooting.md) - Common issues and solutions
+
+## Requirements
+
+- Python 3.13 or higher
+- VyOS device with REST API enabled
+- API key for authentication
+
+## Quick Example
+
+```python
+from pyvyos import VyDevice
+
+device = VyDevice(
+    hostname="192.168.1.1",
+    apikey="your-api-key",
+    port=443,
+    protocol="https",
+    verify=False
+)
+
+response = device.show(path=["system", "image"])
+print(response.result)
+```
+
+## Resources
+
+- [GitHub Repository](https://github.com/vyos-contrib/pyvyos)
+- [PyPI Package](https://pypi.org/project/pyvyos/)
+- [Read the Docs](https://pyvyos.readthedocs.io/)
+
+## License
+
+MIT License - See LICENSE file for details
+
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 0000000..e83974e
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,65 @@
+# Installation
+
+## Prerequisites
+
+PyVyOS requires Python 3.13 or higher. Make sure you have a compatible Python version installed.
+
+## Using pip
+
+The recommended way to install PyVyOS is using pip:
+
+```bash
+pip install pyvyos
+```
+
+## Using uv
+
+If you use `uv` for package management:
+
+```bash
+uv add pyvyos
+```
+
+## From Source
+
+To install from source:
+
+```bash
+git clone https://github.com/vyos-contrib/pyvyos.git
+cd pyvyos
+pip install .
+```
+
+## Verify Installation
+
+After installation, verify it works:
+
+```python
+from pyvyos import VyDevice
+print("PyVyOS installed successfully")
+```
+
+## Dependencies
+
+PyVyOS automatically installs:
+- `requests>=2.32.0` - HTTP library for API calls
+- `python-dotenv>=1.0.1` - Environment variable management
+- `urllib3>=2.5.0` - HTTP client utilities
+
+## Development Installation
+
+For development with testing support:
+
+```bash
+pip install pyvyos[dev]
+```
+
+This includes:
+- `pytest>=6.2.5` - Testing framework
+- `pytest-cov>=4.1` - Coverage reporting
+- `pytest-env>=0.6.2` - Environment variable testing
+
+## Next Steps
+
+After installation, proceed to [Getting Started](getting-started.md) to configure your first device connection.
+
diff --git a/docs/make.bat b/docs/make.bat
deleted file mode 100644
index 747ffb7..0000000
--- a/docs/make.bat
+++ /dev/null
@@ -1,35 +0,0 @@
-@ECHO OFF

-

-pushd %~dp0

-

-REM Command file for Sphinx documentation

-

-if "%SPHINXBUILD%" == "" (

-	set SPHINXBUILD=sphinx-build

-)

-set SOURCEDIR=source

-set BUILDDIR=build

-

-%SPHINXBUILD% >NUL 2>NUL

-if errorlevel 9009 (

-	echo.

-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx

-	echo.installed, then set the SPHINXBUILD environment variable to point

-	echo.to the full path of the 'sphinx-build' executable. Alternatively you

-	echo.may add the Sphinx directory to PATH.

-	echo.

-	echo.If you don't have Sphinx installed, grab it from

-	echo.https://www.sphinx-doc.org/

-	exit /b 1

-)

-

-if "%1" == "" goto help

-

-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

-goto end

-

-:help

-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

-

-:end

-popd

diff --git a/docs/requirements.txt b/docs/requirements.txt
deleted file mode 100644
index f1ce7d3..0000000
--- a/docs/requirements.txt
+++ /dev/null
@@ -1,2 +0,0 @@
-Sphinx>=7.2.6
-sphinx-rtd-theme>=2.0.0
diff --git a/docs/source/conf.py b/docs/source/conf.py
deleted file mode 100644
index bfa4675..0000000
--- a/docs/source/conf.py
+++ /dev/null
@@ -1,36 +0,0 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-
-project = "pyvyos"
-copyright = "2024, Roberto Berto"
-author = "Roberto Berto"
-release = "0.3.0"
-
-# -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
-
-templates_path = ["_templates"]
-exclude_patterns = []
-
-
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-
-html_theme = "sphinx_rtd_theme"
-html_static_path = ["_static"]
-
-
-import os
-import sys
-
-sys.path.insert(0, os.path.abspath("../../pyvyos"))
-
-extensions = [
-    "sphinx.ext.autodoc",
-    "sphinx_rtd_theme",
-]
diff --git a/docs/source/index.rst b/docs/source/index.rst
deleted file mode 100644
index 05c2aa0..0000000
--- a/docs/source/index.rst
+++ /dev/null
@@ -1,214 +0,0 @@
-.. PyVyOS documentation master file, created by
-   sphinx-quickstart on Wed Dec 13 13:02:59 2023.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-PyVyOS - documentation
-==================================
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
-
-pyvyos
-======
-
-.. toctree::
-   :maxdepth: 4
-
-   pyvyos
-   
-PyVyOS Usage
-==================
-
-.. _pyvyos-documentation:
-
-PyVyOS Documentation
-====================
-
-PyVyOS is a Python library for interacting with VyOS devices via their API. This documentation provides a guide on how to use PyVyOS to manage your VyOS devices programmatically.
-
-Installation
-------------
-
-You can install PyVyOS using pip:
-
-.. code-block:: bash
-
-   pip install pyvyos
-
-Getting Started
----------------
-
-Importing and Disabling Warnings for verify=False
---------------------------------------------------
-
-Before using PyVyOS, it's a good practice to disable urllib3 warnings and import the required modules, IF you use verify=False:
-
-.. code-block:: python
-
-   import urllib3
-   urllib3.disable_warnings()
-
-Using API Response Class
-------------------------
-
-PyVyOS uses a custom `ApiResponse` data class to handle API responses:
-
-.. code-block:: python
-
-   @dataclass
-   class ApiResponse:
-       status: int
-       request: dict
-       result: dict
-       error: str
-
-Initializing a VyDevice Object
-------------------------------
-
-To interact with your VyOS device, you'll need to create an instance of the `VyDevice` class. You can set up your device using the following code, assuming you've stored your credentials as environment variables:
-
-.. code-block:: python
-
-   from dotenv import load_dotenv
-
-   # Load environment variables from a .env file
-   load_dotenv()
-
-   # Retrieve VyOS device connection details from environment variables
-   hostname = os.getenv('VYDEVICE_HOSTNAME')
-   apikey = os.getenv('VYDEVICE_APIKEY')
-   port = os.getenv('VYDEVICE_PORT')
-   protocol = os.getenv('VYDEVICE_PROTOCOL')
-   verify_ssl = os.getenv('VYDEVICE_VERIFY_SSL')
-
-   # Convert the verify_ssl value to a boolean
-   verify = verify_ssl.lower() == "true" if verify_ssl else True
-
-   # Create an instance of the VyOS device
-   device = VyDevice(hostname=hostname, apikey=apikey, port=port, protocol=protocol, verify=verify)
-
-Using PyVyOS
-------------
-
-Once you have created a VyDevice object, you can use it to interact with your VyOS device using various methods provided by the library.
-
-Reset
------
-
-The reset method allows you to run a reset command:
-
-.. code-block:: python
-
-   # Execute the reset command
-   response = device.reset(path=["conntrack-sync", "internal-cache"])
-
-   # Check for errors and print the result
-   if not response.error:
-       print(response.result)
-
-Retrieve Show Configuration
----------------------------
-
-The retrieve_show_config method retrieves the VyOS configuration:
-
-.. code-block:: python
-
-   # Retrieve the VyOS configuration
-   response = device.retrieve_show_config(path=[])
-
-   # Check for errors and print the result
-   if not response.error:
-       print(response.result)
-
-Retrieve Return Values
------------------------- 
-
-.. code-block:: python
-
-   # Retrieve VyOS return values for a specific interface
-   response = device.retrieve_return_values(path=["interfaces", "dummy", "dum1", "address"])
-   print(response.result)
-
-Configure Delete
-----------------
-
-.. code-block:: python
-
-   # Delete a VyOS interface configuration
-   response = device.configure_delete(path=["interfaces", "dummy", "dum1"])
-
-Generate
-----------
-
-.. code-block:: python
-
-   # Generate an SSH key with a random string in the name
-   randstring = ''.join(random.choice(string.ascii_letters + string.digits) for _ in range(20))
-   keyrand =  f'/tmp/key_{randstring}'
-   response = device.generate(path=["ssh", "client-key", keyrand])
-
-Show
-------
-
-.. code-block:: python
-
-   # Show VyOS system image information
-   response = device.show(path=["system", "image"])
-   print(response.result)
-
-Reset
-------
-
-.. code-block:: python
-
-   # Reset VyOS with specific parameters
-   response = device.reset(path=["conntrack-sync", "internal-cache"])
-
-Configure Set
--------------
-
-The configure_set method sets a VyOS configuration:
-
-.. code-block:: python
-
-   # Set a VyOS configuration
-   response = device.configure_set(path=["interfaces ethernet eth0 address '192.168.1.1/24'"])
-
-   # Check for errors and print the result
-   if not response.error:
-       print(response.result)
-
-Config File Save
-----------------
-
-.. code-block:: python
-
-   # Save VyOS configuration without specifying a file (default location)
-   response = device.config_file_save()
-
-Config File Save with custom filename
--------------------------------------
-
-.. code-block:: python
-
-   # Save VyOS configuration to a specific file
-   response = device.config_file_save(file="/config/test300.config")
-
-Config File Load
-----------------
-
-.. code-block:: python
-
-   # Load VyOS configuration from a specific file
-   response = device.config_file_load(file="/config/test300.config")
-
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
\ No newline at end of file
diff --git a/docs/source/pyvyos.rst b/docs/source/pyvyos.rst
deleted file mode 100644
index fc02f1a..0000000
--- a/docs/source/pyvyos.rst
+++ /dev/null
@@ -1,21 +0,0 @@
-pyvyos package
-==============
-
-Submodules
-----------
-
-pyvyos.device module
---------------------
-
-.. automodule:: pyvyos.device
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: pyvyos
-   :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000..3e7f286
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,60 @@
+# Troubleshooting
+
+Common issues and solutions when using PyVyOS.
+
+## Connection Issues
+
+**Cannot Connect:** Verify hostname/IP, network connectivity, API enabled, firewall rules, port number.
+
+**SSL Errors:** Use `verify=False` for dev (self-signed certs), install CA certs for production.
+
+## Authentication Problems
+
+**Invalid API Key:** Verify key is correct, check expiration, ensure permissions, regenerate if needed.
+
+## Configuration Errors
+
+**Invalid Path:** Verify path syntax matches VyOS tree, check path exists, use `retrieve_show_config` to inspect.
+
+**Not Applied:** Call `config_file_save()` after changes, check commit requirements, verify permissions.
+
+## Response Issues
+
+**Empty Results:** Check if path has data, verify syntax, try broader path.
+
+**Error Format:** Always check `response.error` first, inspect `response.status`, log full response.
+
+## Performance Issues
+
+**Timeouts:** Increase timeout parameter, check latency, verify device load, break into smaller operations.
+
+**Slow Operations:** Use `configure_multiple_op` for bulk, avoid short polling, consider async for multiple devices.
+
+## Environment Setup
+
+**Variables Not Loading:** Verify `.env` exists, check `load_dotenv()` call, match variable names, use defaults.
+
+## Debugging Tips
+
+```python
+# Enable verbose logging
+import logging
+logging.basicConfig(level=logging.DEBUG)
+
+# Inspect full response
+response = device.show(path=["system"])
+print(f"Status: {response.status}, Error: {response.error}")
+print(f"Result: {response.result}, Request: {response.request}")
+
+# Test connection
+response = device.show(path=["system", "host-name"])
+if response.error:
+    print(f"Connection issue: {response.error}")
+```
+
+## Getting Help
+
+- Check [API Reference](api-reference.md) for method details
+- Review [Examples](examples.md) for usage patterns
+- Open issue on [GitHub](https://github.com/vyos-contrib/pyvyos/issues)
+
diff --git a/docs/vyos-api.md b/docs/vyos-api.md
new file mode 100644
index 0000000..33a443f
--- /dev/null
+++ b/docs/vyos-api.md
@@ -0,0 +1,78 @@
+# VyOS API Command Reference
+
+The JSON definitions for each VyOS REST API command supported by PyVyOS are located in `docs/development/vyos_api/`.
+
+## Location
+
+All JSON specification files are stored in: **`docs/development/vyos_api/`**
+
+These JSONs are reference documentation and are:
+- Used for API documentation generation
+- Available for validation and testing
+- Not packaged with the library (reference only)
+
+## Files
+
+- `schema.json` - JSON Schema definition for all API commands
+- Individual command files:
+  - `configure-set.json` - Set configuration values
+  - `configure-delete.json` - Delete configuration values
+  - `configure-multiple-op.json` - Execute multiple operations atomically
+  - `retrieve-show-config.json` - Retrieve configuration in show format
+  - `retrieve-return-values.json` - Retrieve specific configuration values
+  - `show.json` - Execute show commands
+  - `generate.json` - Generate configuration elements (SSH keys, etc.)
+  - `reset.json` - Reset configuration elements
+  - `config-file-save.json` - Save configuration to file
+  - `config-file-load.json` - Load configuration from file
+  - `reboot.json` - Reboot the device
+  - `poweroff.json` - Power off the device
+  - `image-add.json` - Add VyOS system image
+  - `image-delete.json` - Delete VyOS system image
+
+## Structure
+
+Each JSON file follows this structure:
+
+```json
+{
+  "command": "command-name",
+  "operation": "operation-name",
+  "description": "Description of what the command does",
+  "endpoint": "/endpoint-path",
+  "method": "HTTP_METHOD",
+  "request": {
+    "payload": { ... },
+    "example": { ... }
+  },
+  "response": {
+    "success": { ... },
+    "error": { ... }
+  },
+  "parameters": { ... },
+  "python_usage": "device.method_name(...)"
+}
+```
+
+## Usage
+
+These JSON files can be used for:
+- API documentation generation
+- Request validation
+- Response schema validation
+- Client library code generation
+- Testing and mocking
+
+## JSON Schema
+
+The `schema.json` file defines the complete structure for all API commands and can be used with JSON Schema validators.
+
+## Path Parameter Handling
+
+**Important:** The `path` parameter handling varies by command:
+
+- **config-file commands** (`save`, `load`): The VyOS API requires `path` to be present in the payload, even if empty (`[]`). PyVyOS handles this automatically.
+- **Other commands**: When `path` is empty or not provided, it may be omitted from the payload for cleaner requests.
+
+See individual JSON files in `docs/development/vyos_api/` for specific parameter requirements.
+