docs(ui): brand teal theme + dark mode polish

docs/stylesheets/extra.css

@@ -0,0 +1,13 @@
+:root {
+  --md-primary-fg-color: #00758F;
+  --md-primary-fg-color--light: #0099b8;
+  --md-primary-fg-color--dark: #005f73;
+  --md-accent-fg-color: #00758F;
+}
+
+[data-md-color-scheme="slate"] {
+  --md-primary-fg-color: #0099b8;
+  --md-primary-fg-color--light: #33b4cf;
+  --md-primary-fg-color--dark: #00758F;
+  --md-accent-fg-color: #0099b8;
+}

docs/superpowers/plans/2026-04-30-release-v0.4.6.md

@@ -0,0 +1,334 @@
+# Release v0.4.6 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Ship v0.4.6 to PyPI including the mypy cleanup, pre-commit hook, CLAUDE.md improvements, and docs UI polish — once the ui-refactor work is located or created.
+
+**Architecture:** Standard release flow: UI branch merged first → version bump + changelog on a release branch → local build to verify artifacts → `gh release create` triggers the OIDC publish workflow automatically.
+
+**Tech Stack:** Python / setuptools, MkDocs Material, GitHub Actions OIDC publish, `gh` CLI
+
+---
+
+## Files touched
+
+| File | Change |
+|------|--------|
+| `pyproject.toml` | Bump `version` to `0.4.6` |
+| `CHANGELOG.md` | Add `[0.4.6]` entry |
+| `mkdocs.yml` | UI polish (Task 1) |
+| `docs/index.md` | UI polish if needed (Task 1) |
+
+---
+
+## Task 1: Resolve the ui-refactor branch
+
+The `feat/ui-refactor` branch does not exist on the remote. Dark mode is already wired in `mkdocs.yml` (both `default` and `slate` schemes). Decide one of two paths:
+
+**Path A — branch exists locally somewhere:** push it, open a PR against `main`, merge, then continue to Task 2.
+
+**Path B — start fresh now:** create the branch, make the UI improvements below, merge, then continue.
+
+- [ ] **Check for a local branch**
+
+  ```bash
+  git branch | grep -i refactor
+  ```
+
+  If found, push it:
+  ```bash
+  git push -u origin <branch-name>
+  gh pr create --title "docs(ui): ui-refactor" --body "UI polish for v0.4.6"
+  ```
+  Merge it, pull main, then jump to Task 2.
+
+- [ ] **If not found — create the branch**
+
+  ```bash
+  git checkout -b docs/ui-refactor
+  ```
+
+- [ ] **Apply UI improvements to `mkdocs.yml`**
+
+  Replace the current `palette` + `features` block with the version below.
+  Key changes: `primary` and `accent` moved from generic `blue` to the
+  OpenNMS brand teal (`#00758F`), dark scheme gets a matching override,
+  and three additional nav features are enabled.
+
+  ```yaml
+  theme:
+    name: material
+    palette:
+      - scheme: default
+        primary: custom
+        accent: custom
+        toggle:
+          icon: material/brightness-7
+          name: Switch to dark mode
+      - scheme: slate
+        primary: custom
+        accent: custom
+        toggle:
+          icon: material/brightness-4
+          name: Switch to light mode
+    features:
+      - navigation.instant
+      - navigation.top
+      - navigation.tabs
+      - navigation.sections
+      - search.suggest
+      - search.highlight
+      - content.code.copy
+      - content.tooltips
+
+  extra_css:
+    - stylesheets/extra.css
+  ```
+
+- [ ] **Create `docs/stylesheets/extra.css`**
+
+  ```css
+  :root {
+    --md-primary-fg-color: #00758F;
+    --md-primary-fg-color--light: #0099b8;
+    --md-primary-fg-color--dark: #005f73;
+    --md-accent-fg-color: #00758F;
+  }
+
+  [data-md-color-scheme="slate"] {
+    --md-primary-fg-color: #0099b8;
+    --md-primary-fg-color--light: #33b4cf;
+    --md-primary-fg-color--dark: #00758F;
+    --md-accent-fg-color: #0099b8;
+  }
+  ```
+
+- [ ] **Preview locally**
+
+  ```bash
+  source .venv/bin/activate
+  mkdocs serve
+  ```
+
+  Open http://127.0.0.1:8000. Verify:
+  - Light mode loads with teal nav bar
+  - Dark mode toggle switches to slate scheme with teal accents
+  - API reference page renders correctly
+
+- [ ] **Commit and open PR**
+
+  ```bash
+  git add mkdocs.yml docs/stylesheets/extra.css
+  git commit -m "docs(ui): brand teal theme + dark mode polish for v0.4.6"
+  git push -u origin docs/ui-refactor
+  gh pr create --title "docs(ui): brand teal theme + dark mode polish" \
+    --body "Replaces generic blue with OpenNMS brand teal (#00758F), adds navigation.tabs/sections and content.tooltips, adds extra.css for scheme overrides. Preview: mkdocs serve."
+  ```
+
+- [ ] **Wait for CI, merge**
+
+  ```bash
+  gh pr checks <PR-number> --watch
+  gh pr merge <PR-number> --squash
+  git checkout main && git pull origin main
+  ```
+
+---
+
+## Task 2: Bump version and update CHANGELOG
+
+**Files:** `pyproject.toml`, `CHANGELOG.md`
+
+- [ ] **Create release branch**
+
+  ```bash
+  git checkout -b chore/v0.4.6
+  ```
+
+- [ ] **Bump version in `pyproject.toml`**
+
+  Change line 7:
+  ```toml
+  version = "0.4.6"
+  ```
+
+- [ ] **Add CHANGELOG entry**
+
+  Insert the following block immediately after the `# Changelog` header
+  and the format/semver note lines, before the existing `## [0.4.5]` entry:
+
+  ```markdown
+  ## [0.4.6] - 2026-04-30
+
+  ### Added
+
+  - **Pre-commit ruff hook** (`.pre-commit-config.yaml`): contributors now
+    get lint feedback before pushing. `CONTRIBUTING.md` updated with the
+    optional `pre-commit install` setup step.
+  - **`types-requests`** added to dev dependencies so `mypy` works on a fresh
+    `pip install -e ".[dev]"` without a separate manual install.
+
+  ### Changed
+
+  - **Docs UI**: OpenNMS brand teal (`#00758F`) replaces generic blue across
+    light and dark mode; `navigation.tabs`, `navigation.sections`, and
+    `content.tooltips` enabled.
+  - **`CLAUDE.md`** updated with required prefix, linting/type-check commands,
+    single-test example, `mkdocs serve`, exception hierarchy, and new-mixin
+    step-by-step instructions; redundant 42-line mixin file list removed.
+
+  ### Fixed
+
+  - **427 mypy errors** resolved across 51 files:
+    - All 49 mixin classes now inherit `_OpenNMSBase` so mypy resolves
+      `_get`/`_post`/`_put`/`_delete`/`_patch` through the MRO.
+    - `Optional[X]` annotations added wherever a typed parameter defaulted
+      to `None`.
+    - `dict[str, Any]` annotations added to mixed-type `params`/`data` dicts.
+    - `from __future__ import annotations` added to 8 files that use
+      `dict[str, Any]` subscript syntax, preserving Python 3.8 compatibility.
+    - `_OpenNMSBase` removed from `client.py`'s explicit base list (inherited
+      through mixins, eliminating the MRO conflict).
+  ```
+
+- [ ] **Verify version appears correctly**
+
+  ```bash
+  grep "^version" pyproject.toml
+  ```
+  Expected: `version = "0.4.6"`
+
+- [ ] **Commit**
+
+  ```bash
+  git add pyproject.toml CHANGELOG.md
+  git commit -m "chore: bump to v0.4.6"
+  ```
+
+---
+
+## Task 3: Build and verify the package locally
+
+**Files:** `dist/` (generated, gitignored)
+
+- [ ] **Build**
+
+  ```bash
+  source .venv/bin/activate
+  pip install build -q
+  python -m build
+  ```
+
+  Expected output ends with:
+  ```
+  Successfully built opennms_api_wrapper-0.4.6.tar.gz and opennms_api_wrapper-0.4.6-py3-none-any.whl
+  ```
+
+- [ ] **Inspect the wheel contents**
+
+  ```bash
+  python -m zipfile -l dist/opennms_api_wrapper-0.4.6-py3-none-any.whl | head -30
+  ```
+
+  Verify `opennms_api_wrapper/` files are present and no unwanted files
+  (`.env`, `__pycache__`, `dist/`, `docs/`) are included.
+
+- [ ] **Smoke-test the wheel in a clean env**
+
+  ```bash
+  python3 -m venv /tmp/test-046
+  /tmp/test-046/bin/pip install dist/opennms_api_wrapper-0.4.6-py3-none-any.whl -q
+  /tmp/test-046/bin/python -c "
+  import opennms_api_wrapper as opennms
+  print(opennms.__version__)
+  c = opennms.OpenNMS('http://localhost:8980', 'admin', 'admin')
+  print(type(c))
+  "
+  ```
+
+  Expected:
+  ```
+  0.4.6
+  <class 'opennms_api_wrapper.client.OpenNMS'>
+  ```
+
+- [ ] **Run full test suite one last time**
+
+  ```bash
+  source .venv/bin/activate
+  pytest tests/ -v
+  ```
+  Expected: `490 passed`
+
+---
+
+## Task 4: Open PR, merge, and cut the release
+
+- [ ] **Push and open PR**
+
+  ```bash
+  git push -u origin chore/v0.4.6
+  gh pr create --title "chore: bump to v0.4.6" \
+    --body "$(cat <<'EOF'
+  Release v0.4.6. See CHANGELOG.md for full details.
+
+  ## Included since v0.4.5
+  - Pre-commit ruff hook
+  - 427 mypy errors fixed (51 files)
+  - CLAUDE.md improvements
+  - types-requests in dev deps
+  - Docs UI: brand teal theme + dark mode polish
+  EOF
+  )"
+  ```
+
+- [ ] **Wait for CI to go green**
+
+  ```bash
+  gh pr checks <PR-number> --watch
+  ```
+  All jobs must pass before merging.
+
+- [ ] **Merge**
+
+  ```bash
+  gh pr merge <PR-number> --squash
+  git checkout main && git pull origin main
+  ```
+
+- [ ] **Cut the release (triggers PyPI publish)**
+
+  ```bash
+  gh release create v0.4.6 \
+    --title "v0.4.6" \
+    --notes "$(cat <<'EOF'
+  ## What's new
+
+  ### Added
+  - Pre-commit ruff hook for contributors
+  - `types-requests` in dev dependencies
+
+  ### Changed
+  - Docs: OpenNMS brand teal theme + dark mode polish
+  - Improved `CLAUDE.md` (commands, exception tree, new-mixin guide)
+
+  ### Fixed
+  - 427 mypy errors resolved across 51 files (mixin inheritance, Optional annotations, Python 3.8 compat)
+
+  **Full changelog:** https://github.com/cnewkirk/opennms-api-wrapper/blob/main/CHANGELOG.md
+  EOF
+  )"
+  ```
+
+- [ ] **Confirm PyPI publish succeeded**
+
+  ```bash
+  gh run list --workflow publish.yml --limit 3
+  ```
+  Wait for the run triggered by the release to show `completed / success`.
+
+  Then verify:
+  ```bash
+  pip index versions opennms-api-wrapper 2>/dev/null | head -3
+  ```
+  Expected: `0.4.6` listed as the latest version.

mkdocs.yml

@@ -8,23 +8,29 @@ theme:
   name: material
   palette:
     - scheme: default
-      primary: blue
-      accent: blue
+      primary: custom
+      accent: custom
       toggle:
         icon: material/brightness-7
         name: Switch to dark mode
     - scheme: slate
-      primary: blue
-      accent: blue
+      primary: custom
+      accent: custom
       toggle:
         icon: material/brightness-4
         name: Switch to light mode
   features:
     - navigation.instant
     - navigation.top
+    - navigation.tabs
+    - navigation.sections
     - search.suggest
     - search.highlight
     - content.code.copy
+    - content.tooltips
+
+extra_css:
+  - stylesheets/extra.css
 
 plugins:
   - search