nium-wiki（尼姆维基）

Nium Wiki Generator

Produce professional-grade, domain-organized project Wiki under the .nium-wiki/ directory.

Core Principle: Generated documentation must be detailed, structured, diagrammed, and cross-linked, meeting enterprise-level technical documentation standards.

Quality Gate for Generated Documentation

MANDATORY: Every piece of generated documentation MUST satisfy the following criteria:

Depth of Coverage

• Provide full context for every topic — never leave bare lists or placeholder outlines
• Write specific, explanatory descriptions that address the WHY and HOW behind each concept
• Supply runnable code examples paired with their expected output (🔴 secrets must be sanitized - see "Secret & Credential Sanitization")
• Call out edge cases, caveats, and common mistakes explicitly

Substantive content: A section has real content if it contains ≥ 3 non-empty, non-heading lines, OR at least one code block, diagram, or table. A heading followed by a single sentence or a bare list does not count.

Structural Conventions

• Organize content with hierarchical headings (H2 → H3 → H4) to form a clear information hierarchy
• Summarize key concepts in tables for scanability
• Illustrate processes and flows using Mermaid diagrams
• Interconnect documents via cross-links

🔴 MANDATORY: Link Path Format

ALL source file links MUST use project-root-relative POSIX paths starting with /. NEVER use file:// URIs, absolute filesystem paths, or OS-specific paths. The IDE/editor may provide file paths as file:///Users/.../project/src/foo.ts — you MUST strip the prefix and convert to /src/foo.ts.

Conversion rule: Given any absolute path, remove everything up to and including the project root directory name, then prepend /. Example: file:///home/user/my-project/src/core/foo.ts → /src/core/foo.ts.

🔴 MANDATORY: Secret & Credential Sanitization

CRITICAL: NEVER include actual secrets, credentials, API keys, or sensitive information in generated documentation.

MANDATORY sanitization rules:

Sanitization pattern library:

• API keys: sk_live_XXXXXXXX, pk_test_XXXXXXXX, api_key_XXXXXXXX
• Passwords: ***REDACTED***, <your-password-here>
• Tokens: <your-access-token>, <auth-token-here>
• Generic: XXXXXXXX, <secret-value>, <sensitive-data>

Exception: Mermaid diagrams, source file path links, and markdown structure MUST still be preserved unchanged (except for secret removal within code blocks).

Diagram Requirements (at least 2-3 per document)

Diagram diversity: Count ≥ 2 distinct diagram *types* toward the minimum. Three identical flowcharts do not satisfy the requirement — use flowchart LR, sequenceDiagram, stateDiagram-v2, erDiagram as appropriate for the module. Note: mindmap is optional and does not count toward the ≥ 2 distinct types requirement. It may supplement but never replace the required diagram types above.

Layout rules: Choose direction by content — TB for hierarchies, LR for flows/dependencies. Use subgraph to group related nodes when count > 6. Apply style color coding to highlight key nodes.

File/directory structure MUST use plain-text tree format (├── └──), NEVER use Mermaid diagrams (including mindmap). Mermaid mindmap is only for showing abstract conceptual relationships between modules, never for file paths or directory trees.

🔴 Mermaid Syntax Safety Rules (MANDATORY — Read Before Every Diagram)

⚠️ HARD REQUIREMENT: Before generating ANY Mermaid diagram, you MUST read refs/mermaid-syntax.md in full. Generating without reading this file is a hard requirement violation.

✅ Hard Rules — parser errors (must fix). ⚠️ Suggestions — best practices.

Complexity grouping (when nodes > 6):

Example — Grouped vs waterfall:

%% WRONG — narrow waterfall
flowchart TD
    A --> B --> C --> D --> E --> F --> G --> H
%% CORRECT — grouped by phase
flowchart TD
    subgraph Phase1[Phase 1]
        A --> B
    end
    subgraph Phase2[Phase 2]
        C --> D --> E
    end
    Phase1 --> Phase2

🔴 MANDATORY: Source File Back-References

Each section MUST end with links back to the originating source files (see "Link Path Format" above for path rules):

