@docsector/docsector-reader 4.3.0 → 4.3.1

package/README.md

@@ -51,6 +51,7 @@ 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
+- 🧰 **Docsector CLI Skill Installer** — Install the built-in authoring skill into older scaffolds with `docsector install-skill`
 - 🔗 **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
 - 🖱️ **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
@@ -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.1'
+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.1",
   "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/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.