Architecture

%% litho-mermaid
flowchart TB
    Dev(["Developer in terminal"])
    Browser(["Browser for kanboard UI"])
    Mobile(["Remote device for notifications"])

    subgraph HostProc["Pi coding agent host process"]
        PiAPI["Pi ExtensionAPI: tools, commands, hooks, events, TUI"]
        subgraph UnipiSuite["Unipi extension suite in-process"]
            Umbrella["@pi-unipi/unipi composition root"]
            Modules["23 feature modules on @pi-unipi/core"]
        end
    end

    McpServers["MCP servers as child processes"]
    ChildPi["Child Pi processes for subagents and delegates"]
    Sidekick["Fusion sidekick runtime process"]
    Providers["LLM and image model providers"]
    MemPalace["MemPalace via Python uv bridge"]
    SQLite["SQLite databases"]
    FS["Local filesystem .unipi and ~/.unipi"]
    WebContent["Remote web content"]
    NotifPlatforms["ntfy, gotify, Telegram, native, Focus"]

    Dev --> HostProc
    PiAPI <--> Umbrella
    Umbrella --> Modules
    Modules -->|JSON-RPC stdio| McpServers
    Modules -->|spawn and tail| ChildPi
    Modules -->|spawn| Sidekick
    Modules -->|model registry| Providers
    Modules -->|spawnSync JSON lines| MemPalace
    Modules -->|read write| SQLite
    Modules -->|atomic writes| FS
    Modules -->|wreq-js fetch| WebContent
    Modules -->|dispatch| NotifPlatforms
    NotifPlatforms --> Mobile
    Modules -->|HTTP server| Browser

%% litho-mermaid
flowchart TB
    subgraph HostLayer["Host boundary"]
        PiAPI["Pi ExtensionAPI"]
    end

    subgraph Composition["Composition layer"]
        UmbrellaEntry["@pi-unipi/unipi index.ts fixed load order"]
        Bundle["scripts/build-bundle.mjs produces bundled.js"]
        Tracer["trajectory tracer.scope wraps each module"]
    end

    subgraph Features["Feature modules"]
        direction LR
        subgraph Orch["Agent Orchestration"]
            Subagents["subagents"]
            BgTasks["background-tasks"]
            Ralph["ralph"]
        end
        subgraph Ctx["Context and Memory"]
            Compactor["compactor"]
            Memory["memory"]
            Trajectory["trajectory"]
        end
        subgraph Ext["External Capability"]
            Mcp["mcp"]
            WebApi["web-api"]
            Image["image"]
            Fusion["fusion"]
        end
        subgraph UX["Interaction and Presentation"]
            Footer["footer"]
            AskUser["ask-user"]
            Notify["notify"]
            InfoScreen["info-screen"]
            Shortcuts["input-shortcuts"]
            CmdEnch["command-enchantment"]
            Btw["btw"]
        end
        subgraph Wf["Structured Workflow"]
            Workflow["workflow"]
            Milestone["milestone"]
            Kanboard["kanboard"]
        end
        subgraph Infra["Infra utilities"]
            Utility["utility"]
            Updater["updater"]
        end
    end

    subgraph Kernel["Shared kernel"]
        Core["@pi-unipi/core: constants, UNIPI_EVENTS, sandbox, tui-overlay, tui-width, model-cache, fusion-status, bounded-output"]
    end

    PiAPI --> UmbrellaEntry
    Bundle -.->|builds| UmbrellaEntry
    UmbrellaEntry --> Tracer
    Tracer --> Features
    Features --> Core
    Features --> PiAPI
    Footer -->|direct import| BgTasks

workflow → ralph → memory → utility → info-screen → subagents → background-tasks →
btw → web-api → ask-user → mcp → notify → milestone → kanboard →
command-enchantment → compactor → footer → updater → input-shortcuts → image → fusion → trajectory

