MindBrain Personal Studio

Local Svelte Studio for GhostCrab / MindBrain SQLite databases. It visualizes workspaces, ontologies, instance graphs, projections, and graph gap rules through the GhostCrab HTTP backend.

Install From npm

After the package is published:

npm install @mindflight/mindbrain-personal-studio@latest
npx mindbrain-studio

The package also exposes ghostcrab-studio:

npx -y --package=@mindflight/mindbrain-personal-studio@latest ghostcrab-studio

By default Studio looks for ~/.ghostcrab/databases/ghostcrab.sqlite, matching GhostCrab's user-local SQLite default. Override it for one run:

npx -y --package=@mindflight/mindbrain-personal-studio@latest mindbrain-studio --sqlite /path/to/ghostcrab.sqlite

If the default GhostCrab SQLite does not exist and no explicit database is set, Studio starts against the packaged read-only immeuble demo fixture.

Local Development

pnpm install
cp .env.example .env
pnpm studio

Commands

| Command | Role | |---------|------| | pnpm backend | Start ghostcrab-backend for the SQLite in .env, ~/.ghostcrab, or --sqlite PATH | | pnpm dev | Start Vite wired to that backend, or to the demo fixture when no default GhostCrab DB exists | | pnpm studio | backend --detach then dev in one terminal | | pnpm start | Start the built Node server from build/index.js | | pnpm load:demo | Load the Studio-owned immeuble BIM-lite demo bundle into workspace immeuble | | pnpm demo:verify | Verify the loaded immeuble demo SQLite counts | | pnpm demo:fixture | Rebuild fixtures/immeuble-demo.sqlite from the bundled demo | | pnpm dev:fixture | Offline read-only graph fixture, no backend | | pnpm pack:local | Build and create a local npm tarball in dist-pack/ |

Configuration

Studio reads .env from the package root and accepts the same GhostCrab variables used by @mindflight/ghostcrab-personal-mcp.

Most useful variables:

GHOSTCRAB_SQLITE_PATH=~/.ghostcrab/databases/ghostcrab.sqlite
GHOSTCRAB_BACKEND_ADDR=:8091
GHOSTCRAB_MINDBRAIN_URL=http://127.0.0.1:8091
GHOSTCRAB_BACKEND_BIN=/absolute/path/to/ghostcrab-backend
GHOSTCRAB_ROOT=/absolute/path/to/ghostcrab-personal-mcp
GHOSTCRAB_HOME=~/.ghostcrab
GHOSTCRAB_DATA_DIR=~/.ghostcrab
GHOSTCRAB_CONFIG_DIR=~/.ghostcrab

Backend discovery order:

1. GHOSTCRAB_BACKEND_BIN
2. GHOSTCRAB_ROOT
3. local node_modules/@mindflight/ghostcrab-personal-mcp*
4. sibling checkout ../ghostcrab-personal-mcp
5. ~/.ghostcrab/bin

Typical workflow

pnpm load:demo          # optional, adds immeuble workspace
pnpm studio             # or: pnpm backend (T1) + pnpm dev (T2)

Select workspace immeuble, ontology immeuble::core after loading the demo.

The backend picks a free local port from 8092 when GHOSTCRAB_BACKEND_ADDR is not set and writes a sidecar under data/runtime/. If workspace pickers stay empty, verify /api/brain/health shows the expected SQLite path.

Optional: pnpm seed:immeuble-projections seeds materialized chantier projection snapshots for the Projections tab smoke test.

Internal terms

Studio does not open your GhostCrab SQLite in normal use. A local GhostCrab HTTP backend (ghostcrab-backend) reads the file; Studio calls it via an internal proxy (/api/brain/*). The codebase calls this HTTP mode DATA_SOURCE=brain.

sqlite-demo is different: Studio opens the packaged fixture read-only for graph viewer smoke tests.

Architecture

Svelte UI -> /api/brain/* proxy -> ghostcrab-backend HTTP -> SQLite

Four tabs:

• Modèle — editable taxonomy trees, class/relation lists, optional schema graph
• Données — instance subgraph, search, docked projections drawer
• Projections — full catalog with auto-load and relevance
• Rules — graph gap rules, rule evaluation runs, invalid subjects, and dynamic graph focus

The Rules tab does not create persisted snapshots. It uses rule evaluation subject_entity_id values to focus the Données graph dynamically, like projection snapshot focus.

Publication

This repository publishes @mindflight/mindbrain-personal-studio through npm staged publishing — direct npm publish is no longer allowed. pnpm publish:npm submits the package to npm's staging area; a maintainer must then review and approve it with 2FA before it goes live.

Requirements (checked by the script): npm CLI >= 11.15.0 and Node >= 22.14.0, plus 2FA enabled on the npm account for the approval step.

pnpm install
pnpm check
pnpm build
pnpm pack:local
pnpm publish:npm     # stages the package (nothing goes live yet)

# then, as a maintainer (2FA required):
npm stage list
npm stage view <stage-id>      # or review in the Staged Packages tab on npmjs.com
npm stage approve <stage-id>

Releases should be tagged after the GitHub and GitLab repositories have the same main commit.

Immeuble BIM-Lite Demo

The canonical demo files live in examples/immeuble. The demo covers syndic data plus a lightweight construction-management extension for the Érables roof/facade worksite: architect, contractors, work packages, permit, budget, milestones, inspection, reserves, answer artifacts, materialized projection snapshots, and graph gap rules.

The construction vocabulary is intentionally BIM-inspired, not BIM-compliant. It borrows small patterns from DiCon/BOT/IFC, but does not import IFC, ifcOWL, BOT, DiCon, QUDT, OWL-Time, or PROV as required ontology dependencies. See examples/immeuble/BIM_LITE.md.

Fixture

fixtures/immeuble-demo.sqlite is the packaged offline smoke-test database:

pnpm dev:fixture

For agent-assisted MCP switching, see skills/ghostcrab-perso-sqlite-demo/SKILL.md.

Plans

• Active release plan: docs/plan/2026-06-28-npm-studio-release-0.6.plan.md
• Dual-view MVP (archived): .cursor/dual-view_graph_explorer_33bd283d.plan.md