# Lark Hirono

> Feishu document toolkit: upload markdown as styled docs, optimize existing pages, fetch as markdown, analyze structure, apply keyword highlights, verify quality. Use when user wants to: upload md to feishu, optimize feishu doc, fetch feishu page, analyze document, highlight keywords, verify feishu doc. Triggers on: lark-hirono, feishu upload, feishu optimize, feishu fetch, feishu analyze, feishu highlight, feishu verify.

- Skill: `charles1614/lark-hirono` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add charles1614/lark-hirono`
- Raw SKILL.md: https://api.skillmd.com/api/skills/charles1614/lark-hirono/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: charles1614 (https://skillmd.com/u/charles1614)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/charles1614/lark-hirono

---


# Lark Hirono — Feishu Document Toolkit

Upload markdown as styled Feishu documents, optimize existing pages, fetch/analyze/highlight/verify.

## Skill Files Location

This skill's supporting files are located relative to this SKILL.md:

- `references/optimization-guide.md` — Quality standards and reference patterns for document transformation
- `references/mermaid-guide.md` — When and how to generate mermaid diagrams; examples for common patterns

## Running the CLI

Determine the correct invocation **once** at the start of each session, trying each step in order:

1. **Global install** — check if `lark-hirono` is on PATH:
   ```bash
   command -v lark-hirono
   ```
   If found, use `lark-hirono <action> [options]` for all commands.
   If not found, install with `npm install -g lark-hirono`; and update to latest via `npm update -g lark-hirono`

2. **Local dev repo** — only if working inside a cloned `lark-hirono` repo (the directory containing `package.json` with `"name": "lark-hirono"`), ensure deps are installed (`npm install`) and run:
   ```bash
   npx tsx bin/lark-hirono.ts <action> [options]
   ```

All examples below use `lark-hirono` as shorthand — substitute the resolved command.

## First-Time Setup

Run these steps once before first use. Each step is a prerequisite for the next.

### 1. Install lark-hirono

```bash
npm install -g lark-hirono
```

### 2. Install lark-cli

`lark-hirono` calls the `lark-cli` binary (>= 1.0.9) as a subprocess for all Feishu API operations. If it's not already installed:

```bash
mkdir -p /tmp/larkcli && cd /tmp/larkcli
npm init -y && npm install @larksuite/cli
node node_modules/@larksuite/cli/scripts/install.js
```

Or set the `LARK_CLI` environment variable to point to an existing `lark-cli` binary.

Verify installation:

```bash
lark-cli --version   # should print >= 1.0.9
```

### 3. Configure lark-cli

Initialize the app credentials that lark-cli uses to call Feishu APIs:

```bash
lark-cli config init
```

This is an interactive setup — follow the prompts to provide your Feishu app ID and secret. For details on app setup and scopes, see the `lark-shared` skill (`lark-cli config init` / `lark-cli auth login`).

### 4. Authenticate

```bash
lark-hirono auth login --domain docs
# or equivalently: lark-cli auth login --domain docs
```

This opens a browser for Feishu OAuth. After login, the token is cached by lark-cli (typically in `~/.config/lark/`).

Verify auth:

```bash
lark-hirono auth status
```

If the token has expired, re-run `auth login`.

### 5. Optional config file

Create `lark-hirono.json` in your project directory for defaults (wiki space, node, background mode). This file is optional — all values can be passed as CLI flags instead.

### Prerequisites Summary

- Node.js 20+
- `lark-cli` >= 1.0.9 (installed and authenticated)
- `lark-hirono.json` config file (optional, for wiki-space/wiki-node defaults)

## Data Locations

- **Config file**: `lark-hirono.json` in current directory or ancestors
- **Token cache**: Managed by `lark-cli` (typically `~/.config/lark/`)
- **Keyword batches**: `<input.md>.keywords_batch_N.json` (generated by `highlight extract`)
- **Selected keywords**: `<input.md>.selected_keywords.json` (LLM output, used by pipeline)

## Arguments

$ARGUMENTS should be: `ACTION [ARGS...]`

Determine the action from user intent:

| User intent | Action |
|-------------|--------|
| Upload local markdown to Feishu | `upload <input.md>` |
| Optimize existing Feishu doc | Skill workflow (fetch → edit → upload) |
| Update Feishu doc from local file | `optimize --doc <id> --input <file>` |
| Fetch Feishu doc as markdown | `fetch --doc <id>` |
| Analyze document structure | `analyze <input.md>` |
| Extract table titles for LLM | `highlight extract <input.md>` |
| Apply keyword highlights | `highlight apply <input.md> <keywords.json>` |
| Verify Feishu doc quality | `verify --doc <id>` |
| Authentication management | `auth <subcommand>` |

---

## Action: upload

Upload local markdown file as styled Feishu document.

```bash
lark-hirono upload <input.md> [title] [options]
```

**Options:**
- `--title <title>` — Document title (default: first H1)
- `--wiki-space <id>` — Wiki space ID
- `--wiki-node <id>` — Parent node ID
- `--bg-mode <mode>` — Heading background: light | dark
- `--image-dir <dir>` — Directory for downloaded images
- `--strip-title` — Remove first H1 heading
- `--no-highlight` — Skip keyword highlighting
- `--frontmatter-as-callout` — Convert YAML frontmatter into a Meta callout (blockquote → Feishu callout). Without the flag, frontmatter passes through unchanged.
- `--mention-map <path>` — JSON map keyed by doc URL: `{ "<url>": { "obj_token": "…", "obj_type"?: 22, "title"?: "…" } }`. After upload, any `text_run` link matching a key is rewritten to a native `mention_doc` element so Feishu's backlinks panel and graph view populate.
- `--verify` — Fetch and verify after upload
- `--dry-run` — Preprocess only, print markdown to stdout
- `-v, --verbose` — Verbose logging

**Input format notes:**
- `[^name]` inline footnote refs + `[^name]: body` definitions are auto-detected and rewritten to unicode superscripts (⁽¹⁾…) plus a trailing `## Footnotes` section. Idempotent and a no-op on inputs without footnote defs. Content inside fenced code blocks is left alone.

