docs: migrate documentation to Zensical

.agents/skills/zensical-site/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: zensical-site
+description: Use this skill whenever the user asks for anything related to https://zensical.org/ including researching pages, drafting or editing site copy, planning information architecture, writing Zensical-style markdown, extracting key points from docs, or preparing publish-ready content updates. Trigger even if the user does not explicitly mention "skill" or "zensical-style" but the work is clearly about zensical.org content.
+---
+
+# Zensical Site Assistant
+
+Use this skill to create, revise, and organize content for [zensical.org](https://zensical.org/).
+
+This skill is intentionally lightweight: use compact reference pages for output-critical rules, and
+link out to upstream docs for deep detail.
+
+## When to use this skill
+
+Use this skill if the user asks to:
+
+- Draft new pages/posts for zensical.org.
+- Rewrite existing copy for clarity, tone, or SEO.
+- Build content outlines, page briefs, or navigation structure.
+- Summarize or compare pages from zensical.org.
+- Convert rough notes into Zensical-style markdown.
+
+## Core workflow
+
+1. Clarify the content objective (page type, audience, and intent).
+2. Collect source material from zensical.org and any user-provided notes.
+3. Open [Authoring Reference Index](references/authoring-reference-index.md) and load only the
+   subject references needed for this task.
+4. Draft using the output template in this skill.
+5. Run a quality pass for tone, structure, links, front matter, and factual consistency.
+6. Return final markdown plus a short rationale and suggested next edits.
+
+## Output format
+
+Always provide:
+
+1. `Draft` (markdown ready to paste into the site)
+2. `Rationale` (2-5 bullets explaining important choices)
+3. `Open Questions` (only when missing info blocks quality)
+
+Use the page template in [Page Draft Template](templates/page-draft-template.md) unless the user
+requests another format.
+
+## Writing guidance
+
+- Prefer plain language and concrete examples.
+- Keep paragraphs short and scannable.
+- Use descriptive headings.
+- Avoid hype and vague claims.
+- Include links with meaningful anchor text.
+
+## Reference routing
+
+Start with:
+
+- [Authoring Reference Index](references/authoring-reference-index.md)
+
+Then load only what is needed:
+
+- [Markdown and Links](references/core/markdown-and-links.md) for links, heading structure, and
+  title behavior.
+- [Front Matter](references/core/front-matter.md) for page metadata.
+- [Callouts and Interactive Elements](references/subjects/callouts-and-interactive-elements.md) for
+  admonitions, buttons, tabs, and tooltips.
+- [Code and Technical Content](references/subjects/code-and-technical-content.md) for code blocks,
+  diagrams, and math.
+- [Layout and Media](references/subjects/layout-and-media.md) for grids, images, and icons/emojis.
+- [Data and Visualization](references/subjects/data-and-visualization.md) for tables and structured
+  visual content patterns.
+- [Inline Formatting and Microcontent](references/subjects/inline-formatting-and-microcontent.md)
+  for lists, inline formatting, and footnotes.
+
+If output depends on setup/runtime behavior, feature flags, or config snippets, load:
+
+- [Configuration Reference](references/dependencies/configuration-reference.md)
+- [Extension Prerequisites](references/dependencies/extension-prereqs.md)
+- [Navigation and Runtime Caveats](references/dependencies/navigation-runtime-caveats.md)
+- [Customization Boundaries](references/dependencies/customization-boundaries.md)
+
+Use [Shared Patterns](references/shared-patterns.md) for common rules and shared conventions.
+
+## Sources and verification
+
+- If browsing is available, reference exact pages used.
+- Flag uncertainty instead of guessing.
+- Do not invent product features, policies, or URLs.
+- If deeper implementation detail is needed, cite the relevant upstream Zensical doc rather than
+  expanding these references inline.

.agents/skills/zensical-site/references/authoring-reference-index.md

@@ -0,0 +1,36 @@
+# Authoring Reference Index
+
+Use this page to decide which reference file to load for a task.
+
+## How to use this index
+
+1. Identify the user task type.
+2. Load the matching core or subject reference.
+3. Load dependency references whenever output depends on setup, feature flags, runtime behavior, or
+   TOML snippets.
+4. If the user asks for advanced behavior, link out to upstream docs.
+
+## Task routing
+
+| User need                                             | Open this reference first                                                            | Also check                                                                                                                                                                                                     |
+|-------------------------------------------------------|--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Write or rewrite a standard docs page                 | [Markdown and Links](core/markdown-and-links.md)                                     | [Shared Patterns](shared-patterns.md), [Front Matter](core/front-matter.md)                                                                                                                                    |
+| Set page metadata                                     | [Front Matter](core/front-matter.md)                                                 | [Configuration Reference](dependencies/configuration-reference.md), [Navigation and Runtime Caveats](dependencies/navigation-runtime-caveats.md)                                                               |
+| Explain or draft `zensical.toml` configuration        | [Configuration Reference](dependencies/configuration-reference.md)                   | [Navigation and Runtime Caveats](dependencies/navigation-runtime-caveats.md), [Customization Boundaries](dependencies/customization-boundaries.md)                                                             |
+| Use admonitions, tabs, buttons, or tooltips           | [Callouts and Interactive Elements](subjects/callouts-and-interactive-elements.md)   | [Extension Prerequisites](dependencies/extension-prereqs.md), [Configuration Reference](dependencies/configuration-reference.md)                                                                               |
+| Add code snippets, diagrams, or equations             | [Code and Technical Content](subjects/code-and-technical-content.md)                 | [Extension Prerequisites](dependencies/extension-prereqs.md), [Configuration Reference](dependencies/configuration-reference.md), [Navigation and Runtime Caveats](dependencies/navigation-runtime-caveats.md) |
+| Build media-rich layouts                              | [Layout and Media](subjects/layout-and-media.md)                                     | [Customization Boundaries](dependencies/customization-boundaries.md)                                                                                                                                           |
+| Create tables and structured data sections            | [Data and Visualization](subjects/data-and-visualization.md)                         | [Extension Prerequisites](dependencies/extension-prereqs.md), [Configuration Reference](dependencies/configuration-reference.md)                                                                               |
+| Improve text-level formatting and list structure      | [Inline Formatting and Microcontent](subjects/inline-formatting-and-microcontent.md) | [Shared Patterns](shared-patterns.md)                                                                                                                                                                          |
+| Figure out whether custom CSS/JS/templates are needed | [Customization Boundaries](dependencies/customization-boundaries.md)                 | [Docs Reference Outline](docs-reference-outline.md)                                                                                                                                                            |
+
+## When to escalate to upstream docs
+
+Escalate (link out) when the task asks for:
+
+- complex extension options not covered in these references
+- deep theme customization or override internals
+- unusual runtime behavior across multiple plugins
+- edge-case compatibility behavior that affects production output
+
+Use upstream links from [Docs Reference Outline](docs-reference-outline.md).

.agents/skills/zensical-site/references/content-types.md

@@ -0,0 +1,27 @@
+# Content Types (Scaffold)
+
+Define conventions by content type so outputs stay consistent.
+
+## Homepage sections
+
+- Goal: TODO
+- Typical structure: TODO
+- CTA style: TODO
+
+## Documentation pages
+
+- Goal: TODO
+- Typical structure: TODO
+- Link behavior: TODO
+
+## Blog or updates
+
+- Goal: TODO
+- Typical structure: TODO
+- Tone notes: TODO
+
+## Case studies (if applicable)
+
+- Goal: TODO
+- Typical structure: TODO
+- Evidence style: TODO

.agents/skills/zensical-site/references/core/front-matter.md

@@ -0,0 +1,62 @@
+# Core: Front Matter
+
+Use this reference for page metadata and title/visibility controls.
+
+## Use this when
+
+- creating pages that need metadata
+- setting page title behavior explicitly
+- controlling discoverability or layout behavior per page
+
+## Minimum working pattern
+
+```markdown
+---
+title: Example Page
+description: One-sentence summary for readers.
+---
+
+# Example Page
+
+Page content starts here.
+```
+
+## Required config / prerequisites
+
+- Front matter support is expected in docs authoring flow.
+- Some keys influence behavior only when related setup features are enabled (search, navigation,
+  templates).
+- Use [Configuration Reference](../dependencies/configuration-reference.md) when status labels,
+  template overrides, or search behavior need matching `zensical.toml` setup.
+
+## What to capture in output
+
+- page identity: title/description
+- optional discoverability controls
+- optional layout controls when explicitly requested
+- metadata consistency with page body headings
+
+## Working rules
+
+- Keep front matter minimal; include only fields needed for the task.
+- Align metadata with page purpose and heading text.
+- If uncertain about advanced keys, call it out and provide a safe default.
+
+## Common mistakes to avoid
+
+- stuffing many optional keys without user need
+- title mismatch between front matter and body heading
+- using fields that depend on unknown site configuration without a caveat
+
+## Interactions / caveats
+
+- title precedence is affected by navigation and markdown
+  heading ([Markdown and Links](markdown-and-links.md)).
+- search/layout behavior can depend on setup
+  configuration ([Navigation and Runtime Caveats](../dependencies/navigation-runtime-caveats.md)).
+
+## Deeper docs
+
+- [Front matter](https://zensical.org/docs/authoring/frontmatter/)
+- [Search](https://zensical.org/docs/setup/search/)
+- [Navigation](https://zensical.org/docs/setup/navigation/)

.agents/skills/zensical-site/references/core/markdown-and-links.md

@@ -0,0 +1,60 @@
+# Core: Markdown and Links
+
+Use this reference for baseline page authoring, linking, and title behavior.
+
+## Use this when
+
+- drafting or rewriting standard docs pages
+- creating or updating internal links
+- deciding how titles should be derived
+
+## Minimum working pattern
+
+```markdown
+# Page Title
+
+Intro paragraph with context.
+
+## Section Heading
+
+Use relative links like [Front matter](../frontmatter/).
+```
+
+## Required config / prerequisites
+
+- No special extension needed for basic markdown.
+- Link output behavior depends on URL mode (`use_directory_urls`).
+
+## Key rules
+
+- Write links to docs pages using relative paths.
+- Do not hardcode output `.html` links for internal docs pages.
+- Keep one `#` heading per page body when title is content-driven.
+- If navigation/front matter sets title, ensure content heading stays consistent.
+
+## Page title precedence
+
+In practice, title resolution follows this order:
+
+1. navigation-defined title
+2. front matter title
+3. first-level markdown heading
+4. filename fallback
+
+## Common mistakes to avoid
+
+- linking to built HTML instead of docs-relative page paths
+- mixing absolute and relative links inconsistently
+- adding multiple top-level headings in one page
+- assuming content `#` always controls title when nav/front matter overrides it
+
+## Interactions / caveats
+
+- front matter can override visible title behavior ([Front Matter](front-matter.md)).
+- URL mode impacts generated
+  paths ([Navigation and Runtime Caveats](../dependencies/navigation-runtime-caveats.md)).
+
+## Deeper docs
+
+- [Markdown](https://zensical.org/docs/authoring/markdown/)
+- [Basics: use_directory_urls](https://zensical.org/docs/setup/basics/#use_directory_urls)