feat: v0.4.0 - Architecture refactor, bug fixes, and quality improvementsfeat/architecture-and-quality-improvements

- Fixed #25: config_file_save/load now include path: [] in payload
- Added exception hierarchy (SDKError, HttpError, ApiError, ValidationError)
- Added utility functions (json, ids, paths)
- Added structured logging with request ID tracking
- Added optional Pydantic validation models
- Refactored to pyvyos.core.* structure with backward compatibility shims
- Moved JSON specs to docs/development/vyos_api/
- Added comprehensive test suite (19 shim tests, 16 utils tests, 6 exception tests)
- Updated pyproject.toml for uv sync editable installation
- Added development documentation (architecture, roadmap, quality guidelines)

Maintains 100% backward compatibility with 0.3.0

1 files changed, 84 insertions, 0 deletions

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
+