**For catalog_table docs** (tables with Code/Title columns):
1. Run `highlight extract input.md` first
2. Send JSON to LLM, save as `.selected_keywords.json`
3. Upload will auto-apply keywords if file exists

**Example:**
```bash
lark-hirono upload my-doc.md "My Document" --wiki-space 123456
```

---

## Action: optimize

Light-touch optimization of a Feishu wiki document: fix errors, repair corruption, improve formatting — while preserving the author's tone, style, and intent.

**Core principle**: The original document is the authority. The reference document only guides formatting structure. Never rewrite or restructure aggressively.

**Output**: A new wiki sub-page under the reference document containing the optimized version.

**How it works**: The skill uses CLI commands (`fetch`, `upload`, `analyze`) as tools while applying LLM judgment for corruption detection, emphasis decisions, and quality audits.

### Arguments

- **SOURCE_URL**: The Feishu wiki URL to optimize, e.g. `https://my.feishu.cn/wiki/Abc123`
- **DEST_URL** (optional): A well-formatted reference doc URL; new page is created under its parent node

**Extracting IDs from URLs:**
- Wiki URL `https://my.feishu.cn/wiki/Abc123XYZ` → doc/node ID is `Abc123XYZ` (the path segment after `/wiki/`)
- Use this ID for `--doc`, `--wiki-node` CLI flags

### Workflow

Follow these tasks in order:

1. **Read Source** — Fetch and understand the source document
2. **Read Reference** — Fetch and analyze the reference document's format
3. **Format Analysis** — Compare structures and identify format gaps
4. **Content Review** — Identify factual errors, incomplete descriptions, minor issues
5. **Generate Optimized Version** — Apply light-touch improvements
5.5. **Content Preservation Audit** — Verify no content was dropped or shortened
5.6. **Emphasis Audit** — Verify color/bold density is appropriate
5.7. **Rendered-Layout Regression Check** — Verify no visual regressions
6. **Write to Feishu** — Create new sub-page with optimized content

### Task 1: Read Source Document

```bash
lark-hirono fetch --doc <source-doc-id>
```

Save the full output. This is the document to optimize.

**Analyze carefully:** topic, purpose, writing style/tone, heading structure, content flow, formatting patterns, and **technical payload that must survive** (numbers, formulas, systems, deployment facts, experiment settings, citations, caveats). Record observations for Task 5.

