@docsector/docsector-reader 4.2.0 → 4.3.0

package/README.md

@@ -30,6 +30,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🤖 **AI-Friendly robots.txt** — Scaffold includes a `robots.txt` explicitly allowing 23 AI crawlers (GPTBot, ClaudeBot, PerplexityBot, GrokBot, etc.)
 - 🧭 **Content Signals** — Optional `Content-Signal` directive for declaring AI usage policy (`ai-train`, `search`, `ai-input`) in `robots.txt`
 - 🧩 **Agent Skills Discovery Index** — Optional `/.well-known/agent-skills/index.json` with RFC v0.2.0 schema and SHA-256 digests
+- ✍️ **Docsector Authoring Skill** — Publishable `SKILL.md` that teaches agents Docsector blocks, page patterns, MCP lookup, and WebMCP tools
 - 🪪 **MCP Server Card** — Optional `/.well-known/mcp/server-card.json` for MCP server discovery before connection
 - 🌐 **WebMCP Browser Tools** — Optional registration of in-page tools via `navigator.modelContext` for browser agents
 - 🔗 **Homepage Link Headers** — Auto-generated `Link` response headers for agent discovery (`api-catalog`, `service-doc`, `service-desc`, `describedby`) per RFC 8288 / RFC 9727
@@ -77,6 +78,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🗂️ **Cards Custom Element** — Use `<d-block-cards>` and `<d-block-card>` in Markdown to render linked content cards with optional cover images
 - 🧾 **API JSON Reference Block** — Use `<d-block-api src="..." />` in Markdown to render Quasar-compatible API reference UIs from public JSON assets without inventing a new schema
 - 🗂️ **API Catalog Well-Known** — Auto-generates `/.well-known/api-catalog` as Linkset JSON for machine-readable API discovery
+- 🧠 **Docsector Authoring Skill Docs** — Documents the built-in `SKILL.md` and reference files so agents can learn Docsector blocks, page patterns, MCP lookup, and WebMCP tools from a public manual page
 - 🗃️ **Multi-Version History** — Archive older major versions under `src/pages/.old/<version>/` and expose them at prefixed routes (e.g. `/v0.x/guide/...`) while keeping the current docs at unprefixed routes
 - 🏷️ **Version Selector Badges** — Every version in the sidebar selector displays a color-coded badge: green for released, orange for draft, red for deprecated; fully customizable via `badge: { label, color, textColor }`
 - 📂 **Tabbed Code Blocks** — Group consecutive fenced code blocks into tabs using the `group` and `tab` attributes in the fence info line
@@ -527,6 +529,12 @@ The generated payload follows Agent Skills Discovery RFC v0.2.0 and includes:
 - `$schema`
 - `skills[]` entries with `name`, `type`, `description`, `url`, `digest`
 
+This repository publishes the built-in Docsector authoring skill at:
+
+- `/.well-known/agent-skills/docsector-documentation-authoring/SKILL.md`
+
+The skill teaches agents Docsector Markdown authoring, all documented blocks, page/source conventions, MCP lookup, and WebMCP browser tools.
+
 When `digest` is omitted in config, Docsector computes it automatically from the referenced local artifact and writes it as:
 
 - `sha256:{hex}`
@@ -543,10 +551,10 @@ export default {
     schema: 'https://schemas.agentskills.io/discovery/0.2.0/schema.json',
     skills: [
       {
-        name: 'my-docs-mcp',
+        name: 'docsector-documentation-authoring',
         type: 'skill-md',
-        description: 'Search and fetch docs pages via MCP.',
-        url: '/.well-known/agent-skills/my-docs-mcp/SKILL.md'
+        description: 'Author Docsector documentation with Markdown, custom blocks, MCP, and WebMCP.',
+        url: '/.well-known/agent-skills/docsector-documentation-authoring/SKILL.md'
       }
     ]
   }
@@ -757,10 +765,10 @@ export default {
     schema: 'https://schemas.agentskills.io/discovery/0.2.0/schema.json',
     skills: [
       {
-        name: 'my-docs-mcp',
+        name: 'docsector-documentation-authoring',
         type: 'skill-md',
-        description: 'Search and fetch docs pages via MCP.',
-        url: '/.well-known/agent-skills/my-docs-mcp/SKILL.md'
+        description: 'Author Docsector documentation with Markdown, custom blocks, MCP, and WebMCP.',
+        url: '/.well-known/agent-skills/docsector-documentation-authoring/SKILL.md'
       }
     ]
   },

package/bin/docsector.js

@@ -23,7 +23,7 @@ const packageRoot = resolve(__dirname, '..')
 const args = process.argv.slice(2)
 const command = args[0]
 
