PlanOpticon

docs: comprehensive v0.4.0 documentation and CHANGELOG Update README, all docs/ pages, and create CHANGELOG.md covering: planning agent, companion REPL, 20+ source connectors, OAuth auth, provider registry, exchange format, SQLite migration, and cheap model defaults.

lmata 2026-03-07 23:55 trunk
Commit d13234434adea099463e685818aea09f003c577dce9e5336625b6451a0503e5a
Parent 750b7d8defba039…
9 files changed +71 +105 -33 +83 -6 +41 -12 +561 -11 +47 -4 +80 +174 -1 +24 -4
+ CHANGELOG.md ~ README.md ~ docs/architecture/overview.md ~ docs/architecture/providers.md ~ docs/cli-reference.md ~ docs/getting-started/configuration.md ~ docs/getting-started/quickstart.md ~ docs/guide/cloud-sources.md ~ docs/index.md
A CHANGELOG.md
+71
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -0,0 +1,71 @@
1
+# Changelog
2
+
3
+All notable changes to PlanOpticon are documented in this file.
4
+
5
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+## [0.4.0] - 2026-03-07
9
+
10
+### Added
11
+
12
+- **Planning agent framework** with 11 skills: project_plan, prd, roadmap, task_breakdown, github_integration, requirements_chat, doc_generator, artifact_export, cli_adapter, notes_export, wiki_generator. Invoke via `planopticon agent`.
13
+- **Interactive companion REPL** (`planopticon companion` / `planopticon --chat`) with auto-discovery of knowledge graphs, videos, and documents in the workspace. 15 slash commands for graph exploration, ingestion, export, auth, and runtime provider/model switching.
14
+- **20+ source connectors**: YouTube, Web, GitHub, Reddit, HackerNews, RSS, Podcast, Twitter/X, arXiv, S3, Google Workspace (Docs, Sheets, Slides), Microsoft 365 (SharePoint, OneDrive), Obsidian, Notion, Apple Notes, OneNote, Google Keep, Logseq, Zoom (OAuth), Teams, Google Meet.
15
+- **Pluggable provider registry** supporting 15+ AI providers: OpenAI, Anthropic, Gemini, Ollama, Azure, Together, Fireworks, Cerebras, xAI, Bedrock, Vertex, Mistral, Cohere, AI21, HuggingFace, Qianfan, and LiteLLM.
16
+- **Planning taxonomy classifier** for entity types: goal, requirement, risk, task, milestone, and other planning-specific categories.
17
+- **Unified OAuth manager** (`planopticon auth`) with pre-built configs for Google, Dropbox, Zoom, Notion, GitHub, and Microsoft. Auth chain: saved token, OAuth PKCE, API key fallback.
18
+- **Markdown document generator** producing 7 document types without an LLM: summary, meeting-notes, glossary, relationship-map, status-report, entity-index, csv.
19
+- **Notes export** to Obsidian vaults (YAML frontmatter + wiki-links) and Notion-compatible markdown.
20
+- **GitHub wiki generator** with direct push support.
21
+- **PlanOpticonExchange** canonical JSON interchange format with merge and dedup.
22
+- **Document ingestion pipeline** for PDF, Markdown, and plaintext sources.
23
+- **Knowledge graph viewer** -- self-contained HTML file with inlined D3.js for browser-based graph exploration.
24
+- **Graph query engine** with direct mode (stats, entities, neighbors, relationships) and agentic mode (natural language queries via LLM).
25
+- **Progress callback system** for pipeline status reporting.
26
+
27
+### Changed
28
+
29
+- **SQLite replaces FalkorDB** for knowledge graph storage. Zero external dependencies -- no database server or additional packages required.
30
+- **Default models** now target cheap/fast options: Claude Haiku, GPT-4o-mini, Gemini Flash.
31
+- Output structure updated: `knowledge_graph.db` (SQLite) is now the primary graph file alongside the existing `knowledge_graph.json` export.
32
+
33
+### Fixed
34
+
35
+- 821+ tests passing across the full test suite.
36
+
37
+## [0.3.0] - 2025-12-20
38
+
39
+### Added
40
+
41
+- FalkorDB integration for knowledge graph storage.
42
+- Typed relationships and entity properties in graph data model.
43
+- Relationship existence checks.
44
+
45
+## [0.2.0] - 2025-10-15
46
+
47
+### Added
48
+
49
+- Batch video processing with merged knowledge graphs.
50
+- Cloud sources: Google Drive and Dropbox shared folder fetching.
51
+- Checkpoint/resume for interrupted pipelines.
52
+- PDF report generation.
53
+
54
+## [0.1.0] - 2025-08-01
55
+
56
+### Added
57
+
58
+- Initial release.
59
+- Video analysis with multi-provider AI (OpenAI, Anthropic, Gemini, Ollama).
60
+- Smart frame extraction with change detection.
61
+- People frame filtering via OpenCV face detection.
62
+- Diagram extraction and classification.
63
+- Knowledge graph extraction (entities and relationships).
64
+- Action item detection with assignees and deadlines.
65
+- Markdown and HTML report output.
66
+- Mermaid diagram generation.
67
+
68
+[0.4.0]: https://github.com/ConflictHQ/PlanOpticon/compare/v0.3.0...v0.4.0
69
+[0.3.0]: https://github.com/ConflictHQ/PlanOpticon/compare/v0.2.0...v0.3.0
70
+[0.2.0]: https://github.com/ConflictHQ/PlanOpticon/compare/v0.1.0...v0.2.0
71
+[0.1.0]: https://github.com/ConflictHQ/PlanOpticon/releases/tag/v0.1.0
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -0,0 +1,71 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -0,0 +1,71 @@
1 # Changelog
2
3 All notable changes to PlanOpticon are documented in this file.
4
5 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
8 ## [0.4.0] - 2026-03-07
9
10 ### Added
11
12 - **Planning agent framework** with 11 skills: project_plan, prd, roadmap, task_breakdown, github_integration, requirements_chat, doc_generator, artifact_export, cli_adapter, notes_export, wiki_generator. Invoke via `planopticon agent`.
13 - **Interactive companion REPL** (`planopticon companion` / `planopticon --chat`) with auto-discovery of knowledge graphs, videos, and documents in the workspace. 15 slash commands for graph exploration, ingestion, export, auth, and runtime provider/model switching.
14 - **20+ source connectors**: YouTube, Web, GitHub, Reddit, HackerNews, RSS, Podcast, Twitter/X, arXiv, S3, Google Workspace (Docs, Sheets, Slides), Microsoft 365 (SharePoint, OneDrive), Obsidian, Notion, Apple Notes, OneNote, Google Keep, Logseq, Zoom (OAuth), Teams, Google Meet.
15 - **Pluggable provider registry** supporting 15+ AI providers: OpenAI, Anthropic, Gemini, Ollama, Azure, Together, Fireworks, Cerebras, xAI, Bedrock, Vertex, Mistral, Cohere, AI21, HuggingFace, Qianfan, and LiteLLM.
16 - **Planning taxonomy classifier** for entity types: goal, requirement, risk, task, milestone, and other planning-specific categories.
17 - **Unified OAuth manager** (`planopticon auth`) with pre-built configs for Google, Dropbox, Zoom, Notion, GitHub, and Microsoft. Auth chain: saved token, OAuth PKCE, API key fallback.
18 - **Markdown document generator** producing 7 document types without an LLM: summary, meeting-notes, glossary, relationship-map, status-report, entity-index, csv.
19 - **Notes export** to Obsidian vaults (YAML frontmatter + wiki-links) and Notion-compatible markdown.
20 - **GitHub wiki generator** with direct push support.
21 - **PlanOpticonExchange** canonical JSON interchange format with merge and dedup.
22 - **Document ingestion pipeline** for PDF, Markdown, and plaintext sources.
23 - **Knowledge graph viewer** -- self-contained HTML file with inlined D3.js for browser-based graph exploration.
24 - **Graph query engine** with direct mode (stats, entities, neighbors, relationships) and agentic mode (natural language queries via LLM).
25 - **Progress callback system** for pipeline status reporting.
26
27 ### Changed
28
29 - **SQLite replaces FalkorDB** for knowledge graph storage. Zero external dependencies -- no database server or additional packages required.
30 - **Default models** now target cheap/fast options: Claude Haiku, GPT-4o-mini, Gemini Flash.
31 - Output structure updated: `knowledge_graph.db` (SQLite) is now the primary graph file alongside the existing `knowledge_graph.json` export.
32
33 ### Fixed
34
35 - 821+ tests passing across the full test suite.
36
37 ## [0.3.0] - 2025-12-20
38
39 ### Added
40
41 - FalkorDB integration for knowledge graph storage.
42 - Typed relationships and entity properties in graph data model.
43 - Relationship existence checks.
44
45 ## [0.2.0] - 2025-10-15
46
47 ### Added
48
49 - Batch video processing with merged knowledge graphs.
50 - Cloud sources: Google Drive and Dropbox shared folder fetching.
51 - Checkpoint/resume for interrupted pipelines.
52 - PDF report generation.
53
54 ## [0.1.0] - 2025-08-01
55
56 ### Added
57
58 - Initial release.
59 - Video analysis with multi-provider AI (OpenAI, Anthropic, Gemini, Ollama).
60 - Smart frame extraction with change detection.
61 - People frame filtering via OpenCV face detection.
62 - Diagram extraction and classification.
63 - Knowledge graph extraction (entities and relationships).
64 - Action item detection with assignees and deadlines.
65 - Markdown and HTML report output.
66 - Mermaid diagram generation.
67
68 [0.4.0]: https://github.com/ConflictHQ/PlanOpticon/compare/v0.3.0...v0.4.0
69 [0.3.0]: https://github.com/ConflictHQ/PlanOpticon/compare/v0.2.0...v0.3.0
70 [0.2.0]: https://github.com/ConflictHQ/PlanOpticon/compare/v0.1.0...v0.2.0
71 [0.1.0]: https://github.com/ConflictHQ/PlanOpticon/releases/tag/v0.1.0
M README.md
+105 -33
--- README.md
+++ README.md
@@ -4,31 +4,118 @@
44
 [![PyPI](https://img.shields.io/pypi/v/planopticon)](https://pypi.org/project/planopticon/)
55
 [![Python](https://img.shields.io/pypi/pyversions/planopticon)](https://pypi.org/project/planopticon/)
66
 [![License](https://img.shields.io/github/license/ConflictHQ/PlanOpticon)](LICENSE)
77
 [![Docs](https://img.shields.io/badge/docs-planopticon.dev-blue)](https://planopticon.dev)
88
9
-**AI-powered video analysis and knowledge extraction.**
9
+**AI-powered video analysis, knowledge extraction, and planning.**
1010
11
-PlanOpticon processes video recordings into structured knowledge — transcripts, diagrams, action items, key points, and knowledge graphs. It auto-discovers available models across OpenAI, Anthropic, Gemini, and Ollama, and produces rich multi-format output.
11
+PlanOpticon processes video recordings, documents, and 20+ online sources into structured knowledge graphs, then helps you plan with an AI agent and interactive companion. It auto-discovers models across 15+ AI providers, runs fully offline with Ollama, and produces rich multi-format output.
1212
1313
 ## Features
1414
15
-- **Multi-provider AI** — Auto-discovers and routes to the best available model across OpenAI, Anthropic, Google Gemini, and Ollama (fully offline)
16
-- **Smart frame extraction** — Change detection for transitions + periodic capture for slow-evolving content (document scrolling, screen shares)
17
-- **People frame filtering** — OpenCV face detection automatically removes webcam/video conference frames, keeping only shared content
18
-- **Diagram extraction** — Vision model classification detects flowcharts, architecture diagrams, charts, and whiteboards
19
-- **Knowledge graphs** — Extracts entities and relationships, builds and merges knowledge graphs across videos
20
-- **Action item detection** — Finds commitments, tasks, and follow-ups with assignees and deadlines
21
-- **Batch processing** — Process entire folders of videos with merged knowledge graphs and cross-referencing
22
-- **Rich output** — Markdown, HTML, PDF reports. Mermaid diagrams, SVG/PNG renderings, JSON manifests
23
-- **Cloud sources** — Fetch videos from Google Drive and Dropbox shared folders
24
-- **Checkpoint/resume** — Pipeline resumes from where it left off if interrupted
25
-- **Screengrab fallback** — When extraction isn't perfect, captures frames with captions — something is always better than nothing
15
+- **15+ AI providers** -- OpenAI, Anthropic, Gemini, Ollama, Azure, Together, Fireworks, Cerebras, xAI, Bedrock, Vertex, Mistral, Cohere, AI21, HuggingFace, Qianfan, and LiteLLM. Defaults to cheap models (Haiku, GPT-4o-mini, Gemini Flash).
16
+- **20+ source connectors** -- YouTube, web pages, GitHub, Reddit, HackerNews, RSS, podcasts, arXiv, S3, Google Workspace, Microsoft 365, Obsidian, Notion, Apple Notes, Zoom, Teams, Google Meet, and more.
17
+- **Planning agent** -- 11 skills including project plans, PRDs, roadmaps, task breakdowns, and GitHub integration.
18
+- **Interactive companion** -- Chat REPL with 15 slash commands, auto-discovery of workspace knowledge, and runtime provider/model switching.
19
+- **Knowledge graphs** -- SQLite-backed (zero external deps), entity extraction with planning taxonomy (goals, requirements, risks, tasks, milestones), merge and dedup across sources.
20
+- **Smart video analysis** -- Change-detection frame extraction, face filtering, diagram classification, action item detection, checkpoint/resume.
21
+- **Document ingestion** -- PDF, Markdown, and plaintext pipelines feed the same knowledge graph.
22
+- **Export everywhere** -- Markdown docs (7 types, no LLM required), Obsidian vaults, Notion markdown, GitHub wiki with push, PlanOpticonExchange JSON interchange, HTML/PDF reports, Mermaid diagrams.
23
+- **OAuth-first auth** -- Unified OAuth manager for Google, Dropbox, Zoom, Notion, GitHub, and Microsoft with saved-token / PKCE / API-key fallback chain.
24
+- **Batch processing** -- Process entire folders with merged knowledge graphs and cross-referencing.
25
+
26
+## Quick Start
27
+
28
+```bash
29
+# Install
30
+pip install planopticon
31
+
32
+# Analyze a video
33
+planopticon analyze -i meeting.mp4 -o ./output
34
+
35
+# Ingest a document
36
+planopticon ingest -i spec.pdf -o ./output
37
+
38
+# Fetch from a source
39
+planopticon fetch youtube "https://youtube.com/watch?v=..." -o ./output
40
+
41
+# Process a folder of videos
42
+planopticon batch -i ./recordings -o ./output --title "Weekly Meetings"
43
+
44
+# Query the knowledge graph
45
+planopticon query
46
+planopticon query "entities --type technology"
47
+
48
+# See available AI models
49
+planopticon list-models
50
+```
51
+
52
+## Planning Agent
53
+
54
+Run AI-powered planning skills against your knowledge base:
55
+
56
+```bash
57
+# Generate a project plan from extracted knowledge
58
+planopticon agent "Create a project plan" --kb ./results
59
+
60
+# Build a PRD
61
+planopticon agent "Write a PRD for the authentication system" --kb ./results
62
+
63
+# Break down tasks
64
+planopticon agent "Break this into tasks and estimate effort" --kb ./results
65
+```
66
+
67
+11 skills: `project_plan`, `prd`, `roadmap`, `task_breakdown`, `github_integration`, `requirements_chat`, `doc_generator`, `artifact_export`, `cli_adapter`, `notes_export`, `wiki_generator`.
68
+
69
+## Interactive Companion
70
+
71
+A chat REPL that auto-discovers knowledge graphs, videos, and docs in your workspace:
72
+
73
+```bash
74
+# Launch the companion
75
+planopticon companion
76
+# or
77
+planopticon --chat
78
+```
79
+
80
+15 slash commands: `/help`, `/status`, `/skills`, `/entities`, `/search`, `/neighbors`, `/export`, `/analyze`, `/ingest`, `/auth`, `/provider`, `/model`, `/run`, `/plan`, `/prd`, `/tasks`.
81
+
82
+Switch providers and models at runtime, explore your knowledge graph interactively, or chat with any configured LLM.
83
+
84
+## Source Connectors
85
+
86
+| Category | Sources |
87
+|----------|---------|
88
+| Media | YouTube, Web, Podcasts, RSS |
89
+| Code & Community | GitHub, Reddit, HackerNews, arXiv |
90
+| Cloud Storage | S3, Google Drive, Dropbox |
91
+| Google Workspace | Docs, Sheets, Slides (via gws CLI) |
92
+| Microsoft 365 | SharePoint, OneDrive (via m365 CLI) |
93
+| Notes | Obsidian, Notion, Apple Notes, OneNote, Google Keep, Logseq |
94
+| Meetings | Zoom (OAuth), Teams, Google Meet |
95
+
96
+## Export & Documents
97
+
98
+Generate documents from your knowledge graph without an LLM:
99
+
100
+```bash
101
+planopticon export summary -o ./docs
102
+planopticon export meeting-notes -o ./docs
103
+planopticon export glossary -o ./docs
104
+```
105
+
106
+7 document types: `summary`, `meeting-notes`, `glossary`, `relationship-map`, `status-report`, `entity-index`, `csv`.
107
+
108
+Additional export targets:
109
+- **Obsidian** -- YAML frontmatter + wiki-links vault
110
+- **Notion** -- Compatible markdown
111
+- **GitHub Wiki** -- Generate and push directly
112
+- **PlanOpticonExchange** -- Canonical JSON interchange with merge/dedup
26113
27114
 ## Local Run
28115
29
-PlanOpticon runs entirely offline with Ollama — no API keys, no cloud, no cost.
116
+PlanOpticon runs entirely offline with Ollama -- no API keys, no cloud, no cost.
30117
31118
 > **13.2 hours of video content analyzed, knowledge-graphed, and summarized in ~25 hours of processing time, entirely on local hardware, for free.**
32119
33120
 18 meeting recordings processed on a single machine using `llava` (vision), `qwen3:30b` (chat), and `whisper-large` (transcription via Apple Silicon GPU):
34121
@@ -41,33 +128,17 @@
41128
 | API calls (local) | 1,841 |
42129
 | Tokens processed | 4.87M |
43130
 | Total cost | **$0.00** |
44131
45132
 ```bash
46
-# Fully local analysis — no API keys needed, just Ollama running
133
+# Fully local analysis -- no API keys needed, just Ollama running
47134
 planopticon analyze -i meeting.mp4 -o ./output \
48135
 --provider ollama \
49136
 --vision-model llava:latest \
50137
 --chat-model qwen3:30b
51138
 ```
52139
53
-## Quick Start
54
-
55
-```bash
56
-# Install
57
-pip install planopticon
58
-
59
-# Analyze a single video
60
-planopticon analyze -i meeting.mp4 -o ./output
61
-
62
-# Process a folder of videos
63
-planopticon batch -i ./recordings -o ./output --title "Weekly Meetings"
64
-
65
-# See available AI models
66
-planopticon list-models
67
-```
68
-
69140
 ## Installation
70141
71142
 ### From PyPI
72143
73144
 ```bash
@@ -109,11 +180,12 @@
109180
 ├── captures/ # Screengrab fallbacks
110181
 └── results/
111182
 ├── analysis.md # Markdown report
112183
 ├── analysis.html # HTML report
113184
 ├── analysis.pdf # PDF report
114
- ├── knowledge_graph.json # Entities and relationships
185
+ ├── knowledge_graph.db # SQLite knowledge graph
186
+ ├── knowledge_graph.json # JSON export
115187
 ├── key_points.json # Extracted key points
116188
 └── action_items.json # Tasks and follow-ups
117189
 ```
118190
119191
 ## Processing Depth
@@ -128,6 +200,6 @@
128200
129201
 Full documentation at [planopticon.dev](https://planopticon.dev)
130202
131203
 ## License
132204
133
-MIT License — Copyright (c) 2026 CONFLICT LLC
205
+MIT License -- Copyright (c) 2026 CONFLICT LLC
134206
--- README.md
+++ README.md
@@ -4,31 +4,118 @@
4 [![PyPI](https://img.shields.io/pypi/v/planopticon)](https://pypi.org/project/planopticon/)
5 [![Python](https://img.shields.io/pypi/pyversions/planopticon)](https://pypi.org/project/planopticon/)
6 [![License](https://img.shields.io/github/license/ConflictHQ/PlanOpticon)](LICENSE)
7 [![Docs](https://img.shields.io/badge/docs-planopticon.dev-blue)](https://planopticon.dev)
8
9 **AI-powered video analysis and knowledge extraction.**
10
11 PlanOpticon processes video recordings into structured knowledge — transcripts, diagrams, action items, key points, and knowledge graphs. It auto-discovers available models across OpenAI, Anthropic, Gemini, and Ollama, and produces rich multi-format output.
12
13 ## Features
14
15 - **Multi-provider AI** — Auto-discovers and routes to the best available model across OpenAI, Anthropic, Google Gemini, and Ollama (fully offline)
16 - **Smart frame extraction** — Change detection for transitions + periodic capture for slow-evolving content (document scrolling, screen shares)
17 - **People frame filtering** — OpenCV face detection automatically removes webcam/video conference frames, keeping only shared content
18 - **Diagram extraction** — Vision model classification detects flowcharts, architecture diagrams, charts, and whiteboards
19 - **Knowledge graphs** — Extracts entities and relationships, builds and merges knowledge graphs across videos
20 - **Action item detection** — Finds commitments, tasks, and follow-ups with assignees and deadlines
21 - **Batch processing** — Process entire folders of videos with merged knowledge graphs and cross-referencing
22 - **Rich output** — Markdown, HTML, PDF reports. Mermaid diagrams, SVG/PNG renderings, JSON manifests
23 - **Cloud sources** — Fetch videos from Google Drive and Dropbox shared folders
24 - **Checkpoint/resume** — Pipeline resumes from where it left off if interrupted
25 - **Screengrab fallback** — When extraction isn't perfect, captures frames with captions — something is always better than nothing
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
26
27 ## Local Run
28
29 PlanOpticon runs entirely offline with Ollama — no API keys, no cloud, no cost.
30
31 > **13.2 hours of video content analyzed, knowledge-graphed, and summarized in ~25 hours of processing time, entirely on local hardware, for free.**
32
33 18 meeting recordings processed on a single machine using `llava` (vision), `qwen3:30b` (chat), and `whisper-large` (transcription via Apple Silicon GPU):
34
@@ -41,33 +128,17 @@
41 | API calls (local) | 1,841 |
42 | Tokens processed | 4.87M |
43 | Total cost | **$0.00** |
44
45 ```bash
46 # Fully local analysis — no API keys needed, just Ollama running
47 planopticon analyze -i meeting.mp4 -o ./output \
48 --provider ollama \
49 --vision-model llava:latest \
50 --chat-model qwen3:30b
51 ```
52
53 ## Quick Start
54
55 ```bash
56 # Install
57 pip install planopticon
58
59 # Analyze a single video
60 planopticon analyze -i meeting.mp4 -o ./output
61
62 # Process a folder of videos
63 planopticon batch -i ./recordings -o ./output --title "Weekly Meetings"
64
65 # See available AI models
66 planopticon list-models
67 ```
68
69 ## Installation
70
71 ### From PyPI
72
73 ```bash
@@ -109,11 +180,12 @@
109 ├── captures/ # Screengrab fallbacks
110 └── results/
111 ├── analysis.md # Markdown report
112 ├── analysis.html # HTML report
113 ├── analysis.pdf # PDF report
114 ├── knowledge_graph.json # Entities and relationships
 
115 ├── key_points.json # Extracted key points
116 └── action_items.json # Tasks and follow-ups
117 ```
118
119 ## Processing Depth
@@ -128,6 +200,6 @@
128
129 Full documentation at [planopticon.dev](https://planopticon.dev)
130
131 ## License
132
133 MIT License — Copyright (c) 2026 CONFLICT LLC
134
--- README.md
+++ README.md
@@ -4,31 +4,118 @@
4 [![PyPI](https://img.shields.io/pypi/v/planopticon)](https://pypi.org/project/planopticon/)
5 [![Python](https://img.shields.io/pypi/pyversions/planopticon)](https://pypi.org/project/planopticon/)
6 [![License](https://img.shields.io/github/license/ConflictHQ/PlanOpticon)](LICENSE)
7 [![Docs](https://img.shields.io/badge/docs-planopticon.dev-blue)](https://planopticon.dev)
8
9 **AI-powered video analysis, knowledge extraction, and planning.**
10
11 PlanOpticon processes video recordings, documents, and 20+ online sources into structured knowledge graphs, then helps you plan with an AI agent and interactive companion. It auto-discovers models across 15+ AI providers, runs fully offline with Ollama, and produces rich multi-format output.
12
13 ## Features
14
15 - **15+ AI providers** -- OpenAI, Anthropic, Gemini, Ollama, Azure, Together, Fireworks, Cerebras, xAI, Bedrock, Vertex, Mistral, Cohere, AI21, HuggingFace, Qianfan, and LiteLLM. Defaults to cheap models (Haiku, GPT-4o-mini, Gemini Flash).
16 - **20+ source connectors** -- YouTube, web pages, GitHub, Reddit, HackerNews, RSS, podcasts, arXiv, S3, Google Workspace, Microsoft 365, Obsidian, Notion, Apple Notes, Zoom, Teams, Google Meet, and more.
17 - **Planning agent** -- 11 skills including project plans, PRDs, roadmaps, task breakdowns, and GitHub integration.
18 - **Interactive companion** -- Chat REPL with 15 slash commands, auto-discovery of workspace knowledge, and runtime provider/model switching.
19 - **Knowledge graphs** -- SQLite-backed (zero external deps), entity extraction with planning taxonomy (goals, requirements, risks, tasks, milestones), merge and dedup across sources.
20 - **Smart video analysis** -- Change-detection frame extraction, face filtering, diagram classification, action item detection, checkpoint/resume.
21 - **Document ingestion** -- PDF, Markdown, and plaintext pipelines feed the same knowledge graph.
22 - **Export everywhere** -- Markdown docs (7 types, no LLM required), Obsidian vaults, Notion markdown, GitHub wiki with push, PlanOpticonExchange JSON interchange, HTML/PDF reports, Mermaid diagrams.
23 - **OAuth-first auth** -- Unified OAuth manager for Google, Dropbox, Zoom, Notion, GitHub, and Microsoft with saved-token / PKCE / API-key fallback chain.
24 - **Batch processing** -- Process entire folders with merged knowledge graphs and cross-referencing.
25
26 ## Quick Start
27
28 ```bash
29 # Install
30 pip install planopticon
31
32 # Analyze a video
33 planopticon analyze -i meeting.mp4 -o ./output
34
35 # Ingest a document
36 planopticon ingest -i spec.pdf -o ./output
37
38 # Fetch from a source
39 planopticon fetch youtube "https://youtube.com/watch?v=..." -o ./output
40
41 # Process a folder of videos
42 planopticon batch -i ./recordings -o ./output --title "Weekly Meetings"
43
44 # Query the knowledge graph
45 planopticon query
46 planopticon query "entities --type technology"
47
48 # See available AI models
49 planopticon list-models
50 ```
51
52 ## Planning Agent
53
54 Run AI-powered planning skills against your knowledge base:
55
56 ```bash
57 # Generate a project plan from extracted knowledge
58 planopticon agent "Create a project plan" --kb ./results
59
60 # Build a PRD
61 planopticon agent "Write a PRD for the authentication system" --kb ./results
62
63 # Break down tasks
64 planopticon agent "Break this into tasks and estimate effort" --kb ./results
65 ```
66
67 11 skills: `project_plan`, `prd`, `roadmap`, `task_breakdown`, `github_integration`, `requirements_chat`, `doc_generator`, `artifact_export`, `cli_adapter`, `notes_export`, `wiki_generator`.
68
69 ## Interactive Companion
70
71 A chat REPL that auto-discovers knowledge graphs, videos, and docs in your workspace:
72
73 ```bash
74 # Launch the companion
75 planopticon companion
76 # or
77 planopticon --chat
78 ```
79
80 15 slash commands: `/help`, `/status`, `/skills`, `/entities`, `/search`, `/neighbors`, `/export`, `/analyze`, `/ingest`, `/auth`, `/provider`, `/model`, `/run`, `/plan`, `/prd`, `/tasks`.
81
82 Switch providers and models at runtime, explore your knowledge graph interactively, or chat with any configured LLM.
83
84 ## Source Connectors
85
86 | Category | Sources |
87 |----------|---------|
88 | Media | YouTube, Web, Podcasts, RSS |
89 | Code & Community | GitHub, Reddit, HackerNews, arXiv |
90 | Cloud Storage | S3, Google Drive, Dropbox |
91 | Google Workspace | Docs, Sheets, Slides (via gws CLI) |
92 | Microsoft 365 | SharePoint, OneDrive (via m365 CLI) |
93 | Notes | Obsidian, Notion, Apple Notes, OneNote, Google Keep, Logseq |
94 | Meetings | Zoom (OAuth), Teams, Google Meet |
95
96 ## Export & Documents
97
98 Generate documents from your knowledge graph without an LLM:
99
100 ```bash
101 planopticon export summary -o ./docs
102 planopticon export meeting-notes -o ./docs
103 planopticon export glossary -o ./docs
104 ```
105
106 7 document types: `summary`, `meeting-notes`, `glossary`, `relationship-map`, `status-report`, `entity-index`, `csv`.
107
108 Additional export targets:
109 - **Obsidian** -- YAML frontmatter + wiki-links vault
110 - **Notion** -- Compatible markdown
111 - **GitHub Wiki** -- Generate and push directly
112 - **PlanOpticonExchange** -- Canonical JSON interchange with merge/dedup
113
114 ## Local Run
115
116 PlanOpticon runs entirely offline with Ollama -- no API keys, no cloud, no cost.
117
118 > **13.2 hours of video content analyzed, knowledge-graphed, and summarized in ~25 hours of processing time, entirely on local hardware, for free.**
119
120 18 meeting recordings processed on a single machine using `llava` (vision), `qwen3:30b` (chat), and `whisper-large` (transcription via Apple Silicon GPU):
121
@@ -41,33 +128,17 @@
128 | API calls (local) | 1,841 |
129 | Tokens processed | 4.87M |
130 | Total cost | **$0.00** |
131
132 ```bash
133 # Fully local analysis -- no API keys needed, just Ollama running
134 planopticon analyze -i meeting.mp4 -o ./output \
135 --provider ollama \
136 --vision-model llava:latest \
137 --chat-model qwen3:30b
138 ```
139
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
140 ## Installation
141
142 ### From PyPI
143
144 ```bash
@@ -109,11 +180,12 @@
180 ├── captures/ # Screengrab fallbacks
181 └── results/
182 ├── analysis.md # Markdown report
183 ├── analysis.html # HTML report
184 ├── analysis.pdf # PDF report
185 ├── knowledge_graph.db # SQLite knowledge graph
186 ├── knowledge_graph.json # JSON export
187 ├── key_points.json # Extracted key points
188 └── action_items.json # Tasks and follow-ups
189 ```
190
191 ## Processing Depth
@@ -128,6 +200,6 @@
200
201 Full documentation at [planopticon.dev](https://planopticon.dev)
202
203 ## License
204
205 MIT License -- Copyright (c) 2026 CONFLICT LLC
206
M docs/architecture/overview.md
+83 -6
--- docs/architecture/overview.md
+++ docs/architecture/overview.md
@@ -2,67 +2,144 @@
22
33
 ## System diagram
44
55
 ```mermaid
66
 graph TD
7
- A[Video Input] --> B[Frame Extractor]
7
+ subgraph Sources
8
+ S1[Video Files]
9
+ S2[Google Workspace]
10
+ S3[Microsoft 365]
11
+ S4[Zoom / Teams / Meet]
12
+ S5[YouTube]
13
+ S6[Notes — Obsidian / Notion / Apple Notes]
14
+ S7[GitHub]
15
+ end
16
+
17
+ subgraph Source Connectors
18
+ SC[Source Connectors + OAuth]
19
+ end
20
+
21
+ S1 --> SC
22
+ S2 --> SC
23
+ S3 --> SC
24
+ S4 --> SC
25
+ S5 --> SC
26
+ S6 --> SC
27
+ S7 --> SC
28
+
29
+ SC --> A[Ingest / Analyze Pipeline]
30
+
31
+ A --> B[Frame Extractor]
832
 A --> C[Audio Extractor]
933
 B --> D[Diagram Analyzer]
1034
 C --> E[Transcription]
1135
 D --> F[Knowledge Graph]
1236
 E --> F
1337
 E --> G[Key Point Extractor]
1438
 E --> H[Action Item Detector]
1539
 D --> I[Content Analyzer]
1640
 E --> I
41
+
42
+ subgraph Agent & Skills
43
+ AG[Planning Agent]
44
+ SK[Skill Registry]
45
+ CO[Companion REPL]
46
+ end
47
+
48
+ F --> AG
49
+ G --> AG
50
+ H --> AG
51
+ I --> AG
52
+ AG --> SK
53
+ F --> CO
54
+
1755
 F --> J[Plan Generator]
1856
 G --> J
1957
 H --> J
2058
 I --> J
21
- J --> K[Markdown Report]
22
- J --> L[HTML Report]
23
- J --> M[PDF Report]
24
- D --> N[Mermaid/SVG/PNG Export]
59
+
60
+ subgraph Output & Export
61
+ J --> K[Markdown Report]
62
+ J --> L[HTML Report]
63
+ J --> M[PDF Report]
64
+ D --> N[Mermaid/SVG/PNG Export]
65
+ EX[Exporters — Obsidian / Notion / Exchange / Wiki]
66
+ end
67
+
68
+ AG --> EX
69
+ F --> EX
2570
 ```
2671
2772
 ## Module structure
2873
2974
 ```
3075
 video_processor/
3176
 ├── cli/ # CLI commands (Click)
3277
 │ └── commands.py
78
+├── sources/ # Source connectors
79
+│ ├── gdrive.py # Google Drive
80
+│ ├── gws.py # Google Workspace (Docs, Sheets, Slides, Meet)
81
+│ ├── m365.py # Microsoft 365 (OneDrive, SharePoint, Teams)
82
+│ ├── dropbox.py # Dropbox
83
+│ ├── zoom.py # Zoom recordings
84
+│ ├── youtube.py # YouTube videos
85
+│ ├── notion.py # Notion pages
86
+│ ├── github.py # GitHub repos / wikis
87
+│ ├── obsidian.py # Obsidian vaults
88
+│ └── apple_notes.py # Apple Notes (macOS)
3389
 ├── extractors/ # Media extraction
3490
 │ ├── frame_extractor.py # Video → frames
3591
 │ └── audio_extractor.py # Video → WAV
3692
 ├── analyzers/ # AI-powered analysis
3793
 │ ├── diagram_analyzer.py # Frame classification + extraction
3894
 │ ├── content_analyzer.py # Cross-referencing
3995
 │ └── action_detector.py # Action item detection
4096
 ├── integrators/ # Knowledge assembly
4197
 │ ├── knowledge_graph.py # Entity/relationship graph
98
+│ ├── graph_query.py # Query engine
4299
 │ └── plan_generator.py # Report generation
100
+├── agent/ # Planning agent
101
+│ ├── agent.py # Agent loop
102
+│ ├── skills.py # Skill registry
103
+│ └── companion.py # Companion REPL
104
+├── exporters/ # Export formats
105
+│ ├── markdown.py # Markdown export
106
+│ ├── obsidian.py # Obsidian vault export
107
+│ ├── notion.py # Notion export
108
+│ ├── wiki.py # Wiki generation + push
109
+│ └── exchange.py # PlanOpticon Exchange Format
43110
 ├── providers/ # AI provider abstraction
44111
 │ ├── base.py # BaseProvider ABC
45112
 │ ├── openai_provider.py
46113
 │ ├── anthropic_provider.py
47114
 │ ├── gemini_provider.py
48115
 │ ├── ollama_provider.py # Local Ollama (offline)
116
+│ ├── azure_provider.py # Azure OpenAI
117
+│ ├── together_provider.py
118
+│ ├── fireworks_provider.py
119
+│ ├── cerebras_provider.py
120
+│ ├── xai_provider.py # xAI / Grok
49121
 │ ├── discovery.py # Auto-model-discovery
50122
 │ └── manager.py # ProviderManager routing
51123
 ├── utils/
52124
 │ ├── json_parsing.py # Robust LLM JSON parsing
53125
 │ ├── rendering.py # Mermaid + chart rendering
54126
 │ ├── export.py # HTML/PDF export
55127
 │ ├── api_cache.py # Disk-based response cache
56128
 │ └── prompt_templates.py # LLM prompt management
129
+├── auth.py # OAuth flow management
130
+├── exchange.py # Exchange format schema
57131
 ├── models.py # Pydantic data models
58132
 ├── output_structure.py # Directory layout + manifest I/O
59133
 └── pipeline.py # Core processing pipeline
60134
 ```
61135
62136
 ## Key design decisions
63137
64138
 - **Pydantic everywhere** — All structured data uses pydantic models for validation and serialization
65139
 - **Manifest-driven** — Every run produces `manifest.json` as the single source of truth
66
-- **Provider abstraction** — Single `ProviderManager` wraps OpenAI, Anthropic, Gemini, and Ollama behind a common interface
140
+- **Provider abstraction** — Single `ProviderManager` wraps OpenAI, Anthropic, Gemini, Ollama, and additional providers behind a common interface
67141
 - **No hardcoded models** — Model lists come from API discovery
68142
 - **Screengrab fallback** — When extraction fails, save the frame as a captioned screenshot
143
+- **OAuth-first auth** — All cloud service integrations use OAuth via `planopticon auth`, with credentials stored locally. Service account keys are supported as a fallback for server-side automation
144
+- **Skill registry** — The planning agent discovers and invokes skills dynamically. Skills are self-describing and can be composed by the agent to accomplish complex tasks
145
+- **Exchange format** — A portable JSON format (`exchange.py`) for importing and exporting knowledge graphs between PlanOpticon instances and external tools
69146
--- docs/architecture/overview.md
+++ docs/architecture/overview.md
@@ -2,67 +2,144 @@
2
3 ## System diagram
4
5 ```mermaid
6 graph TD
7 A[Video Input] --> B[Frame Extractor]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
8 A --> C[Audio Extractor]
9 B --> D[Diagram Analyzer]
10 C --> E[Transcription]
11 D --> F[Knowledge Graph]
12 E --> F
13 E --> G[Key Point Extractor]
14 E --> H[Action Item Detector]
15 D --> I[Content Analyzer]
16 E --> I
 
 
 
 
 
 
 
 
 
 
 
 
 
 
17 F --> J[Plan Generator]
18 G --> J
19 H --> J
20 I --> J
21 J --> K[Markdown Report]
22 J --> L[HTML Report]
23 J --> M[PDF Report]
24 D --> N[Mermaid/SVG/PNG Export]
 
 
 
 
 
 
 
25 ```
26
27 ## Module structure
28
29 ```
30 video_processor/
31 ├── cli/ # CLI commands (Click)
32 │ └── commands.py
 
 
 
 
 
 
 
 
 
 
 
33 ├── extractors/ # Media extraction
34 │ ├── frame_extractor.py # Video → frames
35 │ └── audio_extractor.py # Video → WAV
36 ├── analyzers/ # AI-powered analysis
37 │ ├── diagram_analyzer.py # Frame classification + extraction
38 │ ├── content_analyzer.py # Cross-referencing
39 │ └── action_detector.py # Action item detection
40 ├── integrators/ # Knowledge assembly
41 │ ├── knowledge_graph.py # Entity/relationship graph
 
42 │ └── plan_generator.py # Report generation
 
 
 
 
 
 
 
 
 
 
43 ├── providers/ # AI provider abstraction
44 │ ├── base.py # BaseProvider ABC
45 │ ├── openai_provider.py
46 │ ├── anthropic_provider.py
47 │ ├── gemini_provider.py
48 │ ├── ollama_provider.py # Local Ollama (offline)
 
 
 
 
 
49 │ ├── discovery.py # Auto-model-discovery
50 │ └── manager.py # ProviderManager routing
51 ├── utils/
52 │ ├── json_parsing.py # Robust LLM JSON parsing
53 │ ├── rendering.py # Mermaid + chart rendering
54 │ ├── export.py # HTML/PDF export
55 │ ├── api_cache.py # Disk-based response cache
56 │ └── prompt_templates.py # LLM prompt management
 
 
57 ├── models.py # Pydantic data models
58 ├── output_structure.py # Directory layout + manifest I/O
59 └── pipeline.py # Core processing pipeline
60 ```
61
62 ## Key design decisions
63
64 - **Pydantic everywhere** — All structured data uses pydantic models for validation and serialization
65 - **Manifest-driven** — Every run produces `manifest.json` as the single source of truth
66 - **Provider abstraction** — Single `ProviderManager` wraps OpenAI, Anthropic, Gemini, and Ollama behind a common interface
67 - **No hardcoded models** — Model lists come from API discovery
68 - **Screengrab fallback** — When extraction fails, save the frame as a captioned screenshot
 
 
 
69
--- docs/architecture/overview.md
+++ docs/architecture/overview.md
@@ -2,67 +2,144 @@
2
3 ## System diagram
4
5 ```mermaid
6 graph TD
7 subgraph Sources
8 S1[Video Files]
9 S2[Google Workspace]
10 S3[Microsoft 365]
11 S4[Zoom / Teams / Meet]
12 S5[YouTube]
13 S6[Notes — Obsidian / Notion / Apple Notes]
14 S7[GitHub]
15 end
16
17 subgraph Source Connectors
18 SC[Source Connectors + OAuth]
19 end
20
21 S1 --> SC
22 S2 --> SC
23 S3 --> SC
24 S4 --> SC
25 S5 --> SC
26 S6 --> SC
27 S7 --> SC
28
29 SC --> A[Ingest / Analyze Pipeline]
30
31 A --> B[Frame Extractor]
32 A --> C[Audio Extractor]
33 B --> D[Diagram Analyzer]
34 C --> E[Transcription]
35 D --> F[Knowledge Graph]
36 E --> F
37 E --> G[Key Point Extractor]
38 E --> H[Action Item Detector]
39 D --> I[Content Analyzer]
40 E --> I
41
42 subgraph Agent & Skills
43 AG[Planning Agent]
44 SK[Skill Registry]
45 CO[Companion REPL]
46 end
47
48 F --> AG
49 G --> AG
50 H --> AG
51 I --> AG
52 AG --> SK
53 F --> CO
54
55 F --> J[Plan Generator]
56 G --> J
57 H --> J
58 I --> J
59
60 subgraph Output & Export
61 J --> K[Markdown Report]
62 J --> L[HTML Report]
63 J --> M[PDF Report]
64 D --> N[Mermaid/SVG/PNG Export]
65 EX[Exporters — Obsidian / Notion / Exchange / Wiki]
66 end
67
68 AG --> EX
69 F --> EX
70 ```
71
72 ## Module structure
73
74 ```
75 video_processor/
76 ├── cli/ # CLI commands (Click)
77 │ └── commands.py
78 ├── sources/ # Source connectors
79 │ ├── gdrive.py # Google Drive
80 │ ├── gws.py # Google Workspace (Docs, Sheets, Slides, Meet)
81 │ ├── m365.py # Microsoft 365 (OneDrive, SharePoint, Teams)
82 │ ├── dropbox.py # Dropbox
83 │ ├── zoom.py # Zoom recordings
84 │ ├── youtube.py # YouTube videos
85 │ ├── notion.py # Notion pages
86 │ ├── github.py # GitHub repos / wikis
87 │ ├── obsidian.py # Obsidian vaults
88 │ └── apple_notes.py # Apple Notes (macOS)
89 ├── extractors/ # Media extraction
90 │ ├── frame_extractor.py # Video → frames
91 │ └── audio_extractor.py # Video → WAV
92 ├── analyzers/ # AI-powered analysis
93 │ ├── diagram_analyzer.py # Frame classification + extraction
94 │ ├── content_analyzer.py # Cross-referencing
95 │ └── action_detector.py # Action item detection
96 ├── integrators/ # Knowledge assembly
97 │ ├── knowledge_graph.py # Entity/relationship graph
98 │ ├── graph_query.py # Query engine
99 │ └── plan_generator.py # Report generation
100 ├── agent/ # Planning agent
101 │ ├── agent.py # Agent loop
102 │ ├── skills.py # Skill registry
103 │ └── companion.py # Companion REPL
104 ├── exporters/ # Export formats
105 │ ├── markdown.py # Markdown export
106 │ ├── obsidian.py # Obsidian vault export
107 │ ├── notion.py # Notion export
108 │ ├── wiki.py # Wiki generation + push
109 │ └── exchange.py # PlanOpticon Exchange Format
110 ├── providers/ # AI provider abstraction
111 │ ├── base.py # BaseProvider ABC
112 │ ├── openai_provider.py
113 │ ├── anthropic_provider.py
114 │ ├── gemini_provider.py
115 │ ├── ollama_provider.py # Local Ollama (offline)
116 │ ├── azure_provider.py # Azure OpenAI
117 │ ├── together_provider.py
118 │ ├── fireworks_provider.py
119 │ ├── cerebras_provider.py
120 │ ├── xai_provider.py # xAI / Grok
121 │ ├── discovery.py # Auto-model-discovery
122 │ └── manager.py # ProviderManager routing
123 ├── utils/
124 │ ├── json_parsing.py # Robust LLM JSON parsing
125 │ ├── rendering.py # Mermaid + chart rendering
126 │ ├── export.py # HTML/PDF export
127 │ ├── api_cache.py # Disk-based response cache
128 │ └── prompt_templates.py # LLM prompt management
129 ├── auth.py # OAuth flow management
130 ├── exchange.py # Exchange format schema
131 ├── models.py # Pydantic data models
132 ├── output_structure.py # Directory layout + manifest I/O
133 └── pipeline.py # Core processing pipeline
134 ```
135
136 ## Key design decisions
137
138 - **Pydantic everywhere** — All structured data uses pydantic models for validation and serialization
139 - **Manifest-driven** — Every run produces `manifest.json` as the single source of truth
140 - **Provider abstraction** — Single `ProviderManager` wraps OpenAI, Anthropic, Gemini, Ollama, and additional providers behind a common interface
141 - **No hardcoded models** — Model lists come from API discovery
142 - **Screengrab fallback** — When extraction fails, save the frame as a captioned screenshot
143 - **OAuth-first auth** — All cloud service integrations use OAuth via `planopticon auth`, with credentials stored locally. Service account keys are supported as a fallback for server-side automation
144 - **Skill registry** — The planning agent discovers and invokes skills dynamically. Skills are self-describing and can be composed by the agent to accomplish complex tasks
145 - **Exchange format** — A portable JSON format (`exchange.py`) for importing and exporting knowledge graphs between PlanOpticon instances and external tools
146
M docs/architecture/providers.md
+41 -12
--- docs/architecture/providers.md
+++ docs/architecture/providers.md
@@ -1,19 +1,36 @@
11
 # Provider System
22
33
 ## Overview
44
5
-PlanOpticon supports multiple AI providers through a unified abstraction layer.
5
+PlanOpticon supports multiple AI providers through a unified abstraction layer. Default models favor cost-effective options (Haiku, GPT-4o-mini, Gemini Flash) for routine tasks, with more capable models available when needed.
66
77
 ## Supported providers
88
9
-| Provider | Chat | Vision | Transcription |
10
-|----------|------|--------|--------------|
11
-| OpenAI | GPT-4o, GPT-4 | GPT-4o | Whisper-1 |
12
-| Anthropic | Claude Sonnet/Opus | Claude Sonnet/Opus | — |
13
-| Google Gemini | Gemini Flash/Pro | Gemini Flash/Pro | Gemini Flash |
14
-| Ollama (local) | Any installed model | llava, moondream, etc. | — (use local Whisper) |
9
+| Provider | Chat | Vision | Transcription | Env Variable |
10
+|----------|------|--------|--------------|--------------|
11
+| OpenAI | GPT-4o-mini, GPT-4o | GPT-4o-mini, GPT-4o | Whisper-1 | `OPENAI_API_KEY` |
12
+| Anthropic | Claude Haiku, Sonnet, Opus | Claude Haiku, Sonnet, Opus | — | `ANTHROPIC_API_KEY` |
13
+| Google Gemini | Gemini Flash, Pro | Gemini Flash, Pro | Gemini Flash | `GEMINI_API_KEY` |
14
+| Azure OpenAI | GPT-4o-mini, GPT-4o | GPT-4o-mini, GPT-4o | Whisper-1 | `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT` |
15
+| Together AI | Llama, Mixtral, etc. | Llava | — | `TOGETHER_API_KEY` |
16
+| Fireworks AI | Llama, Mixtral, etc. | Llava | — | `FIREWORKS_API_KEY` |
17
+| Cerebras | Llama (fast inference) | — | — | `CEREBRAS_API_KEY` |
18
+| xAI | Grok | Grok | — | `XAI_API_KEY` |
19
+| Ollama (local) | Any installed model | llava, moondream, etc. | — (use local Whisper) | `OLLAMA_HOST` |
20
+
21
+## Default models
22
+
23
+PlanOpticon defaults to cheap, fast models for cost efficiency:
24
+
25
+| Task | Default model |
26
+|------|--------------|
27
+| Vision (diagrams) | Gemini Flash |
28
+| Chat (analysis) | Claude Haiku |
29
+| Transcription | Local Whisper (fallback: Whisper-1) |
30
+
31
+Use `--vision-model` and `--chat-model` to override with more capable models when needed (e.g., `--chat-model claude-sonnet-4-20250514` for complex analysis).
1532
1633
 ## Ollama (offline mode)
1734
1835
 [Ollama](https://ollama.com) enables fully offline operation with no API keys required. PlanOpticon connects via Ollama's OpenAI-compatible API.
1936
@@ -51,31 +68,43 @@
5168
 # Automatically discovers models from all configured providers + Ollama
5269
 ```
5370
5471
 ## Routing preferences
5572
56
-Each task type has a default preference order:
73
+Each task type has a default preference order (cheapest first):
5774
5875
 | Task | Preference |
5976
 |------|-----------|
60
-| Vision | Gemini Flash → GPT-4o → Claude Sonnet → Ollama |
61
-| Chat | Claude Sonnet → GPT-4o → Gemini Flash → Ollama |
77
+| Vision | Gemini Flash → GPT-4o-mini → Claude Haiku → Ollama |
78
+| Chat | Claude Haiku → GPT-4o-mini → Gemini Flash → Ollama |
6279
 | Transcription | Local Whisper → Whisper-1 → Gemini Flash |
6380
64
-Ollama acts as the last-resort fallback — if no cloud API keys are set but Ollama is running, it is used automatically.
81
+Ollama acts as the last-resort fallback -- if no cloud API keys are set but Ollama is running, it is used automatically.
6582
6683
 ## Manual override
6784
6885
 ```python
6986
 pm = ProviderManager(
7087
 vision_model="gpt-4o",
71
- chat_model="claude-sonnet-4-5-20250929",
88
+ chat_model="claude-sonnet-4-20250514",
7289
 provider="openai", # Force a specific provider
7390
 )
91
+
92
+# Use a cheap model for bulk processing
93
+pm = ProviderManager(
94
+ chat_model="claude-haiku-3-5-20241022",
95
+ vision_model="gemini-2.0-flash",
96
+)
7497
7598
 # Or use Ollama for fully offline processing
7699
 pm = ProviderManager(provider="ollama")
100
+
101
+# Use Azure OpenAI
102
+pm = ProviderManager(provider="azure")
103
+
104
+# Use Together AI for open-source models
105
+pm = ProviderManager(provider="together", chat_model="meta-llama/Llama-3.3-70B-Instruct-Turbo")
77106
 ```
78107
79108
 ## BaseProvider interface
80109
81110
 All providers implement:
82111
--- docs/architecture/providers.md
+++ docs/architecture/providers.md
@@ -1,19 +1,36 @@
1 # Provider System
2
3 ## Overview
4
5 PlanOpticon supports multiple AI providers through a unified abstraction layer.
6
7 ## Supported providers
8
9 | Provider | Chat | Vision | Transcription |
10 |----------|------|--------|--------------|
11 | OpenAI | GPT-4o, GPT-4 | GPT-4o | Whisper-1 |
12 | Anthropic | Claude Sonnet/Opus | Claude Sonnet/Opus | — |
13 | Google Gemini | Gemini Flash/Pro | Gemini Flash/Pro | Gemini Flash |
14 | Ollama (local) | Any installed model | llava, moondream, etc. | — (use local Whisper) |
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
15
16 ## Ollama (offline mode)
17
18 [Ollama](https://ollama.com) enables fully offline operation with no API keys required. PlanOpticon connects via Ollama's OpenAI-compatible API.
19
@@ -51,31 +68,43 @@
51 # Automatically discovers models from all configured providers + Ollama
52 ```
53
54 ## Routing preferences
55
56 Each task type has a default preference order:
57
58 | Task | Preference |
59 |------|-----------|
60 | Vision | Gemini Flash → GPT-4o → Claude Sonnet → Ollama |
61 | Chat | Claude Sonnet → GPT-4o → Gemini Flash → Ollama |
62 | Transcription | Local Whisper → Whisper-1 → Gemini Flash |
63
64 Ollama acts as the last-resort fallback — if no cloud API keys are set but Ollama is running, it is used automatically.
65
66 ## Manual override
67
68 ```python
69 pm = ProviderManager(
70 vision_model="gpt-4o",
71 chat_model="claude-sonnet-4-5-20250929",
72 provider="openai", # Force a specific provider
73 )
 
 
 
 
 
 
74
75 # Or use Ollama for fully offline processing
76 pm = ProviderManager(provider="ollama")
 
 
 
 
 
 
77 ```
78
79 ## BaseProvider interface
80
81 All providers implement:
82
--- docs/architecture/providers.md
+++ docs/architecture/providers.md
@@ -1,19 +1,36 @@
1 # Provider System
2
3 ## Overview
4
5 PlanOpticon supports multiple AI providers through a unified abstraction layer. Default models favor cost-effective options (Haiku, GPT-4o-mini, Gemini Flash) for routine tasks, with more capable models available when needed.
6
7 ## Supported providers
8
9 | Provider | Chat | Vision | Transcription | Env Variable |
10 |----------|------|--------|--------------|--------------|
11 | OpenAI | GPT-4o-mini, GPT-4o | GPT-4o-mini, GPT-4o | Whisper-1 | `OPENAI_API_KEY` |
12 | Anthropic | Claude Haiku, Sonnet, Opus | Claude Haiku, Sonnet, Opus | — | `ANTHROPIC_API_KEY` |
13 | Google Gemini | Gemini Flash, Pro | Gemini Flash, Pro | Gemini Flash | `GEMINI_API_KEY` |
14 | Azure OpenAI | GPT-4o-mini, GPT-4o | GPT-4o-mini, GPT-4o | Whisper-1 | `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT` |
15 | Together AI | Llama, Mixtral, etc. | Llava | — | `TOGETHER_API_KEY` |
16 | Fireworks AI | Llama, Mixtral, etc. | Llava | — | `FIREWORKS_API_KEY` |
17 | Cerebras | Llama (fast inference) | — | — | `CEREBRAS_API_KEY` |
18 | xAI | Grok | Grok | — | `XAI_API_KEY` |
19 | Ollama (local) | Any installed model | llava, moondream, etc. | — (use local Whisper) | `OLLAMA_HOST` |
20
21 ## Default models
22
23 PlanOpticon defaults to cheap, fast models for cost efficiency:
24
25 | Task | Default model |
26 |------|--------------|
27 | Vision (diagrams) | Gemini Flash |
28 | Chat (analysis) | Claude Haiku |
29 | Transcription | Local Whisper (fallback: Whisper-1) |
30
31 Use `--vision-model` and `--chat-model` to override with more capable models when needed (e.g., `--chat-model claude-sonnet-4-20250514` for complex analysis).
32
33 ## Ollama (offline mode)
34
35 [Ollama](https://ollama.com) enables fully offline operation with no API keys required. PlanOpticon connects via Ollama's OpenAI-compatible API.
36
@@ -51,31 +68,43 @@
68 # Automatically discovers models from all configured providers + Ollama
69 ```
70
71 ## Routing preferences
72
73 Each task type has a default preference order (cheapest first):
74
75 | Task | Preference |
76 |------|-----------|
77 | Vision | Gemini Flash → GPT-4o-mini → Claude Haiku → Ollama |
78 | Chat | Claude Haiku → GPT-4o-mini → Gemini Flash → Ollama |
79 | Transcription | Local Whisper → Whisper-1 → Gemini Flash |
80
81 Ollama acts as the last-resort fallback -- if no cloud API keys are set but Ollama is running, it is used automatically.
82
83 ## Manual override
84
85 ```python
86 pm = ProviderManager(
87 vision_model="gpt-4o",
88 chat_model="claude-sonnet-4-20250514",
89 provider="openai", # Force a specific provider
90 )
91
92 # Use a cheap model for bulk processing
93 pm = ProviderManager(
94 chat_model="claude-haiku-3-5-20241022",
95 vision_model="gemini-2.0-flash",
96 )
97
98 # Or use Ollama for fully offline processing
99 pm = ProviderManager(provider="ollama")
100
101 # Use Azure OpenAI
102 pm = ProviderManager(provider="azure")
103
104 # Use Together AI for open-source models
105 pm = ProviderManager(provider="together", chat_model="meta-llama/Llama-3.3-70B-Instruct-Turbo")
106 ```
107
108 ## BaseProvider interface
109
110 All providers implement:
111
M docs/cli-reference.md
+561 -11
--- docs/cli-reference.md
+++ docs/cli-reference.md
@@ -1,6 +1,20 @@
11
 # CLI Reference
2
+
3
+## Global options
4
+
5
+These options are available on all commands.
6
+
7
+| Option | Description |
8
+|--------|-------------|
9
+| `-v`, `--verbose` | Enable debug-level logging |
10
+| `-C`, `--chat` | Enable chat mode (interactive follow-up after command completes) |
11
+| `-I`, `--interactive` | Enable interactive REPL mode |
12
+| `--version` | Show version and exit |
13
+| `--help` | Show help and exit |
14
+
15
+---
216
317
 ## `planopticon analyze`
418
519
 Analyze a single video and extract structured knowledge.
620
@@ -95,39 +109,575 @@
95109
 | `-p`, `--provider` | `auto\|openai\|anthropic\|gemini\|ollama` | `auto` | API provider |
96110
 | `--vision-model` | TEXT | auto | Override vision model |
97111
 | `--chat-model` | TEXT | auto | Override chat model |
98112
99113
 ---
114
+
115
+## `planopticon companion`
116
+
117
+Interactive knowledge base companion. Opens a REPL for conversational exploration of your knowledge base.
118
+
119
+```bash
120
+planopticon companion [OPTIONS]
121
+```
122
+
123
+| Option | Type | Default | Description |
124
+|--------|------|---------|-------------|
125
+| `--kb` | PATH | auto-detect | Path to knowledge base directory |
126
+| `-p`, `--provider` | TEXT | `auto` | AI provider |
127
+| `--chat-model` | TEXT | auto | Override chat model |
128
+
129
+**Examples:**
130
+
131
+```bash
132
+# Start companion with auto-detected knowledge base
133
+planopticon companion
134
+
135
+# Point to a specific knowledge base
136
+planopticon companion --kb ./my-kb
137
+
138
+# Use a specific provider
139
+planopticon companion --kb ./kb --provider anthropic --chat-model claude-sonnet-4-20250514
140
+```
141
+
142
+---
143
+
144
+## `planopticon agent`
145
+
146
+Planning agent with adaptive analysis. Runs an agentic loop that reasons about your knowledge base, plans actions, and executes them.
147
+
148
+```bash
149
+planopticon agent [OPTIONS]
150
+```
151
+
152
+| Option | Type | Default | Description |
153
+|--------|------|---------|-------------|
154
+| `--kb` | PATH | auto-detect | Path to knowledge base directory |
155
+| `-I`, `--interactive` | FLAG | off | Interactive mode (ask before each action) |
156
+| `--export` | PATH | none | Export agent results to a file |
157
+| `-p`, `--provider` | TEXT | `auto` | AI provider |
158
+| `--chat-model` | TEXT | auto | Override chat model |
159
+
160
+**Examples:**
161
+
162
+```bash
163
+# Run the agent interactively
164
+planopticon agent --kb ./kb --interactive
165
+
166
+# Run agent and export results
167
+planopticon agent --kb ./kb --export ./plan.md
168
+
169
+# Use a specific model
170
+planopticon agent --kb ./kb --provider openai --chat-model gpt-4o
171
+```
172
+
173
+---
174
+
175
+## `planopticon query`
176
+
177
+Query the knowledge graph directly or with natural language.
178
+
179
+```bash
180
+planopticon query [OPTIONS] [QUERY]
181
+```
182
+
183
+| Option | Type | Default | Description |
184
+|--------|------|---------|-------------|
185
+| `--db-path` | PATH | auto-detect | Path to knowledge graph database |
186
+| `--mode` | `direct\|agentic` | auto | Query mode (direct for structured, agentic for natural language) |
187
+| `--format` | `text\|json\|mermaid` | `text` | Output format |
188
+| `-I`, `--interactive` | FLAG | off | Interactive REPL mode |
189
+
190
+**Examples:**
191
+
192
+```bash
193
+# Show graph stats
194
+planopticon query stats
195
+
196
+# List entities by type
197
+planopticon query "entities --type technology"
198
+planopticon query "entities --type person"
199
+
200
+# Find neighbors of an entity
201
+planopticon query "neighbors Alice"
202
+
203
+# List relationships
204
+planopticon query "relationships --source Alice"
205
+
206
+# Natural language query (requires API key)
207
+planopticon query "What technologies were discussed?"
208
+
209
+# Output as Mermaid diagram
210
+planopticon query --format mermaid "neighbors ProjectX"
211
+
212
+# Output as JSON
213
+planopticon query --format json stats
214
+
215
+# Interactive REPL
216
+planopticon query -I
217
+```
218
+
219
+---
220
+
221
+## `planopticon ingest`
222
+
223
+Ingest documents and files into a knowledge graph.
224
+
225
+```bash
226
+planopticon ingest [OPTIONS] INPUT
227
+```
228
+
229
+| Option | Type | Default | Description |
230
+|--------|------|---------|-------------|
231
+| `--output` | PATH | `./knowledge-base` | Output directory for the knowledge base |
232
+| `--db-path` | PATH | auto | Path to existing knowledge graph database to merge into |
233
+| `--recursive` | FLAG | off | Recursively process directories |
234
+| `-p`, `--provider` | TEXT | `auto` | AI provider |
235
+
236
+**Examples:**
237
+
238
+```bash
239
+# Ingest a single file
240
+planopticon ingest ./meeting-notes.md --output ./kb
241
+
242
+# Ingest a directory recursively
243
+planopticon ingest ./docs/ --output ./kb --recursive
244
+
245
+# Merge into an existing knowledge graph
246
+planopticon ingest ./new-notes/ --db-path ./kb/knowledge_graph.db --recursive
247
+```
248
+
249
+---
100250
101251
 ## `planopticon auth`
102252
103
-Authenticate with a cloud storage service for batch processing.
253
+Authenticate with cloud services via OAuth or API keys.
104254
105255
 ```bash
106
-planopticon auth SERVICE
256
+planopticon auth SERVICE [OPTIONS]
107257
 ```
108258
109259
 | Argument | Values | Description |
110260
 |----------|--------|-------------|
111
-| `SERVICE` | `google\|dropbox` | Cloud service to authenticate with |
261
+| `SERVICE` | `google\|dropbox\|zoom\|notion\|github\|microsoft` | Cloud service to authenticate with |
262
+
263
+| Option | Type | Default | Description |
264
+|--------|------|---------|-------------|
265
+| `--logout` | FLAG | off | Remove stored credentials for the service |
112266
113267
 **Examples:**
114268
115269
 ```bash
116
-# Authenticate with Google Drive (interactive OAuth2)
270
+# Authenticate with Google (Drive, Meet, YouTube, etc.)
117271
 planopticon auth google
118272
119273
 # Authenticate with Dropbox
120274
 planopticon auth dropbox
275
+
276
+# Authenticate with Zoom (for recording access)
277
+planopticon auth zoom
278
+
279
+# Authenticate with Notion
280
+planopticon auth notion
281
+
282
+# Authenticate with GitHub
283
+planopticon auth github
284
+
285
+# Authenticate with Microsoft 365 (OneDrive, Teams, etc.)
286
+planopticon auth microsoft
287
+
288
+# Log out of a service
289
+planopticon auth google --logout
290
+```
291
+
292
+---
293
+
294
+## `planopticon gws`
295
+
296
+Google Workspace commands. List, fetch, and ingest content from Google Workspace (Drive, Docs, Sheets, Slides, Meet).
297
+
298
+### `planopticon gws list`
299
+
300
+List available files and recordings from Google Workspace.
301
+
302
+```bash
303
+planopticon gws list [OPTIONS]
304
+```
305
+
306
+| Option | Type | Default | Description |
307
+|--------|------|---------|-------------|
308
+| `--type` | `drive\|docs\|sheets\|slides\|meet` | all | Filter by content type |
309
+| `--folder-id` | TEXT | none | Google Drive folder ID |
310
+| `--limit` | INT | 50 | Maximum results to return |
311
+
312
+### `planopticon gws fetch`
313
+
314
+Download content from Google Workspace.
315
+
316
+```bash
317
+planopticon gws fetch [OPTIONS] RESOURCE_ID
318
+```
319
+
320
+| Option | Type | Default | Description |
321
+|--------|------|---------|-------------|
322
+| `--output` | PATH | `./downloads` | Output directory |
323
+| `--format` | TEXT | auto | Export format (pdf, docx, etc.) |
324
+
325
+### `planopticon gws ingest`
326
+
327
+Ingest Google Workspace content directly into a knowledge graph.
328
+
329
+```bash
330
+planopticon gws ingest [OPTIONS]
331
+```
332
+
333
+| Option | Type | Default | Description |
334
+|--------|------|---------|-------------|
335
+| `--folder-id` | TEXT | none | Google Drive folder ID |
336
+| `--output` | PATH | `./knowledge-base` | Knowledge base output directory |
337
+| `--recursive` | FLAG | off | Recurse into subfolders |
338
+
339
+**Examples:**
340
+
341
+```bash
342
+# List all Google Workspace files
343
+planopticon gws list
344
+
345
+# List only Google Docs
346
+planopticon gws list --type docs
347
+
348
+# Fetch a specific file
349
+planopticon gws fetch abc123def --output ./downloads
350
+
351
+# Ingest an entire Drive folder into a knowledge base
352
+planopticon gws ingest --folder-id abc123 --output ./kb --recursive
353
+```
354
+
355
+---
356
+
357
+## `planopticon m365`
358
+
359
+Microsoft 365 commands. List, fetch, and ingest content from Microsoft 365 (OneDrive, SharePoint, Teams, Outlook).
360
+
361
+### `planopticon m365 list`
362
+
363
+List available files and recordings from Microsoft 365.
364
+
365
+```bash
366
+planopticon m365 list [OPTIONS]
367
+```
368
+
369
+| Option | Type | Default | Description |
370
+|--------|------|---------|-------------|
371
+| `--type` | `onedrive\|sharepoint\|teams\|outlook` | all | Filter by content type |
372
+| `--site` | TEXT | none | SharePoint site name |
373
+| `--limit` | INT | 50 | Maximum results to return |
374
+
375
+### `planopticon m365 fetch`
376
+
377
+Download content from Microsoft 365.
378
+
379
+```bash
380
+planopticon m365 fetch [OPTIONS] RESOURCE_ID
381
+```
382
+
383
+| Option | Type | Default | Description |
384
+|--------|------|---------|-------------|
385
+| `--output` | PATH | `./downloads` | Output directory |
386
+
387
+### `planopticon m365 ingest`
388
+
389
+Ingest Microsoft 365 content directly into a knowledge graph.
390
+
391
+```bash
392
+planopticon m365 ingest [OPTIONS]
393
+```
394
+
395
+| Option | Type | Default | Description |
396
+|--------|------|---------|-------------|
397
+| `--site` | TEXT | none | SharePoint site name |
398
+| `--path` | TEXT | `/` | Folder path in OneDrive/SharePoint |
399
+| `--output` | PATH | `./knowledge-base` | Knowledge base output directory |
400
+| `--recursive` | FLAG | off | Recurse into subfolders |
401
+
402
+**Examples:**
403
+
404
+```bash
405
+# List all Microsoft 365 content
406
+planopticon m365 list
407
+
408
+# List only Teams recordings
409
+planopticon m365 list --type teams
410
+
411
+# Fetch a specific file
412
+planopticon m365 fetch item-id-123 --output ./downloads
413
+
414
+# Ingest SharePoint content
415
+planopticon m365 ingest --site "Engineering" --path "/Shared Documents" --output ./kb --recursive
416
+```
417
+
418
+---
419
+
420
+## `planopticon recordings`
421
+
422
+List meeting recordings from video conferencing platforms.
423
+
424
+### `planopticon recordings zoom-list`
425
+
426
+List Zoom cloud recordings.
427
+
428
+```bash
429
+planopticon recordings zoom-list [OPTIONS]
430
+```
431
+
432
+| Option | Type | Default | Description |
433
+|--------|------|---------|-------------|
434
+| `--from` | DATE | 30 days ago | Start date (YYYY-MM-DD) |
435
+| `--to` | DATE | today | End date (YYYY-MM-DD) |
436
+| `--limit` | INT | 50 | Maximum results |
437
+
438
+### `planopticon recordings teams-list`
439
+
440
+List Microsoft Teams meeting recordings.
441
+
442
+```bash
443
+planopticon recordings teams-list [OPTIONS]
444
+```
445
+
446
+| Option | Type | Default | Description |
447
+|--------|------|---------|-------------|
448
+| `--from` | DATE | 30 days ago | Start date (YYYY-MM-DD) |
449
+| `--to` | DATE | today | End date (YYYY-MM-DD) |
450
+| `--limit` | INT | 50 | Maximum results |
451
+
452
+### `planopticon recordings meet-list`
453
+
454
+List Google Meet recordings.
455
+
456
+```bash
457
+planopticon recordings meet-list [OPTIONS]
458
+```
459
+
460
+| Option | Type | Default | Description |
461
+|--------|------|---------|-------------|
462
+| `--from` | DATE | 30 days ago | Start date (YYYY-MM-DD) |
463
+| `--to` | DATE | today | End date (YYYY-MM-DD) |
464
+| `--limit` | INT | 50 | Maximum results |
465
+
466
+**Examples:**
467
+
468
+```bash
469
+# List recent Zoom recordings
470
+planopticon recordings zoom-list
471
+
472
+# List Teams recordings from a specific date range
473
+planopticon recordings teams-list --from 2026-01-01 --to 2026-02-01
474
+
475
+# List Google Meet recordings
476
+planopticon recordings meet-list --limit 10
477
+```
478
+
479
+---
480
+
481
+## `planopticon export`
482
+
483
+Export knowledge base content to various formats.
484
+
485
+### `planopticon export markdown`
486
+
487
+Export knowledge base as Markdown files.
488
+
489
+```bash
490
+planopticon export markdown [OPTIONS]
491
+```
492
+
493
+| Option | Type | Default | Description |
494
+|--------|------|---------|-------------|
495
+| `--input` | PATH | auto-detect | Knowledge base path |
496
+| `--output` | PATH | `./export` | Output directory |
497
+
498
+### `planopticon export obsidian`
499
+
500
+Export knowledge base as an Obsidian vault with wikilinks and graph metadata.
501
+
502
+```bash
503
+planopticon export obsidian [OPTIONS]
504
+```
505
+
506
+| Option | Type | Default | Description |
507
+|--------|------|---------|-------------|
508
+| `--input` | PATH | auto-detect | Knowledge base path |
509
+| `--output` | PATH | `./obsidian-vault` | Output vault directory |
510
+
511
+### `planopticon export notion`
512
+
513
+Export knowledge base to Notion.
514
+
515
+```bash
516
+planopticon export notion [OPTIONS]
517
+```
518
+
519
+| Option | Type | Default | Description |
520
+|--------|------|---------|-------------|
521
+| `--input` | PATH | auto-detect | Knowledge base path |
522
+| `--parent-page` | TEXT | none | Notion parent page ID |
523
+
524
+### `planopticon export exchange`
525
+
526
+Export knowledge base as PlanOpticon Exchange Format (JSON).
527
+
528
+```bash
529
+planopticon export exchange [OPTIONS]
530
+```
531
+
532
+| Option | Type | Default | Description |
533
+|--------|------|---------|-------------|
534
+| `--input` | PATH | auto-detect | Knowledge base path |
535
+| `--output` | PATH | `./exchange.json` | Output file path |
536
+
537
+**Examples:**
538
+
539
+```bash
540
+# Export to Markdown
541
+planopticon export markdown --input ./kb --output ./docs
542
+
543
+# Export to Obsidian vault
544
+planopticon export obsidian --input ./kb --output ~/Obsidian/PlanOpticon
545
+
546
+# Export to Notion
547
+planopticon export notion --input ./kb --parent-page abc123
548
+
549
+# Export as exchange format for interoperability
550
+planopticon export exchange --input ./kb --output ./export.json
551
+```
552
+
553
+---
554
+
555
+## `planopticon wiki`
556
+
557
+Generate and publish wiki documentation from your knowledge base.
558
+
559
+### `planopticon wiki generate`
560
+
561
+Generate a static wiki site from the knowledge base.
562
+
563
+```bash
564
+planopticon wiki generate [OPTIONS]
565
+```
566
+
567
+| Option | Type | Default | Description |
568
+|--------|------|---------|-------------|
569
+| `--input` | PATH | auto-detect | Knowledge base path |
570
+| `--output` | PATH | `./wiki` | Output directory |
571
+
572
+### `planopticon wiki push`
573
+
574
+Push a generated wiki to a remote target (e.g., GitHub Wiki, Confluence).
575
+
576
+```bash
577
+planopticon wiki push [OPTIONS]
121578
 ```
122579
123
-After authentication, use `planopticon batch --source gdrive` or `--source dropbox` to process cloud videos.
580
+| Option | Type | Default | Description |
581
+|--------|------|---------|-------------|
582
+| `--input` | PATH | `./wiki` | Wiki directory to push |
583
+| `--target` | TEXT | *required* | Push target (e.g., `github://org/repo`, `confluence://space`) |
584
+
585
+**Examples:**
586
+
587
+```bash
588
+# Generate a wiki from the knowledge base
589
+planopticon wiki generate --input ./kb --output ./wiki
590
+
591
+# Push wiki to GitHub
592
+planopticon wiki push --input ./wiki --target "github://ConflictHQ/project-wiki"
593
+```
124594
125595
 ---
126596
127
-## Global options
597
+## `planopticon kg`
598
+
599
+Knowledge graph management commands.
600
+
601
+### `planopticon kg convert`
602
+
603
+Convert a knowledge graph between formats.
604
+
605
+```bash
606
+planopticon kg convert [OPTIONS]
607
+```
608
+
609
+| Option | Type | Default | Description |
610
+|--------|------|---------|-------------|
611
+| `--input` | PATH | *required* | Input knowledge graph file |
612
+| `--output` | PATH | *required* | Output file path |
613
+| `--format` | `json\|db\|graphml\|csv` | auto (from extension) | Target format |
614
+
615
+### `planopticon kg sync`
616
+
617
+Synchronize two knowledge graphs (merge new data).
618
+
619
+```bash
620
+planopticon kg sync [OPTIONS]
621
+```
622
+
623
+| Option | Type | Default | Description |
624
+|--------|------|---------|-------------|
625
+| `--source` | PATH | *required* | Source knowledge graph |
626
+| `--target` | PATH | *required* | Target knowledge graph to merge into |
627
+
628
+### `planopticon kg inspect`
629
+
630
+Inspect a knowledge graph and display statistics.
631
+
632
+```bash
633
+planopticon kg inspect [OPTIONS] [PATH]
634
+```
635
+
636
+| Option | Type | Default | Description |
637
+|--------|------|---------|-------------|
638
+| `PATH` | PATH | auto-detect | Knowledge graph file |
639
+
640
+### `planopticon kg classify`
641
+
642
+Classify and tag entities in a knowledge graph.
643
+
644
+```bash
645
+planopticon kg classify [OPTIONS]
646
+```
647
+
648
+| Option | Type | Default | Description |
649
+|--------|------|---------|-------------|
650
+| `--db-path` | PATH | auto-detect | Knowledge graph database |
651
+| `-p`, `--provider` | TEXT | `auto` | AI provider for classification |
652
+
653
+### `planopticon kg from-exchange`
654
+
655
+Import a knowledge graph from PlanOpticon Exchange Format.
656
+
657
+```bash
658
+planopticon kg from-exchange [OPTIONS] INPUT
659
+```
660
+
661
+| Option | Type | Default | Description |
662
+|--------|------|---------|-------------|
663
+| `INPUT` | PATH | *required* | Exchange format JSON file |
664
+| `--output` | PATH | `./knowledge-base` | Output knowledge base directory |
665
+
666
+**Examples:**
667
+
668
+```bash
669
+# Convert JSON knowledge graph to FalkorDB format
670
+planopticon kg convert --input ./kg.json --output ./kg.db
671
+
672
+# Merge two knowledge graphs
673
+planopticon kg sync --source ./new-kg.db --target ./main-kg.db
674
+
675
+# Inspect a knowledge graph
676
+planopticon kg inspect ./knowledge_graph.db
677
+
678
+# Classify entities with AI
679
+planopticon kg classify --db-path ./kg.db --provider anthropic
128680
129
-| Option | Description |
130
-|--------|-------------|
131
-| `-v`, `--verbose` | Enable debug-level logging |
132
-| `--version` | Show version and exit |
133
-| `--help` | Show help and exit |
681
+# Import from exchange format
682
+planopticon kg from-exchange ./export.json --output ./kb
683
+```
134684
--- docs/cli-reference.md
+++ docs/cli-reference.md
@@ -1,6 +1,20 @@
1 # CLI Reference
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2
3 ## `planopticon analyze`
4
5 Analyze a single video and extract structured knowledge.
6
@@ -95,39 +109,575 @@
95 | `-p`, `--provider` | `auto\|openai\|anthropic\|gemini\|ollama` | `auto` | API provider |
96 | `--vision-model` | TEXT | auto | Override vision model |
97 | `--chat-model` | TEXT | auto | Override chat model |
98
99 ---
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
100
101 ## `planopticon auth`
102
103 Authenticate with a cloud storage service for batch processing.
104
105 ```bash
106 planopticon auth SERVICE
107 ```
108
109 | Argument | Values | Description |
110 |----------|--------|-------------|
111 | `SERVICE` | `google\|dropbox` | Cloud service to authenticate with |
 
 
 
 
112
113 **Examples:**
114
115 ```bash
116 # Authenticate with Google Drive (interactive OAuth2)
117 planopticon auth google
118
119 # Authenticate with Dropbox
120 planopticon auth dropbox
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
121 ```
122
123 After authentication, use `planopticon batch --source gdrive` or `--source dropbox` to process cloud videos.
 
 
 
 
 
 
 
 
 
 
 
 
 
124
125 ---
126
127 ## Global options
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
128
129 | Option | Description |
130 |--------|-------------|
131 | `-v`, `--verbose` | Enable debug-level logging |
132 | `--version` | Show version and exit |
133 | `--help` | Show help and exit |
134
--- docs/cli-reference.md
+++ docs/cli-reference.md
@@ -1,6 +1,20 @@
1 # CLI Reference
2
3 ## Global options
4
5 These options are available on all commands.
6
7 | Option | Description |
8 |--------|-------------|
9 | `-v`, `--verbose` | Enable debug-level logging |
10 | `-C`, `--chat` | Enable chat mode (interactive follow-up after command completes) |
11 | `-I`, `--interactive` | Enable interactive REPL mode |
12 | `--version` | Show version and exit |
13 | `--help` | Show help and exit |
14
15 ---
16
17 ## `planopticon analyze`
18
19 Analyze a single video and extract structured knowledge.
20
@@ -95,39 +109,575 @@
109 | `-p`, `--provider` | `auto\|openai\|anthropic\|gemini\|ollama` | `auto` | API provider |
110 | `--vision-model` | TEXT | auto | Override vision model |
111 | `--chat-model` | TEXT | auto | Override chat model |
112
113 ---
114
115 ## `planopticon companion`
116
117 Interactive knowledge base companion. Opens a REPL for conversational exploration of your knowledge base.
118
119 ```bash
120 planopticon companion [OPTIONS]
121 ```
122
123 | Option | Type | Default | Description |
124 |--------|------|---------|-------------|
125 | `--kb` | PATH | auto-detect | Path to knowledge base directory |
126 | `-p`, `--provider` | TEXT | `auto` | AI provider |
127 | `--chat-model` | TEXT | auto | Override chat model |
128
129 **Examples:**
130
131 ```bash
132 # Start companion with auto-detected knowledge base
133 planopticon companion
134
135 # Point to a specific knowledge base
136 planopticon companion --kb ./my-kb
137
138 # Use a specific provider
139 planopticon companion --kb ./kb --provider anthropic --chat-model claude-sonnet-4-20250514
140 ```
141
142 ---
143
144 ## `planopticon agent`
145
146 Planning agent with adaptive analysis. Runs an agentic loop that reasons about your knowledge base, plans actions, and executes them.
147
148 ```bash
149 planopticon agent [OPTIONS]
150 ```
151
152 | Option | Type | Default | Description |
153 |--------|------|---------|-------------|
154 | `--kb` | PATH | auto-detect | Path to knowledge base directory |
155 | `-I`, `--interactive` | FLAG | off | Interactive mode (ask before each action) |
156 | `--export` | PATH | none | Export agent results to a file |
157 | `-p`, `--provider` | TEXT | `auto` | AI provider |
158 | `--chat-model` | TEXT | auto | Override chat model |
159
160 **Examples:**
161
162 ```bash
163 # Run the agent interactively
164 planopticon agent --kb ./kb --interactive
165
166 # Run agent and export results
167 planopticon agent --kb ./kb --export ./plan.md
168
169 # Use a specific model
170 planopticon agent --kb ./kb --provider openai --chat-model gpt-4o
171 ```
172
173 ---
174
175 ## `planopticon query`
176
177 Query the knowledge graph directly or with natural language.
178
179 ```bash
180 planopticon query [OPTIONS] [QUERY]
181 ```
182
183 | Option | Type | Default | Description |
184 |--------|------|---------|-------------|
185 | `--db-path` | PATH | auto-detect | Path to knowledge graph database |
186 | `--mode` | `direct\|agentic` | auto | Query mode (direct for structured, agentic for natural language) |
187 | `--format` | `text\|json\|mermaid` | `text` | Output format |
188 | `-I`, `--interactive` | FLAG | off | Interactive REPL mode |
189
190 **Examples:**
191
192 ```bash
193 # Show graph stats
194 planopticon query stats
195
196 # List entities by type
197 planopticon query "entities --type technology"
198 planopticon query "entities --type person"
199
200 # Find neighbors of an entity
201 planopticon query "neighbors Alice"
202
203 # List relationships
204 planopticon query "relationships --source Alice"
205
206 # Natural language query (requires API key)
207 planopticon query "What technologies were discussed?"
208
209 # Output as Mermaid diagram
210 planopticon query --format mermaid "neighbors ProjectX"
211
212 # Output as JSON
213 planopticon query --format json stats
214
215 # Interactive REPL
216 planopticon query -I
217 ```
218
219 ---
220
221 ## `planopticon ingest`
222
223 Ingest documents and files into a knowledge graph.
224
225 ```bash
226 planopticon ingest [OPTIONS] INPUT
227 ```
228
229 | Option | Type | Default | Description |
230 |--------|------|---------|-------------|
231 | `--output` | PATH | `./knowledge-base` | Output directory for the knowledge base |
232 | `--db-path` | PATH | auto | Path to existing knowledge graph database to merge into |
233 | `--recursive` | FLAG | off | Recursively process directories |
234 | `-p`, `--provider` | TEXT | `auto` | AI provider |
235
236 **Examples:**
237
238 ```bash
239 # Ingest a single file
240 planopticon ingest ./meeting-notes.md --output ./kb
241
242 # Ingest a directory recursively
243 planopticon ingest ./docs/ --output ./kb --recursive
244
245 # Merge into an existing knowledge graph
246 planopticon ingest ./new-notes/ --db-path ./kb/knowledge_graph.db --recursive
247 ```
248
249 ---
250
251 ## `planopticon auth`
252
253 Authenticate with cloud services via OAuth or API keys.
254
255 ```bash
256 planopticon auth SERVICE [OPTIONS]
257 ```
258
259 | Argument | Values | Description |
260 |----------|--------|-------------|
261 | `SERVICE` | `google\|dropbox\|zoom\|notion\|github\|microsoft` | Cloud service to authenticate with |
262
263 | Option | Type | Default | Description |
264 |--------|------|---------|-------------|
265 | `--logout` | FLAG | off | Remove stored credentials for the service |
266
267 **Examples:**
268
269 ```bash
270 # Authenticate with Google (Drive, Meet, YouTube, etc.)
271 planopticon auth google
272
273 # Authenticate with Dropbox
274 planopticon auth dropbox
275
276 # Authenticate with Zoom (for recording access)
277 planopticon auth zoom
278
279 # Authenticate with Notion
280 planopticon auth notion
281
282 # Authenticate with GitHub
283 planopticon auth github
284
285 # Authenticate with Microsoft 365 (OneDrive, Teams, etc.)
286 planopticon auth microsoft
287
288 # Log out of a service
289 planopticon auth google --logout
290 ```
291
292 ---
293
294 ## `planopticon gws`
295
296 Google Workspace commands. List, fetch, and ingest content from Google Workspace (Drive, Docs, Sheets, Slides, Meet).
297
298 ### `planopticon gws list`
299
300 List available files and recordings from Google Workspace.
301
302 ```bash
303 planopticon gws list [OPTIONS]
304 ```
305
306 | Option | Type | Default | Description |
307 |--------|------|---------|-------------|
308 | `--type` | `drive\|docs\|sheets\|slides\|meet` | all | Filter by content type |
309 | `--folder-id` | TEXT | none | Google Drive folder ID |
310 | `--limit` | INT | 50 | Maximum results to return |
311
312 ### `planopticon gws fetch`
313
314 Download content from Google Workspace.
315
316 ```bash
317 planopticon gws fetch [OPTIONS] RESOURCE_ID
318 ```
319
320 | Option | Type | Default | Description |
321 |--------|------|---------|-------------|
322 | `--output` | PATH | `./downloads` | Output directory |
323 | `--format` | TEXT | auto | Export format (pdf, docx, etc.) |
324
325 ### `planopticon gws ingest`
326
327 Ingest Google Workspace content directly into a knowledge graph.
328
329 ```bash
330 planopticon gws ingest [OPTIONS]
331 ```
332
333 | Option | Type | Default | Description |
334 |--------|------|---------|-------------|
335 | `--folder-id` | TEXT | none | Google Drive folder ID |
336 | `--output` | PATH | `./knowledge-base` | Knowledge base output directory |
337 | `--recursive` | FLAG | off | Recurse into subfolders |
338
339 **Examples:**
340
341 ```bash
342 # List all Google Workspace files
343 planopticon gws list
344
345 # List only Google Docs
346 planopticon gws list --type docs
347
348 # Fetch a specific file
349 planopticon gws fetch abc123def --output ./downloads
350
351 # Ingest an entire Drive folder into a knowledge base
352 planopticon gws ingest --folder-id abc123 --output ./kb --recursive
353 ```
354
355 ---
356
357 ## `planopticon m365`
358
359 Microsoft 365 commands. List, fetch, and ingest content from Microsoft 365 (OneDrive, SharePoint, Teams, Outlook).
360
361 ### `planopticon m365 list`
362
363 List available files and recordings from Microsoft 365.
364
365 ```bash
366 planopticon m365 list [OPTIONS]
367 ```
368
369 | Option | Type | Default | Description |
370 |--------|------|---------|-------------|
371 | `--type` | `onedrive\|sharepoint\|teams\|outlook` | all | Filter by content type |
372 | `--site` | TEXT | none | SharePoint site name |
373 | `--limit` | INT | 50 | Maximum results to return |
374
375 ### `planopticon m365 fetch`
376
377 Download content from Microsoft 365.
378
379 ```bash
380 planopticon m365 fetch [OPTIONS] RESOURCE_ID
381 ```
382
383 | Option | Type | Default | Description |
384 |--------|------|---------|-------------|
385 | `--output` | PATH | `./downloads` | Output directory |
386
387 ### `planopticon m365 ingest`
388
389 Ingest Microsoft 365 content directly into a knowledge graph.
390
391 ```bash
392 planopticon m365 ingest [OPTIONS]
393 ```
394
395 | Option | Type | Default | Description |
396 |--------|------|---------|-------------|
397 | `--site` | TEXT | none | SharePoint site name |
398 | `--path` | TEXT | `/` | Folder path in OneDrive/SharePoint |
399 | `--output` | PATH | `./knowledge-base` | Knowledge base output directory |
400 | `--recursive` | FLAG | off | Recurse into subfolders |
401
402 **Examples:**
403
404 ```bash
405 # List all Microsoft 365 content
406 planopticon m365 list
407
408 # List only Teams recordings
409 planopticon m365 list --type teams
410
411 # Fetch a specific file
412 planopticon m365 fetch item-id-123 --output ./downloads
413
414 # Ingest SharePoint content
415 planopticon m365 ingest --site "Engineering" --path "/Shared Documents" --output ./kb --recursive
416 ```
417
418 ---
419
420 ## `planopticon recordings`
421
422 List meeting recordings from video conferencing platforms.
423
424 ### `planopticon recordings zoom-list`
425
426 List Zoom cloud recordings.
427
428 ```bash
429 planopticon recordings zoom-list [OPTIONS]
430 ```
431
432 | Option | Type | Default | Description |
433 |--------|------|---------|-------------|
434 | `--from` | DATE | 30 days ago | Start date (YYYY-MM-DD) |
435 | `--to` | DATE | today | End date (YYYY-MM-DD) |
436 | `--limit` | INT | 50 | Maximum results |
437
438 ### `planopticon recordings teams-list`
439
440 List Microsoft Teams meeting recordings.
441
442 ```bash
443 planopticon recordings teams-list [OPTIONS]
444 ```
445
446 | Option | Type | Default | Description |
447 |--------|------|---------|-------------|
448 | `--from` | DATE | 30 days ago | Start date (YYYY-MM-DD) |
449 | `--to` | DATE | today | End date (YYYY-MM-DD) |
450 | `--limit` | INT | 50 | Maximum results |
451
452 ### `planopticon recordings meet-list`
453
454 List Google Meet recordings.
455
456 ```bash
457 planopticon recordings meet-list [OPTIONS]
458 ```
459
460 | Option | Type | Default | Description |
461 |--------|------|---------|-------------|
462 | `--from` | DATE | 30 days ago | Start date (YYYY-MM-DD) |
463 | `--to` | DATE | today | End date (YYYY-MM-DD) |
464 | `--limit` | INT | 50 | Maximum results |
465
466 **Examples:**
467
468 ```bash
469 # List recent Zoom recordings
470 planopticon recordings zoom-list
471
472 # List Teams recordings from a specific date range
473 planopticon recordings teams-list --from 2026-01-01 --to 2026-02-01
474
475 # List Google Meet recordings
476 planopticon recordings meet-list --limit 10
477 ```
478
479 ---
480
481 ## `planopticon export`
482
483 Export knowledge base content to various formats.
484
485 ### `planopticon export markdown`
486
487 Export knowledge base as Markdown files.
488
489 ```bash
490 planopticon export markdown [OPTIONS]
491 ```
492
493 | Option | Type | Default | Description |
494 |--------|------|---------|-------------|
495 | `--input` | PATH | auto-detect | Knowledge base path |
496 | `--output` | PATH | `./export` | Output directory |
497
498 ### `planopticon export obsidian`
499
500 Export knowledge base as an Obsidian vault with wikilinks and graph metadata.
501
502 ```bash
503 planopticon export obsidian [OPTIONS]
504 ```
505
506 | Option | Type | Default | Description |
507 |--------|------|---------|-------------|
508 | `--input` | PATH | auto-detect | Knowledge base path |
509 | `--output` | PATH | `./obsidian-vault` | Output vault directory |
510
511 ### `planopticon export notion`
512
513 Export knowledge base to Notion.
514
515 ```bash
516 planopticon export notion [OPTIONS]
517 ```
518
519 | Option | Type | Default | Description |
520 |--------|------|---------|-------------|
521 | `--input` | PATH | auto-detect | Knowledge base path |
522 | `--parent-page` | TEXT | none | Notion parent page ID |
523
524 ### `planopticon export exchange`
525
526 Export knowledge base as PlanOpticon Exchange Format (JSON).
527
528 ```bash
529 planopticon export exchange [OPTIONS]
530 ```
531
532 | Option | Type | Default | Description |
533 |--------|------|---------|-------------|
534 | `--input` | PATH | auto-detect | Knowledge base path |
535 | `--output` | PATH | `./exchange.json` | Output file path |
536
537 **Examples:**
538
539 ```bash
540 # Export to Markdown
541 planopticon export markdown --input ./kb --output ./docs
542
543 # Export to Obsidian vault
544 planopticon export obsidian --input ./kb --output ~/Obsidian/PlanOpticon
545
546 # Export to Notion
547 planopticon export notion --input ./kb --parent-page abc123
548
549 # Export as exchange format for interoperability
550 planopticon export exchange --input ./kb --output ./export.json
551 ```
552
553 ---
554
555 ## `planopticon wiki`
556
557 Generate and publish wiki documentation from your knowledge base.
558
559 ### `planopticon wiki generate`
560
561 Generate a static wiki site from the knowledge base.
562
563 ```bash
564 planopticon wiki generate [OPTIONS]
565 ```
566
567 | Option | Type | Default | Description |
568 |--------|------|---------|-------------|
569 | `--input` | PATH | auto-detect | Knowledge base path |
570 | `--output` | PATH | `./wiki` | Output directory |
571
572 ### `planopticon wiki push`
573
574 Push a generated wiki to a remote target (e.g., GitHub Wiki, Confluence).
575
576 ```bash
577 planopticon wiki push [OPTIONS]
578 ```
579
580 | Option | Type | Default | Description |
581 |--------|------|---------|-------------|
582 | `--input` | PATH | `./wiki` | Wiki directory to push |
583 | `--target` | TEXT | *required* | Push target (e.g., `github://org/repo`, `confluence://space`) |
584
585 **Examples:**
586
587 ```bash
588 # Generate a wiki from the knowledge base
589 planopticon wiki generate --input ./kb --output ./wiki
590
591 # Push wiki to GitHub
592 planopticon wiki push --input ./wiki --target "github://ConflictHQ/project-wiki"
593 ```
594
595 ---
596
597 ## `planopticon kg`
598
599 Knowledge graph management commands.
600
601 ### `planopticon kg convert`
602
603 Convert a knowledge graph between formats.
604
605 ```bash
606 planopticon kg convert [OPTIONS]
607 ```
608
609 | Option | Type | Default | Description |
610 |--------|------|---------|-------------|
611 | `--input` | PATH | *required* | Input knowledge graph file |
612 | `--output` | PATH | *required* | Output file path |
613 | `--format` | `json\|db\|graphml\|csv` | auto (from extension) | Target format |
614
615 ### `planopticon kg sync`
616
617 Synchronize two knowledge graphs (merge new data).
618
619 ```bash
620 planopticon kg sync [OPTIONS]
621 ```
622
623 | Option | Type | Default | Description |
624 |--------|------|---------|-------------|
625 | `--source` | PATH | *required* | Source knowledge graph |
626 | `--target` | PATH | *required* | Target knowledge graph to merge into |
627
628 ### `planopticon kg inspect`
629
630 Inspect a knowledge graph and display statistics.
631
632 ```bash
633 planopticon kg inspect [OPTIONS] [PATH]
634 ```
635
636 | Option | Type | Default | Description |
637 |--------|------|---------|-------------|
638 | `PATH` | PATH | auto-detect | Knowledge graph file |
639
640 ### `planopticon kg classify`
641
642 Classify and tag entities in a knowledge graph.
643
644 ```bash
645 planopticon kg classify [OPTIONS]
646 ```
647
648 | Option | Type | Default | Description |
649 |--------|------|---------|-------------|
650 | `--db-path` | PATH | auto-detect | Knowledge graph database |
651 | `-p`, `--provider` | TEXT | `auto` | AI provider for classification |
652
653 ### `planopticon kg from-exchange`
654
655 Import a knowledge graph from PlanOpticon Exchange Format.
656
657 ```bash
658 planopticon kg from-exchange [OPTIONS] INPUT
659 ```
660
661 | Option | Type | Default | Description |
662 |--------|------|---------|-------------|
663 | `INPUT` | PATH | *required* | Exchange format JSON file |
664 | `--output` | PATH | `./knowledge-base` | Output knowledge base directory |
665
666 **Examples:**
667
668 ```bash
669 # Convert JSON knowledge graph to FalkorDB format
670 planopticon kg convert --input ./kg.json --output ./kg.db
671
672 # Merge two knowledge graphs
673 planopticon kg sync --source ./new-kg.db --target ./main-kg.db
674
675 # Inspect a knowledge graph
676 planopticon kg inspect ./knowledge_graph.db
677
678 # Classify entities with AI
679 planopticon kg classify --db-path ./kg.db --provider anthropic
680
681 # Import from exchange format
682 planopticon kg from-exchange ./export.json --output ./kb
683 ```
 
 
684
M docs/getting-started/configuration.md
+47 -4
--- docs/getting-started/configuration.md
+++ docs/getting-started/configuration.md
@@ -1,27 +1,70 @@
11
 # Configuration
22
33
 ## Environment variables
4
+
5
+### AI providers
46
57
 | Variable | Description |
68
 |----------|-------------|
79
 | `OPENAI_API_KEY` | OpenAI API key |
810
 | `ANTHROPIC_API_KEY` | Anthropic API key |
911
 | `GEMINI_API_KEY` | Google Gemini API key |
12
+| `AZURE_OPENAI_API_KEY` | Azure OpenAI API key |
13
+| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI endpoint URL |
14
+| `TOGETHER_API_KEY` | Together AI API key |
15
+| `FIREWORKS_API_KEY` | Fireworks AI API key |
16
+| `CEREBRAS_API_KEY` | Cerebras API key |
17
+| `XAI_API_KEY` | xAI (Grok) API key |
1018
 | `OLLAMA_HOST` | Ollama server URL (default: `http://localhost:11434`) |
11
-| `GOOGLE_APPLICATION_CREDENTIALS` | Path to Google service account JSON (for Drive) |
19
+
20
+### Cloud services
21
+
22
+| Variable | Description |
23
+|----------|-------------|
24
+| `GOOGLE_APPLICATION_CREDENTIALS` | Path to Google service account JSON (for server-side Drive access) |
25
+| `ZOOM_CLIENT_ID` | Zoom OAuth app client ID |
26
+| `ZOOM_CLIENT_SECRET` | Zoom OAuth app client secret |
27
+| `NOTION_API_KEY` | Notion integration token |
28
+| `GITHUB_TOKEN` | GitHub personal access token |
29
+| `MICROSOFT_CLIENT_ID` | Azure AD app client ID (for Microsoft 365) |
30
+| `MICROSOFT_CLIENT_SECRET` | Azure AD app client secret |
31
+
32
+### General
33
+
34
+| Variable | Description |
35
+|----------|-------------|
1236
 | `CACHE_DIR` | Directory for API response caching |
1337
38
+## Authentication
39
+
40
+Most cloud services use OAuth via the `planopticon auth` command. Run it once per service to store credentials locally:
41
+
42
+```bash
43
+planopticon auth google # Google Drive, Docs, Meet, YouTube
44
+planopticon auth dropbox # Dropbox
45
+planopticon auth zoom # Zoom recordings
46
+planopticon auth notion # Notion pages
47
+planopticon auth github # GitHub repos and wikis
48
+planopticon auth microsoft # OneDrive, SharePoint, Teams
49
+```
50
+
51
+Credentials are stored in `~/.config/planopticon/`. Use `planopticon auth SERVICE --logout` to remove them.
52
+
53
+For Zoom and Microsoft 365, you also need to set the client ID and secret environment variables before running `planopticon auth`.
54
+
1455
 ## Provider routing
1556
16
-PlanOpticon auto-discovers available models and routes each task to the best option:
57
+PlanOpticon auto-discovers available models and routes each task to the cheapest capable option:
1758
1859
 | Task | Default preference |
1960
 |------|--------------------|
20
-| Vision (diagrams) | Gemini Flash > GPT-4o > Claude Sonnet > Ollama |
21
-| Chat (analysis) | Claude Sonnet > GPT-4o > Gemini Flash > Ollama |
61
+| Vision (diagrams) | Gemini Flash > GPT-4o-mini > Claude Haiku > Ollama |
62
+| Chat (analysis) | Claude Haiku > GPT-4o-mini > Gemini Flash > Ollama |
2263
 | Transcription | Local Whisper > Whisper-1 > Gemini Flash |
64
+
65
+Default models prioritize cost efficiency. For complex or high-stakes analysis, override with more capable models using `--chat-model` or `--vision-model`.
2366
2467
 If no cloud API keys are configured, PlanOpticon automatically falls back to Ollama when a local server is running. This enables fully offline operation when paired with local Whisper for transcription.
2568
2669
 Override with `--provider`, `--vision-model`, or `--chat-model` flags.
2770
2871
--- docs/getting-started/configuration.md
+++ docs/getting-started/configuration.md
@@ -1,27 +1,70 @@
1 # Configuration
2
3 ## Environment variables
 
 
4
5 | Variable | Description |
6 |----------|-------------|
7 | `OPENAI_API_KEY` | OpenAI API key |
8 | `ANTHROPIC_API_KEY` | Anthropic API key |
9 | `GEMINI_API_KEY` | Google Gemini API key |
 
 
 
 
 
 
10 | `OLLAMA_HOST` | Ollama server URL (default: `http://localhost:11434`) |
11 | `GOOGLE_APPLICATION_CREDENTIALS` | Path to Google service account JSON (for Drive) |
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
12 | `CACHE_DIR` | Directory for API response caching |
13
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
14 ## Provider routing
15
16 PlanOpticon auto-discovers available models and routes each task to the best option:
17
18 | Task | Default preference |
19 |------|--------------------|
20 | Vision (diagrams) | Gemini Flash > GPT-4o > Claude Sonnet > Ollama |
21 | Chat (analysis) | Claude Sonnet > GPT-4o > Gemini Flash > Ollama |
22 | Transcription | Local Whisper > Whisper-1 > Gemini Flash |
 
 
23
24 If no cloud API keys are configured, PlanOpticon automatically falls back to Ollama when a local server is running. This enables fully offline operation when paired with local Whisper for transcription.
25
26 Override with `--provider`, `--vision-model`, or `--chat-model` flags.
27
28
--- docs/getting-started/configuration.md
+++ docs/getting-started/configuration.md
@@ -1,27 +1,70 @@
1 # Configuration
2
3 ## Environment variables
4
5 ### AI providers
6
7 | Variable | Description |
8 |----------|-------------|
9 | `OPENAI_API_KEY` | OpenAI API key |
10 | `ANTHROPIC_API_KEY` | Anthropic API key |
11 | `GEMINI_API_KEY` | Google Gemini API key |
12 | `AZURE_OPENAI_API_KEY` | Azure OpenAI API key |
13 | `AZURE_OPENAI_ENDPOINT` | Azure OpenAI endpoint URL |
14 | `TOGETHER_API_KEY` | Together AI API key |
15 | `FIREWORKS_API_KEY` | Fireworks AI API key |
16 | `CEREBRAS_API_KEY` | Cerebras API key |
17 | `XAI_API_KEY` | xAI (Grok) API key |
18 | `OLLAMA_HOST` | Ollama server URL (default: `http://localhost:11434`) |
19
20 ### Cloud services
21
22 | Variable | Description |
23 |----------|-------------|
24 | `GOOGLE_APPLICATION_CREDENTIALS` | Path to Google service account JSON (for server-side Drive access) |
25 | `ZOOM_CLIENT_ID` | Zoom OAuth app client ID |
26 | `ZOOM_CLIENT_SECRET` | Zoom OAuth app client secret |
27 | `NOTION_API_KEY` | Notion integration token |
28 | `GITHUB_TOKEN` | GitHub personal access token |
29 | `MICROSOFT_CLIENT_ID` | Azure AD app client ID (for Microsoft 365) |
30 | `MICROSOFT_CLIENT_SECRET` | Azure AD app client secret |
31
32 ### General
33
34 | Variable | Description |
35 |----------|-------------|
36 | `CACHE_DIR` | Directory for API response caching |
37
38 ## Authentication
39
40 Most cloud services use OAuth via the `planopticon auth` command. Run it once per service to store credentials locally:
41
42 ```bash
43 planopticon auth google # Google Drive, Docs, Meet, YouTube
44 planopticon auth dropbox # Dropbox
45 planopticon auth zoom # Zoom recordings
46 planopticon auth notion # Notion pages
47 planopticon auth github # GitHub repos and wikis
48 planopticon auth microsoft # OneDrive, SharePoint, Teams
49 ```
50
51 Credentials are stored in `~/.config/planopticon/`. Use `planopticon auth SERVICE --logout` to remove them.
52
53 For Zoom and Microsoft 365, you also need to set the client ID and secret environment variables before running `planopticon auth`.
54
55 ## Provider routing
56
57 PlanOpticon auto-discovers available models and routes each task to the cheapest capable option:
58
59 | Task | Default preference |
60 |------|--------------------|
61 | Vision (diagrams) | Gemini Flash > GPT-4o-mini > Claude Haiku > Ollama |
62 | Chat (analysis) | Claude Haiku > GPT-4o-mini > Gemini Flash > Ollama |
63 | Transcription | Local Whisper > Whisper-1 > Gemini Flash |
64
65 Default models prioritize cost efficiency. For complex or high-stakes analysis, override with more capable models using `--chat-model` or `--vision-model`.
66
67 If no cloud API keys are configured, PlanOpticon automatically falls back to Ollama when a local server is running. This enables fully offline operation when paired with local Whisper for transcription.
68
69 Override with `--provider`, `--vision-model`, or `--chat-model` flags.
70
71
M docs/getting-started/quickstart.md
+80
--- docs/getting-started/quickstart.md
+++ docs/getting-started/quickstart.md
@@ -63,10 +63,90 @@
6363
 Batch mode produces per-video outputs plus:
6464
6565
 - Merged knowledge graph across all videos
6666
 - Batch summary with aggregated action items
6767
 - Cross-referenced entities
68
+
69
+## Ingest documents
70
+
71
+Build a knowledge graph from documents, notes, or any text content:
72
+
73
+```bash
74
+# Ingest a single file
75
+planopticon ingest ./meeting-notes.md --output ./kb
76
+
77
+# Ingest a directory recursively
78
+planopticon ingest ./docs/ --output ./kb --recursive
79
+
80
+# Ingest from a URL
81
+planopticon ingest "https://www.youtube.com/watch?v=example" --output ./kb
82
+```
83
+
84
+## Companion REPL
85
+
86
+Chat with your knowledge base interactively:
87
+
88
+```bash
89
+# Start the companion
90
+planopticon companion --kb ./kb
91
+
92
+# Use a specific provider
93
+planopticon companion --kb ./kb --provider anthropic
94
+```
95
+
96
+The companion understands your knowledge graph and can answer questions, find connections, and summarize topics conversationally.
97
+
98
+## Planning agent
99
+
100
+Run the planning agent for adaptive, goal-directed analysis:
101
+
102
+```bash
103
+# Interactive mode — the agent asks before each action
104
+planopticon agent --kb ./kb --interactive
105
+
106
+# Non-interactive with export
107
+planopticon agent --kb ./kb --export ./plan.md
108
+```
109
+
110
+## Query the knowledge graph
111
+
112
+Query your knowledge graph directly without an AI provider:
113
+
114
+```bash
115
+# Show graph stats (entity/relationship counts)
116
+planopticon query stats
117
+
118
+# List entities by type
119
+planopticon query "entities --type technology"
120
+
121
+# Find neighbors of an entity
122
+planopticon query "neighbors Alice"
123
+
124
+# Natural language query (requires API key)
125
+planopticon query "What technologies were discussed?"
126
+
127
+# Interactive REPL
128
+planopticon query -I
129
+```
130
+
131
+## Export
132
+
133
+Export your knowledge base to various formats:
134
+
135
+```bash
136
+# Export to Markdown files
137
+planopticon export markdown --input ./kb --output ./docs
138
+
139
+# Export to an Obsidian vault
140
+planopticon export obsidian --input ./kb --output ~/Obsidian/PlanOpticon
141
+
142
+# Export to Notion
143
+planopticon export notion --input ./kb --parent-page abc123
144
+
145
+# Export as exchange format (portable JSON)
146
+planopticon export exchange --input ./kb --output ./export.json
147
+```
68148
69149
 ## Discover available models
70150
71151
 ```bash
72152
 planopticon list-models
73153
--- docs/getting-started/quickstart.md
+++ docs/getting-started/quickstart.md
@@ -63,10 +63,90 @@
63 Batch mode produces per-video outputs plus:
64
65 - Merged knowledge graph across all videos
66 - Batch summary with aggregated action items
67 - Cross-referenced entities
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
68
69 ## Discover available models
70
71 ```bash
72 planopticon list-models
73
--- docs/getting-started/quickstart.md
+++ docs/getting-started/quickstart.md
@@ -63,10 +63,90 @@
63 Batch mode produces per-video outputs plus:
64
65 - Merged knowledge graph across all videos
66 - Batch summary with aggregated action items
67 - Cross-referenced entities
68
69 ## Ingest documents
70
71 Build a knowledge graph from documents, notes, or any text content:
72
73 ```bash
74 # Ingest a single file
75 planopticon ingest ./meeting-notes.md --output ./kb
76
77 # Ingest a directory recursively
78 planopticon ingest ./docs/ --output ./kb --recursive
79
80 # Ingest from a URL
81 planopticon ingest "https://www.youtube.com/watch?v=example" --output ./kb
82 ```
83
84 ## Companion REPL
85
86 Chat with your knowledge base interactively:
87
88 ```bash
89 # Start the companion
90 planopticon companion --kb ./kb
91
92 # Use a specific provider
93 planopticon companion --kb ./kb --provider anthropic
94 ```
95
96 The companion understands your knowledge graph and can answer questions, find connections, and summarize topics conversationally.
97
98 ## Planning agent
99
100 Run the planning agent for adaptive, goal-directed analysis:
101
102 ```bash
103 # Interactive mode — the agent asks before each action
104 planopticon agent --kb ./kb --interactive
105
106 # Non-interactive with export
107 planopticon agent --kb ./kb --export ./plan.md
108 ```
109
110 ## Query the knowledge graph
111
112 Query your knowledge graph directly without an AI provider:
113
114 ```bash
115 # Show graph stats (entity/relationship counts)
116 planopticon query stats
117
118 # List entities by type
119 planopticon query "entities --type technology"
120
121 # Find neighbors of an entity
122 planopticon query "neighbors Alice"
123
124 # Natural language query (requires API key)
125 planopticon query "What technologies were discussed?"
126
127 # Interactive REPL
128 planopticon query -I
129 ```
130
131 ## Export
132
133 Export your knowledge base to various formats:
134
135 ```bash
136 # Export to Markdown files
137 planopticon export markdown --input ./kb --output ./docs
138
139 # Export to an Obsidian vault
140 planopticon export obsidian --input ./kb --output ~/Obsidian/PlanOpticon
141
142 # Export to Notion
143 planopticon export notion --input ./kb --parent-page abc123
144
145 # Export as exchange format (portable JSON)
146 planopticon export exchange --input ./kb --output ./export.json
147 ```
148
149 ## Discover available models
150
151 ```bash
152 planopticon list-models
153
M docs/guide/cloud-sources.md
+174 -1
--- docs/guide/cloud-sources.md
+++ docs/guide/cloud-sources.md
@@ -1,8 +1,8 @@
11
 # Cloud Sources
22
3
-PlanOpticon can fetch videos directly from cloud storage services.
3
+PlanOpticon connects to 20+ source platforms for fetching videos, documents, and notes.
44
55
 ## Google Drive
66
77
 ### Service account auth
88
@@ -25,10 +25,75 @@
2525
 ### Install
2626
2727
 ```bash
2828
 pip install planopticon[gdrive]
2929
 ```
30
+
31
+## Google Workspace (gws)
32
+
33
+Full Google Workspace integration beyond just Drive. Access Docs, Sheets, Slides, and Meet recordings through the `gws` CLI group.
34
+
35
+### Setup
36
+
37
+```bash
38
+planopticon auth google
39
+```
40
+
41
+A single Google OAuth session covers Drive, Docs, Sheets, Slides, and Meet.
42
+
43
+### Usage
44
+
45
+```bash
46
+# List all Google Workspace content
47
+planopticon gws list
48
+
49
+# List only Google Docs
50
+planopticon gws list --type docs
51
+
52
+# List Meet recordings
53
+planopticon gws list --type meet
54
+
55
+# Fetch a specific file
56
+planopticon gws fetch abc123def --output ./downloads
57
+
58
+# Ingest an entire Drive folder into a knowledge base
59
+planopticon gws ingest --folder-id abc123 --output ./kb --recursive
60
+```
61
+
62
+## Microsoft 365 (m365)
63
+
64
+Access OneDrive, SharePoint, Teams recordings, and Outlook content.
65
+
66
+### Setup
67
+
68
+```bash
69
+# Set your Azure AD app credentials
70
+export MICROSOFT_CLIENT_ID="your-client-id"
71
+export MICROSOFT_CLIENT_SECRET="your-client-secret"
72
+
73
+# Authenticate
74
+planopticon auth microsoft
75
+```
76
+
77
+### Usage
78
+
79
+```bash
80
+# List all Microsoft 365 content
81
+planopticon m365 list
82
+
83
+# List only Teams recordings
84
+planopticon m365 list --type teams
85
+
86
+# List SharePoint files from a specific site
87
+planopticon m365 list --type sharepoint --site "Engineering"
88
+
89
+# Fetch a specific file
90
+planopticon m365 fetch item-id-123 --output ./downloads
91
+
92
+# Ingest SharePoint content into a knowledge base
93
+planopticon m365 ingest --site "Engineering" --path "/Shared Documents" --output ./kb --recursive
94
+```
3095
3196
 ## Dropbox
3297
3398
 ### OAuth2 auth
3499
@@ -40,11 +105,119 @@
40105
 ### Install
41106
42107
 ```bash
43108
 pip install planopticon[dropbox]
44109
 ```
110
+
111
+## YouTube
112
+
113
+PlanOpticon can ingest YouTube videos by URL. Audio is extracted and transcribed, and any visible content (slides, diagrams) is captured from frames.
114
+
115
+```bash
116
+# Ingest a YouTube video
117
+planopticon ingest "https://www.youtube.com/watch?v=example" --output ./kb
118
+
119
+# Ingest a playlist
120
+planopticon ingest "https://www.youtube.com/playlist?list=example" --output ./kb
121
+```
122
+
123
+YouTube ingestion uses `yt-dlp` under the hood. Install it separately if not already available:
124
+
125
+```bash
126
+pip install yt-dlp
127
+```
128
+
129
+## Meeting recordings
130
+
131
+Access cloud recordings from Zoom, Microsoft Teams, and Google Meet.
132
+
133
+### Zoom
134
+
135
+```bash
136
+# Set credentials and authenticate
137
+export ZOOM_CLIENT_ID="your-client-id"
138
+export ZOOM_CLIENT_SECRET="your-client-secret"
139
+planopticon auth zoom
140
+
141
+# List recent Zoom recordings
142
+planopticon recordings zoom-list
143
+
144
+# List recordings from a date range
145
+planopticon recordings zoom-list --from 2026-01-01 --to 2026-02-01
146
+```
147
+
148
+### Microsoft Teams
149
+
150
+```bash
151
+# Authenticate with Microsoft (covers Teams)
152
+planopticon auth microsoft
153
+
154
+# List Teams recordings
155
+planopticon recordings teams-list
156
+
157
+# List recordings from a date range
158
+planopticon recordings teams-list --from 2026-01-01 --to 2026-02-01
159
+```
160
+
161
+### Google Meet
162
+
163
+```bash
164
+# Authenticate with Google (covers Meet)
165
+planopticon auth google
166
+
167
+# List Meet recordings
168
+planopticon recordings meet-list --limit 10
169
+```
170
+
171
+## Notes sources
172
+
173
+PlanOpticon can ingest notes and documents from several note-taking platforms.
174
+
175
+### Obsidian
176
+
177
+Ingest an Obsidian vault directly. PlanOpticon follows wikilinks and parses frontmatter.
178
+
179
+```bash
180
+planopticon ingest ~/Obsidian/MyVault --output ./kb --recursive
181
+```
182
+
183
+### Notion
184
+
185
+```bash
186
+# Set your Notion integration token
187
+export NOTION_API_KEY="secret_..."
188
+
189
+# Authenticate
190
+planopticon auth notion
191
+
192
+# Export knowledge base to Notion
193
+planopticon export notion --input ./kb --parent-page abc123
194
+```
195
+
196
+### Apple Notes
197
+
198
+PlanOpticon can read Apple Notes on macOS via the system AppleScript bridge.
199
+
200
+```bash
201
+planopticon ingest --source apple-notes --output ./kb
202
+```
203
+
204
+### GitHub
205
+
206
+Ingest README files, wikis, and documentation from GitHub repositories.
207
+
208
+```bash
209
+# Set your GitHub token
210
+export GITHUB_TOKEN="ghp_..."
211
+
212
+# Authenticate
213
+planopticon auth github
214
+
215
+# Ingest a repo's docs
216
+planopticon ingest "github://ConflictHQ/PlanOpticon" --output ./kb
217
+```
45218
46219
 ## All cloud sources
47220
48221
 ```bash
49222
 pip install planopticon[cloud]
50223
 ```
51224
--- docs/guide/cloud-sources.md
+++ docs/guide/cloud-sources.md
@@ -1,8 +1,8 @@
1 # Cloud Sources
2
3 PlanOpticon can fetch videos directly from cloud storage services.
4
5 ## Google Drive
6
7 ### Service account auth
8
@@ -25,10 +25,75 @@
25 ### Install
26
27 ```bash
28 pip install planopticon[gdrive]
29 ```
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
30
31 ## Dropbox
32
33 ### OAuth2 auth
34
@@ -40,11 +105,119 @@
40 ### Install
41
42 ```bash
43 pip install planopticon[dropbox]
44 ```
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
45
46 ## All cloud sources
47
48 ```bash
49 pip install planopticon[cloud]
50 ```
51
--- docs/guide/cloud-sources.md
+++ docs/guide/cloud-sources.md
@@ -1,8 +1,8 @@
1 # Cloud Sources
2
3 PlanOpticon connects to 20+ source platforms for fetching videos, documents, and notes.
4
5 ## Google Drive
6
7 ### Service account auth
8
@@ -25,10 +25,75 @@
25 ### Install
26
27 ```bash
28 pip install planopticon[gdrive]
29 ```
30
31 ## Google Workspace (gws)
32
33 Full Google Workspace integration beyond just Drive. Access Docs, Sheets, Slides, and Meet recordings through the `gws` CLI group.
34
35 ### Setup
36
37 ```bash
38 planopticon auth google
39 ```
40
41 A single Google OAuth session covers Drive, Docs, Sheets, Slides, and Meet.
42
43 ### Usage
44
45 ```bash
46 # List all Google Workspace content
47 planopticon gws list
48
49 # List only Google Docs
50 planopticon gws list --type docs
51
52 # List Meet recordings
53 planopticon gws list --type meet
54
55 # Fetch a specific file
56 planopticon gws fetch abc123def --output ./downloads
57
58 # Ingest an entire Drive folder into a knowledge base
59 planopticon gws ingest --folder-id abc123 --output ./kb --recursive
60 ```
61
62 ## Microsoft 365 (m365)
63
64 Access OneDrive, SharePoint, Teams recordings, and Outlook content.
65
66 ### Setup
67
68 ```bash
69 # Set your Azure AD app credentials
70 export MICROSOFT_CLIENT_ID="your-client-id"
71 export MICROSOFT_CLIENT_SECRET="your-client-secret"
72
73 # Authenticate
74 planopticon auth microsoft
75 ```
76
77 ### Usage
78
79 ```bash
80 # List all Microsoft 365 content
81 planopticon m365 list
82
83 # List only Teams recordings
84 planopticon m365 list --type teams
85
86 # List SharePoint files from a specific site
87 planopticon m365 list --type sharepoint --site "Engineering"
88
89 # Fetch a specific file
90 planopticon m365 fetch item-id-123 --output ./downloads
91
92 # Ingest SharePoint content into a knowledge base
93 planopticon m365 ingest --site "Engineering" --path "/Shared Documents" --output ./kb --recursive
94 ```
95
96 ## Dropbox
97
98 ### OAuth2 auth
99
@@ -40,11 +105,119 @@
105 ### Install
106
107 ```bash
108 pip install planopticon[dropbox]
109 ```
110
111 ## YouTube
112
113 PlanOpticon can ingest YouTube videos by URL. Audio is extracted and transcribed, and any visible content (slides, diagrams) is captured from frames.
114
115 ```bash
116 # Ingest a YouTube video
117 planopticon ingest "https://www.youtube.com/watch?v=example" --output ./kb
118
119 # Ingest a playlist
120 planopticon ingest "https://www.youtube.com/playlist?list=example" --output ./kb
121 ```
122
123 YouTube ingestion uses `yt-dlp` under the hood. Install it separately if not already available:
124
125 ```bash
126 pip install yt-dlp
127 ```
128
129 ## Meeting recordings
130
131 Access cloud recordings from Zoom, Microsoft Teams, and Google Meet.
132
133 ### Zoom
134
135 ```bash
136 # Set credentials and authenticate
137 export ZOOM_CLIENT_ID="your-client-id"
138 export ZOOM_CLIENT_SECRET="your-client-secret"
139 planopticon auth zoom
140
141 # List recent Zoom recordings
142 planopticon recordings zoom-list
143
144 # List recordings from a date range
145 planopticon recordings zoom-list --from 2026-01-01 --to 2026-02-01
146 ```
147
148 ### Microsoft Teams
149
150 ```bash
151 # Authenticate with Microsoft (covers Teams)
152 planopticon auth microsoft
153
154 # List Teams recordings
155 planopticon recordings teams-list
156
157 # List recordings from a date range
158 planopticon recordings teams-list --from 2026-01-01 --to 2026-02-01
159 ```
160
161 ### Google Meet
162
163 ```bash
164 # Authenticate with Google (covers Meet)
165 planopticon auth google
166
167 # List Meet recordings
168 planopticon recordings meet-list --limit 10
169 ```
170
171 ## Notes sources
172
173 PlanOpticon can ingest notes and documents from several note-taking platforms.
174
175 ### Obsidian
176
177 Ingest an Obsidian vault directly. PlanOpticon follows wikilinks and parses frontmatter.
178
179 ```bash
180 planopticon ingest ~/Obsidian/MyVault --output ./kb --recursive
181 ```
182
183 ### Notion
184
185 ```bash
186 # Set your Notion integration token
187 export NOTION_API_KEY="secret_..."
188
189 # Authenticate
190 planopticon auth notion
191
192 # Export knowledge base to Notion
193 planopticon export notion --input ./kb --parent-page abc123
194 ```
195
196 ### Apple Notes
197
198 PlanOpticon can read Apple Notes on macOS via the system AppleScript bridge.
199
200 ```bash
201 planopticon ingest --source apple-notes --output ./kb
202 ```
203
204 ### GitHub
205
206 Ingest README files, wikis, and documentation from GitHub repositories.
207
208 ```bash
209 # Set your GitHub token
210 export GITHUB_TOKEN="ghp_..."
211
212 # Authenticate
213 planopticon auth github
214
215 # Ingest a repo's docs
216 planopticon ingest "github://ConflictHQ/PlanOpticon" --output ./kb
217 ```
218
219 ## All cloud sources
220
221 ```bash
222 pip install planopticon[cloud]
223 ```
224
M docs/index.md
+24 -4
--- docs/index.md
+++ docs/index.md
@@ -1,24 +1,29 @@
11
 # PlanOpticon
22
3
-**AI-powered video analysis and knowledge extraction.**
3
+**AI-powered video analysis, knowledge extraction, and planning.**
44
5
-PlanOpticon processes video recordings into structured knowledge — transcripts, diagrams, action items, key points, and knowledge graphs. It auto-discovers available models across OpenAI, Anthropic, and Gemini, and produces rich multi-format output.
5
+PlanOpticon processes video recordings and documents into structured knowledge — transcripts, diagrams, action items, key points, and knowledge graphs. It connects to 20+ source platforms, auto-discovers available models across multiple AI providers, and produces rich multi-format output with an interactive companion REPL and planning agent.
66
77
 ---
88
99
 ## Features
1010
11
-- **Multi-provider AI** — Automatically discovers and routes to the best available model across OpenAI, Anthropic, and Google Gemini
11
+- **Multi-provider AI** — Automatically discovers and routes to the best available model across OpenAI, Anthropic, Google Gemini, and more
12
+- **Planning agent** — Agentic analysis that adaptively adjusts depth, focus, and strategy based on content
13
+- **Companion REPL** — Interactive chat interface for exploring your knowledge base conversationally
14
+- **20+ source connectors** — Google Workspace, Microsoft 365, Zoom, Teams, Meet, Notion, GitHub, YouTube, Obsidian, Apple Notes, and more
15
+- **Document export** — Export knowledge to Markdown, Obsidian, Notion, and exchange formats
16
+- **OAuth authentication** — Built-in `planopticon auth` for Google, Dropbox, Zoom, Notion, GitHub, and Microsoft
1217
 - **Smart frame extraction** — Change detection for transitions + periodic capture (every 30s) for slow-evolving content like document scrolling
1318
 - **People frame filtering** — OpenCV face detection removes webcam/video conference frames, keeping only shared content (slides, documents, screen shares)
1419
 - **Diagram extraction** — Vision model-based classification detects flowcharts, architecture diagrams, charts, and whiteboards
1520
 - **Knowledge graphs** — Extracts entities and relationships, builds and merges knowledge graphs across videos
1621
 - **Action item detection** — Finds commitments, tasks, and follow-ups with assignees and deadlines
1722
 - **Batch processing** — Process entire folders of videos with merged knowledge graphs and cross-referencing
1823
 - **Rich output** — Markdown, HTML, PDF, Mermaid diagrams, SVG/PNG renderings, JSON manifests
19
-- **Cloud sources** — Fetch videos from Google Drive and Dropbox shared folders
24
+- **Cloud sources** — Fetch videos from Google Drive, Dropbox, and many more cloud platforms
2025
 - **Checkpoint/resume** — Pipeline resumes from where it left off if interrupted — no wasted work
2126
 - **Screengrab fallback** — When extraction isn't perfect, captures frames with captions — something is always better than nothing
2227
2328
 ## Quick Start
2429
@@ -27,10 +32,25 @@
2732
 pip install planopticon
2833
2934
 # Analyze a single video
3035
 planopticon analyze -i meeting.mp4 -o ./output
3136
37
+# Ingest documents and build a knowledge graph
38
+planopticon ingest ./notes/ --output ./kb --recursive
39
+
40
+# Chat with your knowledge base
41
+planopticon companion --kb ./kb
42
+
43
+# Run the planning agent interactively
44
+planopticon agent --kb ./kb --interactive
45
+
46
+# Query the knowledge graph
47
+planopticon query stats
48
+
49
+# Export to Obsidian
50
+planopticon export obsidian --input ./kb --output ./vault
51
+
3252
 # Process a folder of videos
3353
 planopticon batch -i ./recordings -o ./output --title "Weekly Meetings"
3454
3555
 # See available AI models
3656
 planopticon list-models
3757
--- docs/index.md
+++ docs/index.md
@@ -1,24 +1,29 @@
1 # PlanOpticon
2
3 **AI-powered video analysis and knowledge extraction.**
4
5 PlanOpticon processes video recordings into structured knowledge — transcripts, diagrams, action items, key points, and knowledge graphs. It auto-discovers available models across OpenAI, Anthropic, and Gemini, and produces rich multi-format output.
6
7 ---
8
9 ## Features
10
11 - **Multi-provider AI** — Automatically discovers and routes to the best available model across OpenAI, Anthropic, and Google Gemini
 
 
 
 
 
12 - **Smart frame extraction** — Change detection for transitions + periodic capture (every 30s) for slow-evolving content like document scrolling
13 - **People frame filtering** — OpenCV face detection removes webcam/video conference frames, keeping only shared content (slides, documents, screen shares)
14 - **Diagram extraction** — Vision model-based classification detects flowcharts, architecture diagrams, charts, and whiteboards
15 - **Knowledge graphs** — Extracts entities and relationships, builds and merges knowledge graphs across videos
16 - **Action item detection** — Finds commitments, tasks, and follow-ups with assignees and deadlines
17 - **Batch processing** — Process entire folders of videos with merged knowledge graphs and cross-referencing
18 - **Rich output** — Markdown, HTML, PDF, Mermaid diagrams, SVG/PNG renderings, JSON manifests
19 - **Cloud sources** — Fetch videos from Google Drive and Dropbox shared folders
20 - **Checkpoint/resume** — Pipeline resumes from where it left off if interrupted — no wasted work
21 - **Screengrab fallback** — When extraction isn't perfect, captures frames with captions — something is always better than nothing
22
23 ## Quick Start
24
@@ -27,10 +32,25 @@
27 pip install planopticon
28
29 # Analyze a single video
30 planopticon analyze -i meeting.mp4 -o ./output
31
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
32 # Process a folder of videos
33 planopticon batch -i ./recordings -o ./output --title "Weekly Meetings"
34
35 # See available AI models
36 planopticon list-models
37
--- docs/index.md
+++ docs/index.md
@@ -1,24 +1,29 @@
1 # PlanOpticon
2
3 **AI-powered video analysis, knowledge extraction, and planning.**
4
5 PlanOpticon processes video recordings and documents into structured knowledge — transcripts, diagrams, action items, key points, and knowledge graphs. It connects to 20+ source platforms, auto-discovers available models across multiple AI providers, and produces rich multi-format output with an interactive companion REPL and planning agent.
6
7 ---
8
9 ## Features
10
11 - **Multi-provider AI** — Automatically discovers and routes to the best available model across OpenAI, Anthropic, Google Gemini, and more
12 - **Planning agent** — Agentic analysis that adaptively adjusts depth, focus, and strategy based on content
13 - **Companion REPL** — Interactive chat interface for exploring your knowledge base conversationally
14 - **20+ source connectors** — Google Workspace, Microsoft 365, Zoom, Teams, Meet, Notion, GitHub, YouTube, Obsidian, Apple Notes, and more
15 - **Document export** — Export knowledge to Markdown, Obsidian, Notion, and exchange formats
16 - **OAuth authentication** — Built-in `planopticon auth` for Google, Dropbox, Zoom, Notion, GitHub, and Microsoft
17 - **Smart frame extraction** — Change detection for transitions + periodic capture (every 30s) for slow-evolving content like document scrolling
18 - **People frame filtering** — OpenCV face detection removes webcam/video conference frames, keeping only shared content (slides, documents, screen shares)
19 - **Diagram extraction** — Vision model-based classification detects flowcharts, architecture diagrams, charts, and whiteboards
20 - **Knowledge graphs** — Extracts entities and relationships, builds and merges knowledge graphs across videos
21 - **Action item detection** — Finds commitments, tasks, and follow-ups with assignees and deadlines
22 - **Batch processing** — Process entire folders of videos with merged knowledge graphs and cross-referencing
23 - **Rich output** — Markdown, HTML, PDF, Mermaid diagrams, SVG/PNG renderings, JSON manifests
24 - **Cloud sources** — Fetch videos from Google Drive, Dropbox, and many more cloud platforms
25 - **Checkpoint/resume** — Pipeline resumes from where it left off if interrupted — no wasted work
26 - **Screengrab fallback** — When extraction isn't perfect, captures frames with captions — something is always better than nothing
27
28 ## Quick Start
29
@@ -27,10 +32,25 @@
32 pip install planopticon
33
34 # Analyze a single video
35 planopticon analyze -i meeting.mp4 -o ./output
36
37 # Ingest documents and build a knowledge graph
38 planopticon ingest ./notes/ --output ./kb --recursive
39
40 # Chat with your knowledge base
41 planopticon companion --kb ./kb
42
43 # Run the planning agent interactively
44 planopticon agent --kb ./kb --interactive
45
46 # Query the knowledge graph
47 planopticon query stats
48
49 # Export to Obsidian
50 planopticon export obsidian --input ./kb --output ./vault
51
52 # Process a folder of videos
53 planopticon batch -i ./recordings -o ./output --title "Weekly Meetings"
54
55 # See available AI models
56 planopticon list-models
57

Keyboard Shortcuts

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