### Task 2: Read Reference Document

```bash
lark-hirono fetch --doc <reference-doc-id>
```

Save the full output. This is the format reference only — not a content source.

**Analyze the FORMAT only:** heading hierarchy, section organization, formatting conventions (bold, lists), content density, structural elements (dividers, quotes, code blocks).

### Task 3: Format Analysis

Read [`references/optimization-guide.md`](<skill-directory>/references/optimization-guide.md) for the detailed comparison framework and known format conventions.

**Reference Discipline:**
- The optimization guide is a style reference, not a license to restyle the document wholesale
- Preserve the source document's macro-structure unless there is a clear formatting defect
- Do not renumber or deepen the heading hierarchy just to match the reference pattern if the source already has a stable hierarchy
- If an opening block, metadata block, or summary layout already works, prefer light cleanup over redesign

Check the source document against these specific format conventions:

| Convention | Expected Pattern |
|------------|-----------------|
| Opening callout | `[!callout]` with description + paper/repo links |
| Numbered headings | `## 1 标题` / `### 1.1 子标题` |
| Heading groups | Continuous numbering across whole doc |
| Level conflicts | Group/chapter titles at correct level vs. sub-items |
| Callouts/quotes | `\|>` / `[!callout]` / `> 📌` freely throughout |
| Code block tags | Language tag on every code block |
| Bold key terms | First mention of important technical terms bolded |
| Inline emphasis | `{red:...}` for key points; `{green:...}` for key terms |

**Hard Constraints:**
- Do **not** assume numbered headings are mandatory when the source already has a coherent hierarchy
- **Exception — Chinese ordinal headings are always a defect**: `## 一、`, `## 二、`, `## 三、`… use Chinese characters that do NOT trigger the tool's blue-number coloring. Always convert to `## 1 Title`, `## 2 Title`… format. This is not optional.
- Do **not** force extra subsection levels simply because the reference is more granular
- **All siblings at the same heading level must be consistently numbered or consistently unnumbered.** A lone unnumbered heading (e.g., `## Cheatsheet`) among numbered siblings must be assigned the next sequential number.
- Treat opening layout, metadata layout, and top-of-document summary layout as high-risk areas where over-editing is likely to regress the page

**Important**: Only note FORMAT differences. Do not compare content topics.

### Task 4: Content Review (Light Touch)

Review the source document for issues that should be fixed regardless of format:

**Fix These:**
- **Factual errors**: Incorrect technical information, wrong version numbers, broken links
- **Incomplete descriptions**: Sentences that trail off, missing explanations, TODO/placeholder text
- **Obvious typos**: Spelling errors, grammar mistakes that change meaning
- **Broken formatting**: Unclosed markdown, inconsistent list indentation
- **Feishu export corruption**: Paragraphs that became headings, broken heading hierarchy, merged content

**Do NOT Change:**
- **Author's tone**: If they write casually, keep it casual
- **Content focus**: If they emphasize certain topics, respect that emphasis
- **Technical opinions**: If they recommend a tool or approach, keep it
- **Original structure**: Only adjust structure if it clearly conflicts with the reference format
- **Level of detail**: If the author was brief on a topic, they may have had a reason

### Task 4.5: Mermaid Diagram (Best-Effort)

Read [`references/mermaid-guide.md`](<skill-directory>/references/mermaid-guide.md) for patterns, rules, and placement examples.

**Decision**: does this document benefit from a diagram? Generate one mermaid block (placed after the opening callout, before the first heading) if the document describes a multi-stage pipeline, system architecture, branching algorithm, or process flow. Skip for reference tables, FAQs, catalogs, or docs with no flow structure. When in doubt, skip — a bad diagram is worse than no diagram.

The pipeline handles all visual styling automatically. You only write the structure.

---

### Task 5: Generate Optimized Version

**CRITICAL**: Read this section carefully before writing.

#### The 80/20 Rule

The optimized document should be **80%+ identical** to the original. Changes should be subtle improvements, not rewrites.

#### What to change:

1. **Opening callout** — **REQUIRED for narrative documents** (text-heavy, few tables). Skip for catalog_table or data_table documents.
   - Write it as the very first block, before any heading.
   - Format: `<callout emoji="ICON" background-color="light-blue" border-color="light-blue">` — choose an icon (e.g. `gift`, `bulb`, `bookmark`, `pushpin`, `rocket`, `star`)
   - Put the document's intro/summary description inside, closed with `</callout>`
   - If the source already has an intro paragraph, blockquote, or summary section that describes the document, reuse or lightly optimize that content as the callout body — do not invent new summary text
   - If no such content exists, synthesize a 1–3 sentence summary from the document's main topic and scope
   - **Pipeline safety net**: Pipeline auto-injects from first paragraph as fallback — always write explicitly for control over content and emoji.

2. **Heading restructuring** — Fix numbering AND hierarchy when needed:
   - Apply **continuous sequential numbering**: `## 1`, `## 2`… for top-level; `### 1.1`, `### 1.2`… for second-level
   - **Input format**: Write `## 1 Title` (number then space then title — **no period in the markdown you write**). The pipeline adds a period automatically for single-level numbers: `## 1 Title` → rendered as `1. Title` with blue prefix. Multi-level numbers (`### 1.1 Sub`) do NOT get a period added.
   - Fix Chinese ordinals: `## 一、标题` → `## 1 标题`
   - **Fix corruption**: Paragraphs that became headings → convert back to paragraphs
   - **Preserve hierarchy**: Do not add or remove heading levels unless structure is broken

3. **Add emphasis** — Apply `{red:...}` and `{green:...}` markers:
   - **Red emphasis**: Key conclusions, results, important claims (10-20 instances in a long doc)
     - Bold phrase: `{red:**important conclusion**}` → renders bold + red
     - Plain text: `{red:term}` → renders red
     - Inline code: `` {red:`cmd`} `` → renders red code
   - **Green emphasis**: First mention of key technical terms (5-10 instances)
     - Plain text: `{green:term}` → renders green
     - Inline code: `` {green:`code`} `` → renders green code
   - **CRITICAL — convert raw `<text color>` tags from fetched docs**: Raw `<text color="green">BF16</text>` HTML from fetched documents does NOT render in uploaded docs — it appears as plain text. During optimization, convert every `<text color="COLOR">CONTENT</text>` to its shorthand form: `{green:CONTENT}`, `{red:CONTENT}`, etc. If the content has bold, place bold inside: `{green:**CONTENT**}`. Never preserve the raw `<text color>` form in the optimized output.
   - **Preserve all existing emphasis**: Every `{red:...}`, `{green:...}`, and `**bold**` in the source document MUST be carried over to the optimized version. Add new emphasis on top; never remove original emphasis.
   - **CRITICAL rendering rules**: Bold INSIDE color tags (`{red:**text**}`, never `**{red:text}**`). No `$formula$` in headings. No `**` wrapping `$formula$` boundaries. See optimization-guide § "Rendering Pitfalls" for full patterns.

4. **Add in-line callouts** — Insert markdown blockquotes for key insights throughout the document body:
   - Use `> 📌 **标题**: ...` for key insights
   - Use `> 📚 **背景**: ...` for background knowledge
   - Target: 5-15 such blockquotes throughout a long document
   - **Pipeline auto-conversion**: Blockquotes matching `TL;DR`, `核心思想`, `关键结论`, `一句话总结`, `核心区别` etc. are auto-converted to `<callout>` XML. Do not manually write `<callout>` XML for these — write `> TL;DR: ...` and let the pipeline convert.
   - **CRITICAL — no emoji prefix inside `<callout>` XML body**: When writing a `<callout>` XML block directly, do NOT start the body text with an emoji (📌, 💡, 📚, etc.). The `emoji=` attribute on the opening tag already provides the icon — adding an emoji in the body text creates a redundant double-icon display. Only the `> 📌 **Title**: ...` blockquote syntax (auto-converted by pipeline) needs the emoji prefix.
   - **CRITICAL — no nested `<callout>` XML**: Lark does not render a `<callout>` XML block nested inside another `<callout>` XML block. If the source document contains this pattern, convert the inner `<callout>` block to plain paragraphs (strip the opening/closing XML tags, keep the text). Markdown blockquotes (`> ...`) inside a `<callout>` body are fine and are NOT nested callouts.

