Skip to content

Commit 822f085

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
committed
feat: add onboarding script for son's Claude Code setup
Interactive prompt that walks Claude through 8 phases: BoJ install, cartridge inventory, Firefox, editor setup, PanLL (with eNSAID explanation), IDApTIK panels, custom wizards. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 8e6a8b0 commit 822f085

1 file changed

Lines changed: 229 additions & 0 deletions

File tree

‎setup-scripts/onboard-son.md‎

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
# BoJ + PanLL Full Onboarding Script
2+
# SPDX-License-Identifier: PMPL-1.0-or-later
3+
#
4+
# INSTRUCTIONS: Copy everything below the line into Claude Code as a single message.
5+
# Claude will walk you through each step interactively.
6+
# ─────────────────────────────────────────────────────────────────────
7+
8+
I want you to set up my full development environment. Follow these phases IN ORDER. Do not skip ahead. Ask me questions where indicated. Do each phase completely before moving to the next.
9+
10+
---
11+
12+
## PHASE 1 — BoJ Server (Bundle of Joy)
13+
14+
BoJ is a cartridge-based MCP server that routes ALL tool integrations through a single unified gateway. Every MCP, LSP, debugger, and AI agent connects through BoJ cartridges instead of running as separate servers.
15+
16+
1. Clone the BoJ server:
17+
```
18+
git clone https://github.com/hyperpolymath/boj-server ~/Documents/hyperpolymath-repos/boj-server
19+
cd ~/Documents/hyperpolymath-repos/boj-server
20+
```
21+
22+
2. Check and install prerequisites (ask me before installing anything):
23+
- **Deno** (runtime) — check `deno --version`
24+
- **Zig** (FFI compilation) — check `zig version`
25+
- **Rust** (if building from source) — check `rustc --version`
26+
- **just** (task runner) — check `just --version`
27+
28+
3. Build the server:
29+
```
30+
just deps
31+
just build
32+
```
33+
34+
4. Start the MCP bridge and verify health:
35+
```
36+
deno run --allow-net --allow-env mcp-bridge/main.js
37+
```
38+
Then in another terminal: `curl http://localhost:7700/health`
39+
40+
5. Register BoJ as my Claude Code MCP server. Create/update `~/.config/claude/mcp_servers.json`:
41+
```json
42+
{
43+
"boj-server": {
44+
"command": "deno",
45+
"args": ["run", "--allow-net", "--allow-env", "<FULL_PATH>/boj-server/mcp-bridge/main.js"],
46+
"env": { "BOJ_URL": "http://localhost:7700" }
47+
}
48+
}
49+
```
50+
51+
6. Verify BoJ is working by calling `boj_health` and `boj_menu` tools.
52+
53+
---
54+
55+
## PHASE 2 — Cartridge Inventory
56+
57+
BoJ ships with 22 built-in cartridges. List them with `boj_menu` and show me what's available in a table:
58+
59+
| Cartridge | Protocols | Purpose |
60+
|-----------|-----------|---------|
61+
62+
The 22 built-in cartridges cover: database, container, git, cloud (Verpex/Cloudflare/Vercel), comms (Gmail/Calendar), ML (HuggingFace), research, LSP, DAP (debug), BSP (build), NeSy (neurosymbolic), agentic, fleet (bot orchestration), proof (Idris2), secrets, observability, IaC, queues, model-router, SSG, UMS, lang, feedback.
63+
64+
For any service I'm currently using that does NOT have a cartridge, use the **cartridge minter** to create one:
65+
66+
**Cartridge Minting Wizard** (for each new cartridge):
67+
1. Ask: "What service/tool do you want to connect?"
68+
2. Ask: "What protocols does it need?" (MCP, LSP, DAP, BSP, NeSy, Agentic, gRPC, REST)
69+
3. Ask: "What domain?" (Database, Container, K8s, Git, Cloud, Comms, ML, Research, etc.)
70+
4. Generate the three-layer cartridge scaffold:
71+
```
72+
cartridges/<name>-mcp/
73+
├── abi/<Name>Mcp/<Name>.idr # Idris2 ABI definition
74+
├── ffi/build.zig # Zig FFI implementation
75+
├── ffi/<name>_ffi.zig # Zig FFI source
76+
└── adapter/<name>_adapter.v # V-lang REST/gRPC/GraphQL adapter
77+
```
78+
5. Configure and provision the cartridge via `boj_cartridge_invoke`
79+
80+
---
81+
82+
## PHASE 3 — Firefox Setup
83+
84+
Set up Firefox as the browser bridge for Claude Code:
85+
86+
1. Check if Firefox is installed (`which firefox`)
87+
2. If not installed, ask me which package manager to use
88+
3. Create a health-check hook at `~/.claude/hooks/boj-health-check.sh` that:
89+
- Checks if BoJ server is running on startup, restarts if not
90+
- Checks if Firefox is running — if YES, do nothing; if NO, launch it **minimised**
91+
- Logs diagnostics to `~/.claude/hooks/boj-diagnostics.log`
92+
4. Make the hook executable: `chmod +x ~/.claude/hooks/boj-health-check.sh`
93+
94+
---
95+
96+
## PHASE 4 — Code Editor
97+
98+
**ASK ME:** "Which code editor do you want to use? (e.g., VS Code, Neovim, Helix, Zed, Lapce, or something else)"
99+
100+
Based on my answer:
101+
- Configure the LSP cartridge (`lsp-mcp`) to connect to my editor's LSP
102+
- Configure the DAP cartridge (`dap-mcp`) for debugging in my editor
103+
- Set up any editor-specific integrations (extensions, plugins, config files)
104+
- If my editor supports it, configure the BSP cartridge for build server integration
105+
106+
---
107+
108+
## PHASE 5 — PanLL (Optional)
109+
110+
**ASK ME:** "Would you like to install PanLL?"
111+
112+
**Explain PanLL like this:**
113+
> PanLL is an **eNSAID** — an Environment for NeSy-Agentic Integrated Development.
114+
>
115+
> Think of it as a mission control dashboard for coding. Instead of just a code editor, PanLL gives you three co-working panels:
116+
> - **Panel-L** (Symbolic) — formal logic, type checking, proof verification
117+
> - **Panel-N** (Neural) — AI reasoning, suggestions, and an advisor called ECHIDNA
118+
> - **Panel-W** (World) — results, dashboards, databases, security tools
119+
>
120+
> You and the AI work together as equals — neither is "the assistant." PanLL monitors cognitive load (a "Vexometer" tracks frustration), adjusts information density, and manages 79+ specialist overlay panels you can summon for different tasks.
121+
>
122+
> It runs as a lightweight Tauri app (5 MB, not an Electron bloat-fest) built in ReScript + Rust.
123+
124+
**If YES:**
125+
126+
1. Clone PanLL:
127+
```
128+
git clone https://github.com/hyperpolymath/panll ~/Documents/hyperpolymath-repos/panll
129+
cd ~/Documents/hyperpolymath-repos/panll
130+
```
131+
132+
2. Install PanLL prerequisites:
133+
- ReScript compiler: `npm install rescript` (exception to npm ban — ReScript requires it)
134+
- Deno (already installed from Phase 1)
135+
- Rust + Tauri 2.0: check `cargo tauri --version`
136+
- Tailwind CSS: handled by deno tasks
137+
138+
3. Build PanLL:
139+
```
140+
just build
141+
```
142+
Or for development:
143+
```
144+
just dev
145+
```
146+
147+
4. Use the **Panel Minter** to verify it works:
148+
- Open PanLL → click Minter in the panel bar
149+
- Or via CLI: the minter generates an 8-file scaffold per panel
150+
151+
**If NO:** Skip to Phase 7.
152+
153+
---
154+
155+
## PHASE 6 — PanLL Panels for IDApTIK & Game Dev
156+
157+
**ASK ME:** "Would you like to set up the existing game development and IDApTIK panels?"
158+
159+
**If YES**, provision these panel sets using the Panel Provisioner:
160+
161+
### IDApTIK eNSAID Panels (11):
162+
| Panel | Purpose |
163+
|-------|---------|
164+
| Valence Shell | Embedded terminal with session recording |
165+
| Game Preview | Live IDApTIK preview with hot-reload |
166+
| VM Inspector | Reversible debugger (step forward/backward) |
167+
| Network Topology | Force-directed in-game network graph |
168+
| Level Architect | Visual level design with validation |
169+
| Coprocessors | Backend coprocessor heatmap (10 types) |
170+
| Multiplayer Monitor | Real-time multiplayer session tracking |
171+
| DLC Workshop | Puzzle pack creation + testing |
172+
| Editor Bridge | Connects PanLL to your code editor |
173+
| Build Dashboard | Build status across all targets |
174+
| Release Manager | Release pipeline and versioning |
175+
176+
### Game Dev Testing Panels (10):
177+
Unit Test Runner, Functional Tester, Regression Guard, Performance Profiler, Load Tester, Soak Monitor, Compatibility Matrix, Exploratory Workbench, Beta Feedback Hub, Balance Analyser
178+
179+
### Game Dev Bridge Panels (8):
180+
Typing Bridge, Neurosym Bridge, Agentic Bridge, Automation Bridge, Database Bridge, Protocol Bridge, Proofs Bridge, Scripting Bridge
181+
182+
### Game Dev Specific Panels (6):
183+
Generator Mode, Architect Mode, Guard AI Tuner, Device Network Designer, Asset Manager, Playtest Recorder
184+
185+
For each panel set, use the **Panel Provisioner** to select isolation tier:
186+
- **Native** (in-process, fastest) — recommended for trusted panels
187+
- **Standard Pod** (Alpine + Podman) — community panels
188+
- **Hardened Pod** (Stapeln + Chainguard) — untrusted panels
189+
190+
Then use the **Panel Configurator** (Workspace panel) to arrange them into workspace modes.
191+
192+
---
193+
194+
## PHASE 7 — Custom Cartridges & Panels
195+
196+
**ASK ME:** "Would you like to create any custom BoJ cartridges or PanLL panels for your development work?"
197+
198+
**If YES for cartridges**, run the **Cartridge Minting Wizard** for each one:
199+
1. "What's the name of this cartridge?"
200+
2. "What does it do? (one sentence)"
201+
3. "What protocols?" — show checklist: ☐ MCP ☐ LSP ☐ DAP ☐ BSP ☐ NeSy ☐ Agentic ☐ gRPC ☐ REST
202+
4. "What domain?" — show checklist: ☐ Database ☐ Container ☐ Git ☐ Cloud ☐ Comms ☐ ML ☐ Research ☐ Other
203+
5. "Any external APIs or services it connects to?"
204+
6. Generate the scaffold, then ask: "Want me to implement the adapter logic now, or leave it as a scaffold?"
205+
206+
**If YES for panels** (and PanLL is installed), run the **Panel Minting Wizard** for each one:
207+
1. "What's the name of this panel?"
208+
2. "What clade kind?" — explain each: directive (controls), scanner (monitors), builder (creates), viewer (displays), ai (neural), bridge (connects external tools)
209+
3. "What does it do? (one sentence)"
210+
4. "Should it connect to any BoJ cartridges?"
211+
5. "What isolation tier?" — Native / Standard Pod / Hardened Pod
212+
6. Generate the 8-file scaffold using the Minter
213+
7. Ask: "Want me to implement the panel logic now, or leave it as a scaffold?"
214+
215+
**Keep asking** "Any more?" until I say I'm done.
216+
217+
---
218+
219+
## PHASE 8 — Final Verification
220+
221+
Run a full system check:
222+
1. `curl http://localhost:7700/health` — BoJ healthy
223+
2. `boj_menu` — all cartridges listed
224+
3. Firefox running (check `pgrep firefox`)
225+
4. Editor integration working
226+
5. If PanLL installed: `just test` in panll directory — all tests pass
227+
6. Show me a summary table of everything installed
228+
229+
**Done!** Tell me: "Your environment is ready. You have [N] BoJ cartridges and [M] PanLL panels configured. Type `boj_menu` any time to see your cartridges, or open PanLL to access your panels."

0 commit comments

Comments
 (0)