---
name: crewx/doc
description: Document management and knowledge tools. TOC extraction, section reader, frontmatter indexing, BM25 search, knowledge graph, and tag aggregation.
metadata:
  version: 0.2.0
  built-in: true
---

# Doc Skill

Document management and knowledge tools. Provides TOC extraction, section reading, frontmatter-based indexing, BM25 search, inter-document knowledge graph, and tag aggregation for markdown documents.

## When to Use This Skill

Use this skill in the following situations:

- "Create a new document" / "Generate a research document"
- "Show the design doc table of contents" / "Extract TOC"
- "Show me only the API design section from the design doc"
- "Summarize the implementation status"
- When you need to understand the structure before analyzing a long markdown document
- "Search documents" / "Find documents about onboarding"
- "Show relationships between documents" / "Show knowledge graph"
- "Tell me which tags are used most"
- When you want to get an overview of the docs/ directory at a glance

## Quick Start

```bash
# Create a new document
npx doc create docs/research "New Document Title" --tags=tag1,tag2 --category=research

# Extract TOC
npx doc toc docs/design-spec.md

# Extract specific section only
npx doc section docs/design-spec.md "API Design"

# Implementation status summary
npx doc summary docs/design-spec.md

# Document indexing (frontmatter-based)
npx doc index

# BM25 document search
npx doc find "onboarding"

# Inter-document knowledge graph
npx doc graph

# Tag aggregation
npx doc tags
```

## Commands

### create - Create New Document

```bash
npx doc create <dir> "<title>" [--tags=t1,t2] [--category=cat] [--author=agent] [--body="content"]
```

Creates a new markdown document with frontmatter in the specified directory.

