/eisland-dev-update-docs

name: eisland-dev-update-docs
description: >
  Update or create documentation in the eIsland VuePress docs site (web/eisland-web-docs).
  Use this skill whenever the user asks to update docs, add documentation, write a doc article,
  document a feature, update the tech stack docs, update plugin docs, update command docs,
  or any task involving files under web/eisland-web-docs/src/. This skill ensures all documentation
  follows the project's CLAUDE.md constraints, uses correct admonition syntax, maintains consistent
  style with existing articles, and properly updates sidebar.ts and README.md indexes.

Update Docs

This skill guides documentation updates for the eIsland VuePress docs site located at `web/eisland-web-docs/`.

Core Rules

These rules come from the project's `CLAUDE.md` and must be followed strictly:

1. **Language**: All documentation content must be written in **English**. No Chinese text allowed. 2. **Admonitions**: Every documentation file MUST use admonition syntax. Each file should include at least one admonition block (`:::tip`, `:::info`, `:::note`, `:::important`, `:::warning`, `:::danger`, or `:::details`). Use a variety of admonition types — do not rely on a single type. 3. **Sidebar**: Do NOT register `README.md` files in the sidebar. VuePress automatically uses each subdirectory's `README.md` as the category index page. 4. **Frontmatter**: Every doc file must have YAML frontmatter with `title` and `icon` fields. 5. **Test Statistics**: When documenting test coverage, use accurate numbers from the latest test run: **125 test files**, **2068 tests**. Update these numbers when new test results show different counts.

Documentation Structure

src/
├── introduction/                # Project introduction and architecture
│   ├── intro/                   # Project introduction
│   ├── tech-stack/              # Technology stack
│   ├── frontend-arch/           # Frontend architecture
│   └── backend-arch/            # Backend architecture
└── developer/                   # Developer guide
    ├── environment-setup/       # Environment configuration
    ├── guides/                  # Development workflows
    ├── standards/               # Coding and documentation standards
    ├── testing/                 # Testing strategies
    ├── commands/                # npm script reference
    └── git-operations/          # Git workflows

Adding New Documentation

Follow these steps in order:

1. Place the file in the appropriate subdirectory under `web/eisland-web-docs/src/` 2. Add the file path to `src/.vuepress/sidebar.ts` under the correct group 3. Add a link to the file in the subdirectory's `README.md` 4. If creating a new subdirectory, create a `README.md` index for it 5. **For API plugin docs**: Register sidebar badge in `src/.vuepress/components/SidebarBadges.vue` if adding Interface, Enum, or Monitor

API Plugin Documentation

For documentation under `src/api-plugins/`, follow the guidelines in `src/api-plugins/CLAUDE.md`:

Icon Convention

Every documentation file MUST use the correct icon in frontmatter:

| Type | Icon | Example | |------|------|---------| | Function/Method | `fa6-solid:code` | `getIconByPath` | | Interface/Type | `fa6-solid:table` | `BluetoothDeviceInfo` | | Class/Monitor | `fa6-solid:cubes` | `BluetoothMonitor` | | Enum | `fa6-solid:list` | `BatteryStatus` | | Plugin index | Category icon | `bluetooth`, `music`, etc. |

Code Examples

All function/method documentation MUST include both TypeScript and JavaScript code blocks using `::: code-tabs` syntax.

Required Sections (Function/Method)

Every function/method document MUST include these sections in this exact order:

1. **Info admonition** — Brief description with internal mechanism and return type 2. **Signature** — TypeScript function signature 3. **Parameters** — Table with Parameter, Type, Description 4. **Usage** — When to use, typical workflow, `:::note` and `:::tip` 5. **Return Value** — Table with Type and Description, `:::warning` 6. **Example** — `::: code-tabs` with TS + JS 7. **Notes** — Exactly 3 admonitions: `:::note`, `:::tip`, `:::important` 8. **Danger Avoidance** — `:::danger` admonition

Sidebar Badge Registration

When adding new Interface, Enum, or Monitor documentation, register the badge in `src/.vuepress/components/SidebarBadges.vue`:

const BADGE_MAP: Record<string, string> = {
  YourNewInterface: 'interface',
  YourNewEnum: 'enum',
  YourNewMonitor: 'monitor',
}

Function badges are auto-detected from URL patterns (`get*`, `set*`, `close*`, etc.).

File Template

Every new documentation file must follow this template:

---
title: Document Title
icon: icon-name
---

# Document Title

:::info
This document covers [brief description of what this document explains]. For related information, see [Related Document](related-doc.md).
:::

## Section Heading

Content here with tables, code blocks, and admonitions.

:::tip
Helpful tips and best practices.
:::

:::warning
Important notices and cautions.
:::

Style Guide

Tables

Use tables for structured data — commands, configurations, comparisons, file listings:

| Command | Script | Description |
|---------|--------|-------------|
| `npm run build` | `vite build` | Build for production |

Code Blocks

Always specify the language:

```bash
npm run build

const x: string = "hello";

{ "key": "value" }

### Admonition Types

Use the right admonition for the right context:

| Type | Use For |
|------|---------|
| `:::info` | Document introduction, general explanations |
| `:::tip` | Best practices, helpful shortcuts |
| `:::note` | Supplementary information, side notes |
| `:::important` | Key information users must be aware of |
| `:::warning` | Cautions, potential issues, breaking changes |
| `:::danger` | Critical security notes, destructive operations |
| `:::details