io.github.zombico/mojulo

Compare the running control-plane package (`mojulo` on npm) and the pinned bot image (`ghcr.io/zombico/mojulo-bot`) against their latest published versions. Returns `{ controlPlane, botImage, warnings }` — each surface reports `current`, `latest`, `updateAvailable`, and a one-line install/update hint when an upgrade exists. Read-only: never installs or restarts anything; surface the hint and let the user run it. Best-effort upstream calls — a registry timeout produces `latest: null` plus a warning, not a tool failure. Call this when the user asks 'am I up to date?', after a long gap between sessions, or before recommending a feature that depends on a recent version.

Forward the agent mojulo's routing index — two wings behind one tool. No `mode` is the STUDIO, the DEFAULT: the creative wing's per-FORM recognizer rows (picture / object / world / building / motion / motion-comic / audio / voice / publication / game) plus the creative drawers (`get_creative_toolset`, routing cards, vocab kinds). `mode:'office'` is the automation backend: `user-framing → entry-tool` rows for bots / connected services / apps / operate-what-exists. Both carry a lean opener, a drawer directory (`get_tool_index`, `get_register_kit`, `get_deliberation_overview`, `get_ui_map`, `get_substrate`), and the standing safety + commitment-level rules. Call FIRST when unsure what mojulo is or which tool fits; open the office when the ask is to WIRE or OPERATE, not to make. A thin map, not a manual — depth lives in the drawers. The disclosure directive branches on the operator's `procedural_disclosure`; optional per-call `register` / `disclosure` override the anchor for this read. Read-only, idempotent.

