update-docs

---
name: update-docs
description: >-
  Sync source files and README demo catalog into markdown via
  .cursor/skills/update-docs/update_doc.sh. Use when updating docs, README,
  quick_start, configuration, .env.example, docker-compose-example.yml,
  docs/demos.yml, adding sync tags, or when the user mentions update_doc.sh,
  doc sync, or documentation updates.
---

# Update Documentation

Script: **`.cursor/skills/update-docs/update_doc.sh`**

After editing synced sources, run:

```bash
.cursor/skills/update-docs/update_doc.sh
```

It does two jobs:

1. **File embeds** — replace `<!-- filename -->` … `<!-- /filename -->` blocks with live file content
2. **README demos** — run `scripts/sync_demos.py` from `docs/demos.yml` into `<!-- demos:readme:… -->` blocks

## Hard rules

| Do | Don't |
|----|--------|
| Edit the **source** (`.env.example`, compose example, `demos.yml`), then run the script | Hand-edit content inside sync tags |
| Update **both** Chinese and English docs for prose changes | Change only one language |
| Keep `docs/demo.md` / `docs/en/demo.md` hand-edited | Overwrite those pages from `demos.yml` (they are takeover / file / MCP scenarios) |
| Point demo **video** work to `.cursor/skills/demo-videos/SKILL.md` | Treat this skill as the recording/upload guide |

## Key files

| File | Role |
|------|------|
| `.cursor/skills/update-docs/update_doc.sh` | Sync driver; `FILES_TO_SYNC` lists embed sources; then calls `sync_demos.py` |
| `docker-compose-example.yml` | Minimal compose snippet in quick start |
| `.env.example` | Env var reference in configuration / quick start |
| `docs/demos.yml` | README demo titles / tasks / Attachment URLs only |
| `scripts/sync_demos.py` | Fills `<!-- demos:readme:en\|zh -->` in `README.md` / `README_zh.md` |
| `docs/demo.md` / `docs/en/demo.md` | Scenario demos — **not** synced |

## Workflow

```
Task Progress:
- [ ] 1. Edit source file(s)
- [ ] 2. Register new embeds in FILES_TO_SYNC (if needed)
- [ ] 3. Add <!-- filename --> tags in target .md (if needed)
- [ ] 4. .cursor/skills/update-docs/update_doc.sh
- [ ] 5. Verify both ZH and EN outputs
```

### 1. Edit the source

Examples: `docker-compose-example.yml`, `.env.example`, `docs/demos.yml`.

For **new README demo videos** (record / `gh image` / confirm publish), follow **demo-videos** skill first, then edit `docs/demos.yml` and run this script.

### 2. Register embeds (new files only)

In `.cursor/skills/update-docs/update_doc.sh`:

```bash
FILES_TO_SYNC=(
    "docker-compose-example.yml:yaml"
    ".env.example:ini"
)
```

Format: `"path:code_type"`. If `code_type` is omitted, it is inferred from the extension.

Supported types: `yaml`, `json`, `javascript`, `typescript`, `python`, `bash`, `css`, `html`, `xml`, `sql`, `markdown`, `ini`, `env`, `dockerfile`, `nginx`, `text`.

### 3. Add sync tags (new embeds only)

Tag name must match `FILES_TO_SYNC` exactly:

````markdown
<!-- filename -->
```yaml
```
<!-- /filename -->
````

README demo blocks (managed by `sync_demos.py`):

```markdown
<!-- demos:readme:en -->
…
<!-- /demos:readme:en -->
```

```markdown
<!-- demos:readme:zh -->
…
<!-- /demos:readme:zh -->
```

Do **not** put `demos:docsify` tags in `docs/demo.md`.

### 4. Run sync

```bash
.cursor/skills/update-docs/update_doc.sh
```

Scans repo `.md` files (skips `.venv`, `.git`, `node_modules`), refreshes embed blocks, then syncs README demos.

### 5. Verify

- Spot-check that fenced blocks match the sources
- Confirm README Demos match `docs/demos.yml`
- Confirm `docs/demo.md` still shows 电脑接管 / 文件处理 / MCP (unchanged by sync)

## Bilingual map

| Chinese | English |
|---------|---------|
| `README_zh.md` | `README.md` |
| `docs/quick_start.md` | `docs/en/quick_start.md` |
| `docs/configuration.md` | `docs/en/configuration.md` |
| `docs/*.md` | `docs/en/*.md` |

## Pitfalls

- Tag text must exactly match the registered filename
- Both open and close tags are required
- Forgetting to run the script before commit leaves docs stale
- Mixing README demos with `docs/demo.md` scenario pages

## Related

- Demo recording / upload / publish confirmation: `.cursor/skills/demo-videos/SKILL.md`

More agent context in Simpleyyt/ai-manus

7 other files this repository gives its agents.