updating skill for new docs workflow

.bash_aliases

@@ -11,7 +11,7 @@ grep -E "set .port|server_name" /app/nginxproxy/data/nginx/proxy_host/*.conf \
 alias nginx='_ports'
 
 # tmp rebuild for hugo development
-alias hugo-rebuild='rm -rf public/ && hugo server --appendPort=false --baseURL="/" --ignoreCache'
+alias hugo-rebuild='cd /srv/dev/hugo/wiki ./preview.sh public'
 
 # helpers for quickly editing aliases
 alias src='source ~/.bash_aliases'

ai/skills/docs_architecture/SKILL.md

@@ -1,33 +1,42 @@
+---
+name: docs_architecture
+description: Exact technical architecture, routing, and deployment workflow for WompMacho's decoupled Hugo/Gitea/Nginx Wiki infrastructure.
+---
+
 # Docs Architecture Skill
 
-This skill documents the exact technical architecture, routing, and deployment workflow for WompMacho's decoupled Hugo/Gitea/Caddy Wiki infrastructure.
+This skill documents the exact technical architecture, routing, and deployment workflow for WompMacho's decoupled Hugo/Gitea/Nginx Wiki infrastructure.
 
 ## 🏗️ 1. Core Architecture (Decoupled Repositories)
 
 The system is split into three independent Git repositories hosted on `git.wompmacho.com`:
 
 1.  **Framework (`/srv/dev/hugo/wiki`)**: Repository `hugo-framework`
-    *   **Purpose**: The central Hugo engine. Contains the Blowfish theme as a submodule (`themes/blowfish`) and the master `config/_default/params.toml`.
+    *   **Purpose**: The central Hugo engine. The Blowfish theme is fully **decoupled/vendored** directly into the project's root folders (`layouts/`, `assets/`, `static/`, `data/`, `i18n/`, `archetypes/`). No theme submodules are used, protecting the site from upstream updates breaking the build.
-    *   **Rule**: NEVER place content (`.md` files) here. NEVER place environment-specific overrides (like hardcoded `editURLs` or top-level menus) in the global `params.toml`. 
+    *   **Rule**: NEVER place content (`.md` files) here. NEVER place environment-specific overrides (like hardcoded `editURLs` or top-level menus) in the global config. 
 
 2.  **Public Wiki (`/srv/docs/public`)**: Repository `docs-public`
     *   **Purpose**: Public-facing markdown notes, assets (`/static`), and its own top-bar menu configuration (`config/_default/menus.en.toml`).
-    *   **Deployment Target**: `/srv/caddy/sites/wiki`
+    *   **Deployment Target**: `/srv/www/docs-public`
     *   **Live URL**: `https://wiki.wompmacho.com` (proxied by NPM).
 
 3.  **Private Wiki (`/srv/docs/private`)**: Repository `docs-private`
     *   **Purpose**: Personal, private markdown notes, assets (`/static`), and its own top-bar menu configuration (`config/_default/menus.en.toml`).
-    *   **Deployment Target**: `/srv/caddy/sites/private-wiki`
+    *   **Deployment Target**: `/srv/www/docs-private`
     *   **Live URL**: `http://10.0.0.190:9897` (or `http://private` via NPM).
 
-## 💻 2. Local Development ("Live Link")
+## 💻 2. Local Development ("Live Link" Automation)
 
-When working on content, the user uses **Code-Server**. To see real-time updates without deploying, the `hugo-framework` repository uses symbolic links.
+When working on content, the user uses **Code-Server**. To see real-time updates without deploying, the framework repository uses automated symlinking and preview scripts.
 
-*   `content -> /srv/docs/public`
+*   **`preview.sh [public|private]`**:
-*   `static -> /srv/docs/public/static`
+    *   Creates symlinks: `content -> /srv/docs/[public|private]` and `static -> /srv/docs/[public|private]/static`.
-
+    *   Overwrites or symlinks specific config overrides (like `menus.en.toml`).
-**Command to start local preview**: `cd /srv/dev/hugo/wiki && hugo server --bind 0.0.0.0 --appendPort=false --baseURL="/"`
+    *   Executes `run-dev.sh` to start the local preview server.
+    *   Traps exits (Ctrl+C, normal exit) to cleanly restore standard framework defaults and remove preview symlinks automatically.
+*   **`run-dev.sh`**:
+    *   Launches the server bound to `0.0.0.0:1313` with code-server proxy parameters.
+    *   Passes `--renderToMemory` to prevent local watch loops and file write latency.
 
 ## 🚀 3. CI/CD Pipeline (Gitea Actions)
 
@@ -35,7 +44,7 @@ Both `docs-public` and `docs-private` have a `.gitea/workflows/deploy.yaml` acti
 
 ### The Build Process
 1.  **Checkout Content**: The runner checks out the markdown content.
-2.  **Clone Framework**: The runner natively clones the `hugo-framework` (including submodules) using `git clone --recurse-submodules https://git.wompmacho.com/wompmacho/hugo-framework.git`.
+2.  **Clone Framework**: The runner clones the central `hugo-framework` repository directly. Because the Blowfish theme is fully decoupled, there is no need for submodule initialization.
 3.  **Inject Content**: Markdown and static files are copied into the framework's workspace.
 4.  **Inject Dynamic Menus**: The `config/_default/menus.en.toml` is injected, automatically overriding the framework's top navigation bar for that specific site.
 5.  **Inject Edit Links (CRITICAL RULE)**: The "Edit this page" link on the bottom of posts MUST NOT be configured via a `params.toml` override, as Hugo replaces the entire file instead of merging it, destroying the Blowfish styling.
@@ -45,17 +54,18 @@ Both `docs-public` and `docs-private` have a `.gitea/workflows/deploy.yaml` acti
 
 ## 🌐 4. Web Server Routing (Nginx)
 
-The system relies on two extremely lightweight `nginx:alpine` containers defined in `gitea/docker-compose.yaml` to serve static files. They act as "dumb" file servers behind Nginx Proxy Manager (NPM), bypassing the complex Host header validation and 0-byte security issues inherent to Caddy.
+The system relies on two extremely lightweight `nginx:alpine` containers defined in `gitea/docker-compose.yaml` to serve static files. They act as file servers behind Nginx Proxy Manager (NPM).
 
 1.  **Public (`public_wiki` - Port 9896)**: 
-    *   Mounts `/srv/caddy/sites/wiki` as read-only.
+    *   Mounts `/srv/www/docs-public` as read-only.
     *   NPM routes `wiki.wompmacho.com` to Docker Host IP on port `9896`.
 2.  **Private (`private_wiki` - Port 9897)**: 
-    *   Mounts `/srv/caddy/sites/private-wiki` as read-only.
+    *   Mounts `/srv/www/docs-private` as read-only.
     *   NPM routes `http://private` to Docker Host IP on port `9897`.
 
 ## 🛠️ 5. Known Quirks and Formatting Rules
 
-*   **Submodules**: Always use `git submodule add -b main <url>` and ensure the commit pointer is tracked. Do not copy theme files physically.
+*   **Decoupled Theme**: The Blowfish theme is committed directly in the main codebase. Do not use Git submodules to track the theme.
 *   **Blowfish Homepage**: If the homepage is blank, it means there are no recent posts. By default, Blowfish's `home` layout only lists files with `type: "article"` or `type: "posts"`. For generic folders, set `type: "page"` and `layout: "list"` in `_index.md`.
 *   **Frontmatter**: Blowfish expects standard Hugo frontmatter (`date:` as a string, `authors: ["Name"]` as an array). MkDocs-style nested YAML is incompatible and will crash the build.
+*   **Troubleshooting**: See `references/troubleshooting.md` for handling theme updates, build loops, and TOC configuration.

ai/skills/docs_architecture/references/troubleshooting.md

@@ -0,0 +1,24 @@
+# Hugo/Blowfish Troubleshooting & Pitfalls
+
+## 1. Infinite Rebuild Loops
+If Hugo triggers a rebuild loop:
+*   **Cause**: Hugo watches the `resources/` directory, and the generation of cached/busted assets (like `admonitions.scss_...json`) triggers a new rebuild event.
+*   **Fix**: Add the following to `config/_default/hugo.toml`:
+    ```toml
+    [watch]
+      ignore = ["resources/**"]
+    ```
+*   **Tool Usage**: If the loop persists, start the server with polling to reduce sensitivity:
+    `hugo server --poll 1s`
+
+## 2. Table of Contents (TOC) Issues
+Blowfish manages TOC natively via `params.toml`. Avoid using manual `[TOC]` or `{{< toc >}}` in your Markdown unless explicitly required by a specific layout.
+*   **Standard Setup**: Ensure `showTableOfContents = true` is set in the `[article]` and `[list]` sections of your `config/_default/params.toml`.
+*   **Custom Layouts**: If TOC is rendering in the wrong place, it is likely due to an overridden `layouts/_default/single.html`. Revert to the native theme structure (`container` and `prose` classes) so the Blowfish partials can handle the placement.
+*   **TOC ScrollSpy Highlighting**: If the TOC fails to highlight active headings when scrolling, verify that `smartTOC = true` is enabled in `params.toml`. If it is nested inside the `[article]` section, ensure that the `layouts/partials/toc.html` checks:
+    `{{ if or .Site.Params.smartTOC .Site.Params.article.smartTOC }}`
+    to correctly resolve the nested parameter.
+
+## 3. Theme Updates & Customization
+*   **Version mismatch**: When Hugo updates, theme templates often break (e.g., `can't evaluate field Locale`).
+*   **Decoupled Theme Installation**: The theme is fully decoupled/vendored in the root folders. If you need to update Blowfish, you will copy/vendor the new templates into `layouts/` and assets into `assets/`, but you must review custom changes to templates such as `layouts/_default/single.html` and `layouts/partials/toc.html` to make sure custom styles and scripts (like multiple TOC elements or active highlight overrides) are preserved.

ai/skills/workflow_management/SKILL.md

@@ -23,3 +23,12 @@ This skill allows Gemini to efficiently manage the lifecycle of project workflow
 - **Action Items**:
     - [ ] [Specific task]
 - **Verification**: [Public-domain method to verify success]
+
+---
+
+## Pitfalls & Best Practices
+
+- **Avoid Absolute Positioning in Layouts**: When customizing themes, prefer Flexbox or Grid over `position: absolute` for structural elements like Sidebars or TOCs to prevent content overlap and preserve responsive layout integrity.
+- **Global Theme Settings**: For TOC rendering in Blowfish, rely on `params.toml` configuration (`showTableOfContents = true`) rather than custom Markdown shortcodes (`[TOC]` or `{{< toc >}}`), which are often theme-incompatible.
+- **Custom CSS vs Theme Overrides**: Always use `assets/css/custom.css` for structural overrides. Never modify theme-internal files (`themes/blowfish/...`), as they will be overwritten during updates.
+- **Container Widths**: When overriding container widths, use relative units (percentages) and `!important` sparingly to avoid breaking theme-defined responsive breakpoints.

docker_compose/homelabel/docker-compose.yaml

@@ -41,12 +41,12 @@
       - backend
     labels:
       # Nginx Proxy Manager Automation
-      - "npm.proxy.domains=homelable"
+      - "npm.proxy.domains=homelable.wompmacho.com"
       - "npm.proxy.host=${DOCKER_HOST_IP}"
       - "npm.proxy.port=${HOMELABEL_FRONT_PORT}"
       - "npm.proxy.scheme=http"
-      #- "npm.proxy.websockets=true"
+      - "npm.proxy.websockets=true"
       #- "npm.proxy.ssl_verify=false"
-      #- "npm.proxy.ssl.force=true"
+      - "npm.proxy.ssl.force=true"
-      #- "npm.proxy.ssl.certificate.id=1"
+      - "npm.proxy.ssl.certificate.id=2"
-      - "pihole.custom-record=[[\"homelable\", \"${DOCKER_HOST_IP}\"]]"
+      - "pihole.custom-record=[[\"homelable.wompmacho.com\", \"${DOCKER_HOST_IP}\"]]"

docker_compose/homepage/config/services.yaml

@@ -265,6 +265,6 @@
         description: neko browser
     - homelable:
         icon: https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/homelable.svg
-        href: "http://homelable/view?key=live"
+        href: "https://homelable.wompmacho.com/view?key=live"
         target: _self
         description: homelable

docker_compose/openai/docker-compose.yaml

@@ -1,6 +1,6 @@
 # Open WebUI - https://docs.openwebui.com/getting-started/quick-start/
 services:
-  openwebui:
+  openai:
     container_name: openai
     image: ghcr.io/open-webui/open-webui:latest
     restart: unless-stopped