---
name: project-docs-diagram
description: Create technical diagrams from repository evidence or a system description, and validate/export Mermaid, PlantUML, draw.io, and Archify sources; not for endpoint API documentation.
---

# Project Docs Diagram

Produce auditable diagrams from repository evidence. A short request such as “根据代码生成架构图” is sufficient; infer scope, view, engine, and export without requiring a reference image or a detailed prompt. The agent interprets architecture and business meaning; scripts validate source anchors and supported diagram semantics. Keep generated files outside the analyzed repository unless the user asks to commit them. Read [the diagram standard](../../docs/DIAGRAM_STANDARD.md) when selecting a profile. The draw.io landscape theme and GitHub template decision are documented in [the template research](../../docs/ARCHITECTURE_TEMPLATE_RESEARCH.md).

Archify `explainer` 是独立的一页文档模式；用户要求项目说明页面时读取 [project-docs-overview](../project-docs-overview/SKILL.md)，不将它作为 typed JSON 图型传入本 Skill 的原生脚本。

## Workflow

First distinguish a repository-current-state diagram from a concept/proposal diagram. For “根据代码／当前项目画图”, follow the source workflow below. For “按描述画 Mem0 架构／设计方案图”, use the supplied components and relationships to author a native diagram and follow the native export path below; skip repository context, inventory and source-evidence requirements. Label the deliverable as a concept/proposal based on the user's description, with assumptions separate from supplied facts. Do not claim it describes the current repository. A generic concept architecture defaults to editable draw.io + PNG; honor an explicit engine or notation. Mixed requests verify current-state claims from source and distinguish proposed additions.

1. Resolve this skill's real directory. The CLI is `../../scripts/generate_architecture.py` relative to that directory. Run `python3 <cli> context --source <repo> --output <workdir>/context.json`. For a relevant symbol discovered in the first pass, repeat `--focus <qualified-method>` to include its CodeGraph callees. Do not create a CodeGraph index on the user's behalf.
2. Inspect the complete context. `files`, `symbols`, `routes`, `configKeys`, and `tables` are never capped; scans are candidates to verify. When `codeGraph` is present, start from its structured classes, routes, and focused calls; use `codegraph explore`/`node` to follow relevant paths. A freshness warning means graph data is only a lead: verify against current source. If `knowledgeGraph` or `domainGraph` exists, use its IDs/flows as navigation and semantic draft, with the same freshness caveat. Graph calls are code facts, not automatically architecture relationships. For a large context, inspect by module without silently discarding modules.
3. Choose a semantic profile before an engine. A short “项目／模块架构图” request defaults to `architecture-landscape`; C4, BPMN, UML sequence, and ERD follow their own notation. Write typed IR v2 using [the view contract](references/diagram-view-ir.md), cite source for every element and relation, and reserve `EXTRACTED` for labels literal on cited lines. Do not infer infrastructure or future components from examples.
4. For a new landscape overview, run `python3 <cli> inventory --source <repo> --output <workdir>/candidates.json` (use `--scope-prefix` only for an explicit module scope). Review every generated candidate and its `members` against current source and CodeGraph, add source-backed `manualCandidates` for important relationships the scanner missed, and give each candidate one `overview`, `detail`, or reasoned `excluded` decision. A mapped element or relation must cite every member line of that candidate. Usage candidates require a relation and detail decisions require nearby detail IRs. See [the coverage schema](references/diagram-view-ir.md). Do not exclude an in-scope dependency merely to reduce density.
5. For a new landscape, run `python3 <cli> validate --source <repo> --ir <workdir>/architecture-ir.json --strict-coverage`, then `python3 <cli> deliver --source <repo> --ir <workdir>/architecture-ir.json --output <workdir>/bundle --format drawio --export-for drawio:png`. `deliver` renders every declared detail before publishing the bundle. `coverageCheck: pass` is required; `declared_only` and `not_declared` are legacy compatibility states. For other profiles use `render` and the selected official engine. Supported exports remain Mermaid/PlantUML `svg|png|pdf`, draw.io `svg|png|jpg|pdf`, and Archify `svg|png|jpg|webp|webm|pdf`. Unsupported combinations fail rather than silently changing notation.
   If the selected official renderer is missing, run `python3 <repository>/scripts/install_renderers.py --auto --engine <engine>` once and retry. This uses the shared Codex/Claude Code renderer setup. An explicit `install.sh --no-engines` disables this automatic step; report that choice or an installation error instead of silently switching engines or export formats.
6. Inspect `drawioQuality` before treating a draw.io output as checked: failures stop rendering; `partial` lists unchecked automatic routes or unsupported geometry. Text measurements are estimates, not actual font layout. Open every exported image and inspect scope, arrow direction, full text, labels, overlap, and unexplained IDs. `geometryCheck: pass` remains the landscape card-bounds check. The landscape limit is 12 elements and 12 relations per view, so split dense diagrams with traceable candidate decisions. Never shorten required labels or drop relationships just to pass a check.

For all source and native diagrams, allow at most two targeted correction rounds per diagram after the first render. Re-run applicable checks and inspect changed exports after each repair; reuse unchanged reviewed outputs. Two identical failures require changing the approach within that budget (for example widening or splitting the view). At the limit, report the remaining defects and the draft files; do not claim completion or silently weaken checks. Report structural/engine checks separately from actual `visualReview: passed|failed|skipped`; use `skipped` with the reason when image viewing is unavailable. Script output `visualReview: required` is a pending check, never a visual pass.

## Official native diagrams outside IR v2

Read [the renderer capability audit](../../docs/RENDERER_CAPABILITY_AUDIT.md) and [the native authoring contract](references/native-diagrams.md) when the user requests another diagram type supported by Mermaid, PlantUML, draw.io, or Archify. For an existing native `.mmd`, `.puml`, `.drawio`, or Archify `.json`, run `python3 ../../scripts/render_native_diagram.py --engine <engine> --input <file> --output <dir> --export png` (repeat `--export` for desired formats). The command runs the actual official engine; Archify 3.2.0 accepts all ten official typed modes: architecture, workflow, sequence, dataflow, lifecycle, erd, tree, class, timeline, and waterfall. Follow the native authoring contract for material-item pointers and timing evidence.

For a **new** diagram outside IR v2, choose the notation, verify source, author official native syntax, and attach a [version 2 evidence manifest](references/native-diagrams.md) when it makes repository claims. Local PlantUML includes are inventoried and packaged. Standard-library or remote includes report `claimCoverage: partial`; disclose that limitation or use a self-contained source before claiming complete coverage. Review inferred claims and the exported image. `claimSemantics: not_proven` remains even when anchors and item coverage pass.

The source-line check proves that a cited snippet exists at that location. It does not prove a business interpretation, runtime route, or relationship. Review `INFERRED` and `AMBIGUOUS` claims against multiple code paths before presenting them as conclusions.