# 🛠️ Manual Setup Guide: TutorClaw v1

This guide explains the **current local-first setup** for PatientZero on your own computer.

This version is no longer written around VPS hosting, Cloudflare tunnels, SSH, or OpenAI keys.

---

## 📋 What This Kit Is

PatientZero is currently being developed as a **local-first AI teaching assistant (TutorClaw)** built on OpenClaw.

The current working model is:

- run the project on your own computer
- edit and test from **PyCharm**
- keep TutorClaw runtime state under its own isolated TutorClaw folder
- use your **own** Gemini/Google keys
- never ship development test keys to users
- avoid disturbing any existing Claw/OpenClaw assistant already installed on the computer

---

## 🧱 Existing Claw/OpenClaw Install Safety

TutorClaw should not overwrite or disturb an existing Claw/OpenClaw assistant.

This is important because some users may already have a working assistant installed outside Builder Kit, such as Butch or another standalone OpenClaw setup.

TutorClaw should use:

```text
~/.builder-kit
```

for shared TutorClaw configuration, and:

```text
~/.builder-kit/instances/main/.openclaw
```

for the default assistant runtime.

Do not manually delete, rename, or reset `~/.openclaw` unless you are intentionally working on a separate non-TutorClaw OpenClaw install and you understand the consequences.

TutorClaw launchers should use configurable gateway ports and matching tokens so they do not accidentally connect to another assistant that is already running.

---

## ✅ Before You Start

You need these things on your computer before running the kit:

### 1. Python

You need Python installed so the local virtual environment can be created and the Python helper files can run.

### 2. Node.js

You need Node.js installed because OpenClaw uses `pnpm` and Node-based tooling.

### 3. pnpm

You need `pnpm` installed and available in your terminal.

### 4. PyCharm

PyCharm is the preferred working environment for this project because it makes it easier to:

- open the whole PatientZero project
- edit files
- run local scripts
- inspect the folder structure
- keep one local source of truth

### 5. Your own provider keys

This kit does **not** include API keys.

You must supply your own:

- `GEMINI_API_KEY`
- `GOOGLE_API_KEY`

Optional:

- `GOOGLE_APPLICATION_CREDENTIALS` if your setup uses a Google service account file

---

## 🔐 Key Safety Rules

These rules are part of the local-first design:

- never put real keys in `config/example.env`
- never commit a real `.env`
- never package TutorClaw runtime secrets for users
- never package a user’s existing `~/.openclaw` folder
- never ship logs or screenshots showing live keys
- every installer user must provide their **own** keys

Development test keys are for private testing only and must never be included in the distributed kit.

---

## 📁 Important Local Paths

### Project root

This is the main editable project folder:

```text
.
```

### Normal WSL install root

This is the normal local-first install location inside WSL:

```text
~/claw-builder-kit
```

### TutorClaw shared home

TutorClaw shared configuration should live here:

```text
~/.builder-kit
```

This folder can hold shared config, instance records, launcher records, logs, and supported skill/support metadata.

### Default TutorClaw runtime

The default TutorClaw assistant runtime should live here:

```text
~/.builder-kit/instances/main/.openclaw
```

This keeps TutorClaw separate from any existing standalone Claw/OpenClaw install.

### Existing standalone OpenClaw runtime

A separate standalone OpenClaw assistant may use:

```text
~/.openclaw
```

Treat this folder as private to another assistant unless you are intentionally maintaining that separate install.

---

## ▶️ Running The Installer

From PowerShell:

```powershell
cd .
wsl bash -lc "cd . && bash install.sh"
```

The installer should:

- prepare the central TutorClaw home
- ask for provider keys if needed
- validate provider keys
- copy/sync the kit into the WSL install root
- configure the default TutorClaw instance
- install/configure the pinned local OpenClaw runtime

---

## ▶️ Starting The Assistant

On Windows, use:

```text
start_assistant_windows.bat
```

The launcher should:

- detect the WSL home directory
- use the TutorClaw install root
- use the TutorClaw shared home
- use the selected TutorClaw instance
- set the correct OpenClaw runtime path
- use a configurable gateway port
- use matching token authentication
- open the generated dashboard URL

This protects existing assistants from being opened accidentally.

---

## 🧪 Alpha/Test Install Pattern

For isolated testing, use separate paths.

Example alpha test values:

```text
BUILDER_KIT_HOME=/home/user/.builder-kit-alpha-test
BUILDER_KIT_INSTALL_ROOT=/home/user/claw-builder-kit-alpha-test
BUILDER_KIT_DEFAULT_INSTANCE=main
BUILDER_KIT_GATEWAY_PORT=19099
```

The alpha test should not use or modify:

```text
~/.openclaw
```

unless that is explicitly intended.

---

## 🧹 Reset And Uninstall

For reset or uninstall steps, use:

```text
RESET_AND_UNINSTALL.md
```

Do not delete `~/.openclaw` just because you are resetting TutorClaw.

TutorClaw reset/uninstall work should normally target:

```text
~/.builder-kit
```

and:

```text
~/.builder-kit/instances/main/.openclaw
```

---

## ✅ Manual Setup Success Checklist

Before calling the setup good, confirm:

- provider keys are not committed
- `config/example.env` contains placeholders only
- the installer validates keys without printing them
- the default model is `google/gemini-2.5-flash-lite`
- TutorClaw runtime is under `~/.builder-kit/instances/main/.openclaw`
- existing `~/.openclaw` is not modified during TutorClaw setup
- launcher opens the TutorClaw assistant, not another assistant
- launcher uses a non-conflicting gateway port and matching token
- `git status --short` is clean after commits