%% litho-mermaid
flowchart LR
    subgraph EventBus["Channel 1: Pi event bus pi.events"]
        Events["UNIPI_EVENTS typed payloads: MODULE_READY, WORKFLOW_*, RALPH_*, MEMORY_*, MCP_*, COMPACTOR_COMPACTED, NOTIFICATION_SENT, ASK_USER_PROMPT, UPDATE_*"]
    end

    subgraph Globals["Channel 2: globalThis shared state"]
        TaskReg["Symbol.for unipi.background-tasks.shared-registry"]
        FusionStat["Symbol.for unipi.fusion.status"]
        InfoReg["globalThis.__unipi_info_registry"]
    end

    subgraph Imports["Channel 3: direct package imports"]
        CoreImp["every module imports @pi-unipi/core"]
        FooterImp["footer imports background-tasks getSharedTaskRegistry"]
        UmbrellaImp["unipi imports all modules"]
    end

    Producers["workflow, ralph, memory, mcp, compactor, updater, ask-user, utility"] -->|emitEvent| Events
    Events -->|pi.events.on| Consumers["notify, footer, info-screen, trajectory"]
    BgTasks["background-tasks"] -->|setSharedTaskRegistry| TaskReg
    TaskReg -->|sync read| FooterNode["footer"]
    TaskReg -->|sync read via symbol| NotifyNode["notify"]
    FusionNode["fusion"] -->|setSharedFusionStatus| FusionStat
    FusionStat -->|getSharedFusionStatus| FooterNode
    InfoScreenNode["info-screen"] -->|publishes| InfoReg
    InfoReg -->|registerGroup| Contributors["subagents, mcp, others"]

%% litho-mermaid
flowchart TB
    PrimaryLLM(["Primary agent LLM"]) -->|spawn_helper get_helper_result| ToolHandler["subagents tool-handler.ts: agent resolution, aliases, budgets, depth guard, context policy, missions"]
    ToolHandler --> AgentManager["agent-manager.ts concurrency queue default 4 background"]
    AgentManager -->|foreground| AgentRunner["agent-runner.ts in-process AgentSession with ESC abort"]
    AgentManager -->|background async| AsyncRunner["async-runner.ts spawns pi --mode json -p"]
    ToolHandler --> WorkflowScript["workflow-script.ts and workflow-worker.ts scripted multi-child runs"]
    ToolHandler --> Worktree["worktree.ts git worktree isolation"]
    AsyncRunner --> PiSpawn["pi-spawn.ts resolves pi binary"]
    AsyncRunner --> Supervisor["supervisor-channel.ts"]
    AsyncRunner --> RunFiles["status.json output.txt events.jsonl"]
    AgentRunner --> FleetView["fleet-view.ts widget.ts conversation-viewer.ts"]

    subgraph BgPkg["background-tasks"]
        Registry["registry.ts BackgroundTaskRegistry: spawn, tail, snapshot, kill tree"]
        Delegate["delegate/: seed, launch, budget, artifacts, result-package"]
        DelegateChild["extensions/delegate-child.ts"]
        SharedReg["registry-shared.ts Symbol.for slot"]
        Registry --> Delegate
        Registry --> SharedReg
        Delegate --> DelegateChild
    end

    subgraph RalphPkg["ralph"]
        RalphLoop["ralph-loop.ts iterative loop with RALPH_LOOP_START END and ITERATION_DONE"]
        Reminder["reminder.ts loop reminder injection"]
        RalphLoop --> Reminder
    end

%% litho-mermaid
flowchart LR
    subgraph CompactorPkg["compactor"]
        Hooks["compaction/hooks.ts"] --> AutoTrigger["auto-trigger.ts token estimate vs budget"]
        AutoTrigger --> Pipeline["summarize.ts compile: normalize, filterNoise, buildSections, formatSummary, merge, ranked brief"]
        Pipeline --> Extractors["extract/: commits, files, goals, preferences"]
        SessionDB["session/db.ts SessionDB SQLite"]
        Resume["session/resume-inject.ts auto-inject.ts recall-blocks.ts"]
        ToolsReg["tools/register.ts: compact, session_recall, sandbox, sandbox_file, sandbox_batch, compactor_stats, compactor_doctor, context_budget"]
        Executor["executor/executor.ts PolyglotExecutor 11 languages, env scrubbing, killTree"]
        Security["security/: policy, scanner, evaluator"]
        Config["config/manager.ts presets.ts"]
        SettingsTUI["tui/settings-overlay.ts"]
        ToolsReg --> Executor --> Security
        ToolsReg --> SessionDB
        SessionDB --> Resume
        Pipeline --> SessionDB
    end

    subgraph MemoryPkg["memory"]
        Storage["storage.ts MemoryStorage"]
        MemPal["mempalace.ts spawnSync Python bridge, uv auto-install"]
        Bridge["bridge/mempalace_bridge.py"]
        Markdown["markdown durable tier"]
        LegacyDB["legacy SQLite fallback and migration source"]
        Storage --> MemPal --> Bridge
        Storage --> Markdown
        Storage -.->|fallback| LegacyDB
    end

    subgraph TrajPkg["trajectory"]
        TracerC["tracer.ts createUnipiTracer scope"]
        Telemetry["telemetry.ts TelemetrySidecar"]
        Capture["capture.ts prefix-integrity.ts server.ts"]
        TracerC --> Telemetry --> Capture
    end

