--- name: graphnet-wiki description: > Convert source material (notes, research, a domain you know, a Zettelkasten dump, a personal knowledge base topic) into a GraphLMS **wiki** project in lean JSON v3 format. Outputs a navigable knowledge graph: rich content nodes connected by topical links, organised by tags. **No quizzes, no prerequisite ordering** — wiki readers browse by clicking nodes and following links. Use when the user asks to "сделать вики", "сделать базу знаний", "запиши это в вики", "build a personal knowledge base", or hands you content to organise for browsing rather than studying. For courses with quizzes and prerequisite-driven learning use the `graphnet-create` skill instead. --- # GraphLMS Content Builder — Wiki Mode Turn source material into a navigable knowledge graph for personal browsing. > **Project type:** import the produced JSON into a project created with type **«Вики»**. > Wiki projects ignore quizzes and the scoring picker — readers click nodes on the > canvas, view their content, and use a browser-style Back / Дальше pair (Дальше falls > through to a connected neighbour when no forward history exists). Tags drive the node > fill colour on the canvas, so they're more important than in a course. > > **For courses (with quizzes, misconception traps, prerequisite progression) use > `graphnet-create`.** ## Mental model A wiki in GraphLMS is a **graph of articles**: - A **graph** is one knowledge area (e.g. "Linux internals", "Личные финансы", "История XX века"). Multiple graphs make a **wiki project**. - A **node** is **one article** — a self-contained, browseable explanation. Unlike a course node, articles are not constrained to "2–5 minutes". A node may be a page-long treatise or a one-paragraph definition; size follows the natural granularity of the topic. - An **edge** A → B means *"A is related to / leads naturally to B"*. **Direction is semantic only for the human reader** (e.g. "general → specific", "cause → effect"): the wiki UI doesn't enforce direction during navigation. There is **no scoring**, **no prerequisite gating**, **no progress** — clicking any node opens it. - **Tags** are first-class: every tag is a per-project entity with a colour. The primary (first) tag on a node drives the **fill colour of its circle on the canvas** in author and wiki views — making it easy to spot related articles at a glance. The point isn't to teach a curriculum; it's to make a *useful* graph the reader can explore by following their curiosity. ## Output format — lean JSON v3 The same wire format as the course skill — the project's type makes the difference, not the JSON. **But quizzes are ignored on import, so don't emit them.** ### Single graph ```json { "version": 3, "name": "Topic name", "defaultLayout": "force", "nodes": [ /* see below */ ], "edges": [ /* see below */ ] } ``` ### Project bundle (multi-graph) ```json { "kind": "project", "version": 2, "name": "Project name", "exportedAt": "2026-04-30T10:00:00Z", "graphs": [ /* lean graph objects */ ] } ``` ### Node ```json { "id": "tcp-handshake", "label": "Трёхэтапное рукопожатие TCP", "sections": [ { "type": "text", "markdown": "Перед обменом данными TCP-клиент и сервер обмениваются тремя пакетами: SYN, SYN-ACK, ACK. Это устанавливает начальные номера последовательностей и подтверждает, что обе стороны готовы говорить." }, { "type": "image", "svg": "...", "caption": "Диаграмма SYN / SYN-ACK / ACK" } ], "tags": ["tcp", "networking"] } ``` **Required:** `id`, `label`. Everything else is optional. **Don't emit `quiz`** — wiki ignores it. (The schema accepts it, but the reader UI hides it; you'd just bloat the file.) **Don't emit `color` on the node** — tag colour wins. See "Tags & colors" below. **`id` rules:** kebab-case, ASCII, unique within the graph. Used for edge references and URL fragments. ### Edge ```json { "source": "tcp-handshake", "target": "tcp-flow-control" } ``` **Required:** `source`, `target` (must reference existing node `id`s in the same graph). **Optional:** `label` — for a wiki, a label is more useful than in a course because the reader sees relations textually (e.g. `"label": "приводит к"`). Use sparingly: only when the relation is non-obvious from the two node labels. **Direction in a wiki** is a soft hint. Don't agonise over which way an edge should go; just pick the more natural reading direction (general → specific, cause → effect, parent topic → child topic, "see also" links can go either way). > **Don't emit a `type` field on edges.** Visual noise without behaviour. ### Section types Identical to the course skill: | Type | Fields | Use for | |---|---|---| | `text` | `markdown` | Prose, formulas, lists, code blocks. **The main building block in a wiki.** | | `image` | `svg` OR `name` OR `fileId` (+ `caption?`) | Diagrams, photos. SVG inline (preferred). | | `audio` | `name` OR `fileId` (+ `title?`) | Talks, pronunciation. | | `media` | `embedUrl?` (YouTube/VK) OR `embedHtml?` | Embedded video. | | `file` | `name` OR `fileId` + `fileName` + `fileSize` | Downloadable PDF/dataset. | For non-SVG media: emit `name` referencing a filename. The user uploads matching files via "Загрузить медиа" in project settings. Names must be unique per project. A wiki article often benefits from being **longer and richer** than a course node — multiple text sections, embedded video, code blocks, diagrams. There's no 2–5 minute budget; let the article be as detailed as the topic deserves. ### Tags & colors — central in a wiki Tags carry more weight here than in a course because: 1. The **primary tag colour** is **always visible** on the node circle (no status colours overriding it — wiki has no progress). 2. Visual clusters by colour help the reader navigate at a glance. 3. The reader uses tag categories as a mental table of contents. **Guidelines:** - Every node should have **at least 1 tag**. Aim for 1–3. - Define a **tag taxonomy upfront** before writing nodes. Sketch ~5–12 tag categories covering the wiki's domain. Examples for a Linux wiki: `kernel`, `networking`, `filesystem`, `process`, `security`, `tooling`, `troubleshooting`. The first tag on each node is the **primary** category that drives its colour. - Don't over-tag. 3 well-chosen tags > 8 redundant ones. - **Total distinct tag labels in a graph: 5–15.** More than that and the colour palette becomes illegible. - The lean JSON v3 schema carries tags as a string array per node; Tag entities themselves (with colours) live in PocketBase per project. After import, the user creates Tag records with hex colours via NodePanel → "Теги" → "Создать тег". The string tags on imported nodes do **not** auto-link to created Tag records yet (v1 limitation) — the user re-tags via the new picker. - In your **final user message**, include a "Suggested tag palette" listing every distinct tag label with a recommended hex colour. Pick semantic colours where possible (e.g. blue for "fundamentals", red for "warnings", green for "tooling"). The user copies the colours when creating Tag entities. ## How to decompose source into a wiki 1. **Read the whole source.** Identify the domain's natural conceptual chunks. 2. **Sketch the tag taxonomy first.** What 5–12 categories partition this domain? Don't pick categories that overlap heavily. 3. **List candidate articles.** ~30–100 ideas; one per natural chunk. Wiki articles can be larger and broader than course nodes. 4. **Decide the right granularity.** Symptoms of bad sizing for a *wiki*: - **Too coarse:** "Networking" — split into "OSI model", "TCP basics", "HTTP", etc. - **Too fine:** separate articles for "TCP SYN packet" and "TCP SYN-ACK packet" — merge into "Three-way handshake". - **Mixed scope:** "Linux kernel + drivers" — split into "Kernel architecture" and "Driver model" with an edge between them. 5. **Sketch the edges.** Add an edge between two nodes when: - The reader would benefit from clicking through (related concepts). - One node is a direct elaboration / specialization of another. - There's a "see also" relation worth surfacing on the canvas. 6. **Cycles are fine.** Unlike a course, a wiki can have cycles (A relates to B which relates back to A). Don't waste effort breaking them. 7. **Coverage check.** Skim the tag taxonomy you sketched: does each tag appear on at least 2–3 nodes? Are there obvious gaps (a tag with 0 nodes, or 0 nodes covering what an expert would say is a core area)? 8. **Tag every node.** Assign 1–3 tags from the taxonomy. The first is primary (colour-driving). If you find a node that fits no tag, your taxonomy is incomplete — extend it; don't shoehorn the node. ## Article writing style A wiki article is a **page**, not a flashcard. ### Patterns that work - **Definitional opening.** Start with one sentence that someone could quote standalone. - **Then expand.** Add the why, the how, and an example. - **Cross-link liberally.** Mention related articles inline ("→ см. *Three-way handshake*"). The reader will use the canvas + edges to navigate, but inline references help readability. - **Diagrams.** Wiki nodes benefit hugely from inline SVG diagrams. A diagram is often the *most navigable* representation of a concept. - **Code blocks, tables, formulas** — use them; markdown supports them. ### Anti-patterns - ❌ **Padding for length.** A short article is fine. Don't add fluff. - ❌ **Quiz-style content.** No questions, no "test yourself" sections — that's the course skill's job. - ❌ **One huge article covering 5 topics.** Split. - ❌ **Articles with zero outgoing or incoming edges.** Every article should connect to at least one other (otherwise it's an island the reader can't reach by browsing). ## Working flow 1. **Clarify.** Ask the user (skip questions where the answer is obvious from context): - Source material? (paste / file path / URL / topic name) - Scope? (one focused topic / a broad domain bundle) - Project name? Single-graph or multi-graph project bundle? - Language? (default: detect from source; Russian if unclear) - Output path? (default: `./graphnet-output/-wiki.json`) 2. **Read / research the source.** 3. **Sketch the tag taxonomy** (5–12 categories) and the article list (~30–100). Show both to the user **before writing JSON** so they can correct the structure cheaply. 4. **Validate the sketch:** - Tag taxonomy partitions the domain (no large overlaps, no gaps). - Every article fits at least one tag. - Articles are at the right granularity (split mixed-scope, merge over-fine). - The graph is connected (no isolated nodes). - Right size: 10–100 articles per graph; split into a project bundle if larger. 5. **Write each article.** Markdown text + diagrams as needed. Length follows the topic. Plan SVG diagrams for at least 1–3 articles where structure benefits. 6. **Emit the JSON file** at the chosen path. Use `Write` tool, not console output. 7. **Tell the user the next steps:** - Create the project as **«Вики»** (otherwise quizzes would still appear in the editor and the canvas would behave like a course). - Open the project's settings → Импорт JSON → select the file. - List any media filenames referenced via `name` to upload via "Загрузить медиа". - **Suggested tag palette:** for every distinct tag label, propose a hex colour (e.g. `- "kernel" → #ef4444`). The user creates these via NodePanel → "Теги" → "Создать тег" and re-tags imported nodes if they want coloured chips on the canvas. - List any domain gaps you noticed but chose not to add. ## Quality checklist (run before writing the file) Structure: - [ ] Every node has `id` and `label` - [ ] All node `id`s are unique - [ ] Every edge's `source` and `target` reference an existing node `id` - [ ] No `quiz` field on any node - [ ] No `color` field on any node (tag colour wins) - [ ] No `type` field on edges - [ ] No isolated nodes (every node connected via at least one edge) - [ ] Total nodes per graph: 10–100. Larger → split into a project bundle Tags: - [ ] Every node has 1–3 tags; first tag is the most informative (primary, drives colour) - [ ] Total distinct tag labels: 5–15 - [ ] No tag has 0 nodes (drop unused tags from taxonomy before emitting) - [ ] Final user message includes a "Suggested tag palette" with hex colours Content: - [ ] Content language matches the source / user request - [ ] Markdown is concise and well-formatted (no raw HTML in `text` sections) - [ ] At least 1–3 nodes have SVG / visual sections if the topic warrants it - [ ] No padding / filler prose; articles end when the topic is covered ## Compact full example A small wiki on TCP basics: ```json { "version": 3, "name": "TCP — основы", "defaultLayout": "force", "nodes": [ { "id": "tcp-overview", "label": "Что такое TCP", "sections": [ { "type": "text", "markdown": "**TCP (Transmission Control Protocol)** — транспортный протокол поверх IP, обеспечивающий надёжную и упорядоченную доставку байтового потока между двумя хостами. В отличие от UDP, TCP гарантирует, что данные дойдут (или соединение разорвётся), и в том же порядке, в котором были отправлены." } ], "tags": ["tcp", "fundamentals"] }, { "id": "tcp-handshake", "label": "Трёхэтапное рукопожатие", "sections": [ { "type": "text", "markdown": "Перед обменом данными клиент и сервер устанавливают соединение тремя пакетами:\n\n1. **SYN** — клиент шлёт запрос с начальным номером последовательности (ISN_c).\n2. **SYN-ACK** — сервер отвечает своим ISN_s и подтверждает ISN_c+1.\n3. **ACK** — клиент подтверждает ISN_s+1.\n\nПосле этого обе стороны знают начальные номера и могут обмениваться данными." }, { "type": "image", "svg": "...", "caption": "SYN → SYN-ACK → ACK" } ], "tags": ["tcp", "fundamentals"] }, { "id": "tcp-flow-control", "label": "Контроль потока", "sections": [ { "type": "text", "markdown": "TCP не даёт быстрому отправителю переполнить медленного получателя: получатель в каждом ACK сообщает **окно** (window) — сколько байт он готов принять до следующего подтверждения. Отправитель не превышает это окно. Если окно сжимается до нуля — отправитель ждёт." } ], "tags": ["tcp", "performance"] } ], "edges": [ { "source": "tcp-overview", "target": "tcp-handshake", "label": "начинается с" }, { "source": "tcp-handshake", "target": "tcp-flow-control" }, { "source": "tcp-overview", "target": "tcp-flow-control" } ] } ``` Notice: no quizzes, all three nodes have tags (with `tcp` as the primary on all — this is a `tcp` wiki, so the primary tag is the same; secondary tags differentiate by aspect: `fundamentals` vs `performance`). ## Reference The full schema and validators live in `src/entities/graph/model/fileSchema.ts` (`parseLeanGraphFile`, `parseLeanProjectFile`). Cross-check there if you hit a validation error after import.