**Source references**
- [cli.ts](/src/cli.ts#L1-L50)
- [index.ts](/src/index.ts#L20-L80)

**Diagram data sources**
- [core/analyzeProject.ts](/src/core/analyzeProject.ts#L1-L100)

🔴 MANDATORY: Source Attribution for Code Block Excerpts

Any code block that is a direct excerpt from a source file (function body, class definition, type definition, import/export statement) MUST carry a source attribution line immediately above the code block. This applies to .ts, .js, .py, .go, .rs, .java, and other language source files.

⚠️ CRITICAL: The attribution line MUST be placed outside the code fence (above the opening ``), using plain text format **without any language-specific comment syntax** (no //, #, /* */`, etc.). The attribution line is plain text, and the Markdown link inside it will be rendered as a clickable link.

✅ CORRECT format:

[Source: cli.ts](/src/cli.ts#L42-L67)

const result = cli.parse(process.argv);

❌ WRONG formats (links will NOT be clickable):

// Wrong: Inside the code block as a comment — the link won't work

// Source: cli.ts const result = cli.parse(process.argv);

// Wrong: Uses comment syntax (//, #, etc.) — renders as code, not text // Source: cli.ts

const result = cli.parse(process.argv);

Attribution is **not required** for:

| Content type | Example | Why no attribution |
|---|---|---|
| Usage / call-site examples | `cli.run(['--help'])` | Calling code, not source excerpt |
| Teaching / invented examples | Any code that does not exist in the source | Not in any source file |
| Mermaid / shell / CLI commands | `flowchart TD\n  A --> B` | Not source code |
| Output / runtime results | `// Output: { id: 1 }` | Results, not source |

### 🔴 MANDATORY: Complexity-Scaled Quality Targets

**Quality standards scale with module complexity — not fixed numbers.**

| Module Role | Doc Depth | Code Examples | Diagrams |
|-------------|-----------|---------------|----------|
| core | Comprehensive (use `module.md`) | 5+ | 2+ |
| util / config | Concise (use `module-simple.md`) | 1-2 | 1 |
| test / example | Minimal (use `module-simple.md`) | 1 | optional |

**General rules**: larger source files → longer docs; more exports → more examples; more dependents → more diagrams.

#### Context Adaptation

| Project Type | Focus Areas |
|-------------|-------------|
| **frontend** | Component Props, state management, UI interaction |
| **backend** | API endpoints, data models, middleware |
| **fullstack** | Frontend-backend interaction, data flow, deployment |
| **library** | API docs, type definitions, compatibility |
| **cli** | Command arguments, config files, usage |

| Language | Example Style |
|----------|--------------|
| **TypeScript** | Type annotations, generics, interfaces |
| **Python** | Docstrings, type hints, decorators |
| **Go** | Error handling, concurrency, interfaces |
| **Rust** | Ownership, lifetimes, error handling |

### Module Document Sections

Use `module.md` (11 sections) for core modules, `module-simple.md` (6 sections) for util/config/helper modules.

**Full template (`module.md`) — for core modules:**

| # | Section | Content |
|---|---------|---------|
| 1 | **Overview** | Intro + value proposition + architecture role (2-3 paragraphs) |
| 2 | **Architecture Position** | Mermaid diagram highlighting module position |
| 3 | **Feature Table** | Features with related APIs |
| 4 | **File Structure** | File tree + responsibilities |
| 5 | **Core Workflow** | Mermaid flowchart |
| 6 | **State Diagram** | ⚡ OPTIONAL — only for stateful modules |
| 7 | **API Summary** | Overview table + link to api.md (no detailed signatures) |
| 8 | **Usage Examples** | 1-3 examples (first = Quick Start) |
| 9 | **Best Practices** | Recommended / avoid patterns |
| 10 | **Design Decisions** | ⚡ OPTIONAL — only for core modules with significant choices |
| 11 | **Dependencies & Related Docs** | Dependency diagram + cross-links |

**Lightweight template (`module-simple.md`) — for util/config/helper/test modules:**

| # | Section | Content |
|---|---------|---------|
| 1 | **Overview** | 1 paragraph |
| 2 | **API Summary** | Overview table + link to api.md |
| 3 | **Usage Examples** | 1-2 examples |
| 4 | **File Structure** | File tree |
| 5 | **Best Practices** | ⚡ OPTIONAL |
| 6 | **Related Docs** | Cross-links |

**Template selection**: Before generating each module's documentation, run `node scripts/index.js analyze-module <module-path>` (or `--batch` for all modules) to get structured signals. Use `docScope` as the primary signal:

| `docScope` | Use this template | Lines target | Diagrams |
|---|---|---|---|
| `core` | `module.md` (11-section) | 400+ | 2+ distinct types required |
| `overview` | `overview.md` (5-section) | 80-150 | optional |
| `_index` | `_index.md` only | 30-50 | none |

The `templateRecommendation` and `roleRecommendation` are based on quantifiable metrics but are **overrideable**: your semantic understanding of the module's business role takes precedence.

> Code provides signals. You make the final decision.

### 🔴 Code Examples

Every code example must:

1. **Complete and runnable**: Include import, initialization, invocation, result handling
2. **Cover exported interfaces**: At least 1 example per major exported API
3. **Include comments**: Explain key steps and design intent
4. **Match project language**: Follow language best practices
5. **Tiered examples for core APIs** (minimum 5 examples per core doc): Three levels — basic usage, advanced usage, and error handling — for each major exported function
6. **Sanitized secrets**: NO actual credentials — use placeholders (see "Secret & Credential Sanitization" above)

### Cross-Document Linking
- Every document MUST contain a **"Related Documents"** section at the end
- Module docs should link outward to: architecture position, API reference, dependency graph
- API docs should link back to: parent module, usage examples, type definitions

**Path format rules for "Related Docs" table (Section 6 / Section 11 in templates)**:
- **Wiki page links**: Use **relative paths** from the current doc's location. E.g., from `modules/badge.md`: `[version]({{ ../api/version.md }})` → resolved to `../api/version.md`
- **Source file references**: Do NOT put source files (`.ts`, `.js`, etc.) in the Related Docs table. Source files belong in **section footers** with absolute paths: `[version.ts](/src/utils/version.ts#L1)`
- **Wrong**: `[version.ts](/wiki/utils/version.md)` — mixes wiki path prefix with source file name
- **Wrong**: `[version.ts](../modules/version.md)` — links to a wiki page, not the source file
- **Correct (source)**: `[version.ts](/src/utils/version.ts#L1)`
- **Correct (wiki page)**: `[API reference](../api/version.md)`

---

## Mode Overrides

> **Applies when**: Running in incremental mode, triggered by the `incremental` pipeline.
> **Priority**: These overrides take precedence over the Quality Gate rules above.
> See [Surgical Edit: Modifying Existing Docs](#surgical-edit-modifying-existing-docs) for the full execution guide.

| Quality Gate Rule | Incremental Mode Behavior |
|---|---|
| core doc ≥ 5 code examples | Add **0–1 example** only when a new API is introduced by the changed source |
| ≥ 2 distinct diagram types | **Do NOT regenerate any diagram** — preserve existing diagrams unchanged |
| Full 11-section `module.md` template | **Patch only the affected section(s)** based on which source files are listed in `triggeredBy` |
| `flowchart LR` for type/module relationships | **Skip** unless the class was modified **and** its source was read |
| API summary must cover all exports | **Only cover exports that changed** |
| core doc ≥ 400 lines | **No minimum** — a 50-line targeted patch is preferable to a 400-line rewrite |
| ≥ 3 source reference links | **Only links related to changed source files** |

---

## Input Classification

Before invoking any CLI commands, parse the user input to determine the execution path:

| InputType | Trigger Phrases | Execution Path |
|-----------|----------------|----------------|
| `FULL` | "generate wiki", "create docs", "rebuild wiki" | Full pipeline — all modules |
| `MODULE_TARGETED` | "generate wiki for X", "update X docs", "upgrade X docs" | Module-level pipeline |
| `MAINTENANCE` | "upgrade wiki", "refresh wiki", "audit docs" | Maintenance pipeline |
| `EXPLORE` | "analyze module X", "explore X" | Read-only analysis, no file writes |

---

## Module-Targeted Generation

> **Applies when**: InputType = `MODULE_TARGETED` (user specifies a specific module).

### Step 0 — Path Resolution

Extract the module path from user input:

"generate wiki for src/core/analyzeProject" → src/core/analyzeProject "update modules/auth docs" → modules/auth "explore utils/fileWalker" → src/utils/fileWalker

Normalize all paths relative to the project root.

### Step 1 — Pre-flight Check

node scripts/index.js analyze-module <path> [--json]

Read the returned `docScope` and `roleRecommendation`:

docScope: core → module.md (11-section, 400+ lines, 2+ diagrams) docScope: overview → overview.md (5-section, 80-150 lines) docScope: _index → _index.md only

Determine document state:

if wiki file already exists for this module: → EXPLORE_THEN_PATCH (surgical edit, preserve existing content) else: → EXPLORE_THEN_GENERATE (first-time generation)

### Step 2 — Code Exploration (Read-Only, No File Writes)

Read the actual source code — do not rely on file names or structure alone:

read_file: all *.ts/*.js source files in the module directory read_file: index.ts / index.js (main exports) read_file: types.ts / types.d.ts (type definitions, if present)

Analyze:

- Function signatures: purpose, parameters, return values, side effects
- Class hierarchies and inheritance
- Data flow paths and state mutations
- Error handling strategies
- Design patterns in use
- 🔴 **Secrets detection**: identify hard-coded credentials, API keys, tokens

### Step 3 — Exploration Report (Output to User, No File Writes)

Display a structured report and **await user confirmation before proceeding**:

Module Exploration Report: <module-name>

Role: <roleRecommendation> Template: <module.md / module-simple.md> State: <EXPLORE_THEN_GENERATE / EXPLORE_THEN_PATCH>

Key Findings

• Exports: N functions, M types
• Dependents: N modules depend on this

Recommended Sections

Proceed with generation? [yes / no / customize]

**This step is mandatory.** A confirmation gate prevents generating content before understanding the code. Do not skip to Step 4 without presenting this report.

### Step 4 — User Response

| Response | Action |
| --- | --- |
| `yes` | Proceed to Step 5 using the recommended template |
| `no` | Exit — write nothing, report nothing |
| `customize` | Apply user-specified section additions or removals, then proceed |

### Step 5 — Execution

**If `incremental` returns empty** (no code changes detected, but user explicitly specified a module):

Skip incremental dependency computation Use user-specified module path as the sole target Do NOT treat as surgical patch (no old doc to compare against) Resume from Step 1 Pre-flight Check, then proceed to generation

**If `incremental` returns affected docs**: use the pipeline's `triggeredBy` + `updateStrength` to decide full vs. surgical.

---

## Full Decision Tree

User Input │ ├─ "generate wiki" (no module specified) │ ├─ .nium-wiki does not exist → init → FULL pipeline → Section 1–11 │ └─ .nium-wiki exists → FULL pipeline → Section 1–11 │ ├─ "generate wiki for <module>" │ ├─ .nium-wiki does not exist → init → MODULE_TARGETED │ └─ .nium-wiki exists │ ├─ incremental has changes → affected docs from pipeline │ └─ incremental is empty → use user-specified module as target │ → Exploration Report → User confirms → Generate │ ├─ "upgrade <module> docs" │ └─ MODULE_TARGETED + force full regeneration │ ├─ "analyze module X" │ └─ Run node scripts/index.js analyze-module <path> --json — JSON signals only, no wiki files written │ └─ "refresh / upgrade wiki" (no module) └─ MAINTENANCE → audit → regenerate failing docs

---

## Workflow

### 1. CLI Commands Quick Reference

> **Execution context**: All `node scripts/index.js` commands below are run from the **skill root directory** (the directory containing `SKILL.md`), NOT the user's project root. The working directory when executing a skill is always the skill root — this is the industry-standard convention across all Coding Agents (Claude Code, Trae, Cursor, CodeGPT, 通义灵码, etc.).
>
> Scripts inside `skills/` are portable: the same skill can be installed globally (`<AGENT_HOME>/skills/nium-wiki/`) or project-locally (`./skills/nium-wiki/`) — the relative path `scripts/index.js` always resolves correctly.

node scripts/index.js init [path] --lang <code> # Initialize .nium-wiki directory (lang: zh/en/ja/ko/fr/de); run from project root node scripts/index.js analyze [path] # Analyze project structure node scripts/index.js analyze-module <path> [--batch|--json] # Analyze module: classify role, recommend template node scripts/index.js incremental [path] # Run incremental pipeline: diff → deps → doc-index → affected docs; run from project root node scripts/index.js diff-index [path] # Detect file changes (--no-update to skip hash write); run from project root node scripts/index.js build-index [path] # Build source ↔ doc mapping index; run from project root node scripts/index.js build-deps [path] # Build import/require dependency graph; run from project root node scripts/index.js audit-docs [.nium-wiki] [--verbose|--json|--mermaid-strict|--role <role>] # Check doc quality node scripts/index.js serve [wiki-path] # Start docsify server

For detailed usage, see `node scripts/index.js --help`

> **⚠️ IMPORTANT**: All commands that take `[path]` (incremental, diff-index, build-index, build-deps, etc.) **must be run from the project root directory**, or pass the absolute/relative path to the project root. The `audit-docs` and `serve` commands take the `.nium-wiki` directory path (default: `.nium-wiki`).

### 2. Language Detection (MANDATORY)

> **⚠️ CRITICAL: This step must be completed BEFORE any other operation.**

Before running any CLI commands or generating any documentation:

1. Check if `.nium-wiki/config.json` exists
2. **If exists**: Read the `language` field — this is the **primary documentation language** and the **source of truth**
3. **If not exists**: You will set it when running `init --lang <code>` (determine from project's natural language + user conversation language)

> **Rule**: The `language` field in `config.json` is the **only authoritative source** for documentation language. Do NOT infer language from source code comments, README, file names, or conversation context.

#### 2.1 Language Conflict Resolution

> **🔴 CRITICAL: Never modify `config.json` directly via file write or text replacement.** Use the following procedures instead:

| Scenario | Action |
| --- | --- |
| Config exists, user wants to add a secondary language (e.g. config=`en`, user wants to also generate `zh`) | Run `node scripts/index.js init [path] --lang zh` — appends `zh` as a secondary language to config |
| User wants to change the primary language (e.g. config=`en`, user wants `zh` as primary) | Run `node scripts/index.js init [path] --lang zh --force` — overwrites primary language to `zh` |
| User wants to generate docs in a language already in config | No config change needed — run `generate-toc --lang <code>` directly |

**Why**: Direct file edits to `config.json` bypass the CLI's validation and can corrupt the JSON structure. Always go through the CLI.

### 4. Language Configuration

Read `.nium-wiki/config.json` and extract the `language` setting. Format is slash-separated: the first language is the **primary language** (e.g. `zh`, `en`, `zh/en`).

- Generate **all primary documentation** in the primary language to `.nium-wiki/wiki/`.
- If secondary languages are configured (e.g. `zh/en` means primary=zh, secondary=en), after primary docs are written, translate all wiki documents into `wiki_{lang}/` directories (e.g. `.nium-wiki/wiki_en/`). See **Step 12** for details.

> **Convention**: `wiki/` = primary language, `wiki_{lang}/` = secondary language. The translated directory must mirror the exact same structure and filenames as `wiki/`.

> **🔴 IMPORTANT: Single-language output only.** Templates contain bilingual headings (e.g. `## Architecture Preview / 架构预览`) for reference purposes only. When generating documentation, output **only** the primary language. Do NOT mix languages or copy the `English / 中文` format into the output.
>
> - If `language` is `en`: headings should be `## Architecture Preview`, NOT `## Architecture Preview / 架构预览`
> - If `language` is `zh`: headings should be `## 架构预览`, NOT `## Architecture Preview / 架构预览`

### 5. Project Analysis (Deep)

Run `node scripts/index.js analyze.` or analyze manually:

1. **Identify tech stack**: Check dependency manifests (e.g. package.json, requirements.txt, go.mod, Cargo.toml, pom.xml, etc.)
2. **Find entry points**: Locate main source files (e.g. src/index.ts, main.py, main.go, main.rs, src/main/java/App.java, etc.)
3. **Identify modules**: Scan src/ directory structure
4. **Find existing docs**: README.md, CHANGELOG.md, etc.

Save structure to `cache/structure.json`.

### 6. Deep Code Analysis (CRITICAL)

**IMPORTANT**: For every module, read the actual source code — do not rely on file names or directory structure alone:

1. **Read source files**: Open key files with read_file tool
2. **Parse semantics**: Determine what the code does, not merely how it is organized
3. **Capture details**:
  - Function signatures: purpose, parameters, return values, side effects
  - Class hierarchies and inheritance chains
  - Data flow paths and state mutations
  - Error handling strategies
  - Design patterns in use
  - 🔴 **Secrets detection**: Identify hard-coded credentials, API keys, tokens, and sensitive data that need sanitization
4. **Map relationships**: Module dependencies, call graphs, data flow
5. **Flag complexity hotspots**: Functions with deep nesting (> 4 levels), high branching (> 10 conditions), or excessive length (> 100 LOC). Document these in module docs with logic explanations and refactoring suggestions.

### 7. Change Detection

Use the **automated incremental pipeline** to detect changes and compute the precise list of affected docs in one step:

node scripts/index.js incremental . [--no-commit] [-v] # run from project root

This runs the full pipeline: `diff-index` → `build-deps` → `build-index` → transitive-impact → doc-dep analysis. It outputs:

- Which source files changed (+added, ~modified, -deleted)
- Which wiki docs need regeneration (with reason: source_changed, dep_changed, doc_dep_changed, inferred)
- Which docs will be deleted
- Which docs are preserved (unchanged)

**If wiki doesn't exist yet**: the pipeline automatically falls back to full-generation mode.

> **IMPORTANT**: Always run `incremental` before generating, not `diff-index` alone. `diff-index` only detects source changes — it does NOT map them to wiki docs. After `incremental` completes, always check i18n sync status (see **Step 12**) before declaring the update done.

### 8. Target Docs (resolved by the pipeline above)

The `incremental` command in Step 5 already resolves this. Each affected doc includes:

- `docPath`: relative wiki path (e.g. `modules/core/source-index.md`)
- `reason`: why it needs updating
- `triggeredBy`: source files that triggered the update

Manual fallback (if pipeline not available): Read `.nium-wiki/cache/doc-index.json` → `sourceToDoc` field. If a changed source file has no entry, infer by naming convention: `src/fooBar.ts` → `modules/foo-bar.md`, and nested paths: `src/core/analyzeProject.ts` → `modules/core/analyze-project.md`.

### 9. Content Generation

> **🔴 MANDATORY: Language from config.json**
>
> Before generating ANY documentation content, you MUST read `.nium-wiki/config.json` and extract the `language` field. Use this language for **ALL** documentation in `wiki/` — do NOT infer language from source code comments, README, or user conversation. See **Step 4** for supported language codes and output conventions.
>
> **Wrong**: "Source code is in English, so I'll generate English docs" **Correct**: "config.json says `language: "zh"`, so I generate Chinese docs"

Generate content adhering to the **quality gate** defined above:

#### 9.1 Template Selection Rules

Not all templates are needed for every project. Apply these rules:

| Template | When to Generate |
| --- | --- |
| `index.md` | always |
| `architecture.md` | always |
| `module.md` / `module-simple.md` | always (choose by module role) |
| `getting-started.md` | project has install steps OR is a library/framework |
| `api.md` | project exports programmatic APIs (functions/classes/types) |
| `doc-map.md` | module count >= 5 |

#### 9.2 Homepage (`index.md`)

**Template**: Read `templates/index.md` for full structure.

#### 9.3 Architecture Doc (`architecture.md`)

**Template**: Read `templates/architecture.md` for full structure.

#### 9.4 Module Docs (`modules/<name>.md`)

**Templates**: Read `templates/module.md` (core) or `templates/module-simple.md` (util/config/helper/test).

- **Key rule**: Detailed API signatures and type definitions belong exclusively in api.md. Module docs only contain an API overview table with a link.

#### 9.5 API Docs (`api/<name>.md`)

**Template**: Read `templates/api.md` for full structure.

- Single source of truth for all API signatures and type definitions.
- Mark `@deprecated` APIs with migration guidance (what to use instead).
- Include parameter constraints where applicable (e.g. "must not be empty", "range 0-100").

#### 9.6 Getting Started (`getting-started.md`)

**Template**: Read `templates/getting-started.md` for full structure.

#### 9.7 Doc Map (`doc-map.md`)

**Template**: Read `templates/doc-map.md` for full structure.

#### 9.8 Source Links

Attach navigable source links next to documented symbols:

functionName 📄

### 11. Save

- Write wiki files to `.nium-wiki/wiki/`
- Sanitize link paths and build indexes **after** wiki files are written:

node scripts/index.js sanitize-links . # run from project root node scripts/index.js build-index . # run from project root node scripts/index.js build-deps . # run from project root node scripts/index.js diff-index . # run from project root (--no-update to skip hash write)

> `sanitize-links` scans all wiki `.md` files and converts any `file://` absolute paths to project-root-relative paths. **MUST** run before `build-index`. `build-index` scans source path links in wiki files to build `cache/doc-index.json` (source ↔ doc mapping for incremental updates). `build-deps` parses import/require statements to build `cache/dep-graph.json` (dependency graph for impact analysis). `diff-index` (without `--no-update`) is called last so the hash snapshot reflects the final state.

- Refresh `meta.json` timestamp

### 12. Multi-language Translation

> **Applies to both full generation and incremental updates.** Every time `wiki/` is modified, secondary language files in `wiki_{lang}/` that correspond to changed docs must be kept in sync — do not leave them stale.
>
> **Skip this step if `language` contains only one language.**

#### 12.1 Build Translation Task List

Run `node scripts/index.js i18n status.nium-wiki` to get the sync report. Extract every file marked `Missing` or `Outdated` into an explicit checklist (e.g. `❌ [Missing] index.md`, `⚠️ [Outdated] architecture.md`).

**You MUST translate every file in this list — no exceptions, no skipping.**

> **Incremental mode**: If this is a partial update (incremental pipeline detected changes), only translate files that are `Outdated` or `Missing` — do NOT re-translate all `Synced` files. **Full generation mode**: Translate all `Missing` files (`Outdated` may not exist yet since memory has not been populated).**

#### 12.2 Translate Files One by One

**🔴 MANDATORY: Process EVERY file in the checklist sequentially.**

For each file:

1. Read the primary wiki file from `wiki/`
2. Translate content to the target language
3. Write to `wiki_{lang}/` with **identical path and filename** (e.g. `wiki/core/auth.md` → `wiki_en/core/auth.md`)
4. **Preserve unchanged**: all Mermaid diagrams, code blocks (EXCEPT sanitize any secrets/credentials if found), source path links, and markdown structure
  - **Secret sanitization exception**: If code blocks contain secrets/credentials, sanitize them using the rules from the "Secret & Credential Sanitization" section

After each file, report progress: `✅ [3/17] wiki_en/core/_index.md`

> **Batching rule**: If the file count exceeds 10, translate in batches of 5. After each batch, report progress and continue immediately — do NOT stop or ask the user unless you hit a context limit. If you must stop, clearly list the remaining untranslated files so the user can say "continue" to resume.

#### 12.3 Finalize

After ALL files are translated:

node scripts/index.js i18n sync-memory .nium-wiki

Run `node scripts/index.js i18n status.nium-wiki` again to verify all files show as `Synced`. If any files are still `Missing` or `Outdated`, go back and translate them.

**Delete rule**: When deleting any file from `wiki/` (e.g. because the source file was deleted), you **MUST** also delete the corresponding file from ALL `wiki_{lang}/` directories.

---

## Surgical Edit: Modifying Existing Docs

> **Applies when**: Updating 1-3 existing wiki documents (incremental pipeline result), not full generation.
>
> When an existing doc already exists, your goal is to **patch the minimum surface area**, not regenerate the full file. Every line you leave untouched is a line that does not need to be reviewed, diffed, or reverted.

### 🔴 Quality Gate Disabled During Incremental Updates

> **⚠️ CRITICAL**: When running in incremental mode (triggered by `incremental` pipeline), the **global Quality Gate rules above do NOT apply** to existing docs being surgically patched. Applying those rules blindly is the primary cause of oversized diffs and unnecessary rewrites.

**See [Mode Overrides](#mode-overrides) for the full table of Quality Gate rule overrides in incremental mode.**

**`updateStrength` from the `incremental` pipeline controls patch depth:**

| `updateStrength` | Meaning | Action |
| --- | --- | --- |
| `full` | Function signature changed OR module role changed | Full regeneration of this doc |
| `incremental` | Transitive/dep/doc-dep propagation | **Surgical patch only** — no quality gate, no template |

> **Rule**: If the pipeline says `updateStrength: incremental` for a doc, treat it as a targeted patch — update only the section that mentions the triggering source, leave everything else untouched.

### Mandatory Steps (Execute in Order)

**Never start from the template when updating an existing doc.**

**Step 1 — Read the baseline**

- read_file: the existing wiki doc (read-only, this is what you are preserving)
- read_file: all source files that triggered the update (from `incremental` output)

**Step 2 — Evaluate match degree** Cross-read the existing doc against the changed source files. Answer:

- Which sections of the existing doc directly correspond to the changed code?
- Which sections are completely unaffected?
- What is your overall match degree?

**Step 3 — Decide strategy by match degree**

| Match degree | Signals | Action |
| --- | --- | --- |
| **≥ 80%** | Internal change only (comment, variable rename, refactor); function signatures unchanged; core topics not touched | **Default: PRESERVE** — update version footer only, do not touch the body. If no version footer exists, create one (a single line). |
| **40–80%** | One function's behavior changed; new export added; file structure changed | Patch only the affected sections — leave everything else untouched |
| **< 40%** | Function renamed or signature changed; module role changed; multiple sections invalidated | Full regeneration of this document |

**Step 4 — Write the patched doc**

- Output MUST be a minimal diff from the original — significantly smaller than a full regeneration
- Do not use the module template as the starting point for an existing doc

**Step 5 — Self-verify** Before finalizing, mentally check: does the new file differ from the original in anything beyond the source-change-affected sections, newly-added sections, and now-incorrect sections? If yes, you are rewriting too much — restore the preserved sections.

### Principle 1 — Preservation Priority

Unless the source has actually changed, the following MUST be preserved exactly as-is:

| Content type | When to update |
| --- | --- |
| Accurate description paragraphs | Never (unless source logic changed) |
| Correct code examples | Never (unless the code itself changed) |
| Mermaid diagrams | Never (unless the underlying flow/calls changed) |
| File structure tree | Only when files were added/removed |
| API summary table | Only when function signatures changed |
| Best practices section | Never (unless the module logic changed) |
| Cross-links | Only when linked docs were moved/renamed |

### Principle 2 — Change Scope Isolation

Before editing, write down the minimum scope:

Change type → Minimum doc impact

1. Function logic changed (signature unchanged)

→ Update only that function's description paragraph → Code example only if the behavior changed → Do NOT rewrite other functions' descriptions

1. New exported function added

→ Append one row to the API summary table → Add one usage example (optional) → Do NOT rewrite existing examples

1. File added/removed

→ Update the File Structure tree → Do NOT regenerate Architecture Position diagram (unless the module's position actually changed)

1. Bug fix (doc described old/wrong behavior)

→ Fix only the affected paragraph → Do NOT restructure the entire section

#### Decision Checklist — What Changed vs What to Update

Before editing, run through this checklist to determine the minimum scope:

- **Function signature changed?** (params, return type, or name) → Update API summary table row + add new signature to examples
- **Function behavior changed in a user-visible way?** (callers must change how they use it) → Update that function's description paragraph + examples
  - Behavior change only affects internal call chains, not external callers? → Update version footer only — do NOT rewrite descriptions or examples
- **Only internal implementation changed?** (helper functions, variable names, refactor) → Update version footer only — do NOT rewrite descriptions or examples

### Principle 3 — Match Degree Evaluation Guide

When evaluating match degree, use these concrete signals:

**High match (≥ 80%) — signals:**

- Changed code is internal implementation detail (comment, variable rename, refactor)
- Doc describes concepts/topics that the change does not touch
- Function signature unchanged; only body logic shifted

**Medium match (40–80%) — signals:**

- Changed code affects one function's behavior → that function's section needs update
- New export added → append to API table, leave other sections intact
- File added/removed → update file structure tree only

**Low match (< 40%) — signals:**

- Function renamed or signature changed → rewrite that function's section
- Module role changed (e.g. core → utility) → full regeneration needed
- Multiple sections invalidated → regenerate the whole doc

### Principle 4 — When in Doubt, Don't Touch

A common failure mode is rewriting a correct paragraph "for better wording" — this creates a large diff with no factual improvement.

Rule:

> **If the existing description is accurate and not outdated, preserve it exactly.** "Accurate" means: correctly describes what the code does. "Not outdated" means: the code has not changed in a way that contradicts the description.
>
> Do not rewrite for stylistic preference, different phrasing, or "cleaner" expression.

If the description is merely "not ideal" but still correct, leave it alone. A smaller diff is always better than a prettier paragraph.

> **🔴 PRESERVE is the default for ≥ 80% match.** The burden of proof is on rewriting, not on preserving. You MUST actively justify any deviation. A 1-line footer update is always preferable to a full rewrite.

### Anti-Patterns (What Not to Do)

| Anti-pattern | Why it's wrong |
| --- | --- |
| Rewrite doc because "source file changed" without asking: what exactly changed? | Large diff, zero factual improvement |
| Full regeneration when function signature is unchanged | Internal implementation change ≠ doc invalidation |
| Regenerate full file from template | Creates massive diff for no reason |
| Rewrite all code examples | Even correct examples get rephrased |
| Reorder sections | Changes the diff noise, no factual benefit |
| Regenerate Mermaid diagrams unnecessarily | Diagram was fine before |
| "Improve" existing descriptions | Accurate = leave alone |
| Rephrase file structure tree | Only update when structure changed |

### HARDCODEd RULES — Violation is a Bug

- **You MUST read the existing doc before writing anything to it**
- **You MUST NOT regenerate a Mermaid diagram if its underlying source has not changed**
- **You MUST NOT rewrite a paragraph that remains accurate**
- **You MUST NOT rewrite a code example whose code has not changed**
- **You MUST NOT use the module template as the starting point for an existing doc**

---

## Output Structure

### 🔴 MANDATORY: Domain-Based Directory Hierarchy (No Flat Layout!)

**Organize by business domain, not flat modules/ directory.**

> **Directory naming rule**: All wiki directory names MUST use **lowercase + hyphens** (kebab-case), e.g. `core/`, `language-handlers/`, `utils/`. Never use PascalCase or camelCase.

.nium-wiki/ ├── config.json ├── meta.json ├── cache/ ├── wiki/ # Primary language docs │ ├── index.md # Project homepage │ ├── architecture.md # System architecture │ ├── getting-started.md # Quick start │ ├── doc-map.md # Document relationship map │ │ │ ├── <Domain-1>/ # Business domain 1 │ │ ├── _index.md # Domain overview │ │ ├── <Sub-domain>/ # Sub-domain │ │ │ ├── _index.md │ │ │ └── <module>.md # 400+ lines │ │ └── ... │ │ │ ├── <Domain-2>/ # Business domain 2 │ │ └── ... │ │ │ └── api/ # API reference ├── wiki_en/ # Secondary language (if configured) │ ├── index.md # Same structure as wiki/ │ ├── architecture.md │ └── ...

### Automatic Domain Discovery

Infer business domains from the project's directory structure, package boundaries, and import graph. Group modules that share a cohesive responsibility into the same domain directory. Each domain MUST contain:

| File | Description |
| --- | --- |
| `_index.md` | Domain overview, architecture diagram, sub-module list |
| Sub-domain dirs | Related modules grouped by function |
| Each document | **400+ lines, 5+ code examples** |

---

## Progressive Scanning for Large Projects

When module count > 10, source files > 50, or LOC > 10,000, switch to batch mode:

1. **Prioritize modules** — entry points (weight 5) > dependents (4) > has docs (3) > code size (2) > recently modified (1)
2. **Generate 1-2 modules per batch** — depth scales with complexity
3. **Track progress** in `cache/progress.json` — record completed/pending modules and current batch number
4. **After each batch** — run `node scripts/index.js audit-docs.nium-wiki --verbose --mermaid-strict`, report results to user, then prompt:
  - `"continue"` — next batch
  - `"audit docs"` — re-run validation
  - `"regenerate <module>"` — redo a specific module
  - If `--mermaid-strict` reports errors: **fix them before continuing** — Mermaid syntax errors degrade the diagram catalog silently and accumulate technical debt.
5. **Resume** — when user says "continue wiki generation", read `cache/progress.json` and pick up where you left off

---

## Documentation Upgrade & Maintenance

When existing wiki docs are outdated or below quality gate, use one of these strategies:

| Strategy | When to Use | User Command |
| --- | --- | --- |
| `full_refresh` | Large version gap or poor overall quality | "refresh all wiki" |
| `incremental_upgrade` | Many modules, want to keep existing content | "upgrade wiki" |
| `targeted_upgrade` | Only specific modules need attention | "upgrade <module> docs" |

Execution: scan existing docs with `node scripts/index.js audit-docs.nium-wiki --mermaid-strict`, generate an upgrade report, then re-generate failing docs batch by batch. **Always include `--mermaid-strict`** so that Mermaid syntax errors block the upgrade and prevent bad diagrams from entering the wiki.

**Version footer** — append to every generated document: `*Generated by [Nium-Wiki v{{NIUM_WIKI_VERSION}}](https://github.com/niuma996/node scripts/index.js) | {{GENERATED_AT}}*` (read version from `skills/node scripts/index.js/scripts/version.json` — `version` field)