%% litho-mermaid
flowchart TB
    subgraph McpPkg["mcp"]
        McpConfig["config/: manager, schema, sync, seed-servers.json"] --> ServerRegistry["bridge/registry.ts ServerRegistry start stop restart with partial-failure cleanup"]
        ServerRegistry --> McpClient["bridge/client.ts McpClient JSON-RPC stdio: initialize, listTools, callTool"]
        ServerRegistry --> Translator["bridge/translator.ts MCP tool to Pi tool with unique names"]
        Translator -->|registerTool or registerExternalTool| PiTools["Pi tool registry"]
        ServerRegistry -->|MCP_SERVER_* MCP_TOOLS_*| McpBus["pi.events"]
        McpTUI["tui/: add-overlay, settings-overlay"] --> ServerRegistry
    end

    subgraph WebPkg["web-api"]
        WebTools["tools.ts"] --> ProviderReg["providers/registry.ts: duckduckgo, tavily, serpapi, perplexity, jina-reader, firecrawl, wigolo"]
        ProviderReg --> Engine["engine/extract.ts: URL validation, wreq-js fetch, content-type routing, defuddle, fallbacks"]
        Engine --> WebCache["cache.ts"]
        Engine --> Format["engine/format.ts dom.ts profiles.ts"]
        ProviderTUI["tui/provider-selector.ts"] --> ProviderReg
    end

    subgraph ImagePkg["image"]
        ImageTools["tools.ts: image_generate image_recognize"] --> GenRec["generate.ts recognize.ts"]
        GenRec --> OpenAIImages["openai-images-api.ts"]
        ImageTools --> VisionGate["vision gating by active model"]
        RegisterProv["register-providers.ts models.ts"] --> GenRec
    end

    subgraph FusionPkg["fusion"]
        Picker["picker.ts preset-editor.ts overlays"] --> PresetStore["preset.ts persisted preset"]
        PresetStore --> SidekickRT["sidekick-runtime.ts"]
        SidekickRT --> Savings["savings.ts"]
        Savings -->|setSharedFusionStatus| CoreFusion["core/fusion-status.ts"]
        FusionTools["tools.ts transcript.ts nudge.ts"] --> SidekickRT
    end

%% litho-mermaid
flowchart LR
    subgraph FooterPkg["footer"]
        Renderer["rendering/renderer.ts FooterRenderer two-row responsive layout"]
        FooterReg["registry/index.ts FooterRegistry"]
        Segments["segments/: core, compactor, memory, mcp, ralph, workflow, kanboard, notify, status-ext"]
        ProcessLine["process-line.ts background task dots"]
        TpsTracker["tps-tracker.ts"]
        Presets["presets.ts glance-editor.ts settings-tui.ts"]
        Renderer --> Segments
        Renderer --> ProcessLine
        FooterReg --> Segments
        Renderer --> TpsTracker
    end

    subgraph NotifyPkg["notify"]
        NotifyEvents["events.ts subscription registry built-in plus MODULE_READY discovered"]
        Platforms["platforms/: native, ntfy, gotify, telegram, focus"]
        Summarize["summarize.ts recap via model"]
        Activity["activity.ts pending wake tasks"]
        NotifyEvents --> Platforms
        NotifyEvents --> Summarize
        NotifyEvents --> Activity
    end

    AskUserC["ask-user: tools.ts, ask-ui.ts, launcher-ui.ts, handoff.ts"]
    InfoScreenC["info-screen: registry.ts cache-first 5s TTL, info-overlay.ts, usage-parser.ts"]
    ShortcutsC["input-shortcuts: chord-overlay, undo-redo, registers, clipboard"]
    CmdEnchC["command-enchantment: provider.ts sorting.ts"]
    BtwC["btw/extensions/btw.ts"]

    EventBus["pi.events"] --> NotifyEvents
    EventBus --> Renderer
    SharedGlobals["globalThis registries"] --> ProcessLine
    SharedGlobals --> InfoScreenC

