From 1254cc5432628c19317249547c92e603b3070178 Mon Sep 17 00:00:00 2001
From: John Lancaster <32917998+jsl12@users.noreply.github.com>
Date: Thu, 18 Jun 2026 22:34:31 -0500
Subject: [PATCH] better

---
 docs/skills/zensical-docs/SKILL.md            | 12 ++++
 .../code-heavy-docs-and-mkdocstrings.md       | 59 ++++++++++++++++++
 docs/skills/zensical-docs/references/index.md |  7 +++
 .../theme-customization-and-icons.md          | 60 +++++++++++++++++++
 .../references/zensical-features.md           | 12 +++-
 5 files changed, 149 insertions(+), 1 deletion(-)
 create mode 100644 docs/skills/zensical-docs/references/code-heavy-docs-and-mkdocstrings.md
 create mode 100644 docs/skills/zensical-docs/references/theme-customization-and-icons.md

diff --git a/docs/skills/zensical-docs/SKILL.md b/docs/skills/zensical-docs/SKILL.md
index 815bdeb..a677dad 100644
--- a/docs/skills/zensical-docs/SKILL.md
+++ b/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`.
 
diff --git a/docs/skills/zensical-docs/references/code-heavy-docs-and-mkdocstrings.md b/docs/skills/zensical-docs/references/code-heavy-docs-and-mkdocstrings.md
new file mode 100644
index 0000000..1688106
--- /dev/null
+++ b/docs/skills/zensical-docs/references/code-heavy-docs-and-mkdocstrings.md
@@ -0,0 +1,59 @@
+# Code-Heavy Documentation with mkdocstrings
+
+Use this reference when your docs include API surfaces, function/class documentation, and source-driven technical reference.
+
+## Why mkdocstrings
+
+mkdocstrings helps generate and maintain API reference pages directly from code and docstrings, reducing drift between implementation and docs.
+
+Primary docs:
+- mkdocstrings home: https://mkdocstrings.github.io/
+- mkdocstrings Python handler: https://mkdocstrings.github.io/python/
+- Griffe (Python parsing engine): https://mkdocstrings.github.io/griffe/
+
+## When to Use It
+
+- You maintain Python modules/classes/functions that need searchable reference docs.
+- You want hand-written concept/task docs plus generated API reference pages.
+- You need consistent signatures, type hints, and docstring rendering.
+
+## Recommended Documentation Split
+
+1. Hand-authored docs for concepts, architecture, and tasks.
+2. Generated docs (mkdocstrings) for API details.
+3. Cross-links in both directions:
+   - task pages link to specific API entries
+   - API pages link to practical guides and examples
+
+## Minimal Integration Pattern
+
+1. Add mkdocstrings and a Python handler package to project dependencies.
+2. Configure docs toolchain to enable mkdocstrings plugin/extension.
+3. Create one API index page per package/domain.
+4. Expand coverage gradually from high-value modules first.
+
+General reference examples:
+- Plugin docs: https://www.mkdocs.org/user-guide/plugins/
+- Material + code/reference setup concepts: https://squidfunk.github.io/mkdocs-material/reference/
+
+## Authoring Guidance for Docstrings
+
+- Begin with a one-line summary in imperative or descriptive form.
+- Document parameters, return values, raised exceptions, and side effects.
+- Include short examples for non-obvious usage.
+- Keep terminology aligned with task docs and architecture pages.
+
+## Quality Gates for Code-Heavy Docs
+
+- API pages build cleanly and include expected modules.
+- Symbols are grouped by domain, not dumped in one long page.
+- Public APIs have meaningful docstrings before publishing.
+- Generated reference pages are linked from user-facing docs.
+- Search can find both conceptual guides and concrete API entries.
+
+## Common Pitfalls
+
+- Treating generated API docs as a replacement for task documentation.
+- Publishing API pages without module-level context.
+- Letting undocumented public APIs accumulate.
+- Not reviewing generated pages after refactors.
diff --git a/docs/skills/zensical-docs/references/index.md b/docs/skills/zensical-docs/references/index.md
index df70035..920db97 100644
--- a/docs/skills/zensical-docs/references/index.md
+++ b/docs/skills/zensical-docs/references/index.md
@@ -4,6 +4,7 @@ Use this index to load only the source references needed for the current task.
 
 ## Zensical Official Docs
 
+- New project scaffolding (`uv run zensical new`): https://zensical.org/docs/
 - Home: https://zensical.org/docs/
 - Setup basics: https://zensical.org/docs/setup/basics/
 - Navigation setup: https://zensical.org/docs/setup/navigation/
@@ -36,3 +37,9 @@ Use this index to load only the source references needed for the current task.
 - Markdown guide: https://www.markdownguide.org/
 - MkDocs configuration reference: https://www.mkdocs.org/user-guide/configuration/
 - Material for MkDocs setup reference: https://squidfunk.github.io/mkdocs-material/setup/
+- mkdocstrings: https://mkdocstrings.github.io/
+
+## Skill-Specific Deep Dives
+
+- Theme customization, colors, icons: [./theme-customization-and-icons.md](./theme-customization-and-icons.md)
+- Code-heavy docs with mkdocstrings: [./code-heavy-docs-and-mkdocstrings.md](./code-heavy-docs-and-mkdocstrings.md)
diff --git a/docs/skills/zensical-docs/references/theme-customization-and-icons.md b/docs/skills/zensical-docs/references/theme-customization-and-icons.md
new file mode 100644
index 0000000..dc9ac26
--- /dev/null
+++ b/docs/skills/zensical-docs/references/theme-customization-and-icons.md
@@ -0,0 +1,60 @@
+# Theme Customization, Colors, and Icons
+
+Use this reference when you want documentation that feels intentional and brand-aligned while preserving readability and accessibility.
+
+## Start from the Scaffold
+
+Always start new projects with `uv run zensical new` so the baseline theme/config scaffolding is in place before customization.
+
+## Customization Strategy
+
+1. Configure theme and feature flags in the project config first.
+2. Apply visual tokens (colors, spacing, typography) in a shared CSS layer.
+3. Add icons and logo assets with consistent naming.
+4. Use template overrides only when config/CSS cannot solve the requirement.
+
+## Key Zensical Customization Surfaces
+
+- Customization overview: https://zensical.org/docs/customization/
+- Additional CSS: https://zensical.org/docs/customization/#additional-css
+- Additional JavaScript: https://zensical.org/docs/customization/#additional-javascript
+- Extending the theme: https://zensical.org/docs/customization/#extending-the-theme
+- Logo and icons setup: https://zensical.org/docs/setup/logo-and-icons/
+
+## Colors and Accessibility
+
+- Define color variables once and reuse them for semantic roles (primary, surface, muted, success, warning).
+- Keep contrast high for body text, code blocks, and nav labels.
+- Test color changes on mobile and desktop, including search highlights and active nav states.
+
+General references:
+- Material design color guidance: https://m3.material.io/styles/color
+- WCAG overview: https://www.w3.org/WAI/standards-guidelines/wcag/
+
+## Icons: Selection and Search Landing Pages
+
+If your theme supports icon sets through your docs stack, these search portals are useful:
+
+- Material Symbols search: https://fonts.google.com/icons
+- Font Awesome icons search: https://fontawesome.com/search
+- Simple Icons search: https://simpleicons.org/
+- Iconify icon set search: https://icon-sets.iconify.design/
+- Lucide icons: https://lucide.dev/icons/
+
+Tip: pick one primary icon family for navigation and status icons, then document naming conventions.
+
+## Extending the Theme Safely
+
+Use overrides as a last step, not the first.
+
+1. Confirm the requirement cannot be solved by config and CSS.
+2. Keep override templates minimal and focused.
+3. Track upstream changes if you override partials.
+4. Add a visual regression checklist for common pages.
+
+## Review Checklist
+
+- Theme changes preserve readability for long-form docs.
+- Icons are consistent in weight/style and meaningful in context.
+- Color changes do not break code-block syntax highlighting or search visibility.
+- Overrides are documented with rationale and owner.
diff --git a/docs/skills/zensical-docs/references/zensical-features.md b/docs/skills/zensical-docs/references/zensical-features.md
index 3298507..ee0675f 100644
--- a/docs/skills/zensical-docs/references/zensical-features.md
+++ b/docs/skills/zensical-docs/references/zensical-features.md
@@ -2,6 +2,13 @@
 
 Use this reference when deciding which Zensical features to enable and why.
 
+## Project Bootstrap
+
+Always start a new docs project with `uv run zensical new`.
+
+- It creates the baseline scaffolding for configuration, docs structure, and theme integration.
+- Treat this as the default starting point rather than manually assembling files.
+
 ## High-Value Feature Groups
 
 ### Navigation and Discoverability
@@ -22,9 +29,12 @@ Source links:
 - `content.code.copy`: copy button in code blocks.
 - `content.code.select`: line range selection support.
 - `content.code.annotate`: inline code annotations.
+- Prefer mkdocstrings for generated API reference pages when documenting Python code.
+- Keep generated API pages linked from hand-authored task and concept docs.
 
 Source links:
 - https://zensical.org/docs/authoring/code-blocks/
+- https://mkdocstrings.github.io/
 
 ### Cross-Page UX Consistency
 
@@ -63,6 +73,6 @@ Source links:
 ## Practical Feature Selection Rules
 
 1. Start with discoverability and clarity features first.
-2. Add convenience features (copy/select/tooltips) when content type supports them.
+2. For code-heavy docs, add copy/select/annotate first, then define mkdocstrings coverage for API reference.
 3. Avoid enabling many features at once without measurement.
 4. Track user success metrics (search success, time-to-answer, support deflection) after each change.