/ README.md
README.md
1 # The InterBrain: From Personal Knowledge Management to Collective Knowledge Gardening 2 3  4 5 ## Introduction 6 7 The InterBrain is an innovative knowledge gardening system that aims to revolutionize the way we collectively relate to our ideas and stories. It transcends the traditional "Second Brain" paradigm, popularized by PKM tools like Obsidian, shifting to a dynamic, relational approach to organizing knowledge as opposed to static, top-down categorization. 8 9 ## 🚀 Ready to Install & Try 10 11 The InterBrain is work-in-progress software with basic functionality now installable as an Obsidian plugin. You can download and install the plugin to start building your liminal web using the existing features, while other capabilities are still in development and the full vision has yet to be comprehensively implemented. 12 13 **[→ Download Plugin](https://github.com/ProjectLiminality/InterBrain/releases/tag/v0.8.0)** | **[→ Installation Guide](#installation--setup)** 14 15 ## Project Status & Roadmap 16 17 > ⚡️ **Current Status: Coherence Beacon System Complete - 8 Foundation Epics Delivered** 18 Epic 8 (Coherence Beacon System) is complete with automatic relationship discovery, bidirectional tracking, Radicle network integration, GitHub Pages publishing, and radial action buttons. All 8 foundation epics are now complete and the InterBrain provides comprehensive distributed knowledge management. 19 20 > 🔬 **Previous Exploration:** 21 Earlier exploration work including screenshots and recordings can be found at [**InterBrain-Prototype**](https://github.com/ProjectLiminality/InterBrain-Prototype). This repository contains the conceptual foundation and visual demonstrations that inform the current development approach. 22 23 > ✅ **Epic 1 Complete:** 24 Foundation infrastructure with: 25 - Vite dual development workflow (browser + plugin) 26 - Command palette architecture (6 core commands) 27 - Service layer abstraction (UI, Git, DreamNode, Vault) 28 - Zustand reactive state management 29 - Vitest testing framework with comprehensive coverage 30 31 > ✅ **Epic 2 Complete:** 32 3D Spatial Visualization System with: 33 - React Three Fiber integration in Obsidian workspace 34 - DreamNode 3D components with star rendering 35 - Google Earth-style sphere rotation controls 36 - Fibonacci sphere layout algorithm 37 - Dynamic view scaling (Apple Watch style) 38 - Comprehensive unit test coverage 39 40 > ✅ **Epic 3 Complete:** 41 DreamNode Management System with: 42 - Service layer architecture with mock/real implementations 43 - Git template system for DreamNode creation 44 - Visual git state indicators (red/blue/clean) 45 - Auto-stash creator mode workflow 46 - Universal drag-drop hit detection 47 - Proto-node creation with animations 48 - Robust testing infrastructure 49 50 > ✅ **Epic 4 Complete:** 51 Liminal Web Layout System with: 52 - ✅ Spatial Orchestration System (Feature #316) 53 - ✅ Undo/Redo Navigation (Feature #320) 54 - ✅ Unified Edit Mode (Feature #321) - Complete with semantic search integration 55 56 > ✅ **Epic 5 Complete - Semantic Search System** 57 Comprehensive semantic search capabilities with local AI sovereignty: 58 - ✅ Intelligent Indexing System (Feature #322) - Background indexing with git integration 59 - ✅ Ollama Embedding API Integration (Feature #290) - Local embedding generation 60 - ✅ Search-as-DreamNode Interface (Feature #323) - Unified search/creation UX paradigm 61 - ✅ Honeycomb Search Layout (Feature #280) - Mathematical precision for 1-36 node positioning 62 - ✅ All Epic 5 features complete with comprehensive test coverage and zero warnings 63 64 > ✅ **Constellation Layout System Complete** 65 Advanced force-directed relationship visualization with mathematical precision: 66 - ✅ Fruchterman-Reingold algorithm implementation on spherical surfaces 67 - ✅ Connected components clustering with automatic discovery 68 - ✅ Global cluster positioning via Fibonacci sphere distribution 69 - ✅ Exponential mapping from planar to curved space layouts 70 - ✅ Camera-facing orientation with 90° rotation for optimal viewing 71 - ✅ Interactive command integration: "Scan Vault for DreamSong Relationships" + "Apply Constellation Layout" 72 - ✅ Enhanced edge interaction with 12x thicker invisible hit detection 73 - ✅ Persistent relationship visualization across all layout modes 74 - ✅ [**Interactive Algorithm Demos**](https://projectliminality.github.io/InterBrain/algorithms/constellation-layout.html) with JSON data support 75 76 > ✅ **Epic 7 Complete - Conversational Copilot System** 77 Person-centered conversational mode with real-time capabilities: 78 - ✅ Real-time transcription with whisper_streaming integration 79 - ✅ FaceTime automation with contact metadata system 80 - ✅ AI-powered conversation summaries via Claude API 81 - ✅ Email export with Obsidian URI deep links 82 - ✅ Semantic search-driven UX with 500-char context window 83 - ✅ Fullscreen DreamTalk/DreamSong overlays 84 - ✅ Shared nodes tracking with bidirectional relationships 85 86 > ✅ **Epic 8 Complete - Coherence Beacon System** 87 Distributed knowledge management with automatic relationship discovery: 88 - ✅ Coherence Beacon discovery system with modal acceptance workflow 89 - ✅ Bidirectional relationship tracking via git hooks 90 - ✅ Radicle network integration with CLI automation 91 - ✅ GitHub Pages publishing with static DreamSong sites 92 - ✅ Universal DreamNode cloning (Radicle/GitHub/UUID support) 93 - ✅ Radial action button system with 10 context-aware buttons 94 - ✅ PascalCase naming system with migration tools 95 - ✅ Songline feature for audio perspectives 96 - ✅ Digital Campfire metaphor for video calls 97 98 > 🌱 **Beyond the Plugin:** 99 The InterBrain is designed as the foundation for **DreamOS** — a decentralized, AI-agent-powered operating system for collective sensemaking and human-computer symbiosis. 100 101 > 💡 **Development Roadmap:** 102 1. ✅ Electron Prototype ([InterBrain-Prototype](https://github.com/ProjectLiminality/InterBrain-Prototype)) 103 2. ✅ Epic 1: Plugin Infrastructure (this repository) 104 3. ✅ Epic 2: 3D Spatial Visualization System 105 4. ✅ Epic 3: DreamNode Management System 106 5. ✅ Epic 4: Liminal Web Layout System (complete) 107 6. ✅ Epic 5: Semantic Search System (complete) 108 7. ✅ Epic 6: DreamWeaving Operations (complete) 109 8. ✅ Epic 7: Conversational Copilot System (complete) 110 9. ✅ Epic 8: Coherence Beacon System (complete) 111 10. 📋 Epic 9: Ready for community input and prioritization 112 11. 🪐 DreamOS system (future evolution) 113 114 Current development progress is tracked through [**GitHub Issues**](https://github.com/ProjectLiminality/InterBrain/issues) and [**Project Board**](https://github.com/users/ProjectLiminality/projects/2). 115 116 ## Installation & Setup 117 118 ### Prerequisites 119 120 1. **Obsidian**: Download and install [Obsidian](https://obsidian.md/) if you haven't already 121 2. **Git**: Install [Git](https://git-scm.com/downloads) - required for DreamNode creation functionality 122 3. **Platform**: Developed and tested on macOS. Windows and Linux compatibility likely but not actively tested 123 124 ### Plugin Installation 125 126 1. **Download**: Get the latest InterBrain plugin from [GitHub Releases](https://github.com/ProjectLiminality/InterBrain/releases) 127 2. **Extract**: Unzip the downloaded file to create an `interbrain` folder 128 3. **Install**: Drag the `interbrain` folder to your Obsidian vault's plugins directory: 129 - **Location**: `<your-vault>/.obsidian/plugins/` (where `<your-vault>` is your specific Obsidian vault folder) 130 - **Tip**: In Obsidian Settings → Community plugins, click the folder icon to open your plugins directory directly 131 4. **Enable**: Restart Obsidian, go to Settings → Community plugins, and enable "InterBrain" 132 133 ### Required for Semantic Search: Ollama Setup 134 135 **Note**: Semantic search features require Ollama. Basic DreamNode creation and liminal web navigation work without it. 136 137 1. **Install Ollama**: Download from [ollama.ai](https://ollama.ai) (available for macOS, Windows, Linux) 138 2. **Install Model**: Run `ollama pull nomic-embed-text` in terminal 139 3. **Check Status**: Use command palette "Ollama: Check Status" to verify setup 140 4. **Index**: Run "Full Index" command to enable semantic search on your DreamNodes 141 142 ### Optional: Radicle Network Setup (Peer-to-Peer Sharing) 143 144 **Note**: Radicle enables peer-to-peer DreamNode sharing without centralized servers. This is optional - DreamNodes work fully offline without it. 145 146 **Platform Support**: 147 - ✅ **macOS & Linux**: Full Radicle support 148 - ⚠️ **Windows**: GitHub-based sharing coming soon (use local-only DreamNodes for now) 149 150 **Setup Steps (macOS/Linux)**: 151 1. **Install Radicle**: Download from [radicle.xyz](https://radicle.xyz) and follow their installation guide 152 2. **Create Identity**: Run `rad auth` to set up your Radicle identity 153 3. **Verify**: The "Share DreamNode" command will appear in InterBrain's command palette once Radicle is detected 154 155 **Using Radicle Network**: 156 - **Initialize**: After creating a DreamNode, open Terminal in that directory and run `rad init --name "YourNodeName"` 157 - **Share DreamNode**: After making commits (saves), use "Share DreamNode" to push to the Radicle network 158 - **Clone DreamNode**: Use "Clone DreamNode from Radicle Network" and enter a friend's Radicle ID 159 - **Note**: Automatic initialization during DreamNode creation is not yet supported due to Radicle CLI requirements 160 161 **What is Radicle?**: A peer-to-peer alternative to GitHub that enables decentralized code collaboration. Your DreamNodes sync directly with trusted peers instead of through centralized servers. Perfect for private knowledge sharing within friend/family networks. 162 163 ### Getting Started 164 165 Once installed, try this simple exercise to build your first liminal web: 166 167 1. Open Obsidian and activate the InterBrain workspace via command palette 168 2. **Run "Full Index"** command (required for semantic search functionality) 169 3. Create a DreamNode for any project or idea you're working on 170 4. Click that node to enter liminal web mode (focused layout) 171 5. **Run "Enter Edit Mode"** command to edit nodes and relationships in 3D space 172 6. Drag and drop pictures of collaborators (name files with their names) 173 7. Click on any person to focus on them, then add shared projects/ideas 174 8. Watch your personal knowledge network emerge through relationships 175 176 **Essential Commands:** 177 - **"Ollama: Check Status"**: Verify if Ollama is properly set up for semantic search 178 - **"Full Index"**: Index your DreamNodes for semantic search (required after Ollama setup) 179 - **"Enter Edit Mode"**: Edit node content and relationships while in liminal web view 180 - **"Activate Search Interface"**: Use semantic search to find and create nodes (requires Ollama + indexing) 181 182 ### Important Notes 183 184 **Security & Development Status**: InterBrain is work-in-progress software under active development. All code is built transparently in public on GitHub where you can review the complete source code and development history. Users should exercise their own judgment when installing development software. As we approach a stable release, security, stability, and comprehensive testing will receive focused attention in line with production software standards. 185 186 ## Core Concepts 187 188 ### Dream Nodes 189 190 The fundamental unit of Project Liminality is the "Dream Node," which is implemented as a Git repository. Dream Nodes can embody two primary concepts: 191 192 1. **Dreams**: Abstract ideas, concepts, or any form of knowledge. 193 2. **Dreamers**: Representations of people or peers. 194 195  196 197 This dual nature allows for a flexible and interconnected knowledge structure. 198 199 ### Dream Talk and Dream Song 200 201 Each Dream Node consists of two main components: 202 203 - **Dream Talk**: A concise, symbolic representation of the idea (like a thumbnail). 204 - **Dream Song**: A more elaborate explanation or exploration of the idea, containing multiple references to other Dream Talks. 205 206  207 208 ### The InteBrain 209 210 Project Liminality structures knowledge based on social relationships and interactions, creating an "InteBrain." This approach allows users to organize information along the lines of their actual relational fields, transcending static, top-down categorization. 211 Thus uniting the multiplicity of Second Brains into a singular, interconnected InterBrain structure. 212 213  214 215 ## Key Features 216 217 ### 🌱 DreamNode Creation 218 219 Creating a new DreamNode is as easy as dragging and dropping a visual representation (DreamTalk) onto the interface. This will automatically create a new DreamNode with the same name as the file, containing the file. 220 Using the Command-N keyboard shortcut you can also create an empty DreamNode with your name of choice. 221 222  223 224 ### 🕸️ Liminal Web 225 226 By linking the ideas you hold to the people you share them with, DreamNodes self-organize into your unique "Liminal Web." 227 228  229 230 This allows you to navigate your knowledge in an intuitive and organic fashion, transcending the need for contrived categorization or hierarchical management. 231 232  233 234 ### 🔍 Semantic Search 235 236 Finding relevant DreamNodes is made easy and intuitive through semantic search - no need to worry about typos or remembering the exact name of any given idea! 237 Just enter a search query that is close enough in meaning to what you're looking for and it will magically be revealed. 238 (This existing feature is the basis for a yet-to-be-implemented realtime conversational copilot that always has the most relevant knowledge at hand for sharing during free-flowing conversation.) 239 240  241 242 ### 🧬 DreamWeaving 243 244 Just like individual software modules can be combined into more sophisticated projects using git repositories, DreamNodes can be woven together into larger wholes. Using the Obsidian canvas, DreamTalk symbols can be woven together with text into DreamSongs. The resulting DreamSong can in turn again be distilled into a single DreamTalk symbol. This reciprocal and recursive many-to-one mapping between DreamSong and DreamTalk allows for the emergence of a vertical holarchy of DreamNodes. A universal pattern for performing the Hegelean Dialectic of ideas in the digital! 245 246  247 248 ### 🔆 Coherence Beacon 249 250 Every time any Dreamer weaves together DreamNodes into larger wholes, the Coherence Beacon is triggered. This mechanism automatically identifies the subset of peers with whom they share any of the input DreamNodes and offers them the higher order DreamNode (including all input DreamNodes they may or may not already hold). By accepting the invitation they extend the signal to all of their peers and so on. This way only coherent ideas spread based on how much they resonate with the network, solving the virality problem. 251 Freedom of speech bound by meritocratic reach! 252 253  254 255 ### 🤖 Integrated AI Assistant 256 257 Since DreamNodes are based on git repositories, prominent AI pair-programming solutions like aider or cursor, being optimized for git, integrate seamlessly with the system. And just like the InteBrain generalizes git repos from computer code to all of knowledge, the same can be done out of the box with AI pair-programmers, using them as universal magical co-creators! 258 With ever more powerful, local, multi-modal models on the horizon and deeper integrations through frameworks like Model Context Protocol (MCP) truly the sky is the limit in terms of what can be achieved collectively through the InteBrain! 259 260  261 262 ### 💬 Conversational Co-Pilot (TBD) 263 264 Through realtime transcription of free flowing conversations (video call or in-person) combined with the existing semantic search functionality, the system will constantly filter for the most relevant DreamNodes, making them readily available for reference and sharing during the dialogue - all without interrupting the flow! Say goodbye to awkward interruptions due to not finding a reference! 265 And the best part: referencing a DreamNode (implicitly or explicitly) automatically offers your peer to clone it. Which means sharing an idea and collaborating on it is the same thing in this system. 266 267  268 269 ### 🎵 Songlines (TBD) 270 271 Everytime an idea is shared during a conversation, and thus the corresponding DreamNode is cloned, the relevant clip of the conversation is automatically added to the DreamNode as yet another way of expressing the idea. This way every DreamNode remembers the path it travels in a unique set of conversation clips - its Songline! 272 Not only do Songlines allow for an organic, decentralized and emergent replacement for static textbook definitions, they also constitute an invaluable source of community-generated and -owned data for representing knowledge in the most effortless yet high bandwidth way. In anticipation of local, multi-modal LLMs with effectively infinite context windows these Songlines may turn out to be a game changer in terms of leveraging collective knowledge and wisdom into actionable projects. 273 274  275 276 ### 📱 Git Client Integration 277 278 Easily open any given DreamNode in your favorite git client of your choice. 279 280  281 282 ### 📊 Organic Content Visualization 283 284 The content within a DreamNode is visually accessible on the backside using the beautiful circle packing algorithm of D3. Instantly access files and folders directly from the InteBrain. 285 286  287 288 ### 📂 Finder Integration 289 290 Reveal DreamNodes in your file system with just one click. 291 292  293 294 ## Real-World Applications & Project Synergy 295 296 The InteBrain system transforms how we share and organize knowledge, creating an organic ecosystem where ideas and initiatives can flourish together. 297 298 ### 🎙️ Enhanced Podcasting 299 - **Real-time knowledge access**: Conversational copilots filter relevant dream nodes based on discussion topics 300 - **Enriched show notes**: Share actual knowledge units rather than just superficial references 301 - **Depth in knowledge transfer**: Audience receives not just references but entire repositories of contextual information 302 303 ### 🔎 Collaborative Investigation 304 - **Emergent collective intelligence**: Investigators can effortlessly combine evidence and knowledge 305 - **Coherence Beacon in action**: Automatically invites collaborators who hold relevant knowledge 306 - **Scaling potential**: Enables millions of citizen journalists to work together on complex cases 307 308 ### 🎓 Future of Education 309 - **Dissolving artificial boundaries**: Between disciplines and between education and life itself 310 - **Living classroom**: Every conversation becomes an educational opportunity 311 - **Emergent curriculum**: Knowledge expands organically based on contextual relevance 312 - **Symbolic teaching**: Complex ideas transmitted through symbols backed by detailed dream nodes 313 314 ### 🎨 Co-Creation Renaissance 315 - **Source and product travel together**: Creative works remain connected to their source files 316 - **Open source everything**: Any digital creation becomes remixable and extensible 317 - **Infinite collaboration**: Weave different creations together through dream weaving 318 - **Context creation**: Shift from "content creators" to "context creators" with living, evolving works 319 320 ### 🕊️ End of Narrative Warfare 321 - **Signal amplification**: Filter out noise in competing narratives 322 - **Perspective integration**: Combine viewpoints to approach deeper truth 323 - **Social resonance filter**: Collective intuition helps identify coherent syntheses 324 - **Propaganda immunity**: System design makes manipulation difficult while healing divisive narratives 325 326 ### 🌐 Emergent Collaborative Networks 327 - **Dream nodes for all initiatives**: Any project can be represented as a dream node while maintaining independence 328 - **Cross-pollination**: Knowledge flows freely between initiatives while respecting autonomy 329 - **Resonance-based connections**: Projects naturally find their complementary partners 330 - **No central authority**: Collaboration emerges organically based on relevance and resonance 331 332 ### 🌿 Conscious Communities 333 - **Knowledge transfer across communities**: Solutions developed in one place effortlessly reach others 334 - **Contextual distribution**: Learning finds exactly where it's needed based on relevance 335 - **Social relationship propagation**: Knowledge travels through trusted connections 336 - **Emergent collective problem-solving**: Communities evolve together rather than in isolation 337 338 ### 🚀 From Incubation to Implementation 339 - **Project merging and spawning**: Smaller initiatives can unify or new ones can form from combinations 340 - **Solutions combine into higher-order solutions**: Building blocks of knowledge stack meaningfully 341 - **Universal pattern recognition**: Similar challenges across different domains find common solutions 342 - **Network of conversations**: All collaboration is rooted in human connection and meaning 343 344 ## Frequently Asked Questions 345 346 ### How does InterBrain prevent echo chambers while maintaining coherence filtering? 347 348 InterBrain addresses the echo chamber problem through a unique **holographic approach** that emphasizes connection over separation. Unlike traditional social media that amplifies differences and enables ideological bubbles, InterBrain's design makes separation literally invisible while highlighting what connects people. 349 350 **The Holographic Principle**: Stories contain people, and people hold stories - they contain each other in a holographic structure where each part contains the whole. This means you can "zoom in" from any relationship to discover the entire network of connections. 351 352 **How It Works**: 353 - **Focus on Connection**: The system only shows you what you share with others, never what separates you 354 - **Filter Bubble Dissolution**: When someone shares a monolithic idea (like "communism"), the system automatically breaks it into constituent sub-modules, creating multiple touchpoints for connection beyond the ideology 355 - **Contextual Perspective**: Ideas exist alongside grandma's recipes and childhood comics, naturally right-sizing ideological concepts 356 - **Dream Weaving**: You can "unweave" large concepts into smaller components, then re-weave them with different elements, creating bridges between seemingly opposed viewpoints 357 358 **The Result**: Instead of filter bubbles, you get an interconnected mycelium network where people constantly discover new relationships and deeper connections. Ideologies become "just one more thought form" among many, losing their disproportionate influence on human relationships. 359 360 **Social Resonance**: The Coherence Beacon system ensures that only genuinely coherent ideas spread, based on authentic resonance rather than viral manipulation. The network effect becomes heart-based rather than algorithm-driven. 361 362 ### What makes InterBrain different from existing knowledge management tools? 363 364 **Relational vs. Hierarchical**: Unlike traditional PKM tools that organize information in static categories, InterBrain organizes knowledge along the lines of your actual social relationships and interactions. 365 366 **Git-Native Architecture**: Every piece of knowledge is a git repository, enabling true version control, collaboration, and decentralized distribution of ideas. 367 368 **3D Spatial Interface**: Ideas exist in a 3D cosmos that reflects their relationships, moving beyond flat file structures to intuitive spatial navigation. 369 370 **Social Propagation**: Knowledge spreads through authentic social connections rather than algorithmic recommendation, creating trust-based rather than engagement-based distribution. 371 372 ### Why use git repositories for individual ideas? 373 374 **Version Control for Thoughts**: Ideas evolve over time - git tracks this evolution naturally while preserving the complete history of how your thinking developed. 375 376 **True Collaboration**: Multiple people can contribute to the same idea while maintaining clear attribution and merge capabilities. 377 378 **Decentralized Architecture**: No central server dependency - your knowledge remains yours while being shareable with your network. 379 380 **AI Integration**: Git-optimized AI tools (like Aider) work seamlessly with DreamNodes, turning AI assistants into universal co-creators for any type of knowledge. 381 382 **Future-Proofing**: As the system evolves toward DreamOS, the git foundation enables unprecedented composability between different applications and knowledge domains. 383 384 ## Command Architecture 385 386 The InterBrain plugin uses Obsidian's command palette as the primary abstraction layer between UI interactions and backend operations. All functionality is accessible via keyboard shortcuts (Cmd/Ctrl+P) and can be triggered programmatically. 387 388 ### Available Commands 389 390 All commands are prefixed with `InterBrain:` in the command palette: 391 392 - **Open DreamSpace** - Opens the 3D spatial visualization view 393 - **Save DreamNode (commit changes)** - Commits current changes with AI assistance 394 - **Create new DreamNode** - Creates a new Dream or Dreamer node 395 - **Weave Dreams into higher-order node** - Combines selected nodes via git submodules 396 - **Toggle DreamNode selection** - Select/deselect nodes for bulk operations 397 - **Share DreamNode via Coherence Beacon** - Share nodes through the social resonance network 398 399 ### Service Layer Architecture 400 401 The plugin implements a clean separation of concerns through dedicated services: 402 403 - **UIService** - User notifications and feedback (success, error, loading states) 404 - **GitService** - Git operations abstraction (commit, create, weave) 405 - **DreamNodeService** - DreamNode state management and selection 406 - **VaultService** - Obsidian Vault API wrapper for file operations 407 408 ### Programmatic Access 409 410 UI components can trigger commands programmatically: 411 412 ```typescript 413 this.app.commands.executeCommandById('interbrain:save-dreamnode'); 414 ``` 415 416 This architecture ensures all functionality remains accessible to both power users (via command palette) and regular users (via UI buttons), while maintaining a clean separation between presentation and business logic. 417 418 ### State Management with Zustand 419 420 The plugin uses Zustand for centralized, reactive state management that integrates seamlessly with the command-driven architecture. 421 422 #### Store Structure 423 424 ```typescript 425 interface InterBrainState { 426 selectedNode: DreamNode | null; // Currently selected node 427 searchResults: DreamNode[]; // Search/filter results 428 spatialLayout: 'constellation' | 'search' | 'focused'; // 3D layout mode 429 } 430 ``` 431 432 #### Integration Pattern 433 434 **Commands → Services → Zustand State → UI Reactivity** 435 436 ```typescript 437 // 1. Command executes 438 this.addCommand({ 439 id: 'save-dreamnode', 440 callback: async () => { 441 const currentNode = this.dreamNodeService.getCurrentNode(); // 2. Service provides state 442 // ... business logic 443 } 444 }); 445 446 // 3. Service updates both internal and reactive state 447 setCurrentNode(node: DreamNode | null): void { 448 this.currentNode = node; // Internal state 449 useInterBrainStore.getState().setSelectedNode(node); // Reactive state 450 } 451 452 // 4. Future UI components read reactively 453 const selectedNode = useInterBrainStore(state => state.selectedNode); 454 ``` 455 456 #### Testing Commands 457 458 The plugin includes test commands to verify state synchronization: 459 - `[TEST] Select Mock DreamNode` - Creates a test node and updates state 460 - `[TEST] Clear DreamNode Selection` - Clears selection and updates state 461 462 These demonstrate the complete flow from command execution to state updates that future UI components can react to. 463 464 ### Testing Framework 465 466 The plugin uses Vitest for comprehensive testing with co-located test patterns following our vertical slice architecture. 467 468 #### Test Organization 469 470 Tests are co-located with the code they test: 471 ``` 472 src/ 473 ├── services/ 474 │ ├── dreamnode-service.ts 475 │ ├── dreamnode-service.test.ts # Co-located tests 476 │ └── ui-service.test.ts 477 ├── store/ 478 │ ├── interbrain-store.ts 479 │ └── interbrain-store.test.ts 480 └── features/ # Future vertical slices 481 └── dream-weaving/ 482 ├── DreamWeaving.tsx 483 └── DreamWeaving.test.tsx 484 ``` 485 486 #### Test Categories 487 488 **Unit Tests**: Service methods, store actions, pure functions 489 **Integration Tests**: Command → Service → State flow 490 **Component Tests**: React components with user interactions (future) 491 492 #### Running Tests 493 494 ```bash 495 npm run test # Run all tests 496 npm run test:watch # Watch mode for development 497 npm run test:coverage # Generate coverage reports 498 npm run check-all # Lint + typecheck + test 499 ``` 500 501 #### Test Utilities 502 503 **Mock Factories**: 504 ```typescript 505 const mockNode = createMockDreamNode({ name: 'Custom Name' }) 506 const mockService = createMockUIService() 507 ``` 508 509 **Store Testing**: 510 ```typescript 511 // Store tests verify reactive state management 512 expect(useInterBrainStore.getState().selectedNode).toBe(mockNode) 513 ``` 514 515 **Obsidian Mocking**: All Obsidian APIs are mocked for isolated testing without dependencies on the Obsidian environment. 516 517 ## License 518 519 Project Liminality is released under the [GNU AFFERO GENERAL PUBLIC LICENSE](LICENSE). 520 521 ## Acknowledgements 522 523 Much of the philosophical foundation for this project has been created in conversation with my co-visionary and dear friend Anna Ziegler. Check out her one-of-a-kind work at https://goodfairy.gift