**Arguments:**
- `dir`: Target directory path (created automatically if it doesn't exist)
- `title`: Document title (converted to filename slug)

**Options:**
- `--tags=t1,t2`: Tag list (comma-separated)
- `--category=cat`: Category (default: `general`)
- `--author=agent`: Author (agent ID, etc.)
- `--body="content"`: Body content

**Filename rules:**
- English: Converted to kebab-case (lowercase, spaces->hyphens)
- Korean: Preserved as-is
- Example: `"Test Document"` -> `test-document.md`
- Example: `"My API Design"` -> `my-api-design.md`

**Output example:**
```
Created: docs/research/test-document.md
```

**Examples:**
```bash
# Basic creation
npx doc create docs/research "Test Document" --tags=test --category=research

# With author and body content
npx doc create docs/research "API Design Doc" --tags=api,design --category=design --author=core_dev --body="## Overview\n\nAPI design document."
```

**Note:** An error occurs if a file already exists at the same path.

### toc - Extract Table of Contents

```bash
npx doc toc <file> [--depth=N]
```

Extracts all headings (#, ##, ###, etc.) from a markdown file and outputs them in tree format.

**Options:**
- `--depth=N`: Maximum heading depth (default: 6)

**Output example:**
```
   L1 # Design Document
   L8   ## Table of Contents
  L20   ## Overview
  L22     ### Infrastructure
  L32     ### Tech Stack
```

### section - Extract Specific Section

```bash
npx doc section <file> <heading>
```

Extracts a specific heading and its sub-content. Useful for viewing only the relevant part without reading the entire document.

**Examples:**
```bash
# Extract only the "API Design" section
npx doc section docs/design-spec.md "API Design"

# Search by ID
npx doc section docs/design-spec.md "api-design"
```

### status - View TOC with Status Markers

```bash
npx doc status <file>
```

Outputs the TOC while displaying the implementation status of each section.

**Recognized status markers:**
- [DONE] / `[x]` / `Implemented` -> Done
- [TODO] / `[ ]` / `Not implemented` -> Todo
- [WARN] / `Partial` -> Partial
- [WIP] / `In progress` -> WIP

### summary - Implementation Status Summary

```bash
npx doc summary <file>
```

Aggregates and summarizes the implementation status across the entire document.

### index - Document Indexing

```bash
npx doc index [dir]
```

Parses and indexes frontmatter from markdown files in the directory.

**Options:**
- `dir`: Target directory (default: `docs/`)

**Indexing criteria:** Must have at least one of `type` or `summary` in frontmatter to be indexed.

**Output example:**
```
Indexed 17 documents from docs/
  CLI-Design (design) [cli, routing, architecture] -- CrewX CLI design document -- routing architecture, built-in tools, subcommand extension
  PRD (prd) [product, requirements] -- Product requirements document
```

### find - BM25 Document Search

```bash
npx doc find <query> [dir]
```

Finds related documents using frontmatter-based BM25 search.

**Options:**
- `query`: Search keyword (required)
- `dir`: Target directory (default: `docs/`)

**Field weights:** `summary: 3`, `tags: 2`, `body: 1`

**Output example:**
```
Found 3 results:
  [4.52] CLI-Design -- CrewX CLI design document
  [2.31] cli-proxy-design -- CLI proxy design
  [1.87] PRD -- Product requirements document
```

### graph - Document Knowledge Graph

```bash
npx doc graph [dir]
```

Automatically analyzes inter-document relationships and generates a knowledge graph.

**Options:**
- `dir`: Target directory (default: `docs/`)

**Edge types (auto-inferred):**
- `shared-tags`: Documents with shared tags (weight: 0.4 + (shared tag count - 1) x 0.1, max 0.8)
- `same-category`: Documents in the same category (weight: 0.2, excludes `general`)
- `same-day`: Documents on the same date

**Output example:**
```
Graph: 17 nodes, 22 edges
Edges:
  CLI-Design <-> cli-proxy-design (shared-tags, w=0.6)
  PRD <-> Design-Doc (same-category, w=0.2)
```

### tags - Tag Aggregation

```bash
npx doc tags [dir]
```

Collects tags from all documents and aggregates them by frequency.

**Options:**
- `dir`: Target directory (default: `docs/`)

**Output example:**
```
Tags (51 unique):
  architecture: 5
  cli: 4
  api: 3
```

### properties - Frontmatter Property Values

```bash
npx doc properties [dir]
```

Collects and displays unique values of frontmatter properties used across documents. Currently aggregates `type` and `category` fields.

**Options:**
- `dir`: Target directory (default: `docs/`)

**Output example:**
```
Frontmatter properties:
  type: document
  category: design, guide, prd, research
```

## Frontmatter Schema

Frontmatter fields recognized by `doc index`. Written as YAML frontmatter at the top of documents.

### Required Conditions

Must have at least one of `type` or `summary` to be indexed.

### Field List

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `type` | `'document' \| 'memory'` | `'document'` | Entry type |
| `category` | `string` | `'general'` | Document classification (design, guide, prd, research, etc.) |
| `tags` | `string[]` | `[]` | Tag list (kebab-case recommended) |
| `summary` | `string` | `''` | One-line summary (displayed in index/find output) |
| `date` | `string` | `''` | Date (YYYY-MM-DD) |

### Frontmatter Example

```yaml
---
type: document
category: design
tags: [cli, routing, architecture]
summary: CrewX CLI design document -- routing architecture, built-in tools, subcommand extension
date: 2026-02-20
---
```

## Document Graph Connections

`doc graph` **automatically infers relationships from frontmatter metadata** without explicit connection fields.

### Conditions for Creating Connections

1. **Shared tags** (`shared-tags`): Two documents sharing 1 or more tags are connected. More shared tags result in higher weight.
2. **Same category** (`same-category`): Documents with the same `category` are connected. (`general` is excluded)
3. **Same date** (`same-day`): Documents with the same `date` are connected.

### How to Strengthen Graph Connections

```yaml
# Related documents are automatically connected when given shared tags
---
tags: [cli, routing]          # CLI-Design
---

---
tags: [cli, proxy]            # cli-proxy-design -> connected via 'cli' tag
---
```

- Using tags **specifically and consistently** creates meaningful connections
- Using the same `category` creates additional connections
- The `general` category is excluded from graph connections

## Recommended Workflows

### 1. Analyzing Large Design Documents

```bash
# 1. First understand the TOC structure
npx doc toc docs/design-spec.md --depth=2

# 2. View details for sections of interest only
npx doc section docs/design-spec.md "Settlement Management"
```

### 2. Tracking Implementation Progress

```bash
# Check status summary
npx doc summary docs/design-spec.md

# Check unimplemented items in detailed TOC
npx doc status docs/design-spec.md
```

### 3. Knowledge Graph Usage

```bash
# 1. Get overview of all documents
npx doc index

# 2. Search for related documents
npx doc find "authentication"

# 3. Visualize inter-document relationships
npx doc graph

# 4. Check tag distribution -- review classification system
npx doc tags

# 5. Property value overview -- verify frontmatter consistency
npx doc properties
```

### 4. Adding Frontmatter When Writing New Documents

```bash
# 1. Check existing categories/tags
npx doc properties
npx doc tags

# 2. Write document with appropriate frontmatter
# 3. Verify indexing
npx doc index
```

## Design Document Recommendations

Use the following format for effective implementation status tracking:

```markdown
## API Design

### GLD001. Guild Info Query [TODO] Not implemented
### GLD002. Guild Quota Query [DONE] Implemented
### GLD003. Guild Settings Change [WIP] In progress
```

Or manage with a table in a separate "Implementation Status" section:

```markdown
# Implementation Status

| ID | Item | Status |
|----|------|--------|
| GLD001 | Guild Info Query | [TODO] Not implemented |
| GLD002 | Guild Quota Query | [DONE] Implemented |
```

### okf — OKF Frontmatter Management

Manage Open Knowledge Format (OKF) frontmatter — generate, validate, and normalize structured metadata for Markdown documents.

```bash
# Create new file with OKF skeleton
npx doc okf init docs/foo.md --title="Foo" --type=Reference --tags=api,guide

# Validate OKF frontmatter (exits non-zero on error)
npx doc okf validate docs/foo.md

# Normalize: fill missing OKF fields in-place (idempotent)
npx doc okf normalize docs/foo.md

# Dry-run: preview normalization without writing
npx doc okf normalize docs/foo.md --dry-run
```

**OKF frontmatter skeleton:**
```yaml
---
type: Reference
title: Foo
description: ""
resource: docs/foo.md
tags: []
timestamp: "2026-06-16T14:30:00.000Z"
crewx:
  highlights: []
---
```

**Options:**

| Option | Applies to | Behavior |
|--------|-----------|----------|
| `--type=<type>` | init, normalize | Default: `Reference` |
| `--title=<title>` | init, normalize | Falls back to first h1, then filename |
| `--description=<text>` | init, normalize | Preserves existing value if omitted |
| `--tags=a,b` | init, normalize | Preserves existing tags if omitted |
| `--dry-run` | normalize | Print result without writing to file |

**Rules:**
- `type` is required; `validate` errors if missing
- `timestamp` is set on first normalize only; subsequent runs preserve it
- Unknown frontmatter keys and `crewx.*` subkeys are always preserved
- Running `normalize` twice produces no diff (idempotent)

## Dependencies

- `@crewx/knowledge-core`: Frontmatter parsing, BM25 search, graph builder
- `js-yaml`: YAML parse/serialize for OKF frontmatter