%% litho-mermaid
flowchart LR
    WorkflowC["workflow/index.ts: /unipi:brainstorm plan work review-work, sandbox levels, WORKFLOW_START END"]
    WorkflowC -->|skills| SkillFiles["SKILL.md instruction files"]
    WorkflowC -->|core/sandbox.ts| SandboxPrims["getBlockedToolsForLevel isToolAllowed"]
    WorkflowC --> WorkflowDocs[".unipi/docs specs plans reviews"]
    MilestoneC["milestone: commands, hooks, MILESTONES.md model"] --> MilestoneDoc["MILESTONES.md"]
    WorkflowDocs --> KParser["kanboard/parser ParserRegistry: CheckboxParser configs, PlanParser, MilestoneParser"]
    MilestoneDoc --> KParser
    KParser --> KServer["kanboard/server plus routes milestone and workflow"]
    KServer --> KUI["kanboard/ui server-rendered pages with htmx and Alpine.js"]
    KUI --> BrowserC(["Browser"])

%% litho-mermaid
flowchart TB
    LLMAgent(["Primary agent"])
    ToolHandlerN["subagents tool-handler"]
    RegistryN["background-tasks registry"]
    CompactorN["compactor pipeline"]
    McpN["mcp ServerRegistry"]
    FusionN["fusion sidekick runtime"]
    BusN["core event bus"]
    TaskSlot["Symbol.for task registry"]
    FusionSlot["Symbol.for fusion status"]
    NotifyN["notify events"]
    FooterN["footer renderer"]
    InfoN["info-screen registry"]

    LLMAgent -->|tool calls| ToolHandlerN
    LLMAgent -->|tool calls| CompactorN
    LLMAgent -->|bridged tool calls| McpN
    ToolHandlerN -->|MODULE_READY task events| BusN
    RegistryN -->|MODULE_READY| BusN
    RegistryN -->|setSharedTaskRegistry| TaskSlot
    CompactorN -->|COMPACTOR_COMPACTED| BusN
    McpN -->|MCP_SERVER_* MCP_TOOLS_*| BusN
    FusionN -->|setSharedFusionStatus| FusionSlot
    BusN --> NotifyN
    BusN --> FooterN
    TaskSlot --> FooterN
    TaskSlot --> NotifyN
    FusionSlot --> FooterN
    ToolHandlerN -->|registerGroup| InfoN
    McpN -->|registerGroup| InfoN

%% litho-mermaid
sequenceDiagram
    participant Pi as Pi host
    participant U as unipi/index.ts
    participant T as trajectory tracer
    participant M as Module e.g. mcp
    participant Bus as pi.events
    participant N as notify footer info-screen

    Pi->>U: default(pi)
    U->>T: createUnipiTracer(pi)
    loop each module in fixed order
        U->>T: tracer.scope(name)
        T-->>U: scoped ExtensionAPI
        U->>M: module(scopedApi)
        M->>M: load or scaffold config
        alt master toggle off
            M->>M: register nothing
        else enabled
            M->>Pi: registerTool registerCommand on(...)
        end
    end
    Pi->>M: session_start
    M->>M: init backends fail-soft
    M->>Bus: emit MODULE_READY name version commands tools
    Bus->>N: MODULE_READY
    N->>N: enable integration for discovered peer

%% litho-mermaid
graph TD
    Start(["Parent agent decides to delegate"]) --> CallSpawn["LLM calls spawn_helper"]
    CallSpawn --> RouteAction{"Action type"}
    RouteAction -->|management| Manage["Fleet management: list, status, kill, view conversation"]
    RouteAction -->|workflowScript| Script["workflow-worker runs scripted multi-child steps"]
    RouteAction -->|single launch| Resolve["Resolve agent profile and aliases"]

    Resolve --> Enabled{"Agent enabled"}
    Enabled -->|no| Reject["Return error to parent"]
    Enabled -->|yes| Depth{"Depth guard passed"}
    Depth -->|no| Reject
    Depth -->|yes| Budget{"Spawn and token budget available"}
    Budget -->|no| Reject
    Budget -->|yes| Policy["Apply context policy, timeout defaults, output limits"]

    Policy --> Mode{"Run mode"}
    Mode -->|foreground| FgRun["AgentManager runs in-process AgentSession via agent-runner"]
    Mode -->|background| Queue["AgentManager queues, max 4 concurrent"]
    Queue --> SpawnProc["async-runner spawns pi --mode json -p"]
    SpawnProc --> Tail["Write status.json, output.txt, events.jsonl; tail output"]

    Script --> Tail
    FgRun --> Collect["Collect AgentRecord result"]
    Tail --> Done{"Finished, failed or timed out"}
    Done -->|timeout| Kill["Kill process tree"]
    Kill --> Emit
    Done -->|finished or failed| Emit["Emit completion on core event bus"]

    Emit --> NotifyStep["notify builds message and dispatches"]
    Emit --> FooterStep["Footer fleet and task segments refresh"]
    Emit --> Wait["Parent calls get_helper_result"]
    Collect --> Wait
    Wait --> Truncate["Apply bounded output truncation"]
    Truncate --> Return(["Result package returned to parent"])

    Manage --> Return
    Reject --> Return
    Esc["User presses ESC in parent"] -.->|abort propagated| Kill

