# Output Specification

All output goes into the `.deepwiki/` directory at the project root.

## Directory Structure

```
.deepwiki/
├── README.md                  # Index page: project title, description, table of contents
├── _outline.md                # Wiki structure outline (intermediate artifact for review)
├── _sidebar.md                # Navigation sidebar with links to all pages
├── pages/                     # Wiki pages (generate-wiki mode)
│   ├── 01-overview.md
│   ├── 02-architecture.md
│   ├── 03-core-features.md
│   └── ...
├── analysis/                  # Architecture reports (analyze mode)
│   ├── architecture.md
│   └── dependencies.md
└── research/                  # Deep research reports (deep-research mode)
    └── {topic-slug}.md
```

## Page Naming Convention

Wiki pages: `{NN}-{kebab-case-title}.md` where NN is a zero-padded two-digit order number.

Examples: `01-overview.md`, `02-system-architecture.md`, `03-authentication-flow.md`

Analysis reports: use descriptive kebab-case names without numbering.

Research reports: use the research topic as slug, e.g., `websocket-handling.md`, `caching-strategy.md`.

## Required Page Elements

Every wiki page must include these elements in order:

### 1. Source Files Block (first thing on the page)

```markdown
<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- `src/auth/login.ts`
- `src/auth/session.ts`
- `src/middleware/auth.ts`
- `src/models/user.ts`
- `src/routes/auth.ts`

</details>
```

Minimum 5 source files. If fewer are relevant, broaden the search.

### 2. H1 Title

```markdown
# Authentication System
```

### 3. Introduction

1-2 paragraphs explaining purpose, scope, and high-level overview.

### 4. Detailed Sections (H2/H3)

Break the topic into logical sections. Each section should:
- Explain architecture, components, data flow, or logic
- Identify key functions, classes, API endpoints
- Include source citations in the format: `Sources: [filename.ext:start_line-end_line]()`

### 5. Mermaid Diagrams

At least one diagram per wiki page. Use Mermaid fenced blocks:

````markdown
```mermaid
graph TD
    A[Request] --> B[Router]
    B --> C[Controller]
    C --> D[Service]
```
````

### 6. Tables (where applicable)

For structured data like API endpoints, config options, or data model fields.

### 7. Summary (optional)

Brief closing paragraph for longer pages.

## README.md Format

The index page follows this structure:

```markdown
# {Project Name} Wiki

{1-2 paragraph project description}

## Table of Contents

### Overview
- [Project Overview](pages/01-overview.md)

### Architecture
- [System Architecture](pages/02-architecture.md)
- [Data Flow](pages/03-data-flow.md)

### Core Features
- [Authentication](pages/04-authentication.md)
- [API Endpoints](pages/05-api-endpoints.md)

...
```

## _sidebar.md Format

```markdown
- **Overview**
  - [Project Overview](pages/01-overview.md)
- **Architecture**
  - [System Architecture](pages/02-architecture.md)
  - [Data Flow](pages/03-data-flow.md)
...
```