-const VERSION = '4.2.0'
+const VERSION = '4.3.0'
 
 const HELP = `
   Docsector Reader v${VERSION}

package/docsector.config.js

@@ -55,6 +55,21 @@ export default {
     toolSuffix: 'docsector'
   },
 
+  // @ Agent Skills
+  agentSkills: {
+    enabled: true,
+    path: '/.well-known/agent-skills/index.json',
+    schema: 'https://schemas.agentskills.io/discovery/0.2.0/schema.json',
+    skills: [
+      {
+        name: 'docsector-documentation-authoring',
+        type: 'skill-md',
+        description: 'Author Docsector documentation with Markdown, custom blocks, MCP, and WebMCP.',
+        url: '/.well-known/agent-skills/docsector-documentation-authoring/SKILL.md'
+      }
+    ]
+  },
+
   // @ Home page source
   homePage: {
     source: 'remote-readme',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "A documentation rendering engine built with Vue 3, Quasar v2 and Vite. Transform Markdown into beautiful, navigable documentation sites.",
   "productName": "Docsector Reader",
   "author": "Rodrigo de Araujo Vieira",

package/public/.well-known/agent-skills/docsector-documentation-authoring/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: docsector-documentation-authoring
+description: "Author Docsector documentation with Markdown, d-block custom elements, page structures, blocks, MCP, WebMCP, and agent-readable docs. Use when writing or editing Docsector pages, choosing content blocks, creating examples, documenting APIs, or helping an AI understand Docsector authoring syntax."
+argument-hint: "Describe the Docsector page, block, or documentation task"
+user-invocable: true
+---
+
+# Docsector Documentation Authoring
+
+## When to Use
+
+Use this skill when creating, reviewing, or editing documentation for a site built with Docsector Reader.
+
+Use it for:
+
+- Choosing the right Docsector block for a content need.
+- Writing Markdown pages with Docsector custom elements.
+- Creating overview, showcase, guide, API reference, changelog, or landing content.
+- Finding live Docsector docs through MCP, WebMCP, Markdown negotiation, or `llms.txt`.
+- Teaching an AI assistant how Docsector pages, blocks, and examples are authored.
+
+## Expected Outcome
+
+- The page uses standard Markdown where Markdown is enough.
+- Rich interactions use the appropriate Docsector custom element.
+- Links, assets, examples, and API JSON use Docsector conventions.
+- The result is easy to scan, accessible, and friendly to both humans and agents.
+- When MCP or WebMCP is available, current Docsector documentation is queried instead of relying only on memory.
+
+## Authoring Workflow
+
+1. Identify the page purpose: concept, tutorial, API reference, release note, navigation hub, example showcase, or troubleshooting guide.
+2. Use headings to shape the reading path. In normal page content, start with `##` because the page title is supplied by metadata.
+3. Pick the simplest block that communicates the content. Prefer Markdown first, then Docsector custom elements when the layout or interaction needs it.
+4. Keep custom element attributes short and explicit. Use `to` for internal navigation and `href` for external URLs.
+5. Put reusable assets in stable public paths such as `/images/...`, `/files/...`, `/api/...`, or `/quasar-api/...`.
+6. For live examples, place Vue SFCs under `src/examples/**/*.vue` and reference them with `<d-block-code-example>`.
+7. For API references, serve JSON from a same-origin public asset and reference it with `<d-block-api>`.
+8. Validate links, anchors, code fences, and custom element closing tags before finishing.
+
+## Quick Block Selection
+
+| Need                            | Use                      |
+| ------------------------------- | ------------------------ |
+| Narrative text                  | Paragraphs               |
+| Page sections and anchors       | Headings                 |
+| Features or requirements        | Unordered lists          |
+| Sequential instructions         | Ordered lists or Stepper |
+| Progress states                 | Task lists               |
+| Notes, tips, warnings           | Hints                    |
+| Quoted text                     | Quotes                   |
+| Commands or source snippets     | Code blocks              |
+| Live Vue demos                  | Code examples            |
+| Flowcharts or diagrams          | Mermaid diagrams         |
+| Screenshots or diagrams         | Images                   |
+| Downloads                       | Files                    |
+| Videos, audio, or pens          | Embedded URLs            |
+| Equations                       | Math and TeX             |
+| Optional detail                 | Expandable               |
+| Guided sequence with navigation | Stepper                  |
+| Changelog or release log        | Timeline                 |
+| Comparisons or matrices         | Tables                   |
+| Custom structure                | Raw HTML                 |
+| Small navigation sets           | Quick Links              |
+| Visual navigation grids         | Cards                    |
+| Structured API docs             | API Reference            |
+
+For the complete syntax and guidance, read [the block catalog](./references/block-catalog.md).
+
+## MCP and WebMCP
+
+When a Docsector site exposes MCP, prefer live lookup for exact syntax and current examples.
+
+Typical MCP tools are named with the configured suffix:
+
+- `search_{suffix}` searches documentation pages.
+- `get_page_{suffix}` returns raw Markdown for a documentation page.
+
+This repository uses the suffix `docsector`, so the local docs tools are expected to be `search_docsector` and `get_page_docsector` when the MCP server is connected.
+
+Use known paths such as:
+
+- `manual/content/blocks/cards/overview`
+- `manual/content/blocks/quick-links/overview`
+- `manual/content/blocks/api-reference/overview`
+- `manual/content/blocks/timeline/showcase`
+
+Browser agents may also see WebMCP tools such as `docs.search_docs`, `docs.get_page`, `docs.navigate_to`, and `docs.copy_current_page`.
+
+Read [MCP and WebMCP reference](./references/mcp-webmcp.md) for details and caveats.
+
+## Page and Asset Conventions
+
+Read [page structure reference](./references/page-structure.md) before changing page layout, localization, examples, or public assets.
+
+Key conventions:
+
+- Manual block docs live under `src/pages/manual/content/blocks/`.
+- Block pages usually have `overview` and `showcase` subpages.
+- Localized source files use suffixes such as `.en-US.md` and `.pt-BR.md`.
+- Downloadable files should use `/files/...` paths backed by `public/files/...`.
+- Images should use `/images/...` paths backed by `public/images/...`.
+- API JSON should use same-origin public paths such as `/api/...` or `/quasar-api/...`.
+
+## Authoring Patterns
+
+Read [authoring patterns](./references/authoring-patterns.md) for common page recipes such as tutorials, changelogs, navigation hubs, API reference pages, and example showcases.
+
+## Quality Checklist
+
+- The page has a clear first section and predictable heading hierarchy.
+- Every custom element has required attributes and matching closing tags unless it is intentionally self-closing.
+- Internal links use route paths and external links use absolute URLs.
+- Images, files, examples, and API JSON point to assets that exist or are intentionally external.
+- Hints are reserved for semantic callouts, not general decoration.
+- Tables are not overloaded with prose that would read better as sections or lists.
+- Nested custom blocks are used conservatively; avoid unsupported nested Expandable and Stepper patterns.
+- MCP or WebMCP was used for current docs when available.

