docs: add spec and features documentation, fix homepage and navigation

- Add docs/spec/ with complete parameter specs for all 6 command groups
  (git, agent, task, magic, script, docs)
- Add docs/features/ with feature introductions for each module
- Fix docs/index.md frontmatter (title/description for docmd homepage)
- Update docmd.config.js navigation to include spec/features sections
  and fix stale paths from deleted files

(Refs: #11)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: qdriven

docmd.config.js

@@ -56,22 +56,46 @@ export default defineConfig({
       collapsible: true,
       children: [
         { title: '概览', path: '/usage/usage' },
-        { title: 'Git 仓库更新', path: '/usage/update' },
-        { title: 'Mono-repo 创建', path: '/usage/create' },
-        { title: '子模块同步', path: '/usage/sync' },
-        { title: 'Gitcode 远程', path: '/usage/gitcode' },
-        { title: '任务管理', path: '/usage/task' },
+        { title: 'Git 管理', path: '/usage/git' },
         { title: 'AI Agent 配置', path: '/usage/agent' },
-        { title: 'VS Code 配置', path: '/usage/vscode-setup' },
+        { title: '任务管理', path: '/usage/task' },
+        { title: '系统工具', path: '/usage/magic' },
+        { title: '脚本管理', path: '/usage/script' },
+        { title: '文档管理', path: '/usage/docs-cmd' },
       ],
     },
     {
       title: '架构设计',
       icon: 'sitemap',
       collapsible: true,
       children: [
-        { title: 'CLI 集成报告', path: '/analysis/cli-integration-report' },
-        { title: 'Spark Hub 架构 RFC', path: '/analysis/spark-hub-architecture-rfc' },
+        { title: '项目分析报告', path: '/analysis/project-analysis' },
+      ],
+    },
+    {
+      title: '功能介绍',
+      icon: 'puzzle-piece',
+      collapsible: true,
+      children: [
+        { title: 'Git 管理', path: '/features/git' },
+        { title: 'Agent 配置', path: '/features/agent' },
+        { title: '任务管理', path: '/features/task' },
+        { title: '系统工具', path: '/features/magic' },
+        { title: '脚本管理', path: '/features/script' },
+        { title: '文档管理', path: '/features/docs-feature' },
+      ],
+    },
+    {
+      title: '命令规格',
+      icon: 'terminal',
+      collapsible: true,
+      children: [
+        { title: 'Git', path: '/spec/git' },
+        { title: 'Agent', path: '/spec/agent' },
+        { title: 'Task', path: '/spec/task' },
+        { title: 'Magic', path: '/spec/magic' },
+        { title: 'Script', path: '/spec/script' },
+        { title: 'Docs', path: '/spec/docs-cmd' },
       ],
     },
     { title: 'Agents', path: '/Agents', icon: 'robot' },

docs/features/agent.md

@@ -0,0 +1,64 @@
+# AI Agent 配置管理
+
+## 功能概述
+
+`spark agent` 统一管理多种 AI Agent（Claude Code、Codex、Kimi、GLM）的配置文件。通过 Profile 模板机制，可以在不同项目间快速切换 Agent 配置。
+
+## 支持的 Agent
+
+| Agent | 配置文件 |
+|-------|---------|
+| Claude Code | `CLAUDE.md`、`.claude/settings.json` 等 |
+| Codex | `AGENTS.md`、codex 配置 |
+| Kimi | `.kimi/` 目录下的配置 |
+| GLM | `.glm/` 目录下的配置 |
+
+## 核心能力
+
+### 配置查看与编辑
+
+查看、编辑、重置各 Agent 的配置文件，无需记忆文件路径。
+
+```bash
+spark agent list                    # 列出所有 Agent
+spark agent view claude-code        # 查看配置
+spark agent edit kimi               # 编辑配置
+spark agent reset glm               # 重置配置
+```
+
+### Profile 模板
+
+Profile 是配置模板，保存了特定 Agent 的完整配置。可以为不同项目或工作模式创建不同 Profile。
+
+```bash
+# 创建 Profile
+spark agent profile add my-claude -t claude-code
+spark agent profile add my-glm -t glm
+
+# 查看 Profile
+spark agent profile show my-claude
+spark agent profile edit my-claude
+```
+
+### 跨项目应用
+
+将 Profile 应用到指定项目，自动创建或覆盖对应的配置文件。
+
+```bash
+spark agent use my-claude                    # 应用到当前目录
+spark agent use my-claude -p /path/to/proj   # 应用到指定项目
+spark agent current                          # 查看当前 Profile
+```
+
+## 使用参数
+
+| 参数 | 说明 |
+|------|------|
+| `--tui` | 交互式选择模式 |
+| `-t, --type` | Profile 的 Agent 类型 |
+| `-p, --project` | 目标项目路径，默认 `.` |
+
+## 相关文档
+
+- [Agent 命令规格](../spec/agent.md)
+- [Agent 使用指南](../usage/agent.md)

docs/features/docs-feature.md

@@ -0,0 +1,67 @@
+# 文档管理
+
+## 功能概述
+
+`spark docs` 管理项目文档结构和 docmd 站点配置。一键创建标准文档目录，自动生成 docmd 配置文件。
+
+## 核心能力
+
+### 文档目录初始化
+
+创建标准文档目录结构：
+
+```
+docs/
+├── Agents.md
+├── analysis/
+├── features/
+├── index.md
+├── quick-start/
+├── README.md
+├── spec/
+├── tips/
+└── usage/
+```
+
+已存在的文件和目录会被跳过，不会覆盖。
+
+```bash
+spark docs init
+spark docs init --root /path/to/project
+```
+
+### docmd 站点初始化
+
+自动生成 docmd 配置文件 `docmd.config.js`：
+- 从 git remote 自动检测项目名称和 GitHub Pages URL
+- 配置 sky 主题、SPA 布局
+- 启用搜索、Mermaid 图表、LLM 全文索引等插件
+- 自动安装 `@docmd/core`（如果未安装）
+- 自动初始化 `package.json`（如果不存在）
+
+```bash
+spark docs site
+spark docs site --root /path/to/project
+```
+
+初始化后可运行：
+```bash
+docmd dev      # 本地预览
+docmd build    # 构建静态站点
+```
+
+## 使用参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `--root` | string | `.` | 项目根目录 |
+
+## 依赖
+
+- Node.js（docmd 站点功能）
+- `@docmd/core`（自动安装）
+
+## 相关文档
+
+- [Docs 命令规格](../spec/docs-cmd.md)
+- [Docs 使用指南](../usage/docs-cmd.md)

docs/features/git.md

@@ -0,0 +1,67 @@
+# Git 仓库管理
+
+## 功能概述
+
+`spark git` 提供多仓库 Git 管理能力，涵盖批量更新、Mono-repo 创建与同步、Gitcode 远程配置、组织仓库克隆等功能。
+
+## 核心能力
+
+### 多仓库批量更新
+
+扫描配置目录下所有 Git 仓库，执行批量 `git pull`。适合同时维护多个仓库的日常更新。
+
+```bash
+spark git update -p ~/workspace
+```
+
+### Mono-repo 管理
+
+将多个独立仓库作为 Submodule 合并为一个 Mono-repo，方便统一管理和版本控制。
+
+```bash
+# 创建 Mono-repo
+spark git create -n my-mono -o ./output
+
+# 同步所有 Submodule 到最新
+spark git sync ./my-mono
+```
+
+### Gitcode 远程集成
+
+为仓库自动添加 Gitcode（https://gitcode.com）远程仓库，实现 GitHub ↔ Gitcode 双向同步。
+
+```bash
+spark git gitcode -p ~/workspace
+```
+
+### 组织仓库管理
+
+克隆 GitHub 组织下所有仓库，或更新组织 README 中的仓库状态列表。
+
+```bash
+# 克隆组织仓库
+spark git clone-org variableway -o ./repos
+
+# 更新组织状态
+spark git update-org-status variableway --update-dot-github
+```
+
+## 使用参数
+
+| 参数 | 说明 |
+|------|------|
+| `-p, --path` | 指定扫描目录（支持多个），默认 `["."]` |
+| `-n, --name` | Mono-repo 名称，默认 `mono-repo` |
+| `-o, --output` | 输出路径 |
+| `--ssh` | 使用 SSH 克隆（clone-org） |
+| `--include` / `--exclude` | 包含/排除匹配模式（clone-org） |
+
+## 依赖
+
+- `git` 命令行工具
+- `gh` CLI（clone-org、update-org-status 需要 GitHub API 访问）
+
+## 相关文档
+
+- [Git 命令规格](../spec/git.md)
+- [Git 使用指南](../usage/git.md)

docs/features/magic.md

@@ -0,0 +1,89 @@
+# 系统工具
+
+## 功能概述
+
+`spark magic` 提供日常开发中的系统工具，包括 DNS 缓存刷新和包管理器镜像源切换。
+
+## 核心能力
+
+### DNS 刷新
+
+一键刷新系统 DNS 缓存，支持 macOS、Windows、Linux。
+
+```bash
+spark magic flush-dns
+```
+
+### Python pip 镜像源切换
+
+管理 pip 的镜像源配置，解决国内访问 PyPI 速度慢的问题。
+
+```bash
+spark magic pip list          # 列出可用源
+spark magic pip use tsinghua  # 切换到清华源
+spark magic pip current       # 查看当前源
+```
+
+可用镜像源：
+
+| 名称 | 说明 |
+|------|------|
+| `tsinghua` | 清华大学 |
+| `aliyun` | 阿里云 |
+| `douban` | 豆瓣 |
+| `ustc` | 中国科技大学 |
+| `tencent` | 腾讯云 |
+
+### Go Module Proxy 切换
+
+管理 Go module proxy 配置。
+
+```bash
+spark magic go list         # 列出可用 proxy
+spark magic go use goproxy  # 切换到 goproxy.cn
+spark magic go current      # 查看当前 proxy
+```
+
+可用 Proxy：
+
+| 名称 | 说明 |
+|------|------|
+| `aliyun` | 阿里云 |
+| `tsinghua` | 清华大学 |
+| `goproxy` | goproxy.cn |
+| `ustc` | 中国科技大学 |
+| `nju` | 南京大学 |
+
+### Node.js npm Registry 切换
+
+管理 npm registry 配置。
+
+```bash
+spark magic node list       # 列出可用 registry
+spark magic node use taobao # 切换到淘宝源
+spark magic node current    # 查看当前 registry
+```
+
+可用 Registry：
+
+| 名称 | 说明 |
+|------|------|
+| `taobao` | 淘宝 |
+| `aliyun` | 阿里云 |
+| `tencent` | 腾讯云 |
+| `huawei` | 华为云 |
+| `ustc` | 中国科技大学 |
+
+## 使用参数
+
+三个镜像切换命令（pip/go/node）共享相同的子命令结构：
+
+| 子命令 | 参数 | 说明 |
+|--------|------|------|
+| `list` | 无 | 列出可用源 |
+| `use` | `<name>` | 切换到指定源 |
+| `current` | 无 | 显示当前配置 |
+
+## 相关文档
+
+- [Magic 命令规格](../spec/magic.md)

docs/features/script.md

@@ -0,0 +1,50 @@
+# 脚本管理
+
+## 功能概述
+
+`spark script` 管理和执行自定义自动化脚本。脚本可以来自配置文件声明，也可以是 `scripts/` 目录下的可执行文件。
+
+## 核心能力
+
+### 脚本发现
+
+自动发现两种来源的脚本：
+1. **配置文件脚本**：`~/.spark.yaml` 中的 `spark.scripts` 或顶层 `scripts` 配置
+2. **目录脚本**：项目 `scripts/` 目录下的可执行文件
+
+配置文件脚本优先级高于目录脚本。
+
+```bash
+spark script list
+```
+
+### 脚本执行
+
+通过名称执行已注册的脚本，支持传递额外参数。
+
+```bash
+spark script run my-script
+spark script run deploy -- --env production
+```
+
+## 使用参数
+
+| 命令 | 参数 | 说明 |
+|------|------|------|
+| `list` | 无 | 列出所有可用脚本 |
+| `run` | `<name> [args...]` | 执行脚本并传递参数 |
+
+## 配置示例
+
+```yaml
+# ~/.spark.yaml
+spark:
+  scripts:
+    - name: hello
+      description: Say hello
+      command: echo "Hello, World!"
+```
+
+## 相关文档
+
+- [Script 命令规格](../spec/script.md)