@docsector/docsector-reader 4.1.0 → 4.3.0

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/content/blocks/api-reference.overview.en-US.md

@@ -0,0 +1,40 @@
+## Overview
+
+API Reference blocks render a JSON document that follows the existing Quasar API schema directly inside Markdown.
+
+This keeps the viewer compatible with Quasar-style API files while still allowing non-Vue APIs to reuse the same section model for props, methods, events, values, arguments, and config shapes.
+
+The block is authored with the custom Markdown element `<d-block-api>`.
+
+## Markdown Syntax
+
+```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"
+/>
+```
+
+## Attributes
+
+| Attribute | Purpose |
+|-----------|---------|
+| `src` | Same-origin JSON path to fetch in the browser |
+| `title` | Optional header override shown above the API card |
+| `page-link` | Shows the Docs button when the JSON has `meta.docsUrl` |
+
+## JSON Source Model
+
+- The first implementation follows the same delivery model as Quasar Docs: the JSON file is served as a public asset and fetched on demand.
+- No Docsector-specific schema is required. If your file already follows the Quasar API structure, it can be rendered as-is.
+- Non-Vue APIs can still use the same shape by filling the sections they need, such as `props`, `methods`, `events`, `value`, `arg`, or `quasarConfOptions`.
+
+## Notes
+
+- `props` are grouped into subtabs when more than one `category` is present.
+- Entries marked with `internal: true` are hidden from the rendered block.
+- The current version expects same-origin JSON assets so the browser can fetch them without CORS workarounds.
+- If the JSON exposes `meta.docsUrl`, `page-link="true"` can surface a Docs button without changing the schema.

package/src/pages/manual/content/blocks/api-reference.overview.pt-BR.md

@@ -0,0 +1,40 @@
+## Visão geral
+
+Os blocos de Referência de API renderizam um documento JSON que segue o schema de API já existente do Quasar diretamente dentro do Markdown.
+
+Isso mantém o viewer compatível com arquivos de API no estilo do Quasar e ainda permite que APIs não-Vue reutilizem o mesmo modelo de seções para props, methods, events, values, arguments e estruturas de configuração.
+
+O bloco é escrito com o elemento Markdown customizado `<d-block-api>`.
+
+## Sintaxe Markdown
+
+```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"
+/>
+```
+
+## Atributos
+
+| Atributo | Finalidade |
+|----------|------------|
+| `src` | Caminho same-origin do JSON a ser buscado no navegador |
+| `title` | Sobrescreve opcionalmente o título exibido acima do card |
+| `page-link` | Exibe o botão Docs quando o JSON possui `meta.docsUrl` |
+
+## Modelo da Fonte JSON
+
+- A primeira implementação segue o mesmo modelo de entrega do Quasar Docs: o arquivo JSON é servido como asset público e carregado sob demanda.
+- Nenhum schema específico do Docsector é exigido. Se o arquivo já seguir a estrutura de API do Quasar, ele pode ser renderizado sem alterações.
+- APIs não-Vue ainda podem usar a mesma forma preenchendo apenas as seções necessárias, como `props`, `methods`, `events`, `value`, `arg` ou `quasarConfOptions`.
+
+## Notas
+
+- `props` são agrupadas em subtabs quando mais de uma `category` está presente.
+- Entradas marcadas com `internal: true` são ocultadas do bloco renderizado.
+- A versão atual espera assets JSON same-origin para que o navegador faça o fetch sem workarounds de CORS.
+- Se o JSON expuser `meta.docsUrl`, `page-link="true"` pode exibir um botão Docs sem alterar o schema.

package/src/pages/manual/content/blocks/api-reference.showcase.en-US.md

@@ -0,0 +1,33 @@
+## Showcase
+
+### Quasar JSON Without Refactoring
+
+This example renders a real Quasar API JSON file copied into `public/quasar-api/`.
+
+<d-block-api src="/quasar-api/QSeparator.json" />
+
+### Generic SDK JSON With the Same Schema
+
+This example uses the same section model for a non-Vue HTTP client and also enables the optional Docs button.
+
+<d-block-api src="/api/manual/http-client.json" title="HTTP Client API" page-link="true" />
+
+## Authoring Syntax
+
+```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"
+/>
+```
+
+## Features Visible Above
+
+- **Quasar JSON compatibility** with a real file served from `public/quasar-api/`
+- **Generic API support** without introducing a new schema
+- **Local filter** across names and descriptions inside the loaded API sections
+- **Grouped props subtabs** when multiple categories exist in the JSON
+- **Optional Docs link** when `meta.docsUrl` is present and `page-link="true"` is used

package/src/pages/manual/content/blocks/api-reference.showcase.pt-BR.md

@@ -0,0 +1,33 @@
+## Showcase
+
+### JSON do Quasar Sem Refatoração
+
+Este exemplo renderiza um arquivo JSON de API real do Quasar copiado para `public/quasar-api/`.
+
+<d-block-api src="/quasar-api/QSeparator.json" />
+
+### JSON de SDK Genérico Com o Mesmo Schema
+
+Este exemplo usa o mesmo modelo de seções para um cliente HTTP não-Vue e também ativa o botão opcional de Docs.
+
+<d-block-api src="/api/manual/http-client.json" title="HTTP Client API" page-link="true" />
+
+## Sintaxe de Autoria
+
+```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"
+/>
+```
+
+## Recursos Visíveis Acima
+
+- **Compatibilidade com JSON do Quasar** usando um arquivo real servido de `public/quasar-api/`
+- **Suporte a APIs genéricas** sem introduzir um novo schema
+- **Filtro local** por nomes e descrições dentro das seções carregadas
+- **Subtabs agrupadas em props** quando múltiplas categorias existem no JSON
+- **Link opcional para Docs** quando `meta.docsUrl` está presente e `page-link="true"` é usado

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
   // =========================================================================
@@ -879,6 +908,34 @@ export default {
     }
   },
 
+  '/content/blocks/api-reference': {
+    config: {
+      icon: 'api',
+      status: 'new',
+      meta: {
+        description: {
+          'en-US': 'API Reference Block — Documentation of Docsector Reader',
+          'pt-BR': 'Bloco de Referência de API — Documentacao do Docsector Reader'
+        }
+      },
+      book: 'manual',
+      menu: {},
+      subpages: {
+        showcase: true
+      }
+    },
+    data: {
+      'en-US': { title: 'API Reference' },
+      'pt-BR': { title: 'Referência de API' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'api json quasar reference props methods events docs metadata custom block',
+        'pt-BR': 'api json quasar referência props métodos eventos docs metadados bloco customizado'
+      }
+    }
+  },
+
   '/content/structures': {
     config: null,
     data: {