PlanOpticon

planopticon / docs / guide / export.md
Source Blame History 756 lines
3551b80… noreply 1 # Export
3551b80… noreply 2
3551b80… noreply 3 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.
3551b80… noreply 4
3551b80… noreply 5 ## Overview of export options
3551b80… noreply 6
3551b80… noreply 7 | Format | Command | API Key | Description |
3551b80… noreply 8 |--------|---------|---------|-------------|
3551b80… noreply 9 | Markdown documents | `planopticon export markdown` | No | 7 document types: summary, meeting notes, glossary, and more |
3551b80… noreply 10 | Obsidian vault | `planopticon export obsidian` | No | YAML frontmatter, `[[wiki-links]]`, tag pages, Map of Content |
3551b80… noreply 11 | Notion-compatible | `planopticon export notion` | No | Callout blocks, CSV database for bulk import |
3551b80… noreply 12 | PlanOpticonExchange JSON | `planopticon export exchange` | No | Canonical interchange format for merging and sharing |
3551b80… noreply 13 | GitHub wiki | `planopticon wiki generate` | No | Home, Sidebar, entity pages, type indexes |
3551b80… noreply 14 | GitHub wiki push | `planopticon wiki push` | Git auth | Push generated wiki to a GitHub repo |
3551b80… noreply 15
3551b80… noreply 16 ## Markdown document generator
3551b80… noreply 17
3551b80… noreply 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.
3551b80… noreply 19
3551b80… noreply 20 ### CLI usage
3551b80… noreply 21
3551b80… noreply 22 ```
3551b80… noreply 23 planopticon export markdown DB_PATH [OPTIONS]
3551b80… noreply 24 ```
3551b80… noreply 25
3551b80… noreply 26 **Arguments:**
3551b80… noreply 27
3551b80… noreply 28 | Argument | Description |
3551b80… noreply 29 |----------|-------------|
3551b80… noreply 30 | `DB_PATH` | Path to a `knowledge_graph.db` file |
3551b80… noreply 31
3551b80… noreply 32 **Options:**
3551b80… noreply 33
3551b80… noreply 34 | Option | Short | Default | Description |
3551b80… noreply 35 |--------|-------|---------|-------------|
3551b80… noreply 36 | `--output` | `-o` | `./export` | Output directory |
3551b80… noreply 37 | `--type` | | `all` | Document types to generate (repeatable). Choices: `summary`, `meeting-notes`, `glossary`, `relationship-map`, `status-report`, `entity-index`, `csv`, `all` |
3551b80… noreply 38
3551b80… noreply 39 **Examples:**
3551b80… noreply 40
3551b80… noreply 41 ```bash
3551b80… noreply 42 # Generate all document types
3551b80… noreply 43 planopticon export markdown knowledge_graph.db
3551b80… noreply 44
3551b80… noreply 45 # Generate only summary and glossary
3551b80… noreply 46 planopticon export markdown kg.db -o ./docs --type summary --type glossary
3551b80… noreply 47
3551b80… noreply 48 # Generate meeting notes and CSV
3551b80… noreply 49 planopticon export markdown kg.db --type meeting-notes --type csv
3551b80… noreply 50 ```
3551b80… noreply 51
3551b80… noreply 52 ### Document types
3551b80… noreply 53
3551b80… noreply 54 #### summary (Executive Summary)
3551b80… noreply 55
3551b80… noreply 56 A high-level overview of the knowledge graph. Contains:
3551b80… noreply 57
3551b80… noreply 58 - Total entity and relationship counts
3551b80… noreply 59 - Entity breakdown by type (table with counts and example names)
3551b80… noreply 60 - Key entities ranked by number of connections (top 10)
3551b80… noreply 61 - Relationship type breakdown with counts
3551b80… noreply 62
3551b80… noreply 63 This is useful for getting a quick overview of what a knowledge base contains.
3551b80… noreply 64
3551b80… noreply 65 #### meeting-notes (Meeting Notes)
3551b80… noreply 66
3551b80… noreply 67 Formats knowledge graph data as structured meeting notes. Organizes entities into planning-relevant categories:
3551b80… noreply 68
3551b80… noreply 69 - **Discussion Topics**: Entities of type `concept`, `technology`, or `topic` with their descriptions
3551b80… noreply 70 - **Participants**: Entities of type `person`
3551b80… noreply 71 - **Decisions & Constraints**: Entities of type `decision` or `constraint`
3551b80… noreply 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`
3551b80… noreply 73 - **Open Questions / Loose Ends**: Entities with one or fewer relationships (excluding people), indicating topics that may need follow-up
3551b80… noreply 74
3551b80… noreply 75 Includes a generation timestamp.
3551b80… noreply 76
3551b80… noreply 77 #### glossary (Glossary)
3551b80… noreply 78
3551b80… noreply 79 An alphabetically sorted dictionary of all entities in the knowledge graph. Each entry shows:
3551b80… noreply 80
3551b80… noreply 81 - Entity name (bold)
3551b80… noreply 82 - Entity type (italic, in parentheses)
3551b80… noreply 83 - First description
3551b80… noreply 84
3551b80… noreply 85 Format:
3551b80… noreply 86
3551b80… noreply 87 ```
3551b80… noreply 88 **Entity Name** *(type)*
3551b80… noreply 89 : Description text here.
3551b80… noreply 90 ```
3551b80… noreply 91
3551b80… noreply 92 #### relationship-map (Relationship Map)
3551b80… noreply 93
3551b80… noreply 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.
3551b80… noreply 95
3551b80… noreply 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.
3551b80… noreply 97
3551b80… noreply 98 #### status-report (Status Report)
3551b80… noreply 99
3551b80… noreply 100 A project-oriented status report that highlights planning entities:
3551b80… noreply 101
3551b80… noreply 102 - **Overview**: Counts of entities, relationships, features, milestones, requirements, and risks/constraints
3551b80… noreply 103 - **Milestones**: Entities of type `milestone` with descriptions
3551b80… noreply 104 - **Features**: Table of entities of type `feature` with descriptions (truncated to 60 characters)
3551b80… noreply 105 - **Risks & Constraints**: Entities of type `risk` or `constraint`
3551b80… noreply 106
3551b80… noreply 107 Includes a generation timestamp.
3551b80… noreply 108
3551b80… noreply 109 #### entity-index (Entity Index)
3551b80… noreply 110
3551b80… noreply 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.
3551b80… noreply 112
3551b80… noreply 113 #### csv (CSV Export)
3551b80… noreply 114
3551b80… noreply 115 A CSV file suitable for spreadsheet import. Columns:
3551b80… noreply 116
3551b80… noreply 117 | Column | Description |
3551b80… noreply 118 |--------|-------------|
3551b80… noreply 119 | Name | Entity name |
3551b80… noreply 120 | Type | Entity type |
3551b80… noreply 121 | Description | First description |
3551b80… noreply 122 | Related To | Semicolon-separated list of entities this entity has outgoing relationships to |
3551b80… noreply 123 | Source | First occurrence source |
3551b80… noreply 124
3551b80… noreply 125 ### Entity briefs
3551b80… noreply 126
3551b80… noreply 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:
3551b80… noreply 128
3551b80… noreply 129 - Entity name and type
3551b80… noreply 130 - Summary (all descriptions)
3551b80… noreply 131 - Outgoing relationships (table of target entities and relationship types)
3551b80… noreply 132 - Incoming relationships (table of source entities and relationship types)
3551b80… noreply 133 - Source occurrences with timestamps and context text
3551b80… noreply 134
3551b80… noreply 135 ## Obsidian vault export
3551b80… noreply 136
3551b80… noreply 137 The Obsidian exporter creates a complete vault structure with YAML frontmatter, `[[wiki-links]]` for entity cross-references, and Obsidian-compatible metadata.
3551b80… noreply 138
3551b80… noreply 139 ### CLI usage
3551b80… noreply 140
3551b80… noreply 141 ```
3551b80… noreply 142 planopticon export obsidian DB_PATH [OPTIONS]
3551b80… noreply 143 ```
3551b80… noreply 144
3551b80… noreply 145 **Options:**
3551b80… noreply 146
3551b80… noreply 147 | Option | Short | Default | Description |
3551b80… noreply 148 |--------|-------|---------|-------------|
3551b80… noreply 149 | `--output` | `-o` | `./obsidian-vault` | Output vault directory |
3551b80… noreply 150
3551b80… noreply 151 **Example:**
3551b80… noreply 152
3551b80… noreply 153 ```bash
3551b80… noreply 154 planopticon export obsidian knowledge_graph.db -o ./my-vault
3551b80… noreply 155 ```
3551b80… noreply 156
3551b80… noreply 157 ### Generated structure
3551b80… noreply 158
3551b80… noreply 159 ```
3551b80… noreply 160 my-vault/
3551b80… noreply 161 _Index.md # Map of Content (MOC)
3551b80… noreply 162 Tag - Person.md # One tag page per entity type
3551b80… noreply 163 Tag - Technology.md
3551b80… noreply 164 Tag - Concept.md
3551b80… noreply 165 Alice.md # Individual entity notes
3551b80… noreply 166 Python.md
3551b80… noreply 167 Microservices.md
3551b80… noreply 168 ...
3551b80… noreply 169 ```
3551b80… noreply 170
3551b80… noreply 171 ### Entity notes
3551b80… noreply 172
3551b80… noreply 173 Each entity gets a dedicated note with:
3551b80… noreply 174
3551b80… noreply 175 **YAML frontmatter:**
3551b80… noreply 176
3551b80… noreply 177 ```yaml
3551b80… noreply 178 ---
3551b80… noreply 179 type: technology
3551b80… noreply 180 tags:
3551b80… noreply 181 - technology
3551b80… noreply 182 aliases:
3551b80… noreply 183 - Python 3
3551b80… noreply 184 - CPython
3551b80… noreply 185 date: 2026-03-07
3551b80… noreply 186 ---
3551b80… noreply 187 ```
3551b80… noreply 188
3551b80… noreply 189 The frontmatter includes:
3551b80… noreply 190
3551b80… noreply 191 - `type`: The entity type
3551b80… noreply 192 - `tags`: Entity type as a tag (for Obsidian tag-based filtering)
3551b80… noreply 193 - `aliases`: Any known aliases for the entity (if available)
3551b80… noreply 194 - `date`: The export date
3551b80… noreply 195
3551b80… noreply 196 **Body content:**
3551b80… noreply 197
3551b80… noreply 198 - `# Entity Name` heading
3551b80… noreply 199 - Description paragraphs
3551b80… noreply 200 - `## Relationships` section with `[[wiki-links]]` to related entities:
3551b80… noreply 201 ```
3551b80… noreply 202 - **uses**: [[FastAPI]]
3551b80… noreply 203 - **depends_on**: [[PostgreSQL]]
3551b80… noreply 204 ```
3551b80… noreply 205 - `## Referenced by` section with incoming relationships:
3551b80… noreply 206 ```
3551b80… noreply 207 - **implements** from [[Backend Service]]
3551b80… noreply 208 ```
3551b80… noreply 209
3551b80… noreply 210 ### Index note (Map of Content)
3551b80… noreply 211
3551b80… noreply 212 The `_Index.md` file serves as a Map of Content (MOC), listing all entities grouped by type with `[[wiki-links]]`:
3551b80… noreply 213
3551b80… noreply 214 ```markdown
3551b80… noreply 215 ---
3551b80… noreply 216 type: index
3551b80… noreply 217 tags:
3551b80… noreply 218 - MOC
3551b80… noreply 219 date: 2026-03-07
3551b80… noreply 220 ---
3551b80… noreply 221
3551b80… noreply 222 # Index
3551b80… noreply 223
3551b80… noreply 224 **47** entities | **31** relationships
3551b80… noreply 225
3551b80… noreply 226 ## Concept
3551b80… noreply 227
3551b80… noreply 228 - [[Microservices]]
3551b80… noreply 229 - [[REST API]]
3551b80… noreply 230
3551b80… noreply 231 ## Person
3551b80… noreply 232
3551b80… noreply 233 - [[Alice]]
3551b80… noreply 234 - [[Bob]]
3551b80… noreply 235 ```
3551b80… noreply 236
3551b80… noreply 237 ### Tag pages
3551b80… noreply 238
3551b80… noreply 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.
3551b80… noreply 240
3551b80… noreply 241 ## Notion-compatible markdown export
3551b80… noreply 242
3551b80… noreply 243 The Notion exporter creates Markdown files with Notion-style callout blocks and a CSV database file for bulk import into Notion.
3551b80… noreply 244
3551b80… noreply 245 ### CLI usage
3551b80… noreply 246
3551b80… noreply 247 ```
3551b80… noreply 248 planopticon export notion DB_PATH [OPTIONS]
3551b80… noreply 249 ```
3551b80… noreply 250
3551b80… noreply 251 **Options:**
3551b80… noreply 252
3551b80… noreply 253 | Option | Short | Default | Description |
3551b80… noreply 254 |--------|-------|---------|-------------|
3551b80… noreply 255 | `--output` | `-o` | `./notion-export` | Output directory |
3551b80… noreply 256
3551b80… noreply 257 **Example:**
3551b80… noreply 258
3551b80… noreply 259 ```bash
3551b80… noreply 260 planopticon export notion knowledge_graph.db -o ./notion-export
3551b80… noreply 261 ```
3551b80… noreply 262
3551b80… noreply 263 ### Generated structure
3551b80… noreply 264
3551b80… noreply 265 ```
3551b80… noreply 266 notion-export/
3551b80… noreply 267 Overview.md # Knowledge graph overview page
3551b80… noreply 268 entities_database.csv # CSV for Notion database import
3551b80… noreply 269 Alice.md # Individual entity pages
3551b80… noreply 270 Python.md
3551b80… noreply 271 ...
3551b80… noreply 272 ```
3551b80… noreply 273
3551b80… noreply 274 ### Entity pages
3551b80… noreply 275
3551b80… noreply 276 Each entity page uses Notion-style callout syntax for metadata:
3551b80… noreply 277
3551b80… noreply 278 ```markdown
3551b80… noreply 279 # Python
3551b80… noreply 280
3551b80… noreply 281 > :computer: **Type:** technology
3551b80… noreply 282
3551b80… noreply 283 ## Description
3551b80… noreply 284
3551b80… noreply 285 A high-level programming language...
3551b80… noreply 286
3551b80… noreply 287 > :memo: **Properties**
3551b80… noreply 288 > - **version:** 3.11
3551b80… noreply 289 > - **paradigm:** multi-paradigm
3551b80… noreply 290
3551b80… noreply 291 ## Relationships
3551b80… noreply 292
3551b80… noreply 293 | Target | Relationship |
3551b80… noreply 294 |--------|-------------|
3551b80… noreply 295 | FastAPI | uses |
3551b80… noreply 296 | Django | framework_for |
3551b80… noreply 297
3551b80… noreply 298 ## Referenced by
3551b80… noreply 299
3551b80… noreply 300 | Source | Relationship |
3551b80… noreply 301 |--------|-------------|
3551b80… noreply 302 | Backend Service | implements |
3551b80… noreply 303 ```
3551b80… noreply 304
3551b80… noreply 305 ### CSV database
3551b80… noreply 306
3551b80… noreply 307 The `entities_database.csv` file contains all entities in a format suitable for Notion's CSV database import:
3551b80… noreply 308
3551b80… noreply 309 | Column | Description |
3551b80… noreply 310 |--------|-------------|
3551b80… noreply 311 | Name | Entity name |
3551b80… noreply 312 | Type | Entity type |
3551b80… noreply 313 | Description | First two descriptions, semicolon-separated |
3551b80… noreply 314 | Related To | Comma-separated list of outgoing relationship targets |
3551b80… noreply 315
3551b80… noreply 316 ### Overview page
3551b80… noreply 317
3551b80… noreply 318 The `Overview.md` page provides a summary with entity counts and a grouped listing of all entities by type.
3551b80… noreply 319
3551b80… noreply 320 ## GitHub wiki generator
3551b80… noreply 321
3551b80… noreply 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.
3551b80… noreply 323
3551b80… noreply 324 ### CLI usage
3551b80… noreply 325
3551b80… noreply 326 **Generate wiki pages locally:**
3551b80… noreply 327
3551b80… noreply 328 ```
3551b80… noreply 329 planopticon wiki generate DB_PATH [OPTIONS]
3551b80… noreply 330 ```
3551b80… noreply 331
3551b80… noreply 332 | Option | Short | Default | Description |
3551b80… noreply 333 |--------|-------|---------|-------------|
3551b80… noreply 334 | `--output` | `-o` | `./wiki` | Output directory for wiki pages |
3551b80… noreply 335 | `--title` | | `Knowledge Base` | Wiki title (shown on Home page) |
3551b80… noreply 336
3551b80… noreply 337 **Push wiki pages to GitHub:**
3551b80… noreply 338
3551b80… noreply 339 ```
3551b80… noreply 340 planopticon wiki push WIKI_DIR REPO [OPTIONS]
3551b80… noreply 341 ```
3551b80… noreply 342
3551b80… noreply 343 | Argument | Description |
3551b80… noreply 344 |----------|-------------|
3551b80… noreply 345 | `WIKI_DIR` | Path to the directory containing generated wiki `.md` files |
3551b80… noreply 346 | `REPO` | GitHub repository in `owner/repo` format |
3551b80… noreply 347
3551b80… noreply 348 | Option | Short | Default | Description |
3551b80… noreply 349 |--------|-------|---------|-------------|
3551b80… noreply 350 | `--message` | `-m` | `Update wiki` | Git commit message |
3551b80… noreply 351
3551b80… noreply 352 **Examples:**
3551b80… noreply 353
3551b80… noreply 354 ```bash
3551b80… noreply 355 # Generate wiki pages
3551b80… noreply 356 planopticon wiki generate knowledge_graph.db -o ./wiki
3551b80… noreply 357
3551b80… noreply 358 # Generate with a custom title
3551b80… noreply 359 planopticon wiki generate kg.db -o ./wiki --title "Project Wiki"
3551b80… noreply 360
3551b80… noreply 361 # Push to GitHub
3551b80… noreply 362 planopticon wiki push ./wiki ConflictHQ/PlanOpticon
3551b80… noreply 363
3551b80… noreply 364 # Push with a custom commit message
3551b80… noreply 365 planopticon wiki push ./wiki owner/repo -m "Add entity pages"
3551b80… noreply 366 ```
3551b80… noreply 367
3551b80… noreply 368 ### Generated pages
3551b80… noreply 369
3551b80… noreply 370 The wiki generator creates the following pages:
3551b80… noreply 371
3551b80… noreply 372 | Page | Description |
3551b80… noreply 373 |------|-------------|
3551b80… noreply 374 | `Home.md` | Main wiki page with entity counts, type links, and artifact links |
3551b80… noreply 375 | `_Sidebar.md` | Navigation sidebar with links to Home, entity type indexes, and artifacts |
3551b80… noreply 376 | `{Type}.md` | One index page per entity type with a table of entities and descriptions |
3551b80… noreply 377 | `{Entity}.md` | Individual entity pages with type, descriptions, relationships, and sources |
3551b80… noreply 378
3551b80… noreply 379 ### Entity pages
3551b80… noreply 380
3551b80… noreply 381 Each entity page contains:
3551b80… noreply 382
3551b80… noreply 383 - Entity name as the top heading
3551b80… noreply 384 - **Type** label
3551b80… noreply 385 - **Descriptions** section (bullet list)
3551b80… noreply 386 - **Relationships** table with wiki-style links to target entities
3551b80… noreply 387 - **Referenced By** table with links to source entities
3551b80… noreply 388 - **Sources** section listing occurrences with timestamps and context
3551b80… noreply 389
3551b80… noreply 390 All entity and type names are cross-linked using GitHub wiki-compatible links (`[Name](Sanitized-Name)`).
3551b80… noreply 391
3551b80… noreply 392 ### Push behavior
3551b80… noreply 393
3551b80… noreply 394 The `wiki push` command:
3551b80… noreply 395
3551b80… noreply 396 1. Clones the existing GitHub wiki repository (`https://github.com/{repo}.wiki.git`).
3551b80… noreply 397 2. If the wiki does not exist yet, initializes a new Git repository.
3551b80… noreply 398 3. Copies all `.md` files from the wiki directory into the clone.
3551b80… noreply 399 4. Commits the changes.
3551b80… noreply 400 5. Pushes to the remote (tries `master` first, then `main`).
3551b80… noreply 401
3551b80… noreply 402 This requires Git authentication with push access to the repository. The wiki must be enabled in the GitHub repository settings.
3551b80… noreply 403
3551b80… noreply 404 ## PlanOpticonExchange JSON format
3551b80… noreply 405
3551b80… noreply 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.
3551b80… noreply 407
3551b80… noreply 408 ### CLI usage
3551b80… noreply 409
3551b80… noreply 410 ```
3551b80… noreply 411 planopticon export exchange DB_PATH [OPTIONS]
3551b80… noreply 412 ```
3551b80… noreply 413
3551b80… noreply 414 | Option | Short | Default | Description |
3551b80… noreply 415 |--------|-------|---------|-------------|
3551b80… noreply 416 | `--output` | `-o` | `./exchange.json` | Output JSON file path |
3551b80… noreply 417 | `--name` | | `Untitled` | Project name for the exchange payload |
3551b80… noreply 418 | `--description` | | (empty) | Project description |
3551b80… noreply 419
3551b80… noreply 420 **Examples:**
3551b80… noreply 421
3551b80… noreply 422 ```bash
3551b80… noreply 423 # Basic export
3551b80… noreply 424 planopticon export exchange knowledge_graph.db
3551b80… noreply 425
3551b80… noreply 426 # With project metadata
3551b80… noreply 427 planopticon export exchange kg.db -o exchange.json --name "My Project" --description "Sprint 3 analysis"
3551b80… noreply 428 ```
3551b80… noreply 429
3551b80… noreply 430 ### Schema
3551b80… noreply 431
3551b80… noreply 432 The exchange format has the following top-level structure:
3551b80… noreply 433
3551b80… noreply 434 ```json
3551b80… noreply 435 {
3551b80… noreply 436 "version": "1.0",
3551b80… noreply 437 "project": {
3551b80… noreply 438 "name": "My Project",
3551b80… noreply 439 "description": "Sprint 3 analysis",
3551b80… noreply 440 "created_at": "2026-03-07T10:30:00.000000",
3551b80… noreply 441 "updated_at": "2026-03-07T10:30:00.000000",
3551b80… noreply 442 "tags": ["sprint-3", "backend"]
3551b80… noreply 443 },
3551b80… noreply 444 "entities": [
3551b80… noreply 445 {
3551b80… noreply 446 "name": "Python",
3551b80… noreply 447 "type": "technology",
3551b80… noreply 448 "descriptions": ["A high-level programming language"],
3551b80… noreply 449 "source": "transcript",
3551b80… noreply 450 "occurrences": [
3551b80… noreply 451 {
3551b80… noreply 452 "source": "meeting.mp4",
3551b80… noreply 453 "timestamp": "00:05:23",
3551b80… noreply 454 "text": "We should use Python for the backend"
3551b80… noreply 455 }
3551b80… noreply 456 ]
3551b80… noreply 457 }
3551b80… noreply 458 ],
3551b80… noreply 459 "relationships": [
3551b80… noreply 460 {
3551b80… noreply 461 "source": "Python",
3551b80… noreply 462 "target": "Backend Service",
3551b80… noreply 463 "type": "used_by",
3551b80… noreply 464 "content_source": "transcript:meeting.mp4",
3551b80… noreply 465 "timestamp": 323.0
3551b80… noreply 466 }
3551b80… noreply 467 ],
3551b80… noreply 468 "artifacts": [
3551b80… noreply 469 {
3551b80… noreply 470 "name": "Project Plan",
3551b80… noreply 471 "content": "# Project Plan\n\n...",
3551b80… noreply 472 "artifact_type": "project_plan",
3551b80… noreply 473 "format": "markdown",
3551b80… noreply 474 "metadata": {}
3551b80… noreply 475 }
3551b80… noreply 476 ],
3551b80… noreply 477 "sources": [
3551b80… noreply 478 {
3551b80… noreply 479 "source_id": "abc123",
3551b80… noreply 480 "source_type": "video",
3551b80… noreply 481 "title": "Sprint Planning Meeting",
3551b80… noreply 482 "path": "/recordings/meeting.mp4",
3551b80… noreply 483 "url": null,
3551b80… noreply 484 "mime_type": "video/mp4",
3551b80… noreply 485 "ingested_at": "2026-03-07T10:00:00.000000",
3551b80… noreply 486 "metadata": {}
3551b80… noreply 487 }
3551b80… noreply 488 ]
3551b80… noreply 489 }
3551b80… noreply 490 ```
3551b80… noreply 491
3551b80… noreply 492 **Top-level fields:**
3551b80… noreply 493
3551b80… noreply 494 | Field | Type | Description |
3551b80… noreply 495 |-------|------|-------------|
3551b80… noreply 496 | `version` | `str` | Schema version (currently `"1.0"`) |
3551b80… noreply 497 | `project` | `ProjectMeta` | Project-level metadata |
3551b80… noreply 498 | `entities` | `List[Entity]` | Knowledge graph entities |
3551b80… noreply 499 | `relationships` | `List[Relationship]` | Knowledge graph relationships |
3551b80… noreply 500 | `artifacts` | `List[ArtifactMeta]` | Generated artifacts (plans, PRDs, etc.) |
3551b80… noreply 501 | `sources` | `List[SourceRecord]` | Content source provenance records |
3551b80… noreply 502
3551b80… noreply 503 ### Merging exchange files
3551b80… noreply 504
3551b80… noreply 505 The exchange format supports merging, with automatic deduplication:
3551b80… noreply 506
3551b80… noreply 507 - Entities are deduplicated by name
3551b80… noreply 508 - Relationships are deduplicated by the tuple `(source, target, type)`
3551b80… noreply 509 - Artifacts are deduplicated by name
3551b80… noreply 510 - Sources are deduplicated by `source_id`
3551b80… noreply 511
3551b80… noreply 512 ```python
3551b80… noreply 513 from video_processor.exchange import PlanOpticonExchange
3551b80… noreply 514
3551b80… noreply 515 # Load two exchange files
3551b80… noreply 516 ex1 = PlanOpticonExchange.from_file("sprint-1.json")
3551b80… noreply 517 ex2 = PlanOpticonExchange.from_file("sprint-2.json")
3551b80… noreply 518
3551b80… noreply 519 # Merge ex2 into ex1
3551b80… noreply 520 ex1.merge(ex2)
3551b80… noreply 521
3551b80… noreply 522 # Save the combined result
3551b80… noreply 523 ex1.to_file("combined.json")
3551b80… noreply 524 ```
3551b80… noreply 525
3551b80… noreply 526 The `project.updated_at` timestamp is updated automatically on merge.
3551b80… noreply 527
3551b80… noreply 528 ### Python API
3551b80… noreply 529
3551b80… noreply 530 **Create from a knowledge graph:**
3551b80… noreply 531
3551b80… noreply 532 ```python
3551b80… noreply 533 from video_processor.exchange import PlanOpticonExchange
3551b80… noreply 534 from video_processor.integrators.knowledge_graph import KnowledgeGraph
3551b80… noreply 535
3551b80… noreply 536 kg = KnowledgeGraph(db_path="knowledge_graph.db")
3551b80… noreply 537 kg_data = kg.to_dict()
3551b80… noreply 538
3551b80… noreply 539 exchange = PlanOpticonExchange.from_knowledge_graph(
3551b80… noreply 540 kg_data,
3551b80… noreply 541 project_name="My Project",
3551b80… noreply 542 project_description="Analysis of sprint planning meetings",
3551b80… noreply 543 tags=["planning", "backend"],
3551b80… noreply 544 )
3551b80… noreply 545 ```
3551b80… noreply 546
3551b80… noreply 547 **Save and load:**
3551b80… noreply 548
3551b80… noreply 549 ```python
3551b80… noreply 550 # Save to file
3551b80… noreply 551 exchange.to_file("exchange.json")
3551b80… noreply 552
3551b80… noreply 553 # Load from file
3551b80… noreply 554 loaded = PlanOpticonExchange.from_file("exchange.json")
3551b80… noreply 555 ```
3551b80… noreply 556
3551b80… noreply 557 **Get JSON Schema:**
3551b80… noreply 558
3551b80… noreply 559 ```python
3551b80… noreply 560 schema = PlanOpticonExchange.json_schema()
3551b80… noreply 561 ```
3551b80… noreply 562
3551b80… noreply 563 This returns the full JSON Schema for validation and documentation purposes.
3551b80… noreply 564
3551b80… noreply 565 ## Python API for all exporters
3551b80… noreply 566
3551b80… noreply 567 ### Markdown document generation
3551b80… noreply 568
3551b80… noreply 569 ```python
3551b80… noreply 570 from pathlib import Path
3551b80… noreply 571 from video_processor.exporters.markdown import (
3551b80… noreply 572 generate_all,
3551b80… noreply 573 generate_executive_summary,
3551b80… noreply 574 generate_meeting_notes,
3551b80… noreply 575 generate_glossary,
3551b80… noreply 576 generate_relationship_map,
3551b80… noreply 577 generate_status_report,
3551b80… noreply 578 generate_entity_index,
3551b80… noreply 579 generate_csv_export,
3551b80… noreply 580 generate_entity_brief,
3551b80… noreply 581 DOCUMENT_TYPES,
3551b80… noreply 582 )
3551b80… noreply 583 from video_processor.integrators.knowledge_graph import KnowledgeGraph
3551b80… noreply 584
3551b80… noreply 585 kg = KnowledgeGraph(db_path=Path("knowledge_graph.db"))
3551b80… noreply 586 kg_data = kg.to_dict()
3551b80… noreply 587
3551b80… noreply 588 # Generate all document types at once
3551b80… noreply 589 created_files = generate_all(kg_data, Path("./export"))
3551b80… noreply 590
3551b80… noreply 591 # Generate specific document types
3551b80… noreply 592 created_files = generate_all(
3551b80… noreply 593 kg_data,
3551b80… noreply 594 Path("./export"),
3551b80… noreply 595 doc_types=["summary", "glossary", "csv"],
3551b80… noreply 596 )
3551b80… noreply 597
3551b80… noreply 598 # Generate individual documents (returns markdown string)
3551b80… noreply 599 summary = generate_executive_summary(kg_data)
3551b80… noreply 600 notes = generate_meeting_notes(kg_data, title="Sprint Planning")
3551b80… noreply 601 glossary = generate_glossary(kg_data)
3551b80… noreply 602 rel_map = generate_relationship_map(kg_data)
3551b80… noreply 603 status = generate_status_report(kg_data, title="Q1 Status")
3551b80… noreply 604 index = generate_entity_index(kg_data)
3551b80… noreply 605 csv_text = generate_csv_export(kg_data)
3551b80… noreply 606
3551b80… noreply 607 # Generate a brief for a single entity
3551b80… noreply 608 entity = kg_data["nodes"][0]
3551b80… noreply 609 relationships = kg_data["relationships"]
3551b80… noreply 610 brief = generate_entity_brief(entity, relationships)
3551b80… noreply 611 ```
3551b80… noreply 612
3551b80… noreply 613 ### Obsidian export
3551b80… noreply 614
3551b80… noreply 615 ```python
3551b80… noreply 616 from pathlib import Path
3551b80… noreply 617 from video_processor.agent.skills.notes_export import export_to_obsidian
3551b80… noreply 618 from video_processor.integrators.knowledge_graph import KnowledgeGraph
3551b80… noreply 619
3551b80… noreply 620 kg = KnowledgeGraph(db_path=Path("knowledge_graph.db"))
3551b80… noreply 621 kg_data = kg.to_dict()
3551b80… noreply 622
3551b80… noreply 623 created_files = export_to_obsidian(kg_data, Path("./obsidian-vault"))
3551b80… noreply 624 print(f"Created {len(created_files)} files")
3551b80… noreply 625 ```
3551b80… noreply 626
3551b80… noreply 627 ### Notion export
3551b80… noreply 628
3551b80… noreply 629 ```python
3551b80… noreply 630 from pathlib import Path
3551b80… noreply 631 from video_processor.agent.skills.notes_export import export_to_notion_md
3551b80… noreply 632 from video_processor.integrators.knowledge_graph import KnowledgeGraph
3551b80… noreply 633
3551b80… noreply 634 kg = KnowledgeGraph(db_path=Path("knowledge_graph.db"))
3551b80… noreply 635 kg_data = kg.to_dict()
3551b80… noreply 636
3551b80… noreply 637 created_files = export_to_notion_md(kg_data, Path("./notion-export"))
3551b80… noreply 638 ```
3551b80… noreply 639
3551b80… noreply 640 ### Wiki generation
3551b80… noreply 641
3551b80… noreply 642 ```python
3551b80… noreply 643 from pathlib import Path
3551b80… noreply 644 from video_processor.agent.skills.wiki_generator import (
3551b80… noreply 645 generate_wiki,
3551b80… noreply 646 write_wiki,
3551b80… noreply 647 push_wiki,
3551b80… noreply 648 )
3551b80… noreply 649 from video_processor.integrators.knowledge_graph import KnowledgeGraph
3551b80… noreply 650
3551b80… noreply 651 kg = KnowledgeGraph(db_path=Path("knowledge_graph.db"))
3551b80… noreply 652 kg_data = kg.to_dict()
3551b80… noreply 653
3551b80… noreply 654 # Generate pages as a dict of {filename: content}
3551b80… noreply 655 pages = generate_wiki(kg_data, title="Project Wiki")
3551b80… noreply 656
3551b80… noreply 657 # Write to disk
3551b80… noreply 658 written = write_wiki(pages, Path("./wiki"))
3551b80… noreply 659
3551b80… noreply 660 # Push to GitHub (requires git auth)
3551b80… noreply 661 success = push_wiki(Path("./wiki"), "owner/repo", message="Update wiki")
3551b80… noreply 662 ```
3551b80… noreply 663
3551b80… noreply 664 ## Companion REPL
3551b80… noreply 665
3551b80… noreply 666 Inside the interactive companion REPL, use the `/export` command:
3551b80… noreply 667
3551b80… noreply 668 ```
3551b80… noreply 669 > /export markdown
3551b80… noreply 670 Export 'markdown' requested. Use the CLI command:
3551b80… noreply 671 planopticon export markdown ./knowledge_graph.db
3551b80… noreply 672
3551b80… noreply 673 > /export obsidian
3551b80… noreply 674 Export 'obsidian' requested. Use the CLI command:
3551b80… noreply 675 planopticon export obsidian ./knowledge_graph.db
3551b80… noreply 676 ```
3551b80… noreply 677
3551b80… noreply 678 The REPL provides guidance on the CLI command to run; actual export is performed via the CLI.
3551b80… noreply 679
3551b80… noreply 680 ## Common workflows
3551b80… noreply 681
3551b80… noreply 682 ### Analyze videos and export to Obsidian
3551b80… noreply 683
3551b80… noreply 684 ```bash
3551b80… noreply 685 # Analyze meeting recordings
3551b80… noreply 686 planopticon analyze meeting-1.mp4 -o ./results
3551b80… noreply 687 planopticon analyze meeting-2.mp4 --db-path ./results/knowledge_graph.db
3551b80… noreply 688
3551b80… noreply 689 # Ingest supplementary docs
3551b80… noreply 690 planopticon ingest ./specs/ --db-path ./results/knowledge_graph.db
3551b80… noreply 691
3551b80… noreply 692 # Export to Obsidian vault
3551b80… noreply 693 planopticon export obsidian ./results/knowledge_graph.db -o ~/Obsidian/ProjectVault
3551b80… noreply 694
3551b80… noreply 695 # Open in Obsidian and explore the graph view
3551b80… noreply 696 ```
3551b80… noreply 697
3551b80… noreply 698 ### Generate project documentation
3551b80… noreply 699
3551b80… noreply 700 ```bash
3551b80… noreply 701 # Generate all markdown documents
3551b80… noreply 702 planopticon export markdown knowledge_graph.db -o ./docs
3551b80… noreply 703
3551b80… noreply 704 # The output includes:
3551b80… noreply 705 # docs/summary.md - Executive summary
3551b80… noreply 706 # docs/meeting-notes.md - Meeting notes format
3551b80… noreply 707 # docs/glossary.md - Entity glossary
3551b80… noreply 708 # docs/relationship-map.md - Relationships + Mermaid diagram
3551b80… noreply 709 # docs/status-report.md - Project status report
3551b80… noreply 710 # docs/entity-index.md - Master entity index
3551b80… noreply 711 # docs/csv.csv - Spreadsheet-ready CSV
3551b80… noreply 712 # docs/entities/ - Individual entity briefs
3551b80… noreply 713 ```
3551b80… noreply 714
3551b80… noreply 715 ### Publish a GitHub wiki
3551b80… noreply 716
3551b80… noreply 717 ```bash
3551b80… noreply 718 # Generate wiki pages
3551b80… noreply 719 planopticon wiki generate knowledge_graph.db -o ./wiki --title "Project Knowledge Base"
3551b80… noreply 720
3551b80… noreply 721 # Review locally, then push
3551b80… noreply 722 planopticon wiki push ./wiki ConflictHQ/my-project -m "Initial wiki from meeting analysis"
3551b80… noreply 723 ```
3551b80… noreply 724
3551b80… noreply 725 ### Share data between projects
3551b80… noreply 726
3551b80… noreply 727 ```bash
3551b80… noreply 728 # Export from project A
3551b80… noreply 729 planopticon export exchange ./project-a/knowledge_graph.db \
3551b80… noreply 730 -o project-a.json --name "Project A"
3551b80… noreply 731
3551b80… noreply 732 # Export from project B
3551b80… noreply 733 planopticon export exchange ./project-b/knowledge_graph.db \
3551b80… noreply 734 -o project-b.json --name "Project B"
3551b80… noreply 735
3551b80… noreply 736 # Merge in Python
3551b80… noreply 737 python -c "
3551b80… noreply 738 from video_processor.exchange import PlanOpticonExchange
3551b80… noreply 739 a = PlanOpticonExchange.from_file('project-a.json')
3551b80… noreply 740 b = PlanOpticonExchange.from_file('project-b.json')
3551b80… noreply 741 a.merge(b)
3551b80… noreply 742 a.to_file('combined.json')
3551b80… noreply 743 print(f'Combined: {len(a.entities)} entities, {len(a.relationships)} relationships')
3551b80… noreply 744 "
3551b80… noreply 745 ```
3551b80… noreply 746
3551b80… noreply 747 ### Export for spreadsheet analysis
3551b80… noreply 748
3551b80… noreply 749 ```bash
3551b80… noreply 750 # Generate just the CSV
3551b80… noreply 751 planopticon export markdown knowledge_graph.db --type csv -o ./export
3551b80… noreply 752
3551b80… noreply 753 # The file export/csv.csv can be opened in Excel, Google Sheets, etc.
3551b80… noreply 754 ```
3551b80… noreply 755
3551b80… noreply 756 Alternatively, the Notion export includes an `entities_database.csv` that can be imported into any spreadsheet tool or Notion database.

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button