%% litho-mermaid
graph TD
    Trigger{"Trigger source"} -->|turn hook| Estimate["auto-trigger estimates tokens vs budget"]
    Trigger -->|/unipi compact| Compile
    Trigger -->|compact tool| Compile
    Estimate --> Over{"Over threshold"}
    Over -->|no| Skip(["No action this turn"])
    Over -->|yes| Compile["compile in summarize.ts"]

    Compile --> S1["1 normalize messages"]
    S1 --> S2["2 filterNoise"]
    S2 --> S3["3 buildSections: commits, files, goals, preferences"]
    S3 --> Ranked{"Ranked brief enabled"}
    Ranked -->|yes| Brief["selectRankedBriefBlocks"]
    Ranked -->|no| S4
    Brief --> S4["4 formatSummary"]
    S4 --> S5["5 merge with previous summary"]
    S5 --> Replace["Replace history with merged summary"]

    Replace --> DB["SessionDB inserts events and compaction counters"]
    Replace --> Seg["Compactor footer segment shows stats"]
    Replace --> Evt["COMPACTOR_COMPACTED on core bus"]

    Resume(["Later session start"]) --> Inject["resume-inject restores prior summary"]
    DB --> Inject
    Inject --> Recall["Agent calls session_recall for blocks"]

%% litho-mermaid
sequenceDiagram
    participant Pi as Pi host
    participant I as mcp/index.ts
    participant R as ServerRegistry
    participant C as McpClient
    participant S as MCP server child
    participant Tr as translator.ts

    Pi->>I: session_start
    I->>I: detect registerTool or registerExternalTool
    I->>R: new ServerRegistry(emitEvent, registerTool, unregisterTool)
    I->>R: loadAndResolve(cwd)
    loop each resolved server
        R->>C: start over stdio
        C->>S: initialize
        alt handshake fails
            R->>R: mark failed, disconnect, clean partial registrations
        else ok
            C->>S: tools/list
            S-->>C: tools
            C-->>Tr: translate to Pi tool defs with unique names
            Tr->>Pi: registerTool
            R->>Pi: emit MCP_SERVER_STARTED MCP_TOOLS_REGISTERED
        end
    end
    Note over R: agent calls are proxied via callTool
    Note over R: session end disconnects all and unregisters tools

%% litho-mermaid
graph LR
    Call(["web fetch or search tool call"]) --> CacheHit{"Cache hit"}
    CacheHit -->|yes| Return(["Return cached text"])
    CacheHit -->|no| Provider["Select provider from registry"]
    Provider --> Validate["Validate URL and options"]
    Validate --> Fetch["wreq-js TLS-fingerprinted fetch"]
    Fetch --> Refresh{"Meta refresh detected"}
    Refresh -->|yes| Fetch
    Refresh -->|no| Route["Route by content type"]
    Route --> Extract["defuddle extraction"]
    Extract --> Enough{"Content sufficient"}
    Enough -->|no| Fallback["Fallback extraction strategy"]
    Enough -->|yes| FormatStep
    Fallback --> FormatStep["Format to text"]
    FormatStep --> Store["Store in cache"]
    Store --> Return

%% litho-mermaid
graph TD
    Cmd(["User runs /unipi:model"]) --> ResolveM["Resolve Pi model registry via core model-cache"]
    ResolveM --> Rows["Convert models to picker rows"]
    Rows --> Overlay["Mount picker overlay in TUI"]
    Overlay --> Pick{"User selects pair"}
    Pick -->|cancel| NoChange(["No change"])
    Pick -->|confirm| Apply["Apply FusionResult to persisted preset"]
    Apply --> SidekickStep["Stop old sidekick, spawn new sidekick runtime"]
    SidekickStep --> Publish["setSharedFusionStatus active pair and savings"]
    Publish --> FooterF["Footer core segment renders fusion status"]
    PresetCmd(["User runs /unipi:fusion-preset"]) --> Editor["Preset editor overlay"]
    Editor --> Apply

