docs: prepare v0.4.0 release

Rewrite the README around the supported public API, add a public API
stability policy, document the deprecation timeline, and refresh the
CHANGELOG with the full 0.4.0 scope. Add a short CONTRIBUTING guide.
Apply minor pending fixes to LICENSE and .env.example. Fix a couple of
verify=False antipatterns in the docs/ pages.

README:
- Badges (PyPI version, Python versions, license, CI).
- Quick start that actually runs (no missing import, no global
  disable_warnings, correct VYDEVICE_VERIFY_SSL parse).
- Environment variable table with defaults.
- ApiResponse contract documented as a dataclass.
- Compact API overview (configure / retrieve / show / generate / reset /
  config-file / system / image).
- Public API stability section with the 0.4 -> 0.5 -> 0.6 -> 1.0
  deprecation timeline.
- Logging section: NullHandler default, pyvyos logger, redacted key.
- VyOS compatibility note (1.4 LTS, 1.5 rolling).
- Development with uv; optional pre-commit.

CHANGELOG:
- Consolidated 0.4.0 entry covering both the architecture refactor and
  this cleanup, since 0.4.0 was tagged in git but never published.
- Explicit Added / Changed / Removed / Fixed / Compatibility / Notes
  sections.
- 0.3.0 entry annotated as 'tagged but never released to PyPI'.

CONTRIBUTING.md:
- Scope statement (thin HTTPS API wrapper).
- Pull request rules; explicit 'do not change HTTP payload in passing'.
- Development setup with uv.
- Public API stability summary.

Fixes from the previous review-fixes branch:
- LICENSE copyright now reads 'GravScale, Roberto Berto'.
- .env.example default flipped to VYDEVICE_VERIFY_SSL=true with
  field descriptions.
- docs/getting-started.md: VERIFY_SSL default to true; urllib3
  disable_warnings now passes the specific InsecureRequestWarning.
- docs/index.md: quick example uses verify=True; removed RTD link
  (RTD config was removed in this release because the build never
  worked).

1 files changed, 78 insertions, 31 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 15b9314..3132e02 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,50 +5,97 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.4.0] - 2025-01-XX
+## [0.4.0] - 2025-11-20
+
+`0.4.0` is a cleanup and consolidation release. It is the first version
+since `0.2.2` published to PyPI. The git tag `v0.4.0` previously pointed at
+the intermediate refactor commit `6b4e901`; it has been moved to the
+release commit that includes the cleanup described below.
+
+This release **does not change HTTP payload generation or request/response
+behavior**.
 
 ### Added
-- Exception hierarchy (`SDKError`, `HttpError`, `ApiError`, `ValidationError`) in `pyvyos.exceptions`
-- Utility functions in `pyvyos.utils`:
-  - `json.redact_key()` and `json.safe_dumps()` for secure JSON handling
-  - `ids.request_id()` for request tracing
-  - `paths.build_path()` for building configuration paths
-- Structured logging in `RestClient` with request ID tracking and elapsed time
-- Optional Pydantic validation models in `pyvyos.specs.commands.*` for request/response validation
-- Development documentation:
-  - Architecture guide (`docs/development/architecture.md`)
-  - Refactor roadmap (`docs/development/refactor-roadmap.md`)
-  - Quality and utils guidelines (`docs/development/quality-and-utils.md`)
-- Comprehensive test suite for backward compatibility (19 tests for shims, 16 tests for utils, 6 tests for exceptions)
-- `[tool.uv] package = true` in `pyproject.toml` for editable installation via `uv sync`
+- `pyvyos/py.typed` PEP 561 marker, advertising the package as typed.
+- `.pre-commit-config.yaml` with neutral hooks (trailing whitespace,
+  end-of-file fixer, YAML/TOML syntax check, large-file guard).
+- GitHub Actions ecosystem entry in `.github/dependabot.yml` so workflow
+  versions stay current.
+- Documented public API stability and deprecation timeline in `README.md`.
 
 ### Changed
