From a4db33531e54f704669f0e2ac6b5691b9f638e16 Mon Sep 17 00:00:00 2001
From: John Lancaster <32917998+jsl12@users.noreply.github.com>
Date: Thu, 18 Jun 2026 22:33:19 -0500
Subject: [PATCH] zensical-docs skills started

---
 docs/skills/zensical-docs/SKILL.md            | 153 ++++++++++++++++++
 .../references/discoverability-and-ia.md      |  74 +++++++++
 .../references/documentation-quality.md       |  54 +++++++
 docs/skills/zensical-docs/references/index.md |  38 +++++
 .../references/zensical-features.md           |  68 ++++++++
 5 files changed, 387 insertions(+)
 create mode 100644 docs/skills/zensical-docs/SKILL.md
 create mode 100644 docs/skills/zensical-docs/references/discoverability-and-ia.md
 create mode 100644 docs/skills/zensical-docs/references/documentation-quality.md
 create mode 100644 docs/skills/zensical-docs/references/index.md
 create mode 100644 docs/skills/zensical-docs/references/zensical-features.md

diff --git a/docs/skills/zensical-docs/SKILL.md b/docs/skills/zensical-docs/SKILL.md
new file mode 100644
index 0000000..815bdeb
--- /dev/null
+++ b/docs/skills/zensical-docs/SKILL.md
@@ -0,0 +1,153 @@
+---
+name: zensical-docs
+description: 'Plan, write, and improve high-quality documentation with Zensical. Use for information architecture, progressive discoverability, writing standards, navigation/search tuning, and feature-driven docs site configuration.'
+argument-hint: 'What are you documenting, who is the audience, and what Zensical features are in scope?'
+---
+
+# Zensical Documentation Authoring
+
+Create documentation that is easy to discover, easy to scan, and easy to trust, then configure Zensical so the site reinforces those outcomes.
+
+## When to Use
+
+- You are creating or restructuring docs in a Zensical project.
+- You need a repeatable workflow for docs quality and discoverability.
+- You want guidance that combines writing best practices with Zensical feature choices.
+- You need a checklist-driven review before publishing.
+
+## Progressive Loading References
+
+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)
+- 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)
+
+## Inputs To Collect
+
+Collect these before writing. If missing, make explicit assumptions.
+
+1. Audience: beginner, intermediate, advanced, or mixed.
+2. User goals: top tasks users come to complete.
+3. Product scope: features, versions, and deployment context.
+4. Content constraints: release deadlines, localization, legal/compliance needs.
+5. Navigation constraints: explicit `nav` vs implicit structure.
+6. Site-level expectations: search quality, code example depth, diagrams, API docs.
+
+## Procedure
+
+### Step 0: Audit Current Documentation
+
+Build a quick baseline of what exists now.
+
+1. List docs sections and current nav structure.
+2. Identify orphan pages (not in nav, weak internal linking, or no inbound links).
+3. Identify stale sections (version drift, missing prerequisites, broken commands).
+4. Capture recurring support questions and map each to a missing or weak doc page.
+
+Completion check: you can name the top 5 current documentation gaps.
+
+### Step 1: Define Outcomes and Page Taxonomy
+
+Organize content by user intent, not by internal team boundaries.
+
+1. Split content into at least four buckets:
+   - Learn (concepts and mental models)
+   - Do (task/how-to guides)
+   - Reference (API, config, CLI, schemas)
+   - Troubleshoot (symptoms, diagnostics, fixes)
+2. For each bucket, define success criteria and expected time-to-answer.
+3. Add clear page entry criteria (what belongs here, what does not).
+
+Completion check: every planned page maps to one primary user intent.
+
+### Step 2: Design Progressive Discoverability
+
+Make docs progressively discoverable from overview to detail.
+
+1. Start each section with an index/overview page that answers:
+   - who this section is for
+   - what problems it solves
+   - where to go next
+2. Keep page openings front-loaded:
+   - first paragraph states purpose and outcome
+   - first heading after intro is usually prerequisites or quickstart path
+3. Add consistent wayfinding on every page:
+   - links to prerequisite concepts
+   - links to next steps
+   - links to relevant reference sections
+4. Prefer short sections, descriptive headings, and stable anchor names.
+
+Completion check: users can navigate from high-level overview to exact procedure in 3 clicks or fewer.
+
+### Step 3: Author High-Trust Content
+
+Use writing patterns that reduce ambiguity and failure.
+
+1. Use imperative, task-oriented titles (for example: "Configure SSO with OIDC").
+2. State assumptions and prerequisites before commands.
+3. Provide copy-paste-safe examples and expected outputs.
+4. Include rollback or recovery steps for risky operations.
+5. Separate normative guidance (must/should) from optional patterns.
+6. Call out version-specific behavior explicitly.
+
+Completion check: each task page includes prerequisites, steps, expected result, and failure recovery.
+
+### Step 4: Apply Zensical Features Intentionally
+
+Load [./references/zensical-features.md](./references/zensical-features.md) and choose features based on content needs.
+
+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 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`.
+
+Completion check: each enabled feature has a documented rationale tied to a user outcome.
+
+### Step 5: Standardize Navigation and Search Quality
+
+1. Use explicit nav for critical docs journeys and release-stable ordering.
+2. Keep page titles and H1 aligned with search intent language users actually type.
+3. Avoid duplicate page titles across sections.
+4. Use concise first paragraphs because search snippets often rely on early content.
+5. Add cross-links between concept, task, and reference pages.
+
+Completion check: top support queries return a correct page within first search results.
+
+### Step 6: Publish and Validate
+
+1. Build the site: `uv run zensical build`
+2. Validate links, code blocks, and navigation paths.
+3. Review on desktop and mobile for scanability and heading rhythm.
+4. Check that key journeys (new user setup, common task, troubleshooting flow) are uninterrupted.
+
+Completion check: no broken links, no dead-end pages, and all critical journeys are complete.
+
+## Completion Checks
+
+- Page taxonomy is intent-based: Learn, Do, Reference, Troubleshoot.
+- 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.
+- Navigation and search behavior are verified with real user tasks.
+- Site builds cleanly with `uv run zensical build`.
+
+## Output Contract
+
+Return:
+
+1. Proposed docs architecture and navigation map.
+2. Zensical feature configuration recommendations with rationale.
+3. A prioritized writing backlog (must-have, should-have, nice-to-have).
+4. A quality-gate checklist for pre-publish review.
+
+## Guardrails
+
+- Do not produce architecture-only docs without concrete task pages.
+- Do not bury prerequisites or version constraints below the fold.
+- Do not rely only on search; preserve strong navigational paths.
+- Do not enable features without documenting the expected user benefit.
diff --git a/docs/skills/zensical-docs/references/discoverability-and-ia.md b/docs/skills/zensical-docs/references/discoverability-and-ia.md
new file mode 100644
index 0000000..4a01ca0
--- /dev/null
+++ b/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)
+
+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.
+
+Relevant Zensical configuration docs:
+- Navigation: https://zensical.org/docs/setup/navigation/
+- Search: https://zensical.org/docs/setup/search/
+- Header: https://zensical.org/docs/setup/header/
+- Footer: 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
diff --git a/docs/skills/zensical-docs/references/documentation-quality.md b/docs/skills/zensical-docs/references/documentation-quality.md
new file mode 100644
index 0000000..2689751
--- /dev/null
+++ b/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.
+
+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.
+
+Source links:
+- 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.
diff --git a/docs/skills/zensical-docs/references/index.md b/docs/skills/zensical-docs/references/index.md
new file mode 100644
index 0000000..df70035
--- /dev/null
+++ b/docs/skills/zensical-docs/references/index.md
@@ -0,0 +1,38 @@
+# Zensical Docs Skill References
+
+Use this index to load only the source references needed for the current task.
+
+## Zensical Official Docs
+
+- 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
+
+- 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
+
+- 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/
diff --git a/docs/skills/zensical-docs/references/zensical-features.md b/docs/skills/zensical-docs/references/zensical-features.md
new file mode 100644
index 0000000..3298507
--- /dev/null
+++ b/docs/skills/zensical-docs/references/zensical-features.md
@@ -0,0 +1,68 @@
+# Zensical Features and Configuration Patterns
+
+Use this reference when deciding which Zensical features to enable and why.
+
+## 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.
+
+Source links:
+- 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.
+
+Source links:
+- https://zensical.org/docs/authoring/code-blocks/
+
+### 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.
+
+Source links:
+- https://zensical.org/docs/authoring/content-tabs/
+- https://zensical.org/docs/authoring/tooltips/
+- 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).
+
+Source links:
+- https://zensical.org/docs/setup/search/
+- 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.
+
+Source links:
+- https://zensical.org/docs/customization/
+- https://zensical.org/docs/customization/#additional-css
+- https://zensical.org/docs/customization/#additional-javascript
+- https://zensical.org/docs/customization/#extending-the-theme
+
+## Practical Feature Selection Rules
+
+1. Start with discoverability and clarity features first.
+2. Add convenience features (copy/select/tooltips) when content type supports them.
+3. Avoid enabling many features at once without measurement.
+4. Track user success metrics (search success, time-to-answer, support deflection) after each change.