%% litho-mermaid
graph TD
    CallA(["Agent calls ask_user"]) --> ValidateA["Validate TypeBox schema and normalise options"]
    ValidateA --> Allowed{"Format allowed by settings"}
    Allowed -->|no| ErrA(["Return validation error"])
    Allowed -->|yes| RenderA["Render TUI prompt"]
    RenderA --> AlertA["notify dispatches ASK_USER_PROMPT and tracks wake task"]
    RenderA --> ChoiceA{"User action"}
    ChoiceA -->|answer| ResponseA["Build AskUserResponse"]
    ChoiceA -->|hand off| LauncherA["Launcher UI starts new session and hands off"]
    LauncherA --> ResponseA
    ResponseA --> ReturnA(["Return to agent"])

%% litho-mermaid
graph TD
    CmdW(["User runs workflow command"]) --> Dispatch["Dispatch to skill for LLM instruction"]
    Dispatch --> SandboxW["Enforce sandbox level via core/sandbox"]
    SandboxW --> Snapshot["Show sandbox snapshot message"]
    Snapshot --> Work["Agent works within sandbox"]
    Work --> MilestoneW["Milestone commands and hooks update MILESTONES.md"]
    Work --> DocsW["Plans and specs written to .unipi/docs"]

    Board(["User starts kanboard server"]) --> Scan["ParserRegistry parseAll scans files"]
    DocsW --> Scan
    MilestoneW --> Scan
    Scan --> Detect["Auto-detect parser by path"]
    Detect --> Parse["Parse frontmatter and checkboxes"]
    Parse --> Serve["HTTP routes render workflow and milestone pages"]

    Work --> SegW["Footer workflow and kanboard segments"]
    CmdW --> RalphQ{"ralph detected via MODULE_READY"}
    RalphQ -->|yes| LoopW["Optionally run as autonomous loop"]

%% litho-mermaid
graph LR
    EventN(["Pi lifecycle or module event"]) --> Match["Subscription registry matches handler"]
    Match --> Text["Build message text from payload"]
    Text --> Summ{"Recap summarisation on"}
    Summ -->|yes| Recap["Summarise activity via model"]
    Summ -->|no| Prio
    Recap --> Prio["Map event to priority"]
    Prio --> Suppress{"Focus or activity suppression"}
    Suppress -->|suppressed| Drop(["Drop"])
    Suppress -->|allowed| PlatformsN["For each enabled platform"]
    PlatformsN --> NativeN["Native"]
    PlatformsN --> NtfyN["ntfy"]
    PlatformsN --> GotifyN["gotify"]
    PlatformsN --> TelegramN["Telegram"]
    PlatformsN --> FocusN["Focus"]
    Match --> Wake["Track pending wake task if input needed"]

%% litho-mermaid
flowchart TB
    subgraph DevMachine["Developer machine"]
        subgraph PiProcess["Pi host process Node 22"]
            BundledJs["packages/unipi/bundled.js"]
            Skills["per-package skills directories"]
            Prompts["packages/subagents/prompts"]
        end
        ChildPiProcs["Child pi processes"]
        McpProcs["MCP server processes"]
        SidekickProc["Fusion sidekick process"]
        PyBridge["Python MemPalace bridge uv venv"]
        KanServer["Kanboard HTTP server localhost"]
        TrajServer["Trajectory server localhost"]
        subgraph Disk["Local disk"]
            ProjectDir[".unipi project dir: docs, ralph, session db"]
            UserDir["~/.unipi: memory, configs"]
            TempRoots["temp roots: delegate artifacts, async runs"]
        end
    end

    Registry["npm registry @pi-unipi/*"]
    Remote["Remote services: providers, web, notification platforms"]

    Registry -->|npm install| PiProcess
    PiProcess --> ChildPiProcs
    PiProcess --> McpProcs
    PiProcess --> SidekickProc
    PiProcess --> PyBridge
    PiProcess --> KanServer
    PiProcess --> TrajServer
    PiProcess --> Disk
    ChildPiProcs --> TempRoots
    PiProcess --> Remote