swapped docs symlink

src/personal_mcp/docs/skills/zensical-docs/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: zensical-docs
+description: 'Reference skill for Zensical documentation mechanics. Use for quick lookup of docs structure, feature options, and source links. Prefer inline Markdown links to source docs and avoid bare URLs because this content is rendered as human docs and MCP resources.'
+---
+
+# Zensical Documentation Authoring
+
+Use this as a compact reference for Zensical mechanics and as the place to record evolving preferences for how this repository uses them.
+
+## When to Use
+
+- You need a quick reminder of Zensical features, docs structure, or configuration mechanics.
+- You want direct links back to source documentation before changing docs behavior.
+- You want one small file you can keep editing as your preferences around docs authoring become clearer.
+
+## How To Use This Skill
+
+1. Start here for a quick decision about what kind of docs change you are making.
+2. Open only the linked reference that matches the current task.
+3. Add or revise preference notes in this file when you decide how this repo should use a feature.
+
+## Quick Reference Map
+
+Open only what you need:
+
+- Official docs and source map: [source map](./references/index.md)
+- Zensical feature catalog and setup links: [feature catalog](./references/zensical-features.md)
+- Theme, icons, and visual customization: [theme customization](./references/theme-customization-and-icons.md)
+- Writing quality and review criteria: [documentation quality](./references/documentation-quality.md)
+- Navigation and discoverability patterns: [discoverability and IA](./references/discoverability-and-ia.md)
+- Code-heavy docs and API reference patterns: [code-heavy docs](./references/code-heavy-docs-and-mkdocstrings.md)
+
+## Common Cases
+
+### New docs project
+
+- Start with `uv run zensical new`.
+- Then review the [source map](./references/index.md) and [feature catalog](./references/zensical-features.md).
+
+### Restructuring docs or navigation
+
+- Review [discoverability and IA](./references/discoverability-and-ia.md).
+- Use it to decide overview pages, section structure, and cross-linking.
+
+### Improving writing quality
+
+- Review [documentation quality](./references/documentation-quality.md).
+- Use it for page quality gates, trust signals, and review criteria.
+
+### Adjusting theme or UI mechanics
+
+- Review [theme customization](./references/theme-customization-and-icons.md).
+- Use it for icons, color, theme extensions, and presentation choices.
+
+### Documenting APIs or code-heavy systems
+
+- Review [code-heavy docs](./references/code-heavy-docs-and-mkdocstrings.md).
+- Use it when generated API reference belongs alongside hand-authored docs.
+
+## Preferences To Maintain Here
+
+Keep this section short and revise it over time.
+
+### Preferred feature choices
+
+- Add the Zensical features you usually enable first.
+- Note which features are situational and why.
+- Prefer Zensical-native features and conventions when they cover the need cleanly.
+- Expect general backward compatibility with MkDocs patterns and configuration unless there is a documented reason not to.
+
+### Preferred docs structure
+
+- Record whether this repo prefers explicit nav, index pages, task-first docs, or another pattern.
+
+### Preferred API docs approach
+
+- Record whether to use mkdocstrings, how much API surface to publish, and how to link task docs back to reference pages.
+
+## Source-First Rule
+
+When making a recommendation, link back to the relevant reference file first, and when possible to the upstream docs linked from that reference.
+
+## Link Formatting Rule
+
+Because this project publishes the same markdown for both `/docs` and MCP resources, link quality is part of the content contract.
+
+- Never leave a bare URL in prose or list items.
+- Prefer using in-place Markdown links with meaningful labels.
+- For external sources, prefer `[descriptive label](https://...)` over raw `https://...`.
+- For internal files, prefer relative Markdown links so rendered docs remain navigable.
+- Any mention of a library or a specific library feature should include a link to source documentation somewhere on the page.
+- If inline linking is awkward or the citation payload is too large, use a footnote or tooltip citation instead.
+
+Example preferred style:
+
+- `See [importlib.resources](https://docs.python.org/3/library/importlib.resources.html) for packaging details.`
+
+Example to avoid:
+
+- `See https://docs.python.org/3/library/importlib.resources.html for packaging details.`
+
+Acceptable alternatives when inline links are not ideal:
+
+- Add a footnote-style source citation at the end of the section or page.
+- Add a tooltip citation when the docs pattern supports it.
+
+## Compatibility Rule
+
+Prefer the Zensical-native way of doing something when it exists and is well-supported.
+Assume MkDocs compatibility is still expected for most configuration and authoring patterns, and call out any case where a Zensical recommendation intentionally diverges from standard MkDocs behavior.
+
+## Output Contract
+
+Return only what is useful for the current docs task:
+
+1. Which reference to read next.
+2. The smallest recommended docs or config change.
+3. Any repo-specific preference this suggests should be added back into this skill.
+4. For any library or feature-level claim, include a source-doc citation somewhere (inline link preferred; footnote or tooltip acceptable).

src/personal_mcp/docs/skills/zensical-docs/references/code-heavy-docs-and-mkdocstrings.md

