@docsector/docsector-reader 4.3.0 → 4.3.2

package/README.md

@@ -51,7 +51,8 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🚨 **GitHub-Style Alerts** — Native support for `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, and `[!CAUTION]`
 - 🌍 **Internationalization (i18n)** — Multi-language support with HJSON locale files and per-page translations
 - 🌗 **Dark/Light Mode** — Automatic theme switching with Quasar Dark Plugin
-- 🔗 **Anchor Navigation** — Right-side Table of Contents tree with stable scroll tracking, auto-scroll to the active section, and active-heading resolution based on the last heading that crossed the content threshold
+- 🧰 **Docsector CLI Skill Installer** — Install the built-in authoring skill into older scaffolds with `docsector install-skill`
+- 🔗 **Anchor Navigation** — Right-side source-ordered Table of Contents tree with stable scroll tracking, auto-scroll to the active section, and active-heading resolution based on the last heading that crossed the content threshold
 - 🖱️ **Active Menu Item UX** — Active menu entries keep pointer cursor, clear URL hash without redundant navigation, and prevent accidental label text selection
 - 🔎 **Search** — Menu search across all documentation content and tags
 - 📱 **Responsive** — Mobile-friendly with collapsible sidebar and drawers
@@ -535,6 +536,14 @@ This repository publishes the built-in Docsector authoring skill at:
 
 The skill teaches agents Docsector Markdown authoring, all documented blocks, page/source conventions, MCP lookup, and WebMCP browser tools.
 
+For projects scaffolded before the built-in skill existed, run:
+
+```bash
+npx docsector install-skill
+```
+
+The helper copies the skill into `.github/skills/` for repository-local assistants and into `public/.well-known/agent-skills/` for published discovery. Existing folders are skipped unless `--force` is passed.
+
 When `digest` is omitted in config, Docsector computes it automatically from the referenced local artifact and writes it as:
 
 - `sha256:{hex}`
@@ -1087,6 +1096,8 @@ Notes:
 
 ```bash
 docsector init <name>          # Scaffold a new consumer project
+docsector install-skill        # Install the built-in authoring skill
+docsector install-skill --force # Refresh an existing installed authoring skill
 docsector dev                  # Start dev server (port 8181)
 docsector dev --port 3000      # Custom port
 docsector build                # Build for production (dist/spa/)

package/bin/docsector.js

@@ -8,11 +8,12 @@
  *   docsector dev          — Start development server with hot-reload
  *   docsector build        — Build optimized SPA for production
  *   docsector serve        — Serve the production build locally
+ *   docsector install-skill — Install the built-in authoring skill into a project
  *   docsector help         — Show help information
  */
 
 import { spawn } from 'child_process'
-import { existsSync, mkdirSync, writeFileSync, copyFileSync } from 'fs'
+import { existsSync, mkdirSync, writeFileSync, copyFileSync, cpSync } from 'fs'
 import { resolve, dirname } from 'path'
 import { fileURLToPath } from 'url'
 
@@ -23,7 +24,25 @@ const packageRoot = resolve(__dirname, '..')
 const args = process.argv.slice(2)
 const command = args[0]
 
-const VERSION = '4.3.0'
+const VERSION = '4.3.2'
+const AUTHORING_SKILL_NAME = 'docsector-documentation-authoring'
+const AUTHORING_SKILL_DESCRIPTION = 'Author Docsector documentation with Markdown, custom blocks, MCP, and WebMCP.'
+const AUTHORING_SKILL_PUBLIC_PATH = `/.well-known/agent-skills/${AUTHORING_SKILL_NAME}/SKILL.md`
+const AUTHORING_SKILL_SOURCE_DIR = resolve(packageRoot, 'public', '.well-known', 'agent-skills', AUTHORING_SKILL_NAME)
+const AUTHORING_SKILL_CONFIG_SNIPPET = `\
+agentSkills: {
+  enabled: true,
+  path: '/.well-known/agent-skills/index.json',
+  schema: 'https://schemas.agentskills.io/discovery/0.2.0/schema.json',
+  skills: [
+    {
+      name: '${AUTHORING_SKILL_NAME}',
+      type: 'skill-md',
+      description: '${AUTHORING_SKILL_DESCRIPTION}',
+      url: '${AUTHORING_SKILL_PUBLIC_PATH}'
+    }
+  ]
+}`
 
 const HELP = `
   Docsector Reader v${VERSION}
@@ -37,11 +56,14 @@ const HELP = `
     dev          Start development server with hot-reload (port 8181)
     build        Build optimized SPA for production (output: dist/spa/)
     serve        Serve the production build locally