5. **Fix code blocks** — Add language tags if missing.
6. **Fix factual errors** — Correct typos, broken links, wrong information
7. **Preserve images, tables, equations verbatim** — Copy `<image token>`, `<lark-table>`, `<equation>` tags unchanged at their original positions. Do not rewrite `<equation>` as `$...$`. Do not emit pipe-wrapped `|lark-table ...|` — use `<lark-table>` XML or standard markdown tables. See [`references/optimization-guide.md`](<skill-directory>/references/optimization-guide.md) § "Verified Syntax Reference" for full correct/incorrect patterns.
   - **CRITICAL — equations**: Never write bare LaTeX subscripts (`_{\text{...}}`) outside `$...$` or `<equation>` delimiters — bare `_` becomes italic. Multi-subscript bug: 2+ `_{...}` in one formula breaks (lark-cli pairs `_` as italic). Workaround: use single-char subscripts without braces (`_p`, `_h`). Single `_{...}` per formula is safe.
   - **CRITICAL — lark-table cells**: `***bold-italic***` with underscored content (e.g. `***sm__throughput***`) breaks — lark-cli misinterprets `_` inside `***`. Use backtick code format (`` `sm__throughput` ``) for metric names with underscores.
8. **`<quote-container>` handling** — lark-cli upload does NOT support `<quote-container>` (silently drops). Pipeline auto-converts: → blockquote (outside tables) / `<callout>` grey (inside tables). Leave as-is or convert manually.

#### What NOT to change:

- Do not rewrite paragraphs for style
- Do not add new sections or remove existing sections
- Do not change technical details or recommendations
- Do not restructure the document's argument flow

### Task 5.5: Content Preservation Audit

**CRITICAL**: Before writing to Feishu, verify that no content was lost.

Compare the optimized version against the source:

- [ ] All sections present (no sections removed)
- [ ] All paragraphs present (no paragraphs dropped)
- [ ] All code blocks present (no code removed)
- [ ] All tables present (no data lost)
- [ ] All links preserved (no links removed)
- [ ] Technical details intact (numbers, formulas, commands)
- [ ] All `<image token="...">` tags present (count source vs output — zero missing)
- [ ] All `<equation>` blocks present and unchanged (do not rewrite or split formulas)

**If content is missing**: Add it back. The optimized version must have 100% of the original content.

### Task 5.6: Emphasis Audit

Verify that emphasis density is appropriate:

- [ ] Red emphasis: 10-20 instances in a long document (or proportional to length)
- [ ] Green emphasis: 5-10 instances for first-mention technical terms
- [ ] Not over-emphasized: No more than 3 emphasized items per paragraph
- [ ] Not under-emphasized: Key conclusions are highlighted

### Task 5.7: Rendered-Layout Regression Check

Verify that the optimized document will not have visual regressions:

- [ ] Headings will render correctly (proper hierarchy)
- [ ] Code blocks have language tags
- [ ] Tables will render (proper markdown table syntax)
- [ ] Callouts will render (proper blockquote syntax)
- [ ] No unclosed markdown syntax

### Task 6: Write to Feishu

**If the source was a local file** (e.g., `report.md`): write the optimized content to `report_upload.md` (same directory, `_upload` suffix). Never modify the original file. Never use a `/tmp/` path.

**If the source was fetched from Feishu**: write to any convenient temp file (e.g., `<title>_upload.md` in current directory).

```bash
# Step 1: Write optimized content to upload file
# For local source report.md → use report_upload.md
cat > report_upload.md << 'OPTIMIZED_CONTENT_END'
[optimized markdown content here]
OPTIMIZED_CONTENT_END

# Step 2: Upload — default is always to create a new sibling page
lark-hirono optimize --doc <doc-id> --input report_upload.md --new \
  --title "Optimized: [Original Title]"

# Only update in place if the user explicitly asked to overwrite the original:
# lark-hirono optimize --doc <doc-id> --input report_upload.md
```

Note the `--new` flag creates a sibling page under the same parent node. Capture the returned URL/doc-id for the verification step below.

### Task 7: Post-Upload Verification (Required)

After uploading, verify the rendered document has no regressions before reporting to the user.

```bash
lark-hirono verify --doc <new-doc-id>
```