package/public/.well-known/agent-skills/docsector-documentation-authoring/references/authoring-patterns.md

@@ -0,0 +1,98 @@
+# Docsector Authoring Patterns
+
+Use these patterns to choose a page shape before writing detailed content.
+
+## Tutorial or Setup Guide
+
+Use when readers must follow a sequence.
+
+Recommended blocks:
+
+- Headings for major phases.
+- Stepper for guided, interactive sequences.
+- Code blocks for commands and configuration.
+- Hints for warnings or best practices.
+- Files for downloadable checklists or templates.
+
+Start with a short outcome statement, then move into steps. Keep each step focused on one action and one result.
+
+## Concept or Overview Page
+
+Use when readers need understanding before action.
+
+Recommended blocks:
+
+- Paragraphs for explanation.
+- Headings for scannable sections.
+- Unordered lists for capabilities and constraints.
+- Images or Mermaid diagrams for mental models.
+- Quick Links or Cards for next steps.
+
+Avoid heavy custom blocks if a simple section and list are clearer.
+
+## Navigation Hub
+
+Use when a page primarily routes readers to other content.
+
+Recommended blocks:
+
+- Quick Links for compact next steps.
+- Cards for visual destinations.
+- Short paragraphs for framing.
+- Headings only when the hub has multiple groups.
+
+Use `to` for Docsector routes and `href` for external URLs.
+
+## Changelog or Release Notes
+
+Use when content is chronological.
+
+Recommended blocks:
+
+- Timeline for dated entries.
+- Timeline tags for release channels, categories, or status.
+- Hints for breaking changes or migration warnings.
+- Code blocks for commands that users must run.
+- Quick Links for related upgrade docs.
+
+Give timeline items stable `anchor` values for important releases and migration entries.
+
+## API Reference Page
+
+Use when structured API data is available.
+
+Recommended blocks:
+
+- API Reference for Quasar-compatible JSON.
+- Code blocks for quick usage examples.
+- Hints for compatibility or deprecation notes.
+- Tables only for small summaries not already covered by the API block.
+
+Keep JSON assets under same-origin public paths such as `/api/manual/...` or `/quasar-api/...`.
+
+## Example Showcase
+
+Use when readers need to inspect behavior and source.
+
+Recommended blocks:
+
+- Code Examples for live Vue SFC previews.
+- Code blocks for smaller standalone snippets.
+- Expandable for optional implementation notes.
+- Cards or Quick Links for related examples.
+
+Use `expanded="true"` when source inspection is the main value. Set `codepen="false"` when an example cannot be exported safely.
+
+## Troubleshooting Page
+
+Use when readers need to diagnose and resolve problems.
+
+Recommended blocks:
+
+- Headings for symptoms or error messages.
+- Hints for warnings and high-risk operations.
+- Ordered lists for resolution steps.
+- Code blocks for commands and logs.
+- Expandable for verbose logs or advanced diagnostics.
+
+Keep the shortest successful path visible and move rare details into Expandable blocks.

package/public/.well-known/agent-skills/docsector-documentation-authoring/references/block-catalog.md

