# Prompt — Install a MeshKore cluster (orchestrated wizard)

Use this when an agent is asked to install MeshKore on a repo. The agent
**must ask the user the questions in section 1 first**, then choose the
right path in section 2, then execute.

---

## 1 · Ask the user (always, before doing anything)

You are the installer agent. You will likely be the **orchestrator** of
the cluster going forward. Ask the user, in plain conversational tone:

### Q1 — What is this cluster for?

```
1. dev       — multiple agents collaborate on this codebase (most common
                for big repos with many modules and ongoing tasks)
2. comms     — agents just message each other; no shared codebase
3. service   — one or more agents serve requests from the wider mesh
                (e.g. a translator, a partner integration)
4. mixed     — both dev and service in the same cluster
```

If the user is not sure: ask "do you want AI agents to collaborate on
the code in this repo?" Yes → dev. Just want a chat channel between
agents? → comms. Want this repo to expose a service agent? → service.
Both? → mixed.

### Q2 — Who will participate?

For **dev** clusters, ask:

```
A. Just me with multiple AI clients on this one machine
   (e.g. Claude Code in VS Code + Claude Code CLI + DeepSeek for deploys)
B. Me + my teammates, each on their own machine
C. Me on multiple machines or VMs (simulating multi-machine)
D. Just me with a single AI client (essentially solo, but using the
   cluster for roadmap/portal benefits)
```

Default: A.

### Q3 — Which AI clients are available?

```
- Claude Code (Anthropic API key, cli or VS Code extension)
- DeepSeek (DEEPSEEK_API_KEY)
- Qwen / DashScope (DASHSCOPE_API_KEY)
- Cursor (Cursor CLI)
- Other / custom
```

Ask the user to list which they have. The orchestrator role goes to
their primary one (Claude Code in VS Code is the typical pick). Cheap
clients (DeepSeek, Qwen) are good for deploys and tests.

### Q4 — Auto-commit policy?

```
1. Manual — daemon stages, I commit and push when ready (default, safer)
2. Auto-commit, no auto-push
3. Full auto: commit + push on every task completion
```

Default: 1 (manual). Recommended for first-time users.

### Q5 — (only if dev) Cluster ID and name?

```
- id: short, lowercase, hyphenated. Suggest: <repo-name>-cluster
- name: human-readable, e.g. "Acme Project — Dev Cluster"
- description: one line about the project
```

Don't proceed until you have answers to Q1, Q3, Q5 at minimum. Q2 and Q4
have safe defaults.

---

## 2 · Plan the install based on the answers

Given the answers, draft a one-paragraph summary and **show it to the
user for confirmation** before executing. Example:

```
You want to set up a 'dev' cluster called 'meshkore-main' for collaborative
work on this repo. The orchestrator will be Claude Code (VS Code), and
you'll add Claude Code CLI + DeepSeek as client agents. Manual commit
policy. I'll: 1) curl the Python daemon into .meshkore/scripts/,
2) scaffold .meshkore/public/cluster.yaml, 3) declare 3 agent
identities under .meshkore/agents/, 4) start the daemon with
`python3 .meshkore/scripts/daemon.py`. Does this look right? (yes/edit)
```

Wait for "yes" before doing anything destructive.

---

## 3 · Execute (deterministic steps, in order)

The daemon is a single Python file that uses only the standard library.
No `pip`, no `npm`, no installer, no admin rights, no per-OS binary —
works identically on every machine with Python ≥ 3.8 (Mac default,
Linux default, Windows Store or python.org).

### 3.1 Download the daemon

```bash
cd <repo-root>
mkdir -p .meshkore/scripts
curl -fsSL https://meshkore.com/reference/cluster/scripts/daemon.py \
     -o .meshkore/scripts/daemon.py
```

Verify:

```bash
head -1 .meshkore/scripts/daemon.py    # → #!/usr/bin/env python3
wc -l   .meshkore/scripts/daemon.py    # → ~1700 lines
```

If `curl` is unavailable, the same file is browseable at
`https://meshkore.com/reference/cluster/scripts/`.

### 3.2 Scaffold `cluster.yaml` + `.gitignore`

The daemon needs `.meshkore/public/cluster.yaml` to know who this
cluster is. Use the answers from Q1 (type) and Q5 (id + name):

```bash
mkdir -p .meshkore/public .meshkore/agents .meshkore/credentials
cat > .meshkore/public/cluster.yaml <<EOF
version: 1
id: <id-from-Q5>
type: <type-from-Q1>
name: "<name-from-Q5>"
description: "(one-line about this repo)"

transport:
  protocol: websocket
  endpoint: wss://hub.meshkore.com/ws
  fallback: https://hub.meshkore.com

bootstrap:
  hub:     https://hub.meshkore.com
  docs:    https://hub.meshkore.com/platform/docs/agent
  install: https://meshkore.com/cluster/install
  operate: https://meshkore.com/cluster/operate
  spec:    https://meshkore.com/standard/spec

admission:
  mode: pubkey
  approval: manual
  github_users: []

members: []
EOF
echo 6 > .meshkore/STANDARD_VERSION
```

Scaffold the deployment links registry (standard §13) **always** —
even an empty registry surfaces correctly in the cockpit's Links
tab. The operator should NEVER have to create this file by hand
later. Drop one block per module declared in `cluster.yaml.modules`,
fill in whatever URLs you know (leave the rest as empty strings; the
panel hides empty slots):