Check the output for:
- [ ] Callout present (narrative docs)
- [ ] Headings numbered sequentially, no Chinese ordinals
- [ ] No `\#` artifacts (escaped hashes leaked into text — pipeline uses ZWSP instead)
- [ ] No plain-text `<text color>` tags visible in content
- [ ] Content count plausible (not drastically shorter than source)

**If issues are found** → fix the local upload file, re-upload with `--new` (or overwrite the just-created page if you have its ID), and verify again. Iterate up to **3 times total**.

**After a clean verify** (or after exhausting 3 attempts), report to user:
1. **URL** of the new page
2. **Changes made** — brief list of formatting improvements applied
3. **Confidence level** — how confident you are in the changes; note any unresolved issues from the retry loop

---

## Action: fetch

Retrieve Feishu document as markdown.

```bash
lark-hirono fetch --doc <doc-id> [--output file.md]
```

**Options:**
- `--doc <id>` — Document ID (required)
- `--output <file>` — Save to file (default: stdout)

Outputs markdown to stdout unless `--output` is given.

---

## Action: analyze

Analyze markdown document structure.

```bash
lark-hirono analyze <input.md>
```

Returns JSON with:
- `document_type` — narrative | data_table | catalog_table | mixed
- `heading_count` — Number of headings
- `table_count` — Number of tables
- `table_rows` — Total table rows
- `suggested_modules` — Recommended transformations

---

## Action: highlight

Extract table titles for LLM keyword selection, or apply keywords to markdown.

### Extract

```bash
lark-hirono highlight extract <input.md> [--batch-size N]
```

Extracts Code/Title columns from tables, saves as:
- `input.md.keywords_batch_0.json`
- `input.md.keywords_batch_1.json` (if >200 titles)

**Next step:** Send JSON files to LLM, save response as `input.md.selected_keywords.json`

### Apply

```bash
lark-hirono highlight apply <input.md> <keywords.json> [--inplace]
```

Wraps keywords in `{red:**keyword**}` tags within table titles.

**Note:** `upload` and `optimize` auto-apply if `.selected_keywords.json` exists.

---

## Action: verify

Fetch and verify Feishu document quality.

```bash
lark-hirono verify --doc <doc-id>
lark-hirono verify <doc-id>          # positional form
```

**Options:**
- `--doc <id>` — Document ID (required unless passed positionally)
- `-v, --verbose` — Verbose output

Reports:
- Block/heading/table counts, heading background coverage
- Red highlights and bold header counts
- Residual HTML tags (should be empty)
- Pass/fail checks for structural and content-level expectations

Exit code `0` on pass, `1` on any failing check.

---

## Action: auth

Feishu authentication management (passthrough to lark-cli).

```bash
lark-hirono auth login
lark-hirono auth status
```

---

## Document Types

**Narrative** — Text-heavy documents with headings
- Transforms: normalize, headings, callout
- No LLM needed

**Catalog_table** — Tables with Code/Title columns, 50+ rows
- Transforms: normalize, tables, keyword highlighting
- LLM needed for keyword selection

**Data_table** — Tables with <50 rows
- Transforms: normalize, tables
- No LLM needed

---

## Workflow Examples

### Upload narrative doc
```bash
lark-hirono upload my-article.md
```

### Upload catalog_table doc with keywords
```bash
lark-hirono highlight extract catalog.md
# Send catalog.md.keywords_batch_0.json to LLM
# Save response as catalog.md.selected_keywords.json
lark-hirono upload catalog.md
```

### Optimize existing Feishu doc
```bash
lark-hirono optimize --doc CcKqdWjF2o2UzixXZDecXxvInyc
```

### Update Feishu doc from local file
```bash
lark-hirono optimize --doc CcKqdWjF2o2UzixXZDecXxvInyc --input local.md
```

### Upload a note with frontmatter + native backlinks
```bash
# mentions.json is a JSON object keyed by doc URL:
# { "https://www.feishu.cn/wiki/<node_token>": { "obj_token": "<obj_token>" } }
lark-hirono upload post.md \
  --frontmatter-as-callout \
  --mention-map mentions.json
```
After upload, any markdown link to a URL in `mentions.json` becomes a native
Feishu doc mention, populating the backlinks panel on the target doc.

---

## Supporting Files

- `references/optimization-guide.md` — Quality standards and reference patterns
- `references/mermaid-guide.md` — Mermaid diagram patterns and examples