@@ -0,0 +1,321 @@
+# Docsector Block Catalog
+
+This catalog summarizes the Docsector authoring blocks that an agent should know before writing documentation. Each block has live manual pages at `manual/content/blocks/{slug}/overview` and usually `manual/content/blocks/{slug}/showcase`.
+
+## Custom Element Blocks
+
+| Block         | Syntax                                              | Use For                                                  | Manual Path                                    |
+| ------------- | --------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------- |
+| Quick Links   | `<d-block-quick-links>` with `<d-block-quick-link>` | Small sets of next-step links                            | `manual/content/blocks/quick-links/overview`   |
+| Cards         | `<d-block-cards>` with `<d-block-card>`             | Visual navigation grids and landing sections             | `manual/content/blocks/cards/overview`         |
+| Timeline      | `<d-block-timeline>` with `<d-block-timeline-item>` | Changelogs, release notes, rollout logs                  | `manual/content/blocks/timeline/overview`      |
+| Stepper       | `<d-block-stepper>` with `<d-block-step>`           | Guided multi-step flows with navigation                  | `manual/content/blocks/stepper/overview`       |
+| Expandable    | `<d-block-expandable>`                              | Optional details, appendices, longer examples            | `manual/content/blocks/expandable/overview`    |
+| Files         | `<d-block-file>`                                    | Download cards for attachments                           | `manual/content/blocks/files/overview`         |
+| Embedded URLs | `<d-block-embedded-url>`                            | YouTube, Vimeo, Spotify, CodePen, or link-card fallbacks | `manual/content/blocks/embedded-urls/overview` |
+| Code Examples | `<d-block-code-example>`                            | Live Vue SFC previews with source inspection             | `manual/content/blocks/code-examples/overview` |
+| API Reference | `<d-block-api>`                                     | Quasar-compatible JSON API reference UIs                 | `manual/content/blocks/api-reference/overview` |
+
+### Quick Links
+
+Use Quick Links when a page needs a compact group of destinations without a long prose list.
+
+```html
+<d-block-quick-links title="Get started">
+  <d-block-quick-link
+    title="Install"
+    description="Set up the project"
+    to="/guide/getting-started"
+  />
+  <d-block-quick-link
+    title="GitHub"
+    description="Open the repository"
+    href="https://github.com/docsector/docsector-reader"
+  />
+</d-block-quick-links>
+```
+
+Use `to` for internal navigation and `href` for external URLs. Keep descriptions short.
+
+### Cards
+
+Use Cards for landing sections, curated resource grids, and visual navigation.
+
+```html
+<d-block-cards title="Explore more">
+  <d-block-card
+    title="Install"
+    description="Set up the project"
+    to="/guide/getting-started"
+    image="/images/cards/getting-started-cover.svg"
+  />
+  <d-block-card
+    title="GitHub"
+    description="Open the repository"
+    href="https://github.com/docsector/docsector-reader"
+    icon="launch"
+  />
+</d-block-cards>
+```
+
+Prefer `image` for landing-page tiles and `icon` for lighter cards without covers.
+
+### Timeline
+
+Use Timeline for chronological entries such as changelogs, release notes, migrations, and rollout journals.
+
+```html
+<d-block-timeline>
+  <d-block-timeline-item date="2025-12-25" anchor="brand-new-update">
+    <d-block-timeline-tag color="warning" icon="rocket_launch"
+      >beta</d-block-timeline-tag
+    >
+    <d-block-timeline-tag color="secondary" text-color="white"
+      >docs</d-block-timeline-tag
+    >
+
+    ## A brand new update Use this block for release notes, product
+    announcements, migration notices, or operational updates.
+  </d-block-timeline-item>
+</d-block-timeline>
+```
+
+Every item needs `date`. Tags are optional and support text content or `label`, plus `color`, `text-color`, and `icon`. `anchor` is optional; Docsector can generate one from the date and first visible text. Headings inside timeline items are flattened so the page ToC stays stable.
+
+### Stepper
+
+Use Stepper when the reader should move through a guided sequence.
+
+```html
+<d-block-stepper>
+  <d-block-step title="Install dependencies">
+    Run `npm install` in the project root.
+  </d-block-step>
+
+  <d-block-step
+    title="Ship the release"
+    icon="rocket_launch"
+    active-icon="rocket_launch"
+    done-icon="task_alt"
+  >
+    Use icon attributes when a numbered prefix is not expressive enough.
+  </d-block-step>
+</d-block-stepper>
+```
+
+Every step needs `title`. Step bodies support common Markdown such as paragraphs, lists, hints, code fences, images, tables, and math. Avoid nested Stepper blocks and other custom Docsector blocks inside steps in the current version.
+
+### Expandable
+
+Use Expandable for optional material that should not interrupt the main reading path.
+
+```html
+<d-block-expandable title="Release checklist" open="true">
+  - Review breaking changes - Update screenshots - Run smoke tests
+</d-block-expandable>
+```
+
+Use `open="true"` to start expanded. Keep page headings outside expandable bodies because inner headings are flattened. Avoid nesting one expandable inside another.
+
+### Files
+
+Use Files for attachments such as checklists, PDFs, sample bundles, and release assets.
+
+```html
+<d-block-file
+  src="/files/manual/release-checklist.txt"
+  title="Release checklist"
+  size="1 KB"
+>
+  Download the example attachment used in this manual.
+</d-block-file>
+```
+
+`src` is required. `title` and `size` are optional. When `title` is omitted, Docsector falls back to the file name from `src`. Store repo-tracked attachments under `public/files/` and reference them as `/files/...`.
+
+### Embedded URLs
+
+Use Embedded URLs for curated public embeds while keeping Docsector's consistent card and preview treatment.
+
+```html
+<d-block-embedded-url
+  url="https://www.youtube.com/watch?v=M7lc1UVf-VE"
+  title="YouTube player demo"
+>
+  Optional caption rendered as inline Markdown.
+</d-block-embedded-url>
+```
+
+`url` is required and `title` is optional. Supported providers are YouTube, Vimeo, Spotify, and CodePen. Unsupported or private URLs render as safe external-link cards.
+
+### Code Examples
+
+Use Code Examples to render project Vue SFCs as live previews with source inspection.
+
+```html
+<d-block-code-example
+  src="manual/code-examples/basic-counter"
+  title="Basic counter"
+/>
+```
+
+Place examples under `src/examples/**/*.vue`. The `src` value is normalized to kebab-case, so `manual/code-examples/basic-counter` resolves to `src/examples/manual/code-examples/BasicCounter.vue`. `file` is an alias for `src`.
+
+Common attributes:
+
+| Attribute    | Purpose                                        |
+| ------------ | ---------------------------------------------- |
+| `src`        | Example id under `src/examples/**/*.vue`       |
+| `file`       | Alias for `src`                                |
+| `title`      | Header title above the preview                 |
+| `expanded`   | Opens the source panel by default when `true`  |
+| `codepen`    | Shows the CodePen action unless set to `false` |
+| `scrollable` | Gives the preview a fixed scrollable height    |
+| `overflow`   | Allows horizontal and vertical overflow        |
+| `height`     | Sets a preview height such as `360` or `420px` |
+
+### API Reference
+
+Use API Reference blocks to render Quasar-compatible JSON API documentation.
+
+```html
+<d-block-api src="/quasar-api/QSeparator.json" />
+
+<d-block-api
+  src="/api/manual/http-client.json"
+  title="HTTP Client API"
+  page-link="true"
+/>
+```
+
+`src` is required and should point to same-origin JSON. `title` overrides the header. `page-link="true"` shows a Docs button when the JSON includes `meta.docsUrl`. Useful JSON sections include `props`, `methods`, `events`, `value`, `arg`, and `quasarConfOptions`; entries with `internal: true` are hidden.
+
+## Markdown and Native Blocks
+
+| Block            | Syntax                     | Use For                         | Manual Path                                       |
+| ---------------- | -------------------------- | ------------------------------- | ------------------------------------------------- |
+| Paragraphs       | Plain Markdown text        | Explanations and transitions    | `manual/content/blocks/paragraphs/overview`       |
+| Headings         | `##`, `###`, `####`        | Sections, anchors, page ToC     | `manual/content/blocks/headings/overview`         |
+| Unordered Lists  | `- item`                   | Feature sets and requirements   | `manual/content/blocks/unordered-lists/overview`  |
+| Ordered Lists    | `1. item`                  | Sequential procedures           | `manual/content/blocks/ordered-lists/overview`    |
+| Task Lists       | `- [ ] item`, `- [x] item` | Static checklists               | `manual/content/blocks/task-lists/overview`       |
+| Hints            | `> [!WARNING]`             | Semantic notes and warnings     | `manual/content/blocks/hints/overview`            |
+| Quotes           | `> text`                   | Neutral quoted text             | `manual/content/blocks/quotes/overview`           |
+| Code Blocks      | Fenced code                | Commands and snippets           | `manual/content/blocks/code-blocks/overview`      |
+| Mermaid Diagrams | Fenced `mermaid` code      | Flowcharts and diagrams         | `manual/content/blocks/mermaid-diagrams/overview` |
+| Images           | `![caption](/path.png)`    | Screenshots and illustrations   | `manual/content/blocks/images/overview`           |
+| Math and TeX     | `$...$`, `$$...$$`         | Inline and display equations    | `manual/content/blocks/math-and-tex/overview`     |
+| Tables           | Markdown tables            | Comparisons and matrices        | `manual/content/blocks/tables/overview`           |
+| Raw HTML         | HTML tags                  | Custom structure and attributes | `manual/content/blocks/raw-html/overview`         |
+
+### Paragraphs
+
+Use paragraphs for narrative copy. Separate paragraphs with a blank line. Inline emphasis, links, inline code, and math work inside normal paragraphs.
+
+### Headings
+
+Use headings to organize the page and feed the right-side table of contents. In page content, start with `##` because the page title is generated from page metadata. Keep heading levels in order and use headings for sections that readers may bookmark or deep-link.
+
+### Lists
+
+Use unordered lists when order does not matter. Use ordered lists when sequence matters. Use task lists when each item should show a done or not-done state. Published task-list checkboxes are static and cannot be toggled by readers.
+
+### Hints
+
+Use GitHub-style alert markers in blockquotes:
+
+```markdown
+> [!WARNING]
+> This operation may interrupt workers.
+```
+
+Supported markers are `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, and `CAUTION`. Unknown markers fall back to regular quotes.
+
+### Quotes
+
+Use regular blockquotes for cited text or neutral notes that should stand apart from the main flow without semantic alert styling.
+
+```markdown
+> This is a regular quote.
+```
+
+### Code Blocks
+
+Use fenced code blocks for commands and snippets. Docsector renders syntax highlighting, line numbers, copy support, grouped tabs, breadcrumbs, and file metadata.
+
+````markdown
+```bash :filename="install.sh";
+npm install
+npm run dev
+```
+````
+
+Useful metadata attributes are `filename`, `group`, `tab`, and `breadcrumb` using `:attr;` syntax.
+
+### Mermaid Diagrams
+
+Use a fenced `mermaid` block for diagrams.
+
+````markdown
+```mermaid
+flowchart TD
+  A[Start] --> B[Finish]
+```
+````
+
+Docsector lazy-loads Mermaid, renders responsive SVG, adapts to light and dark mode, and shows a safe error state for invalid Mermaid syntax.
+
+### Images
+
+Use standard Markdown images for screenshots, illustrations, diagrams, and product UI.
+
+```markdown
+![Dashboard overview](/images/example-dashboard.png)
+```
+
+Standalone Markdown images render as block figures with click-to-zoom. The label is used as both caption and alt text. Use raw `<figure>` and `<picture>` markup when alt text and visible caption need to differ.
+
+### Math and TeX
+
+Use single dollar delimiters for inline math and double dollar delimiters for display math.
+
+```markdown
+Use $E = mc^2$ inside a sentence.
+
+$$
+\int_0^1 x^2 dx
+$$
+```
+
+Math works in paragraphs, hints, and expandable blocks. Delimiters remain literal inside inline code and fenced code blocks.
+
+### Tables
+
+Use tables for comparisons, option matrices, compatibility notes, and scannable row-column content.
+
+```markdown
+| Feature | Status | Notes                    |
+| ------- | ------ | ------------------------ |
+| Search  | Done   | Available in the sidebar |
+```
+
+Keep column labels short. Split very dense tables into smaller sections.
+
+### Raw HTML
+
+Use raw HTML only when Markdown is not expressive enough or when authoring Docsector custom elements.
+
+```html
+<div data-kind="secondary-note">
+  This block uses raw HTML inside the page source.
+</div>
+```
+
+Prefer plain Markdown first. Keep raw markup readable because documentation content still needs maintenance.
+
+## Renderer and Parser References
+
+- `src/components/page-section-tokens.js` parses custom elements and Markdown tokens.
+- `src/components/DPageTokens.vue` dispatches tokens to block components.
+- `src/components/DBlockCards.vue`, `DBlockQuickLinks.vue`, `DBlockTimeline.vue`, `DBlockStepper.vue`, `DBlockExpandable.vue`, `DBlockFile.vue`, `DBlockEmbeddedUrl.vue`, `DBlockCodeExample.vue`, and `DBlockApi.vue` render custom element blocks.
+- `src/components/DBlockSourceCode.vue`, `DBlockMermaidDiagram.vue`, `DBlockBlockquote.vue`, and `DBlockImage.vue` render richer Markdown blocks.

package/public/.well-known/agent-skills/docsector-documentation-authoring/references/mcp-webmcp.md

@@ -0,0 +1,90 @@
+# MCP and WebMCP Reference
+
+Docsector can expose documentation to agents through MCP, WebMCP, Markdown negotiation, and `llms.txt`. Use these sources when an assistant needs current docs instead of only the static guidance in this skill.
+
+## MCP Server
+
+When configured, Docsector generates an MCP endpoint at:
+
+```text
+/mcp
+```
+
+The server exposes tools named with the configured suffix:
+
+| Tool                | Purpose                               |
+| ------------------- | ------------------------------------- |
+| `search_{suffix}`   | Search documentation pages by keyword |
+| `get_page_{suffix}` | Fetch raw Markdown for a page path    |
+
+This repository configures `toolSuffix: 'docsector'`, so connected MCP clients should see:
+
+```text
+search_docsector
+get_page_docsector
+```
+
+## MCP Page Paths
+
+`get_page_{suffix}` expects paths without a leading slash, trailing slash, or `.md` suffix. It can try an `/overview` fallback when the primary path is not found.
+
+Useful examples:
+
+```text
+manual/content/blocks/quick-links/overview
+manual/content/blocks/cards/overview
+manual/content/blocks/code-examples/overview
+manual/content/blocks/api-reference/overview
+manual/content/blocks/timeline/showcase
+guide/getting-started/overview
+```
+
+## Recommended Agent Flow
+
+1. Use `search_{suffix}` for discovery, such as `search_docsector` with `"timeline block"`.
+2. Use `get_page_{suffix}` with the best matching path.
+3. Read the returned Markdown examples before authoring or changing a custom element.
+4. Prefer the live manual page when it conflicts with this static skill.
+5. If MCP is not connected, use Markdown URLs, `llms.txt`, or the references bundled with this skill.
+
+## WebMCP Browser Tools
+
+When `navigator.modelContext` is available in a secure browser context, Docsector can register browser-side tools. Typical tool names are:
+
+| Tool                     | Purpose                                                           |
+| ------------------------ | ----------------------------------------------------------------- |
+| `docs.search_docs`       | Search docs through the MCP bridge                                |
+| `docs.get_page`          | Fetch page Markdown through the MCP bridge                        |
+| `docs.navigate_to`       | Navigate the single-page app to a route and optional hash         |
+| `docs.copy_current_page` | Return the current page path, Markdown URL, and optionally source |
+
+Use these tools when working inside a Docsector page with a browser agent. Use MCP tools directly when working from an editor or external assistant.
+
+## Markdown and LLM Discovery
+
+Docsector pages can expose raw Markdown in several ways:
+
+- Append `.md` to a page URL.
+- Send `Accept: text/markdown` to use Markdown negotiation.
+- Use `/llms.txt` for an index of pages when `siteUrl` is configured.
+- Use `/llms-full.txt` for concatenated full content when generated.
+
+These are useful fallbacks when MCP is unavailable.
+
+## Discovery Artifacts
+
+Docsector can also publish machine-readable discovery files:
+
+| Artifact                               | Purpose                      |
+| -------------------------------------- | ---------------------------- |
+| `/.well-known/mcp/server-card.json`    | MCP server discovery         |
+| `/.well-known/agent-skills/index.json` | Agent Skills Discovery index |
+| `/.well-known/api-catalog`             | API catalog Linkset JSON     |
+
+## Caveats
+
+- MCP search indexes pages, not individual component schemas.
+- Public API JSON files under `/api/...` and `/quasar-api/...` are static assets and may not be directly searchable through MCP page search.
+- WebMCP requires browser support for `navigator.modelContext` and a secure context, except where localhost is allowed by the browser.
+- Generated MCP indexes are build artifacts, so a production build is required after source changes.
+- If multiple Docsector sites are connected to the same assistant, each site should use a unique MCP tool suffix.

package/public/.well-known/agent-skills/docsector-documentation-authoring/references/page-structure.md

@@ -0,0 +1,101 @@
+# Docsector Page Structure
+
+Use this reference when adding or editing Docsector content files, assets, examples, and API reference data.
+
+## Page Sources
+
+Docsector pages are registered in index files such as `src/pages/manual.index.js` and backed by localized Markdown files under `src/pages/`.
+
+Manual content blocks follow this pattern:
+
+```text
+src/pages/manual/content/blocks/{block}.overview.en-US.md
+src/pages/manual/content/blocks/{block}.showcase.en-US.md
+src/pages/manual/content/blocks/{block}.overview.pt-BR.md
+src/pages/manual/content/blocks/{block}.showcase.pt-BR.md
+```
+
+The route path maps to MCP/page paths such as:
+
+```text
+manual/content/blocks/cards/overview
+manual/content/blocks/cards/showcase
+```
+
+## Overview and Showcase
+
+Use `overview` for conceptual explanation, syntax, attributes, and authoring notes. Use `showcase` for varied examples that demonstrate the block in realistic content.
+
+Most block docs should include both subpages. Structure docs such as page, subpage, or books may use different subpage rules depending on their registry configuration.
+
+## Localization
+
+Localized Markdown files use locale suffixes such as `.en-US.md` and `.pt-BR.md`. Keep route structure and headings aligned across locales when possible so translation progress and navigation remain useful.
+
+New repository-facing documentation and AI customization files should be written in English unless the file is explicitly a locale-specific translation.
+
+## Assets
+
+Use public site paths in Markdown:
+
+| Asset Type      | Repo Location           | Public Path       |
+| --------------- | ----------------------- | ----------------- |
+| Images          | `public/images/...`     | `/images/...`     |
+| Files           | `public/files/...`      | `/files/...`      |
+| Manual API JSON | `public/api/manual/...` | `/api/manual/...` |
+| Quasar API JSON | `public/quasar-api/...` | `/quasar-api/...` |
+
+Prefer absolute public paths in documentation so pages keep working when routes move.
+
+## Code Examples
+
+Live code examples are Vue SFC files discovered from `src/examples/**/*.vue`.
+
+Reference them with:
+
+```html
+<d-block-code-example
+  src="manual/code-examples/basic-counter"
+  title="Basic counter"
+/>
+```
+
+The `src` value is normalized to kebab-case and resolves to a PascalCase `.vue` file. For example, `manual/code-examples/basic-counter` resolves to `src/examples/manual/code-examples/BasicCounter.vue`.
+
+Use `file` as an alias for `src` only when migrating from Quasar Docs-style examples.
+
+## API Reference JSON
+
+API blocks fetch JSON from same-origin public assets:
+
+```html
+<d-block-api
+  src="/api/manual/http-client.json"
+  title="HTTP Client API"
+  page-link="true"
+/>
+```
+
+The JSON can follow Quasar's API schema. Useful sections include `props`, `methods`, `events`, `value`, `arg`, and `quasarConfOptions`. Entries marked `internal: true` are hidden.
+
+## Navigation and Metadata
+
+Page registry entries in `src/pages/*.index.js` define titles, status, icons, books, menu placement, subpage availability, descriptions, and search tags.
+
+When adding new content, check the nearest existing entry and keep metadata consistent with that section.
+
+## Authoring Rules
+
+- Prefer Markdown for simple content.
+- Use custom elements only when they add structure, interaction, or a clearer reading path.
+- Use `to` for internal Docsector routes and `href` for external URLs.
+- Avoid repeating the same Markdown source in multiple routes.
+- Keep page headings outside Expandable, Stepper, and Timeline bodies when they are meant to appear in the page-level table of contents.
+- Avoid unsupported nested custom block combinations unless current manual docs explicitly show the pattern.
+
+## Validation Pointers
+
+- Parser behavior is centered in `src/components/page-section-tokens.js`.
+- Rendering is dispatched by `src/components/DPageTokens.vue`.
+- Manual block registration is covered by `tests/manual-content-showcases.spec.js`.
+- Parser and block edge cases are covered by focused tests such as `tests/page-section-tokens.spec.js`, `tests/code-example-source.spec.js`, `tests/embedded-url-providers.spec.js`, and `tests/api-block-model.spec.js`.

package/src/pages/manual/basic/agent-skills.overview.en-US.md

@@ -0,0 +1,77 @@
+## Overview
+
+Docsector Reader ships a public authoring skill for AI agents that need to understand how Docsector documentation works.
+
+The skill is a `SKILL.md` file with companion references. It explains Docsector Markdown conventions, every documented block, page structure, asset paths, authoring patterns, MCP lookup, and WebMCP browser tools.
+
+## Public URLs
+
+The built-in skill is published as a static artifact:
+
+```text
+/.well-known/agent-skills/docsector-documentation-authoring/SKILL.md
+```
+
+The discovery index points agents to the same file and includes a SHA-256 digest:
+
+```text
+/.well-known/agent-skills/index.json
+```
+
+## What the Skill Contains
+
+<d-block-quick-links title="Skill references">
+  <d-block-quick-link
+    title="SKILL.md"
+    description="The compact workflow agents load first"
+    href="/.well-known/agent-skills/docsector-documentation-authoring/SKILL.md"
+  />
+  <d-block-quick-link
+    title="Block catalog"
+    description="All Docsector blocks, syntax, and when-to-use guidance"
+    href="/.well-known/agent-skills/docsector-documentation-authoring/references/block-catalog.md"
+  />
+  <d-block-quick-link
+    title="Page structure"
+    description="Page files, locales, assets, examples, and API JSON conventions"
+    href="/.well-known/agent-skills/docsector-documentation-authoring/references/page-structure.md"
+  />
+  <d-block-quick-link
+    title="MCP and WebMCP"
+    description="How agents can search, fetch, navigate, and copy live docs"
+    href="/.well-known/agent-skills/docsector-documentation-authoring/references/mcp-webmcp.md"
+  />
+</d-block-quick-links>
+
+## Local and Published Copies
+
+Docsector keeps two synchronized copies of the same skill:
+
+- `.github/skills/docsector-documentation-authoring/` for repository-local assistants such as GitHub Copilot in VS Code.
+- `public/.well-known/agent-skills/docsector-documentation-authoring/` for the built documentation site.
+
+During build, Docsector copies the public artifact into `dist/spa/.well-known/agent-skills/` and generates the discovery index.
+
+## How Agents Should Use It
+
+Agents should load `SKILL.md` first, then open reference files only when a task needs more detail.
+
+For current page examples, agents can combine the skill with Docsector's MCP tools:
+
+```text
+search_docsector
+get_page_docsector
+```
+
+Browser agents can also use WebMCP tools when `navigator.modelContext` is available:
+
+- `docs.search_docs`
+- `docs.get_page`
+- `docs.navigate_to`
+- `docs.copy_current_page`
+
+## When to Publish Your Own Skill
+
+Publish a project-specific skill when your documentation has domain rules that are not covered by the built-in Docsector authoring skill.
+
+Use Docsector's `agentSkills` config to expose the skill through `/.well-known/agent-skills/index.json`, and keep the artifact under `public/.well-known/agent-skills/...` when you want Docsector to compute the digest automatically.

package/src/pages/manual/basic/agent-skills.overview.pt-BR.md

@@ -0,0 +1,77 @@
+## Visão Geral
+
+O Docsector Reader publica uma skill de autoria para agentes de IA que precisam entender como a documentação Docsector funciona.
+
+A skill é um arquivo `SKILL.md` com referências complementares. Ela explica as convenções de Markdown do Docsector, todos os blocos documentados, estrutura de páginas, caminhos de assets, padrões de autoria, busca via MCP e ferramentas WebMCP no navegador.
+
+## URLs Públicas
+
+A skill embutida é publicada como artefato estático:
+
+```text
+/.well-known/agent-skills/docsector-documentation-authoring/SKILL.md
+```
+
+O índice de descoberta aponta os agentes para o mesmo arquivo e inclui um digest SHA-256:
+
+```text
+/.well-known/agent-skills/index.json
+```
+
+## O Que a Skill Contém
+
+<d-block-quick-links title="Referências da skill">
+  <d-block-quick-link
+    title="SKILL.md"
+    description="O fluxo compacto que os agentes carregam primeiro"
+    href="/.well-known/agent-skills/docsector-documentation-authoring/SKILL.md"
+  />
+  <d-block-quick-link
+    title="Catálogo de blocos"
+    description="Todos os blocos Docsector, sintaxe e orientação de uso"
+    href="/.well-known/agent-skills/docsector-documentation-authoring/references/block-catalog.md"
+  />
+  <d-block-quick-link
+    title="Estrutura de páginas"
+    description="Arquivos de página, locales, assets, exemplos e convenções de API JSON"
+    href="/.well-known/agent-skills/docsector-documentation-authoring/references/page-structure.md"
+  />
+  <d-block-quick-link
+    title="MCP e WebMCP"
+    description="Como agentes podem buscar, ler, navegar e copiar docs ao vivo"
+    href="/.well-known/agent-skills/docsector-documentation-authoring/references/mcp-webmcp.md"
+  />
+</d-block-quick-links>
+
+## Cópias Local e Publicada
+
+O Docsector mantém duas cópias sincronizadas da mesma skill:
+
+- `.github/skills/docsector-documentation-authoring/` para assistentes locais do repositório, como o GitHub Copilot no VS Code.
+- `public/.well-known/agent-skills/docsector-documentation-authoring/` para o site de documentação gerado.
+
+Durante o build, o Docsector copia o artefato público para `dist/spa/.well-known/agent-skills/` e gera o índice de descoberta.
+
+## Como Agentes Devem Usar
+
+Agentes devem carregar primeiro o `SKILL.md` e abrir os arquivos de referência apenas quando a tarefa precisar de mais detalhes.
+
+Para exemplos atuais de páginas, agentes podem combinar a skill com as ferramentas MCP do Docsector:
+
+```text
+search_docsector
+get_page_docsector
+```
+
+Agentes no navegador também podem usar ferramentas WebMCP quando `navigator.modelContext` estiver disponível:
+
+- `docs.search_docs`
+- `docs.get_page`
+- `docs.navigate_to`
+- `docs.copy_current_page`
+
+## Quando Publicar Sua Própria Skill
+
+Publique uma skill específica do projeto quando sua documentação tiver regras de domínio que não são cobertas pela skill de autoria embutida do Docsector.
+
+Use a configuração `agentSkills` do Docsector para expor a skill por `/.well-known/agent-skills/index.json`, e mantenha o artefato em `public/.well-known/agent-skills/...` quando quiser que o Docsector calcule o digest automaticamente.

package/src/pages/manual.index.js

@@ -265,6 +265,35 @@ export default {
     }
   },
 
+  '/basic/agent-skills': {
+    config: {
+      icon: 'psychology',
+      status: 'new',
+      version: 'v4.3.0',
+      meta: {
+        description: {
+          'en-US': 'Agent Skills — Documentation of Docsector Reader',
+          'pt-BR': 'Skills de Agentes — Documentacao do Docsector Reader'
+        }
+      },
+      book: 'manual',
+      menu: {},
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'Agent Skills' },
+      'pt-BR': { title: 'Skills de Agentes' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'agent skills skill md authoring blocks references mcp webmcp ai discovery well-known copilot',
+        'pt-BR': 'skills agentes skill md autoria blocos referências mcp webmcp ia descoberta well-known copilot'
+      }
+    }
+  },
+
   // =========================================================================
   // Content
   // =========================================================================