better

docs/skills/zensical-docs/SKILL.md

@@ -21,8 +21,17 @@ Load only the references required for the current task:
 
 - Source map for official docs and APIs: [./references/index.md](./references/index.md)
 - Zensical features and configuration links: [./references/zensical-features.md](./references/zensical-features.md)
+- Theme customization, colors, icons, and extension patterns: [./references/theme-customization-and-icons.md](./references/theme-customization-and-icons.md)
 - Docs writing quality and style guidance: [./references/documentation-quality.md](./references/documentation-quality.md)
 - Information architecture and discoverability patterns: [./references/discoverability-and-ia.md](./references/discoverability-and-ia.md)
+- Code-heavy API docs with mkdocstrings: [./references/code-heavy-docs-and-mkdocstrings.md](./references/code-heavy-docs-and-mkdocstrings.md)
+
+## Project Bootstrap Rule
+
+Always start a new documentation project with `uv run zensical new`.
+
+- This command provides the baseline scaffolding you need for structure, configuration, and theme setup.
+- Do not hand-build a new project skeleton when this command is available.
 
 ## Inputs To Collect
 
@@ -97,12 +106,14 @@ Completion check: each task page includes prerequisites, steps, expected result,
 ### Step 4: Apply Zensical Features Intentionally
 
 Load [./references/zensical-features.md](./references/zensical-features.md) and choose features based on content needs.
+Load [./references/code-heavy-docs-and-mkdocstrings.md](./references/code-heavy-docs-and-mkdocstrings.md) when the docs include Python APIs or other generated references.
 
 Decision matrix:
 
 - If docs are deep and section-heavy: enable `navigation.indexes`, `navigation.path`, and `navigation.sections`.
 - If speed and perceived responsiveness matter: enable `navigation.instant` and `navigation.instant.prefetch`.
 - If code-heavy content exists: enable `content.code.copy`, `content.code.select`, and `content.code.annotate`.
+- If code-heavy content includes API references: standardize on mkdocstrings for generated API docs and keep hand-written task guides alongside generated reference pages.
 - If users rely on search often: enable `search.highlight` and improve heading quality for better snippets.
 - If many pages share tab labels (for example Python/JS): enable `content.tabs.link`.
 
@@ -133,6 +144,7 @@ Completion check: no broken links, no dead-end pages, and all critical journeys
 - Every major section has an overview page and next-step links.
 - Task docs contain prerequisites, steps, expected results, and recovery guidance.
 - Enabled Zensical features are justified and aligned to user needs.
+- Code-heavy documentation strategy is explicit, including when and how mkdocstrings is used.
 - Navigation and search behavior are verified with real user tasks.
 - Site builds cleanly with `uv run zensical build`.