```bash
curl -fsSL https://meshkore.com/reference/cluster/templates/links.yaml \
  -o .meshkore/public/links.yaml
# Then edit: one entry per module from cluster.yaml.modules with
# whichever of {local.url, local.command, local.health, prod.url,
# prod.provider, prod.project, prod.deploy_command, repo.branch}
# applies. The cockpit's Links tab is read-only; the operator edits
# this file directly, so the scaffold is the agent's responsibility.
# Schema: https://meshkore.com/standard#13-links-registry.
```

Initialise the protocols folder (standard §14). Protocols are
reusable multi-step runbooks the operator invokes with "apply P<N>":

```bash
mkdir -p .meshkore/protocols/log
# Reference protocols ship with the standard. Curl the template
# whenever you want to author a new one:
curl -fsSL https://meshkore.com/reference/cluster/templates/protocol.md \
  -o .meshkore/protocols/_template.md
```

Update `.gitignore` to commit only the public bootstrap, the version
marker, and the protocols folder (run logs stay local):

```bash
cat >> .gitignore <<'EOF'

# MeshKore — commit only the public bootstrap, the version marker,
# and the protocols playbook. Run logs stay per-machine.
.meshkore/*
!.meshkore/public/
!.meshkore/STANDARD_VERSION
!.meshkore/protocols/
.meshkore/protocols/log/
EOF
```

### 3.3 Declare your agent identities (one tiny YAML per identity)

For each AI client the user named in Q3, write a YAML to
`.meshkore/agents/<identity>.yaml`:

```bash
HOST=$(hostname)
cat > .meshkore/agents/${HOST}-claude-code-orchestrator.yaml <<EOF
id: ${HOST}-claude-code-orchestrator
kind: claude-code
role: orchestrator
permissions: edits
EOF
```

Suggest these role assignments based on Q3:

- **Claude Code (primary)** → `orchestrator`
- **Claude Code (secondary license)** → `developer`
- **DeepSeek / Qwen** → `deployer` and/or `tester`
- **Cursor** → `reviewer`

API keys (Anthropic, DeepSeek, etc.) live as text files under
`.meshkore/credentials/<provider>.env` — they are gitignored
automatically by step 3.2.

### 3.4 Start the daemon

One command, no flags:

```bash
python3 .meshkore/scripts/daemon.py
```

The daemon binds the first free port in `5570–5589`, mints a bearer
token at `.meshkore/credentials/portal-token`, and serves both HTTP
and WebSocket. First-run output:

```
[meshcore-py 2026-…Z] meshcore-py listening on http://127.0.0.1:5571
                       (identity=<host>-claude-code-orchestrator, cluster=<id>)
[meshcore-py 2026-…Z] cron: <N> job(s) registered, this daemon is coordinator, tick every 10s
```

Health-check from another terminal:

```bash
curl -fsS http://localhost:5571/health
```

Expect `{"ok": true, "implementation": "python", "features": [...]}`.

### 3.5 Open the cockpit and confirm

```bash
open https://architect.meshkore.com    # macOS
# or:
xdg-open https://architect.meshkore.com # Linux
# or:
start https://architect.meshkore.com    # Windows
```

The cockpit (Architect) is a static HTML page that auto-discovers
the daemon on `localhost:5570–5589` from the browser. The user pastes
the bearer token (saved at `.meshkore/credentials/portal-token` on
first daemon run; the cockpit remembers it after that).

In the cockpit the user should see:
- **Roadmap** tab — empty (no tasks yet)
- **Network** tab — every identity declared in 3.3 with online dot
- **Config** tab — cluster id, type, transport, daemon features
- **Chat** tab — coordinator chat (spawns `claude` via the daemon
  when the user types)

### 3.6 Report to the user

```
Done. Cluster '<id>' is live with <N> agent identities.
Cockpit: https://architect.meshkore.com  (auto-discovers your local daemon)
Daemon command (re-run any time after reboot):
    cd <repo>
    python3 .meshkore/scripts/daemon.py
First task suggestion: open the cockpit, type a prompt in Chat, the
orchestrator picks it up and runs.
```

---

## 4 · Failure modes — what to do

- **Catalog unreachable** (`curl` to `meshkore.com/reference/...` fails):
  fall back to the templates bundled with the binary (under the binary's
  install path `<binary-dir>/templates/`). Tell the user.
- **Port 5570 already taken by an unrelated process**: ask the user for
  a different port (`portal.port` in `cluster.yaml`). Common when 5570
  conflicts with another tool.
- **No git repo**: refuse to proceed. Tell the user `git init` first.
- **Working tree dirty**: warn and ask whether to proceed; if yes,
  daemon will avoid touching uncommitted files.

---

## 5 · Things you must NEVER do

- Commit `.meshkore/credentials/`. Ever.
- Commit anything outside `.meshkore/public/`.
- Push to `origin` without asking the user.
- Skip Q1 / Q3 / Q5. Defaults are not safe for these.
- Assume the user wants `--yolo` mode. Always confirm destructive steps.
- Recommend two checkouts of the same repo on the same machine. Use
  multiple identities with one checkout (see
  [`/standard.md`](https://meshkore.com/standard.md)).

---

## See also

- [Cluster install (human page)](https://meshkore.com/cluster/install)
- [Cluster spec v1 (RFC)](https://meshkore.com/standard/spec)
- [Agent docs router](https://hub.meshkore.com/platform/docs/agent)
- [Reference catalog](https://meshkore.com/reference/)