PlanOpticon provides multiple ways to export knowledge graph data into formats suitable for documentation, note-taking, collaboration, and interchange. All export commands work offline from a `knowledge_graph.db` file -- no API key is needed for template-based exports.
4
5
## Overview of export options
6
7
| Format | Command | API Key | Description |
8
|--------|---------|---------|-------------|
9
| Markdown documents | `planopticon export markdown` | No | 7 document types: summary, meeting notes, glossary, and more |
10
| Obsidian vault | `planopticon export obsidian` | No | YAML frontmatter, `[[wiki-links]]`, tag pages, Map of Content |
11
| Notion-compatible | `planopticon export notion` | No | Callout blocks, CSV database for bulk import |
12
| PlanOpticonExchange JSON | `planopticon export exchange` | No | Canonical interchange format for merging and sharing |
13
| GitHub wiki | `planopticon wiki generate` | No | Home, Sidebar, entity pages, type indexes |
14
| GitHub wiki push | `planopticon wiki push` | Git auth | Push generated wiki to a GitHub repo |
15
16
## Markdown document generator
17
18
The markdown exporter produces structured documents from knowledge graph data using pure template-based generation. No LLM calls are made -- the output is deterministic and based entirely on the entities and relationships in the graph.
19
20
### CLI usage
21
22
```
23
planopticon export markdown DB_PATH [OPTIONS]
24
```
25
26
**Arguments:**
27
28
| Argument | Description |
29
|----------|-------------|
30
| `DB_PATH` | Path to a `knowledge_graph.db` file |
A high-level overview of the knowledge graph. Contains:
57
58
- Total entity and relationship counts
59
- Entity breakdown by type (table with counts and example names)
60
- Key entities ranked by number of connections (top 10)
61
- Relationship type breakdown with counts
62
63
This is useful for getting a quick overview of what a knowledge base contains.
64
65
#### meeting-notes (Meeting Notes)
66
67
Formats knowledge graph data as structured meeting notes. Organizes entities into planning-relevant categories:
68
69
- **Discussion Topics**: Entities of type `concept`, `technology`, or `topic` with their descriptions
70
- **Participants**: Entities of type `person`
71
- **Decisions & Constraints**: Entities of type `decision` or `constraint`
72
- **Action Items**: Entities of type `goal`, `feature`, or `milestone`, shown as checkboxes. If an entity has an `assigned_to` or `owned_by` relationship, the owner is shown as `@name`
73
- **Open Questions / Loose Ends**: Entities with one or fewer relationships (excluding people), indicating topics that may need follow-up
74
75
Includes a generation timestamp.
76
77
#### glossary (Glossary)
78
79
An alphabetically sorted dictionary of all entities in the knowledge graph. Each entry shows:
80
81
- Entity name (bold)
82
- Entity type (italic, in parentheses)
83
- First description
84
85
Format:
86
87
```
88
**Entity Name** *(type)*
89
: Description text here.
90
```
91
92
#### relationship-map (Relationship Map)
93
94
A comprehensive view of all relationships in the graph, organized by relationship type. Each type gets its own section with a table of source-target pairs.
95
96
Also includes a **Mermaid diagram** of the top 20 most-connected entities, rendered as a `graph LR` flowchart with labeled edges. This diagram can be rendered natively in GitHub, GitLab, Obsidian, and many other Markdown viewers.
97
98
#### status-report (Status Report)
99
100
A project-oriented status report that highlights planning entities:
101
102
- **Overview**: Counts of entities, relationships, features, milestones, requirements, and risks/constraints
103
- **Milestones**: Entities of type `milestone` with descriptions
104
- **Features**: Table of entities of type `feature` with descriptions (truncated to 60 characters)
105
- **Risks & Constraints**: Entities of type `risk` or `constraint`
106
107
Includes a generation timestamp.
108
109
#### entity-index (Entity Index)
110
111
A master index of all entities grouped by type. Each type section lists entities alphabetically with their first description. Shows total entity count and number of types.
112
113
#### csv (CSV Export)
114
115
A CSV file suitable for spreadsheet import. Columns:
116
117
| Column | Description |
118
|--------|-------------|
119
| Name | Entity name |
120
| Type | Entity type |
121
| Description | First description |
122
| Related To | Semicolon-separated list of entities this entity has outgoing relationships to |
123
| Source | First occurrence source |
124
125
### Entity briefs
126
127
In addition to the selected document types, the `generate_all()` function automatically creates individual entity brief pages in an `entities/` subdirectory. Each brief contains:
128
129
- Entity name and type
130
- Summary (all descriptions)
131
- Outgoing relationships (table of target entities and relationship types)
132
- Incoming relationships (table of source entities and relationship types)
133
- Source occurrences with timestamps and context text
134
135
## Obsidian vault export
136
137
The Obsidian exporter creates a complete vault structure with YAML frontmatter, `[[wiki-links]]` for entity cross-references, and Obsidian-compatible metadata.
- `tags`: Entity type as a tag (for Obsidian tag-based filtering)
193
- `aliases`: Any known aliases for the entity (if available)
194
- `date`: The export date
195
196
**Body content:**
197
198
- `# Entity Name` heading
199
- Description paragraphs
200
- `## Relationships` section with `[[wiki-links]]` to related entities:
201
```
202
- **uses**: [[FastAPI]]
203
- **depends_on**: [[PostgreSQL]]
204
```
205
- `## Referenced by` section with incoming relationships:
206
```
207
- **implements** from [[Backend Service]]
208
```
209
210
### Index note (Map of Content)
211
212
The `_Index.md` file serves as a Map of Content (MOC), listing all entities grouped by type with `[[wiki-links]]`:
213
214
```markdown
215
---
216
type: index
217
tags:
218
- MOC
219
date: 2026-03-07
220
---
221
222
# Index
223
224
**47** entities | **31** relationships
225
226
## Concept
227
228
- [[Microservices]]
229
- [[REST API]]
230
231
## Person
232
233
- [[Alice]]
234
- [[Bob]]
235
```
236
237
### Tag pages
238
239
One tag page is created per entity type (e.g., `Tag - Person.md`, `Tag - Technology.md`). Each page has frontmatter tagging it with the entity type and lists all entities of that type with descriptions.
240
241
## Notion-compatible markdown export
242
243
The Notion exporter creates Markdown files with Notion-style callout blocks and a CSV database file for bulk import into Notion.
entities_database.csv # CSV for Notion database import
269
Alice.md # Individual entity pages
270
Python.md
271
...
272
```
273
274
### Entity pages
275
276
Each entity page uses Notion-style callout syntax for metadata:
277
278
```markdown
279
# Python
280
281
> :computer: **Type:** technology
282
283
## Description
284
285
A high-level programming language...
286
287
> :memo: **Properties**
288
> - **version:** 3.11
289
> - **paradigm:** multi-paradigm
290
291
## Relationships
292
293
| Target | Relationship |
294
|--------|-------------|
295
| FastAPI | uses |
296
| Django | framework_for |
297
298
## Referenced by
299
300
| Source | Relationship |
301
|--------|-------------|
302
| Backend Service | implements |
303
```
304
305
### CSV database
306
307
The `entities_database.csv` file contains all entities in a format suitable for Notion's CSV database import:
308
309
| Column | Description |
310
|--------|-------------|
311
| Name | Entity name |
312
| Type | Entity type |
313
| Description | First two descriptions, semicolon-separated |
314
| Related To | Comma-separated list of outgoing relationship targets |
315
316
### Overview page
317
318
The `Overview.md` page provides a summary with entity counts and a grouped listing of all entities by type.
319
320
## GitHub wiki generator
321
322
The wiki generator creates a complete set of GitHub wiki pages from a knowledge graph, including navigation (Home page and Sidebar) and cross-linked entity pages.
323
324
### CLI usage
325
326
**Generate wiki pages locally:**
327
328
```
329
planopticon wiki generate DB_PATH [OPTIONS]
330
```
331
332
| Option | Short | Default | Description |
333
|--------|-------|---------|-------------|
334
| `--output` | `-o` | `./wiki` | Output directory for wiki pages |
335
| `--title` | | `Knowledge Base` | Wiki title (shown on Home page) |
336
337
**Push wiki pages to GitHub:**
338
339
```
340
planopticon wiki push WIKI_DIR REPO [OPTIONS]
341
```
342
343
| Argument | Description |
344
|----------|-------------|
345
| `WIKI_DIR` | Path to the directory containing generated wiki `.md` files |
346
| `REPO` | GitHub repository in `owner/repo` format |
planopticon wiki generate knowledge_graph.db -o ./wiki
357
358
# Generate with a custom title
359
planopticon wiki generate kg.db -o ./wiki --title "Project Wiki"
360
361
# Push to GitHub
362
planopticon wiki push ./wiki ConflictHQ/PlanOpticon
363
364
# Push with a custom commit message
365
planopticon wiki push ./wiki owner/repo -m "Add entity pages"
366
```
367
368
### Generated pages
369
370
The wiki generator creates the following pages:
371
372
| Page | Description |
373
|------|-------------|
374
| `Home.md` | Main wiki page with entity counts, type links, and artifact links |
375
| `_Sidebar.md` | Navigation sidebar with links to Home, entity type indexes, and artifacts |
376
| `{Type}.md` | One index page per entity type with a table of entities and descriptions |
377
| `{Entity}.md` | Individual entity pages with type, descriptions, relationships, and sources |
378
379
### Entity pages
380
381
Each entity page contains:
382
383
- Entity name as the top heading
384
- **Type** label
385
- **Descriptions** section (bullet list)
386
- **Relationships** table with wiki-style links to target entities
387
- **Referenced By** table with links to source entities
388
- **Sources** section listing occurrences with timestamps and context
389
390
All entity and type names are cross-linked using GitHub wiki-compatible links (`[Name](Sanitized-Name)`).
391
392
### Push behavior
393
394
The `wiki push` command:
395
396
1. Clones the existing GitHub wiki repository (`https://github.com/{repo}.wiki.git`).
397
2. If the wiki does not exist yet, initializes a new Git repository.
398
3. Copies all `.md` files from the wiki directory into the clone.
399
4. Commits the changes.
400
5. Pushes to the remote (tries `master` first, then `main`).
401
402
This requires Git authentication with push access to the repository. The wiki must be enabled in the GitHub repository settings.
403
404
## PlanOpticonExchange JSON format
405
406
The PlanOpticonExchange is the canonical interchange format for PlanOpticon data. Every command produces it, and every export adapter can consume it. It provides a structured, versioned JSON representation of a complete knowledge graph with project metadata.