1. Getting Started

Multi-Map is a spatial mapping ecosystem. Instead of folders and files, you organize information into "Constellations" of interconnected nodes. Every map begins with a Universe Root. From there, you can spawn Hubs, Notes, Portals, and structured schema elements depending on the Map's designated Type (Generic, Web Architecture, Prompt Engine, Agent Config, Flowchart, Person Profile, Link Hub, Data Architecture, or File System).

2. Navigation & Controls

Mouse & Touch Controls

The Radial Menu & Moons

Selecting a node opens its Radial Menu—a circular array of quick actions (Edit, Link, Add, Delete, Collapse).

Non-Destructive Collapse: When you collapse a node (🌚), its children are hidden from the map and replaced by orbiting "Moons" around the parent. Clicking a Moon instantly expands the branch and focuses the camera on the child.

Keyboard Power-User Shortcuts

Multi-Map natively supports standard mind-map keyboard editing for rapid, mouse-free node creation. When a node is selected:

3. Node Operations & Linking

Two-Step Targeted Linking

While "Add" creates strict hierarchical structures (solid lines), you can draw conceptual relationships between any two nodes using the Two-Step Linking workflow (dotted lines).

Changing Parents (Reparenting)

Clipping Branches

If a map becomes too cluttered, select the Clip (✂️) action on a node. This deletes the node and its downstream children from the current map, pastes them into an entirely new Map file, and leaves behind a Portal node in its exact place pointing to the new file.

4. Phase Engines (Views)

Multi-Map separates your raw data from how it is displayed. "Phases" are different iframe-based lenses through which you can view the exact same Mapstate JSON. Switching phases never alters the underlying data—only how it's rendered.

• 🗺️
  Celestial Map (Default)

  The default spatial graph. Free-form dragging, force-directed physics engine enabled. Nodes float as constellations with organic branching layouts.

• 🔮
  Orbital Focus (Magic Circle)

  A strict hierarchical view. Displays only the selected "Sun" node, its immediate "Planets" (children), and its "Halo" (parent). Clicking planets navigates deep into the tree without visual clutter.

• 🌐
  🌐
  Web Architect & Spatial Browser

  A live HTML compiler. If your map uses web-* nodes, this engine dynamically compiles them into live, rendered HTML/Tailwind inside an iframe.

  Advanced Iframe Integration: If you input a valid URL (e.g. google.com or https://wikipedia.org) into the payload of a web-root node, the engine will automatically mount the live website into the background iframe. Any children attached to that node will physically render beneath the live website. If a site employs X-Frame blocking, an "Open in New Tab" escape hatch appears.
• 📜
  Prompt Engine

  Compiles downstream prompt-* nodes (role, context, goal, instructions, constraints, examples, variables) into a linear, formatted Markdown document for LLM consumption. Supports chaining via prompt-chain nodes with portal execution.

• 🤖
  Agent Config

  Dedicated sandbox viewport providing a dynamic overview of the agent architecture—persona, router, skills, tools, memory, and guardrails—rendered from agent-* node hierarchies.

• 👤
  Person / Identity

  Translates person-root node data into a professional profile or CV format. Hub children represent career sections, skills, and experience.

5. Project Directory & Data Manager

Multi-Map organizes files hierarchically into Projects, Folders, and Pages. The left-hand Data Manager sidebar and the right-hand Profile drawer provide full project and library management.

6. Smart Roots & Portals

To link maps together, create a Portal node. Portals act as wormholes to other pages in your library. Maps have intrinsic Subtype Mapstates (e.g., "Generic", "Web Architecture") which enforce strict Ontology rules globally across the map.

Dynamic Portal System

In previous versions, a specialized smart-portal node type existed separately. Now, all Portals are dynamic. The system utilizes Smart Roots to determine behavior. Using the Portal Inspector, you can either select an existing map as the destination, or create a New Submap by selecting a Map Type.

7. MM-AI Assistant

Multi-Map features a native LLM integration (Gemini) capable of converting natural language into spatial MapState JSON, modifying existing maps, and providing structural tutoring.

8. Core Architecture

The platform relies on a Decoupled State Machine pattern. The DOM never dictates truth.

9. Node & Connection Ontology

Defined in multi-map-rules.js, this schema dictates what types of nodes can exist and how they are allowed to connect. Universal Exception: Any node is allowed to have a child of type note or web-link.

Connection Types

• Structural (Solid): Strict Parent/Child hierarchy. Acts as a spring in the physics engine. Triggers cascading deletions.
• Association (Dashed): Loose conceptual relation. Ignored by physics springs and orbital views. Created via 2-Step linking.
• Flow (Dotted): Directional sequence logic (reserved for Logic Gates / execution loops).

Schema Hierarchy by Map Type

Web Architect Nodes (Detail)

10. JSON Schema & Arrays

The JSON standard for importing/exporting mapstates. The system can parse a single object OR an array [{...}, {...}] of mapstates during upload.

{
  "map_id": "u7b9v2z1x",
  "meta": {
    "title": "Project Master Plan",
    "type": "generic",          // Map type: generic|web|prompt|agent|flow|person|link|data|file
    "created": "2026-02-24T12:00:00Z",
    "notes": "System schema reference",
    "shared": false,
    "project_id": "proj_abc",   // Links to parent project
    "isMaster": false           // true only for Project Directory pages
  },
  "nodes": [
    {
      "id": "abc123xyz",
      "type": "hub",            // Must match MultiMapSchema.definitions
      "title": "Central Architecture",
      "content": "Description payload here...",
      "data": {
        "x": 145.2,             // Canvas X coordinate
        "y": -22.4,             // Canvas Y coordinate
        "isCore": true,         // Pinned (immune to physics)
        "collapsed": false      // Children hidden behind Moons
      },
      "submaps": []
    }
  ],
  "connections": [
    {
      "id": "edge_999",
      "from": "abc123xyz",      // Source node ID
      "to": "def456lmn",        // Target node ID
      "type": "structural"      // structural | association | flow
    }
  ],
  "session": {
    "viewport": { "x": 960, "y": 540, "scale": 1 },
    "selectedId": null,
    "remoteTemplates": [],
    "layoutMode": "organic"
  },
  "submaps": []                 // Caches templates or local portal configurations
}

11. Force-Directed Physics

The layout is driven by a custom iterative algorithm found in Kernel.resolveOverlaps(). It applies two simultaneous forces to form organic trees dynamically.

Upon node creation, a fast 40-iteration burst runs to clear space. Clicking the "Arrange" UI button triggers a deep 150-iteration simulation to organically untangle complex webs. Pinned nodes (isCore: true) are immune to physics forces.

12. Serverless Library Engine

In v14.7, we deprecated fetch() calls to external JSON files to bypass local file:// CORS restrictions. The engine now uses a globally mounted MultiMapLibrary object loaded via multi-map-library.js.

13. Federation & API Roadmap

The platform is actively transitioning toward a federated, decentralized storage model.