updating skill for new docs workflow

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.