@@ -0,0 +1,63 @@
+# 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.
+
+!!! info "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 the Zensical docs toolchain to enable mkdocstrings within the site build.
+3. Create one API index page per package/domain.
+4. Expand coverage gradually from high-value modules first.
+
+!!! info "General reference examples"
+    - [Zensical docs home and setup entry point](https://zensical.org/docs/)
+    - [Zensical code blocks and authoring patterns](https://zensical.org/docs/authoring/code-blocks/)
+    - [Zensical customization overview](https://zensical.org/docs/customization/)
+
+!!! note "Compatibility"
+    Zensical is generally expected to remain compatible with MkDocs-style configuration patterns, but prefer Zensical-native documentation and examples when they cover the same behavior.
+
+## 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.

src/personal_mcp/docs/skills/zensical-docs/references/discoverability-and-ia.md

@@ -0,0 +1,74 @@
+# Discoverability and Information Architecture
+
+Use this reference to design docs that are progressively discoverable from overview to implementation detail.
+
+## IA Model
+
+Organize by user intent, then by product area.
+
+Recommended top-level model:
+
+1. Learn (concepts, architecture, mental models)
+2. Do (task/how-to paths)
+3. Reference (API, config, command catalog)
+4. Troubleshoot (symptoms, diagnostics, fixes)
+
+!!! info "IA references"
+    - [Diataxis framework](https://diataxis.fr/)
+    - [Divio documentation system](https://documentation.divio.com/)
+
+## Progressive Discoverability Pattern
+
+### Layer 1: Section Overview
+
+Each section starts with an index page containing:
+
+- What this section is for
+- Who should read it
+- Common journeys
+- Links to key tasks and references
+
+### Layer 2: Task or Concept Pages
+
+Each page includes:
+
+- 1-2 sentence purpose
+- prerequisites
+- internal links to references and next steps
+
+### Layer 3: Deep Reference
+
+Keep deep details in dedicated reference pages and link to them from task pages when needed.
+
+## Navigation Design Rules
+
+1. Keep navigation labels user-facing and action-oriented.
+2. Avoid duplicate labels in separate branches.
+3. Place high-frequency tasks near the top.
+4. Keep section depth shallow where possible.
+
+!!! info "Relevant Zensical configuration docs"
+    - [Navigation setup](https://zensical.org/docs/setup/navigation/)
+    - [Search setup](https://zensical.org/docs/setup/search/)
+    - [Header setup](https://zensical.org/docs/setup/header/)
+    - [Footer setup](https://zensical.org/docs/setup/footer/)
+
+## Link Strategy
+
+- Every deep page should have at least one inbound link from a higher-level index page.
+- Add "See also" blocks for neighboring tasks.
+- Link to source-of-truth reference pages instead of duplicating config tables.
+
+## Search Optimization for Docs
+
+- Put key terms in title and first paragraph.
+- Use specific H2/H3 headings that match user query language.
+- Keep repeated boilerplate minimal so snippets stay informative.
+
+## Review Heuristics
+
+A documentation journey is healthy when:
+
+- users can identify their path within 10 seconds on a section index page
+- users can complete primary tasks without opening more than 2-3 tabs
+- users can recover from common errors without external support tickets

src/personal_mcp/docs/skills/zensical-docs/references/documentation-quality.md

@@ -0,0 +1,54 @@
+# Documentation Quality Best Practices
+
+Use this reference when writing or reviewing docs for clarity, correctness, and trust.
+
+## Core Writing Principles
+
+1. Write for a specific audience and task.
+2. Lead with outcomes, not internal implementation details.
+3. Keep concepts, tasks, and references distinct.
+4. Make examples executable and verifiable.
+5. Prefer precise language over marketing language.
+
+!!! info "Primary references"
+    - [Diataxis](https://diataxis.fr/)
+    - [Divio documentation system](https://documentation.divio.com/)
+    - [Write the Docs guide](https://www.writethedocs.org/guide/)
+
+## Style and Readability
+
+- Use consistent terminology and avoid synonym drift.
+- Use short paragraphs and meaningful headings.
+- Prefer active voice and imperative instructions for task pages.
+- Add notes/warnings only for high-impact caveats.
+
+!!! info "Style sources"
+    - [Google developer style](https://developers.google.com/style)
+    - [Microsoft Writing Style Guide](https://learn.microsoft.com/style-guide/welcome/)
+    - [MDN writing guidelines](https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines)
+
+## Task Page Quality Pattern
+
+Each task page should include:
+
+1. Goal and scope.
+2. Prerequisites (permissions, versions, environment).
+3. Step-by-step procedure.
+4. Expected result and verification command/output.
+5. Common failure modes and recovery path.
+6. Related links (concept, reference, troubleshooting).
+
+## Quality Gates Before Publish
+
+- Accuracy: commands and code examples are validated.
+- Completeness: no critical missing steps.
+- Discoverability: page is linked from at least one overview page.
+- Freshness: version-specific notes and dates are present where needed.
+- Accessibility: heading structure and link text are clear.
+
+## Anti-Patterns
+
+- Mixing conceptual explanation and long procedural flow in the same section without structure.
+- Hiding prerequisites mid-page.
+- Using screenshots as the only source of truth for commands.
+- Publishing pages with no owner and no review cadence.

src/personal_mcp/docs/skills/zensical-docs/references/index.md

@@ -0,0 +1,48 @@
+# Zensical Docs Skill References
+
+Use this index to load only the source references needed for the current task.
+
+## Zensical Official Docs
+
+!!! info "Zensical official docs"
+    - [New project scaffolding](https://zensical.org/docs/) for `uv run zensical new`.
+    - [Home](https://zensical.org/docs/)
+    - [Setup basics](https://zensical.org/docs/setup/basics/)
+    - [Navigation setup](https://zensical.org/docs/setup/navigation/)
+    - [Header setup and announcement bar](https://zensical.org/docs/setup/header/)
+    - [Footer setup](https://zensical.org/docs/setup/footer/)
+    - [Repository and content actions](https://zensical.org/docs/setup/repository/)
+    - [Search setup](https://zensical.org/docs/setup/search/)
+    - [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)
+    - [Theme extension and overrides](https://zensical.org/docs/customization/#extending-the-theme)
+    - [Language setup](https://zensical.org/docs/setup/language/)
+    - [Logo and icons](https://zensical.org/docs/setup/logo-and-icons/)
+    - [Code blocks and annotations](https://zensical.org/docs/authoring/code-blocks/)
+    - [Content tabs](https://zensical.org/docs/authoring/content-tabs/)
+    - [Footnotes](https://zensical.org/docs/authoring/footnotes/)
+    - [Tooltips](https://zensical.org/docs/authoring/tooltips/)
+
+## Adjacent Documentation Quality Sources
+
+!!! info "Documentation quality sources"
+    - [Divio documentation system](https://documentation.divio.com/)
+    - [Write the Docs guide](https://www.writethedocs.org/guide/)
+    - [Google developer documentation style guide](https://developers.google.com/style)
+    - [Microsoft Writing Style Guide](https://learn.microsoft.com/style-guide/welcome/)
+    - [MDN writing guidelines](https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines)
+    - [Diataxis framework](https://diataxis.fr/)
+
+## Related Tooling References
+
+!!! info "Related tooling"
+    - [Markdown guide](https://www.markdownguide.org/)
+    - [Zensical setup and configuration entry point](https://zensical.org/docs/)
+    - [Zensical customization reference](https://zensical.org/docs/customization/)
+    - [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)

src/personal_mcp/docs/skills/zensical-docs/references/theme-customization-and-icons.md

@@ -0,0 +1,62 @@
+# 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
+
+!!! info "Zensical sources"
+    - [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.
+
+!!! info "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 "Icon family consistency"
+    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.

src/personal_mcp/docs/skills/zensical-docs/references/zensical-features.md

@@ -0,0 +1,78 @@
+# Zensical Features and Configuration Patterns
+
+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
+
+- `navigation.indexes`: lets sections have index pages for overview content.
+- `navigation.path`: adds breadcrumb-like context.
+- `navigation.sections`: groups top-level sections for large doc sets.
+- `navigation.instant`: enables instant internal navigation.
+- `navigation.instant.prefetch`: prefetches likely next pages.
+- `navigation.top`: shows a back-to-top affordance.
+- `navigation.tracking`: keeps URL anchors in sync with active section.
+
+!!! info "Source links"
+    - [Zensical navigation setup](https://zensical.org/docs/setup/navigation/)
+
+### Code-Heavy Documentation
+
+- `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.
+
+!!! info "Source links"
+    - [Zensical code blocks](https://zensical.org/docs/authoring/code-blocks/)
+    - [mkdocstrings](https://mkdocstrings.github.io/)
+
+### Cross-Page UX Consistency
+
+- `content.tabs.link`: keeps same-named tabs synchronized.
+- `content.tooltips`: improves tooltip behavior for links.
+- `content.footnote.tooltips`: inline footnote previews.
+
+!!! info "Source links"
+    - [Zensical content tabs](https://zensical.org/docs/authoring/content-tabs/)
+    - [Zensical tooltips](https://zensical.org/docs/authoring/tooltips/)
+    - [Zensical footnotes](https://zensical.org/docs/authoring/footnotes/)
+
+### Search and Content Actions
+
+- `search.highlight`: highlights matches after search navigation.
+- `content.action.edit` and `content.action.view` (if repository integration is configured).
+
+!!! info "Source links"
+    - [Zensical search setup](https://zensical.org/docs/setup/search/)
+    - [Zensical repository setup](https://zensical.org/docs/setup/repository/)
+
+## Styling and Extensibility
+
+Use site-level customization when docs need stronger visual affordances.
+
+- `extra_css`: add targeted style overrides.
+- `extra_javascript`: add behavior enhancements.
+- Theme override directory (`custom_dir`) for template-level changes.
+
+!!! info "Source links"
+    - [Zensical 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)
+
+## Practical Feature Selection Rules
+
+1. Start with discoverability and clarity features first.
+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.