Return just the register-tuning surface — the active communication-settings notice (which `vocabulary_register` / `procedural_disclosure` cell is active and where it came from), the active-cell concept glossary, the refusal legend (one row per family of refusal: what it protects · the next move — pull this when a tool said no and you're unsure what the no means), the active-cell disclosure directive, and the invariant commitment-level floor (the four gates). Resolves the operator anchor the same way `forward_context` does; optional per-call `register` / `disclosure` override it for this one read. Call once after orientation, whenever the operator revises their KYC anchor, or when decoding a refusal. Read-only, idempotent.

Return what mojulo is and what it can honestly claim — a 3D compiler for agents: Media (objects, worlds, views, audio) and Game as re-runnable recipes on the operator's machine; the digital (Godot, Unity, Unreal, Blender) and physical (STL / 3MF) pipelines; where inference runs; what the retained automation backend (Bot, Connected Service, App) adds — PLUS a dozen SELF-DESCRIPTION facts (process, state, network posture, credentials, costs, uninstall, source) to DERIVE meta-answers from. Call for 'what is this really?' or questions about mojulo ITSELF: 'does it phone home?', 'where does my data live?', 'do I have to pay?', 'how do I uninstall?'. Read-only, no inputs, idempotent.

One-line-per-tool index across every ring — call when a `forward_context` row isn't specific enough (Media tools live behind `get_creative_toolset`). **~48k**: a host declaring a smaller output cap gets the compact rules card fitted to that cap instead; `full: true` returns the whole index regardless. Read-only, idempotent.

Read the ledger the substrate keeps of its own MCP tool calls — shapes and timings, one row per handler invocation across both call paths (rpc + plan-executor); nothing leaves the machine. Three modes: no args → a per-tool aggregate table (calls, error rate, p50/p95 latency, last-called) over the last `sinceDays` (default 7) plus the most recent errors and timeouts; `{ tool }` → that tool's recent calls newest-first with status + duration; `{ orientation: true }` → the orientation-gap cut (weak semantic searches, vocab-drawer misses, sessions that oriented then made no non-orientation call) — the measurement of whether the ask-and-discover loop is rewarding the question. This is the in-session answer to "which tool broke?" / "what's slow?" / "is the lexicon working?" without leaving the chat. Records SHAPES only — never input values or conversation content. Read-only, idempotent. Mirrors the `/observability` dashboard page.

Return the page-by-page map of the `mojulo-ui` dashboard (the human-shaped face of the same `~/.mojulo/` state this MCP drives): one line per page describing what it's for and when to point the user at it (`/bots`, `/chat-builder`, `/apps`, `/data`, `/map`, `/graph`, `/plan`, `/research`, `/sketches`, `/maker`, `/settings`, …). You don't drive these pages — call this when the user wants to *look*, *browse*, or *click*, or when a visual scan would beat several rounds of tool output, so you can name the right page. Read-only, no inputs, idempotent.

Return one annotated end-to-end trace of a successful flight for a paradigm — the real call sequence with realistic args, abbreviated return shapes, the commitment gates named where they happen (proposed vs materialized, dry-run vs promoted, sealed vs not recorded), and one deliberate refusal + recovery so the first 'no' you meet in the wild is a recognized shape. Paradigms: `bot` (build → compile → operate), `connected-service` (inventory → primitive binding → seal), `app` (scaffold → commit → start → fulfill inference), `game` (the promotion-gate flagship: watch a level get refused, prove it completable, re-mint), `media` (stash → gather → cook). Omit `paradigm` for the index. Pull BEFORE your first build of a paradigm — one read replaces trial-and-error against per-tool descriptions. Traces are illustrative (refs and values will differ) but the call sequence, gate order, and refusal shapes are real. Read-only, idempotent.

Mint a flow-chart, data-chart, or standard diagram → a /sketches/<ref> url. Kernel diagram maker (no creative pack). Manifest: { title, viewBox:{width,height}, + stations[]+edges[] (boxes+arrows) and/or marks[] (rect/circle/wedge/line/text/…) }. Edges { from,to,label?,head?,tail?,dashed? }: head/tail typed markers (arrow/triangle-open/diamond[-filled]/crowsfoot-one|many/dot/none), from===to self-loops. Higher-level kinds auto-lower to marks: kind:'sequence' {actors,messages}, kind:'gantt' {scale,tasks}, lanes[] (swimlanes), boundaries[] (containment), station.divider (ERD). Vocab: semantic_search({kinds:['sketch_vocab']}). Returns {ok,ref,url}. (Illustration/worlds/beats → create_sketch.)

AUDIO — Mojulo Beats: synthesized soundtracks, compositions, grooves and SFX as tiny seeded recipes (never samples): create / get / update / annotate / diff / export beats plus beats-vocab cards; a composition can SING via a voice part. Open for 'background music for the forest level', 'a sting when the boss appears', "tweak bar 2's kick", 'render the tune to a WAV'.

CATALYSTS & EXTENSION — curated workflow recipes shipped via MCP: get / list / recommend catalysts, the meta-catalyst, mint a custom catalyst or drawer, and host-adapter info (get / list adapters — how a recipe lands as a Skill on this host). Open for 'is there a recipe for X', 'install this workflow as a skill', 'extend mojulo with a new drawer'.

CONNECTED SERVICES — deliberate over the operator's installed MCP servers and bind workflows over them (no chatbot): declare inventory & skills, record/read provider capabilities, browse mcp-orbit components, get composition recommendations, bind primitives and triggers, read the deliberation overview and the contextmap (brief / commit). Open for 'wire Gmail + Calendar into a routine', 'every Monday summarize new leads into our CRM', 'sync submissions to a sheet nightly', 'what MCPs do I have', 'automate X across my services'.

DIAGRAMS & CHARTS + scene sketches viewed in the dashboard: flow charts (stations + edges), data charts (stacked bars, donut / ring, KPI tiles, marks), scene illustrations and keyframe / scene-motion animation of drawn characters; revise a sketch in place, visual-diff two sketches, read sketch-vocab layout cards and style presets. Open for 'draw / diagram X', 'a bar chart of signups by week', 'a donut chart of the split', 'sketch our pipeline as boxes and arrows', 'make my drawn character talk and blink', 'update that sketch'.

GAMES — playable standalone artifacts composed over media: create_game (levels are worlds minted with a game contract), pixelizer 2D reducer games, sprite sheets (create + bake), game projects (create / get / update / bind / list), game-vocab cards, and export_game (self-contained folder). Open for 'a playable dungeon crawler I can actually walk around in', 'a roguelike where my gear persists across floors', 'a pixel-art game with sprites', 'a pixel-art cutscene of my hero', 'export my game so a friend can play it'.

Painted scene & figure ILLUSTRATION + publication covers: the inverse-stable-diffusion knob-resolution loop (sketch_what_possible) that feeds create_sketch recipe families, and create_cover for title art composed under one art direction. Open for 'paint a moody mountain valley', 'illustrate my hero', 'a cover for this book'. Sketch minting is homed in pack_diagram; this pack dispatches it too.

AI-IMAGE + MESH RENDER pipeline — direct, queue, and gate externally-painted images and externally-sculpted meshes (the mesh quartet parks a greybox for Meshy / Tripo / Hunyuan3D…): render packets for image-outcome / comic / character-sheet sketches, the durable request → pull → submit → accept / reject worker loop, and binding finished PNGs and character sheets back onto their sketches. Open for 'have the image model paint this', 'an AI-painted portrait rendered by an image model', 'run the render queue', 'accept that render'.

MOTION & FILM (+ motion-comic) — add TIME to a static subject: forge_motion (camera moves and performances rendered to flipbook SVG + GIF), stitch_motion (clips → one film), motion-vocab cards, and the click-gated motion-comic authored via update_sketch. Open for 'give me a spinning view of that molecule', 'record the hero clearing the chasm and show me the clip', 'walk to the exit to check the level is beatable' (traversal proof), 'present these charts one after another as a click-through deck', 'merge the clips into a single movie'.

3D SOLIDS — figures, creatures, objects, buildings, wordmarks, vehicles: mint_solid (kinds figure / manji-tree / workbench / assembler / carved-solid / solid-turntable / edifice / vehicle), edit_solid (skin / emote ops), solid-vocab cards, measure_solid (numbers back off a solid), and verify_machina feasibility checks. Open for 'model a wine glass true to size', 'a woman mid-stride' (a posed figure), 'our logo in shiny chrome', 'a 3D creature', 'put the wheels and the chassis together into one model', 'turn this concept art into a 3D model piece by piece', 'rebuild a drawing as a real 3D model, segment by segment'. Placing solids IN an environment is pack_world.

PLAN MODE — the speculative layer over sealed reality: enter plan mode, forge and revise plans, read and list them, compile a plan to a manifest of tool calls and execute it under per-execution operator approval, sketch a plan visual. Open for 'let's plan this out', 'turn this session into a plan', 'execute the plan'.

VISUAL REFERENCE — read a photo YOU can see into mojulo dials: reference_protocol hands the extraction protocol (scene perspective or human pose — you are the vision adapter, no image sent), capture_reference files the read as a reusable cage + insights in a stash. Open for 'recreate the camera angle from this photo', 'match this pose'.

RESEARCH MODE — accretive gathering upstream of plans: enter research mode, start a research book, bind items into it, read and list books, synthesize an abstract (with deterministic review), run a parameter experiment sweep with auto-plotted outcomes, sketch the research. Open for 'research this', 'gather sources into a book', 'sweep the parameter and plot the outcome'.

APPS & RUNTIME — local apps (install_scaffold → start / stop / status, runner listing), runtime daemons (list / status / start / stop / restart), and the agent-task loop (pull_agent_task → submit_envelope_inference → cancel; chat signals and decisions for the chat_turn worker). Open for 'scaffold and run a local app', 'watch a folder and process new files as they arrive', 'a background worker that reacts to events', 'restart the daemon', 'work the task queue'.

GATHER / STASH / COOK / PUBLISH — typed collection into stashes (gather, mint / get / list / rename a stash, update / archive items, bind / unbind to anchors), then COOK stashes into an Outcome Artifact (agent-authored report + visuals) and forge publications. Open for 'save this for later', 'collect these into a stash', 'cook these notes into a report', 'make a zine / picture book / publication'.

STUDY VIEWS — animated 3D study objects that teach a phenomenon: create_view kinds across science / math / bio, view-vocab parameter manuals, measure_view for SI-honest time-series read-back from the stored recipe, and save_recipe to KEEP a tuned setup in the operator's cookbook (view and beats recipes alike), recallable by intent later. Open for 'help my kid understand black holes', 'an animated science explainer for my kid', 'animate how DNA copies itself', 'measure the orbit', 'save this setup for my class'.

VOICE — deterministic voice registers (confidence × depth resolved to Kokoro blend weights, pure math): create / read a voice, bind worker-rendered WAV samples, and the voice-vocab drawer. Scope is voiceover and narration, not character acting. Open for 'a warm narrator voice', 'render this line in her voice', 'design how the guide sounds'.

WORLDS — traversable three.js environments: compose_world (BASE × THEME × overrides — city, transport-hub, controllable, action, planetary, painted-landscape, math, school, dungeon), theme packs, glTF export (export_model), binding refined meshes back (bind_mesh_render), and modeler-lingo translation. Open for 'build a little town I can wander around', 'an airport', 'a game where I drive', 'export to Blender'.

Fuzzy retrieval over durable mojulo state: principles, capability bodies, mcp-orbit components / compositions / provider artifacts, declared MCP tool inventory, the shipped catalyst library, sketch vocabulary cards, the per-knob `sketch_method` capability records, manji-program-bearing cards (mandala-patterns + shot-glyphs whose card declares a `manjiProgram` field), painted-landscape glyph cards, view-vocab cards (one per `create_view` kind / `compose_world` base — the study-object and world parameter manuals), solid-vocab cards (one per `mint_solid` kind / `edit_solid` op — the figure/creature/object/structure parameter manuals), motion-vocab cards (one per `forge_motion` / `stitch_motion` subject family — camera / deck / effect / world / stitch), and routing cards (`kinds:['routing']`: creative recognizer rows → entry tool + forks, returned whole). Use when you have an intent or topic but not a specific ref — for finding which rows in the contextmap / capabilities / composer state are relevant before navigating them structurally, which sketch layout card to read before composing a diagram, which view kind or world base fits an intent, or which shot-glyph / mandala-pattern to pass as `programRef` to `create_manji_tree`. Returns `{ results: [{ source_kind, source_ref, score, snippet }] }`; snippets are capped at ~280 chars and the agent is expected to pair this with the structured readers (`meta_context_brief`, `get_mcp_capabilities`, `get_mcp_orbit_component`, `get_catalyst`, `get_sketch_vocab`, `get_view_vocab`, `get_solid_vocab`, `get_motion_vocab`, ...) to retrieve full bodies — or in the `manji_program` case, pass the `source_ref` straight to `create_manji_tree`, or in the `painted_landscape` case use the card's `id` as a named glyph in `compose_world`'s 'painted-landscape' `overrides`. Optional `kinds` filter restricts to one or more source kinds; default returns all kinds. Capability rows that have been superseded never appear in results — the search filter…

Report runtime versions: server name + version (from package.json), MCP protocol version, Node version, platform os/arch, the pinned bot container image tag, whether MOJULO_OFFLINE_BUILD is on, and the active MOJULO_HOME. Use this to diagnose version mismatches between a user-reported issue and what their control plane is actually running, or to confirm a version bump landed after a publish. Read-only, no inputs, idempotent.