feat(docs): polish pass 1 — nav order, robust release macro, internal helpers

- docs/.pages: explicit nav order (Home -> Getting started -> Guides -> Reference -> Architecture -> Contributing -> Release notes), with ... fallback
- docs/architecture/.pages: order handwritten pages first, internal-helpers last
- homepage.py: latest_release() reads release notes from disk (docs-build/generated/release-notes/) instead of calling gh api at build time. Removes runtime dependency on gh CLI + GH_TOKEN
- workflow: generate Internal scope reference into docs/architecture/internal-helpers/, drop GH_TOKEN from Build site step
- gitignore: docs/architecture/internal-helpers/

Author: ctrl-alt-automate

.github/workflows/docs.yml

@@ -62,6 +62,14 @@ jobs:
             -OutputPath ./docs-build/generated/reference `
             -Scope Public
 
+      - name: Build reference (internal helpers)
+        shell: pwsh
+        run: |
+          ./scripts/Build-PlatyPSReference.ps1 `
+            -ModulePath ./PowerNetbox.psd1 `
+            -OutputPath ./docs-build/generated/architecture/internal-helpers `
+            -Scope Internal
+
       - name: Build release notes
         shell: pwsh
         env:
@@ -76,14 +84,13 @@ jobs:
           # reference/common-parameters.md (Task 17). Same selective pattern used
           # in local dev verification.
           for d in docs/reference/*/; do rm -rf "$d"; done
-          rm -rf docs/release-notes
-          mkdir -p docs/reference docs/release-notes
+          rm -rf docs/release-notes docs/architecture/internal-helpers
+          mkdir -p docs/reference docs/release-notes docs/architecture/internal-helpers
           cp -r docs-build/generated/reference/. docs/reference/
           cp -r docs-build/generated/release-notes/. docs/release-notes/
+          cp -r docs-build/generated/architecture/internal-helpers/. docs/architecture/internal-helpers/
 
       - name: Build site
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           cd docs-build
           mkdocs build --strict

.gitignore

@@ -80,3 +80,4 @@ docs/reference/Plugins/
 docs/superpowers/plans/
 docs/superpowers/specs/
 docs/release-notes/
+docs/architecture/internal-helpers/

docs-build/macros/homepage.py

@@ -1,15 +1,22 @@
 """Homepage macros: cmdlet count, latest release, compat table."""
 
-import json
 import re
-import subprocess
 from pathlib import Path
 
 
 # Resolve PowerNetbox.psd1 relative to this file's location, not CWD.
 # docs-build/macros/homepage.py -> docs-build/macros -> docs-build -> worktree root
 PSD1_PATH = Path(__file__).parent.parent.parent / "PowerNetbox.psd1"
 
+# Release notes live in docs-build/generated/release-notes/ (CI-generated) or
+# fall back to docs/release-notes/ (already-merged copy).
+_WORKTREE_ROOT = Path(__file__).parent.parent.parent
+_GENERATED_RELEASE_DIR = _WORKTREE_ROOT / "docs-build" / "generated" / "release-notes"
+_DOCS_RELEASE_DIR = _WORKTREE_ROOT / "docs" / "release-notes"
+
+_VERSION_RE = re.compile(r"^\d+\.\d+\.\d+(\.\d+)?\.md$")
+_RELEASED_RE = re.compile(r"^Released (\d{4}-\d{2}-\d{2})\b")
+
 
 def _count_public_cmdlets() -> int:
     """Count Verb-NB* entries in the FunctionsToExport block of the psd1."""
@@ -19,19 +26,57 @@ def _count_public_cmdlets() -> int:
     return len(entries)
 
 
+def _parse_version(filename: str) -> tuple:
+    """Return a tuple of ints for semver sorting from a filename like '4.5.8.1.md'."""
+    stem = filename[:-3]  # strip .md
+    return tuple(int(x) for x in stem.split("."))
+
+
 def _fetch_latest_release() -> dict | None:
-    """Call `gh api ...releases/latest` and return parsed JSON, or None on failure."""
-    try:
-        out = subprocess.check_output(
-            ["gh", "api", "repos/ctrl-alt-automate/PowerNetbox/releases/latest"],
-            text=True,
-            stderr=subprocess.DEVNULL,
-            timeout=30,
-        )
-        return json.loads(out)
-    except Exception:
+    """Read the newest release note from disk and return a dict matching the old
+    GitHub API shape: {tag_name, published_at, body}. Returns None on failure."""
+    # Prefer the CI-generated directory; fall back to docs/release-notes/
+    release_dir = None
+    for candidate in (_GENERATED_RELEASE_DIR, _DOCS_RELEASE_DIR):
+        if candidate.is_dir():
+            release_dir = candidate
+            break
+
+    if release_dir is None:
         return None
 
+    version_files = [f.name for f in release_dir.iterdir() if _VERSION_RE.match(f.name)]
+    if not version_files:
+        return None
+
+    # Sort descending by semver and pick the newest
+    latest_filename = sorted(version_files, key=_parse_version, reverse=True)[0]
+    version = latest_filename[:-3]  # strip .md
+
+    text = (release_dir / latest_filename).read_text(encoding="utf-8")
+    lines = text.splitlines()
+
+    # Find the "Released YYYY-MM-DD" line
+    date = "unknown"
+    body_start = 0
+    for i, line in enumerate(lines):
+        m = _RELEASED_RE.match(line)
+        if m:
+            date = m.group(1)
+            body_start = i + 1
+            break
+
+    # Everything after the Released line is the body (skip leading blank lines)
+    body_lines = lines[body_start:]
+    while body_lines and not body_lines[0].strip():
+        body_lines = body_lines[1:]
+
+    return {
+        "tag_name": f"v{version}",
+        "published_at": f"{date}T00:00:00Z",
+        "body": "\n".join(body_lines),
+    }
+
 
 def register_homepage(env):
     """Register homepage macros with the mkdocs-macros env."""

docs/.pages

@@ -0,0 +1,9 @@
+nav:
+  - index.md
+  - getting-started
+  - guides
+  - reference
+  - architecture
+  - contributing
+  - release-notes
+  - ...

docs/architecture/.pages

@@ -0,0 +1,9 @@
+nav:
+  - overview.md
+  - function-naming.md
+  - error-handling.md
+  - parameter-conventions.md
+  - functions-map.md
+  - helpers-map.md
+  - graphql-internals.md
+  - internal-helpers