-- Moved JSON API specifications from `pyvyos/vyos-api/` to `docs/development/vyos_api/` (reference only)
-- Updated `pyproject.toml` to include optional `validation` dependency group for Pydantic
-- Enhanced `RestClient` logging with structured fields (request_id, command, op, status, elapsed_ms)
-- Refactored internal structure to `pyvyos.core.*` while maintaining full backward compatibility via shims
+- `pyvyos.core.*` is now the internal implementation layer; the supported
+  public API is `from pyvyos import VyDevice, ApiResponse`. The legacy
+  `pyvyos.device` and `pyvyos.rest` shims continue to work without
+  warnings.
+- `RestClient` logging is now plain and structured: command, op, status,
+  elapsed milliseconds. No request-ID field.
+- `pyproject.toml`:
+  - declared the wheel package explicitly,
+  - removed duplicated dependency blocks,
+  - dropped the unused `validation` extra,
+  - raised the pytest floor for Python 3.13.
+- PR validation workflow upgraded to `actions/checkout@v4`,
+  `actions/setup-python@v5`, and `astral-sh/setup-uv@v3`.
+- `.env.example` default flipped to `VYDEVICE_VERIFY_SSL=true`; commented
+  with field descriptions.
+
+### Removed
+- `pyvyos.specs` package (experimental Pydantic models). It was never
+  imported by the runtime and had 0% test coverage. Pydantic is no longer
+  an optional dependency.
+- `pyvyos.exceptions` module (`SDKError`, `HttpError`, `ApiError`,
+  `ValidationError`). The hierarchy was defined but never raised anywhere
+  in the codebase. Error reporting continues through `ApiResponse.error`.
+- `pyvyos.utils.ids.request_id` helper. The generated UUIDs were attached
+  to log records but never propagated to callers — half-implemented
+  tracing is worse than none. It will be reintroduced if and when real
+  observability hooks land.
+- `pyvyos.utils` no longer re-exports `request_id`.
+- Obsolete tooling: `Makefile` (hard-coded `env/bin/python`),
+  `run_tests.sh`, `run_tests.py`.
+- Dead workflow `.github/workflows/python-app.yml` (Python 3.12, only ran
+  flake8 with pytest commented out, referenced a non-existent
+  `requirements.txt`).
+- `sphinx/` source tree and `.readthedocs.yaml`: the RTD configuration
+  pointed to `docs/source/conf.py` while the Sphinx tree lived under
+  `sphinx/source/`, so the build never worked and no documentation was
+  ever published. The hand-written Markdown docs under `docs/` are
+  retained.
+- Stale development notes under `docs/development/` (architecture,
+  refactor roadmap, quality-and-utils) — they described the pre-cleanup
+  proposal that included specs/exceptions/request_id.
+- Tests for the removed modules (`tests/test_exceptions.py`,
+  `tests/utils/test_ids.py`).
 
 ### Fixed
-- **Fixed #25**: `config_file_save()` and `config_file_load()` now correctly include `path: []` in payload as required by VyOS API
-- Path parameter handling for `config-file` commands (always includes `path: []`)
-- Secret redaction in logs and sanitized payloads
+- `LICENSE` copyright now reads `2023 GravScale, Roberto Bertó`.
 
-### Security
-- API keys are automatically redacted in logs and response payloads
+### Compatibility
+- Public imports are unchanged:
+  - `from pyvyos import VyDevice, ApiResponse`
+  - `from pyvyos.device import VyDevice`
+  - `from pyvyos.rest import RestClient, ApiResponse`
+- HTTP payload generation is unchanged.
+- Request and response behaviour is unchanged.
+- No compatibility shim has been deprecated in this release.
 
 ### Notes
-- This release maintains 100% backward compatibility with version 0.3.0
-- All existing imports and code will continue to work without changes
-- New internal structure (`pyvyos.core.*`) is available but not required for existing code
+- This release prepares the project for the upcoming `0.5.x` work:
+  contract tests for public payloads, fixes to the public method edges
+  (`image_add`/`image_delete`, `timeout`, mutable defaults), stdlib-based
+  validators, and a tidier internal core.
 
 ## [0.3.0] - 2024-XX-XX
 
+Tagged in git but never published to PyPI. Released to PyPI as part of
+`0.4.0`.
+
 ### Added
-- Initial release
-- Core functionality for VyOS REST API interaction
-- Support for configure, retrieve, show, generate, reset, config-file, reboot, poweroff, and image operations
+- Initial public release of the SDK structure.
+- Core functionality for VyOS HTTPS API: configure, retrieve, show,
+  generate, reset, config-file, reboot, poweroff, and image operations.
 
 [Unreleased]: https://github.com/vyos-contrib/pyvyos/compare/v0.4.0...HEAD
-[0.4.0]: https://github.com/vyos-contrib/pyvyos/compare/v0.3.0...v0.4.0
+[0.4.0]: https://github.com/vyos-contrib/pyvyos/compare/v0.2.2...v0.4.0
 [0.3.0]: https://github.com/vyos-contrib/pyvyos/releases/tag/v0.3.0
-