+    install-skill
+                 Copy the built-in Docsector authoring skill into this project
     version      Show version number
     help         Show this help message
 
   Options:
     --port <number>   Override dev server port (default: 8181)
+    --force           Overwrite an existing installed authoring skill
 
   Examples:
     docsector init my-docs
@@ -49,6 +71,8 @@ const HELP = `
     docsector dev --port 3000
     docsector build
     docsector serve
+    docsector install-skill
+    docsector install-skill --force
 
   Documentation:
     https://github.com/docsector/docsector-reader
@@ -235,10 +259,10 @@ export default {
   //   schema: 'https://schemas.agentskills.io/discovery/0.2.0/schema.json',
   //   skills: [
   //     {
-  //       name: 'my-docs-mcp',
+  //       name: '${AUTHORING_SKILL_NAME}',
   //       type: 'skill-md',
-  //       description: 'Search and read docs pages through MCP.',
-  //       url: '/.well-known/agent-skills/my-docs-mcp/SKILL.md'
+  //       description: '${AUTHORING_SKILL_DESCRIPTION}',
+  //       url: '${AUTHORING_SKILL_PUBLIC_PATH}'
   //     }
   //   ]
   // },
@@ -783,6 +807,75 @@ function run (cmd, cmdArgs = []) {
   })
 }
 
+function copyAuthoringSkillTarget (targetDir, { force = false } = {}) {
+  if (!existsSync(AUTHORING_SKILL_SOURCE_DIR)) {
+    throw new Error(`Built-in authoring skill not found at ${AUTHORING_SKILL_SOURCE_DIR}`)
+  }
+
+  if (targetDir === AUTHORING_SKILL_SOURCE_DIR) {
+    return 'already-source'
+  }
+
+  if (existsSync(targetDir) && !force) {
+    return 'skipped'
+  }
+
+  mkdirSync(dirname(targetDir), { recursive: true })
+  cpSync(AUTHORING_SKILL_SOURCE_DIR, targetDir, {
+    recursive: true,
+    force: true
+  })
+
+  return existsSync(targetDir) ? 'installed' : 'failed'
+}
+
+function installAuthoringSkill ({ projectRoot = process.cwd(), force = false } = {}) {
+  const targets = [
+    {
+      label: 'Repository-local skill',
+      dir: resolve(projectRoot, '.github', 'skills', AUTHORING_SKILL_NAME)
+    },
+    {
+      label: 'Public skill artifact',
+      dir: resolve(projectRoot, 'public', '.well-known', 'agent-skills', AUTHORING_SKILL_NAME)
+    }
+  ]
+
+  console.log(`\n  Installing ${AUTHORING_SKILL_NAME} into ${projectRoot}...\n`)
+
+  try {
+    for (const target of targets) {
+      const result = copyAuthoringSkillTarget(target.dir, { force })
+      if (result === 'installed') {
+        console.log(`  created ${target.label}: ${target.dir}`)
+      } else if (result === 'already-source') {
+        console.log(`  using package ${target.label}: ${target.dir}`)
+      } else if (result === 'skipped') {
+        console.log(`  skipped ${target.label}: ${target.dir}`)
+      } else {
+        throw new Error(`Unable to install ${target.label} at ${target.dir}`)
+      }
+    }
+  } catch (err) {
+    console.error(`\n  Error: ${err.message}\n`)
+    process.exit(1)
+  }
+
+  if (!force) {
+    console.log('\n  Existing skill folders are left untouched. Use --force to refresh them.')
+  }
+
+  console.log('\n  To publish the skill discovery index, add this to docsector.config.js:\n')
+  console.log(
+    AUTHORING_SKILL_CONFIG_SNIPPET.split('\n')
+      .map(line => `  ${line}`)
+      .join('\n')
+  )
+  console.log('\n  Then run:')
+  console.log('    npx docsector build')
+  console.log('')
+}
+
 /**
  * Scaffold a new Docsector documentation project.
  */
@@ -916,6 +1009,10 @@ switch (command) {
     run('serve', ['dist/spa', '--history', ...args.slice(1)])
     break
 
+  case 'install-skill':
+    installAuthoringSkill({ force: args.includes('--force') })
+    break
+
   case 'version':
   case '-v':
   case '--version':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "4.3.0",
+  "version": "4.3.2",
   "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/src/components/DPageSection.vue

@@ -1,10 +1,11 @@
 <script setup>
-import { computed } from 'vue'
+import { computed, watch } from 'vue'
 import { useStore } from 'vuex'
 import { useI18n } from "vue-i18n"
 
 import DPageTokens from './DPageTokens.vue'
 import { pageValueI18nPath } from '../i18n/path'
+import { buildPageAnchorTree } from './page-anchor-tree'
 import { tokenizePageSectionSource } from './page-section-tokens'
 
 defineProps({
@@ -30,6 +31,10 @@ const tokenized = computed(() => {
 
   return tokenizePageSectionSource(t(pageValueI18nPath(absolute, 'source')))
 })
+
+watch(tokenized, (tokens) => {
+  store.commit('page/setAnchorTree', buildPageAnchorTree(tokens))
+}, { immediate: true })
 </script>
 
 <template>

package/src/components/page-anchor-tree.js

@@ -0,0 +1,45 @@
+const isTreeHeadingToken = (token) => token?.tag === 'h2' || token?.tag === 'h3'
+
+const hasAnchorId = (value) => value !== null && value !== undefined && value !== false && value !== ''
+
+const createRootNode = (children = []) => ({
+  id: 0,
+  children
+})
+
+const createTreeNode = (token) => ({
+  id: token.anchorId,
+  label: token.content,
+  children: []
+})
+
+export const buildPageAnchorTree = (tokens = []) => {
+  const anchors = []
+  const rootNode = createRootNode()
+  const seenAnchors = new Set()
+  let currentParentNode = null
+
+  for (const token of Array.isArray(tokens) ? tokens : []) {
+    if (!isTreeHeadingToken(token) || !hasAnchorId(token.anchorId) || seenAnchors.has(token.anchorId)) {
+      continue
+    }
+
+    seenAnchors.add(token.anchorId)
+    anchors.push(token.anchorId)
+
+    const node = createTreeNode(token)
+
+    if (token.tag === 'h3' && currentParentNode !== null) {
+      currentParentNode.children.push(node)
+      continue
+    }
+
+    rootNode.children.push(node)
+    currentParentNode = token.tag === 'h2' ? node : null
+  }
+
+  return {
+    anchors,
+    nodes: [rootNode]
+  }
+}

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

@@ -52,6 +52,45 @@ Docsector keeps two synchronized copies of the same skill:
 
 During build, Docsector copies the public artifact into `dist/spa/.well-known/agent-skills/` and generates the discovery index.
 
+## Retrofitting Older Scaffolds
+
+Projects scaffolded before this skill existed can import it with the CLI helper:
+
+```bash
+npx docsector install-skill
+```
+
+The command copies the built-in skill into both expected locations:
+
+- `.github/skills/docsector-documentation-authoring/`
+- `public/.well-known/agent-skills/docsector-documentation-authoring/`
+
+Existing folders are skipped so local edits are not overwritten. Use `--force` when you intentionally want to refresh the installed copy from the package:
+
+```bash
+npx docsector install-skill --force
+```
+
+The helper does not rewrite `docsector.config.js`. After installing the files, enable discovery with:
+
+```javascript
+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'
+    }
+  ]
+}
+```
+
+Then run `npx docsector build` to generate `/.well-known/agent-skills/index.json` with the computed digest.
+
 ## How Agents Should Use It
 
 Agents should load `SKILL.md` first, then open reference files only when a task needs more detail.

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

@@ -52,6 +52,45 @@ O Docsector mantém duas cópias sincronizadas da mesma skill:
 
 Durante o build, o Docsector copia o artefato público para `dist/spa/.well-known/agent-skills/` e gera o índice de descoberta.
 
+## Retrocompatibilidade Com Scaffolds Antigos
+
+Projetos criados antes dessa skill existir podem importá-la com o helper da CLI:
+
+```bash
+npx docsector install-skill
+```
+
+O comando copia a skill embutida para os dois locais esperados:
+
+- `.github/skills/docsector-documentation-authoring/`
+- `public/.well-known/agent-skills/docsector-documentation-authoring/`
+
+Pastas existentes são ignoradas para não sobrescrever edições locais. Use `--force` quando quiser atualizar a cópia instalada a partir do pacote:
+
+```bash
+npx docsector install-skill --force
+```
+
+O helper não reescreve `docsector.config.js`. Depois de instalar os arquivos, habilite a descoberta com:
+
+```javascript
+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'
+    }
+  ]
+}
+```
+
+Depois execute `npx docsector build` para gerar `/.well-known/agent-skills/index.json` com o digest calculado.
+
 ## 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.

package/src/pages/manual/basic/d-page-anchor.overview.en-US.md

@@ -6,7 +6,7 @@ Under the hood, this behavior is powered by `DPageAnchor`.
 
 ## How It Works
 
-1. As each heading component (DH1–DH6) mounts, it registers itself in the `page/nodes` store via `useNavigator`
+1. `DPageSection` tokenizes the current subpage and rebuilds the heading tree in source order
 2. `DPageAnchor` reads the `page/nodes` getter to render the tree
 3. When the user scrolls, the scroll observer in `DPage` updates the selected anchor
 4. Clicking a tree node navigates to the corresponding heading
@@ -22,7 +22,7 @@ The implementation interacts with these store state/getters:
 
 ## Tree Rendering
 
-Uses Quasar's `QTree` component with `default-expand-all`. The node key is the heading's numeric `id`, and the label is the heading text.
+Uses Quasar's `QTree` component with `default-expand-all`. The node key is the heading `id`, and the label is the heading text. H2 tokens become top-level tree entries, and H3 tokens nest under the nearest preceding H2.
 
 The root node (from DH1) shows the page title from i18n when no label is set:
 

package/src/pages/manual/basic/d-page-anchor.overview.pt-BR.md

@@ -6,7 +6,7 @@ Na implementação, esse comportamento é sustentado por `DPageAnchor`.
 
 ## Como Funciona
 
-1. Conforme cada componente de título (DH1–DH6) é montado, ele se registra no store `page/nodes` via `useNavigator`
+1. `DPageSection` tokeniza a subpágina atual e reconstrói a árvore de títulos na ordem do conteúdo
 2. `DPageAnchor` lê o getter `page/nodes` para renderizar a árvore
 3. Quando o usuário faz scroll, o observador de scroll no `DPage` atualiza a âncora selecionada
 4. Clicar em um nó da árvore navega até o título correspondente
@@ -22,7 +22,7 @@ A implementação interage com estes estados/getters da store:
 
 ## Renderização da Árvore
 
-Usa o componente `QTree` do Quasar com `default-expand-all`. A chave do nó é o `id` numérico do título, e o label é o texto do título.
+Usa o componente `QTree` do Quasar com `default-expand-all`. A chave do nó é o `id` do título, e o label é o texto do título. Tokens H2 viram entradas de primeiro nível, e tokens H3 ficam aninhados no H2 anterior mais próximo.
 
 O nó raiz (do DH1) mostra o título da página do i18n quando nenhum label é definido:
 

package/src/store/Page.js

@@ -1,3 +1,50 @@
+const createDefaultNodes = () => [
+  {
+    id: 0,
+    children: []
+  }
+]
+
+const cloneNode = (node) => {
+  const clonedNode = {
+    id: node.id,
+    children: Array.isArray(node.children) ? node.children.map(cloneNode) : []
+  }
+
+  if (node.label !== undefined) {
+    clonedNode.label = node.label
+  }
+
+  return clonedNode
+}
+
+const normalizeNodes = (nodes) => {
+  if (!Array.isArray(nodes) || nodes.length === 0) {
+    return createDefaultNodes()
+  }
+
+  const [rootNode] = nodes
+
+  if (rootNode?.id !== 0) {
+    return createDefaultNodes()
+  }
+
+  return [cloneNode(rootNode)]
+}
+
+const uniqueAnchors = (anchors) => {
+  const seenAnchors = new Set()
+
+  return (Array.isArray(anchors) ? anchors : []).filter((anchorId) => {
+    if (anchorId === null || anchorId === undefined || anchorId === false || seenAnchors.has(anchorId)) {
+      return false
+    }
+
+    seenAnchors.add(anchorId)
+    return true
+  })
+}
+
 const getNodePath = (nodes, targetId, ancestry = []) => {
   for (const node of nodes) {
     const nextAncestry = [...ancestry, node.id]
@@ -18,6 +65,24 @@ const getNodePath = (nodes, targetId, ancestry = []) => {
   return null
 }
 
+const findNode = (nodes, targetId) => {
+  for (const node of nodes) {
+    if (node.id === targetId) {
+      return node
+    }
+
+    if (Array.isArray(node.children) && node.children.length > 0) {
+      const found = findNode(node.children, targetId)
+
+      if (found !== null) {
+        return found
+      }
+    }
+  }
+
+  return null
+}
+
 export default {
   namespaced: true,
 
@@ -26,12 +91,7 @@ export default {
 
     anchors: [],
 
-    nodes: [
-      {
-        id: 0,
-        children: []
-      }
-    ],
+    nodes: createDefaultNodes(),
     nodesExpanded: [0],
 
     scrolling: false,
@@ -73,29 +133,36 @@ export default {
     },
 
     resetNodes (state) {
-      state.nodes = [
-        {
-          id: 0,
-          children: []
-        }
-      ]
+      state.nodes = createDefaultNodes()
     },
     pushNodes (state, node) {
-      const found = state.nodes[0].children.find(x => x.id === node.id)
+      const found = findNode(state.nodes, node.id)
 
-      if (!found) {
-        const value = {
-          id: node.id,
-          label: node.label,
-          children: node.children
-        }
+      if (found) {
+        found.label = node.label
+        return
+      }
 
-        const children = state.nodes[0].children
-        if (node.child && children.length) {
-          children.at(-1).children.push(value)
-        } else {
-          state.nodes[0].children.push(value)
-        }
+      const value = {
+        id: node.id,
+        label: node.label,
+        children: node.children
+      }
+
+      const children = state.nodes[0].children
+      if (node.child && children.length) {
+        children.at(-1).children.push(value)
+      } else {
+        state.nodes[0].children.push(value)
+      }
+    },
+    setAnchorTree (state, { anchors = [], nodes = createDefaultNodes() } = {}) {
+      state.anchors = uniqueAnchors(anchors)
+      state.nodes = normalizeNodes(nodes)
+      state.nodesExpanded = [0]
+
+      if (state.anchor !== 0 && !state.anchors.includes(state.anchor)) {
+        state.anchor = 0
       }
     },
     resetNodesExpanded (state) {