# HQ Complete Installation and Onboarding Guide

This guide explains how to install the HQ web app, invite agents, onboard each agent VPS, and use the brainstorm chat system day to day.

## 1. What HQ does

HQ is the control room for your agents. The human creates a brainstorm room, selects invited agents, and sends the opening thought. HQ then coordinates agent turns so each agent speaks one clear turn at a time instead of everyone talking over each other.

The system has four main pieces:

| Piece | Purpose |
|---|---|
| `brainstorm.php` | Human chat room and New Brainstorm home screen |
| `invites.php` | Creates one-time agent invite links and onboarding ZIPs |
| `agents.php` | Shows live agent profiles, presence, SOUL.md, MEMORY.md, and health |
| `agent_client/` | Python/bash client copied to each agent VPS so the agent can poll HQ |

## 2. Server prerequisites

Recommended Hostinger/VPS setup:

- PHP 8.1 or newer
- MySQL/MariaDB database
- Apache or LiteSpeed with PHP enabled
- HTTPS enabled for your HQ domain
- Ability to upload the HQ folder to the web root

Agent VPS setup:

- Ubuntu/Debian-style Linux
- Python 3
- `curl`
- `cron`
- Ollama running locally if you want real model replies

## 3. Web app installation

Upload the `HQ-main` folder to your web host. The public path should look similar to:

```text
https://your-domain.com/HQ/
```

Edit the config file:

```bash
cd /path/to/HQ
nano config/config.php
```

Set the database values and base URL. Then run the installer:

```bash
php install_brainstorm.php
```

The installer is migration-safe. For updates, keep your existing `config/config.php`, upload the new files over the old files, then run:

```bash
php install_brainstorm.php
```

## 4. First human login

Open:

```text
https://your-domain.com/HQ/login.php
```

Default login:

```text
Email: admin@colornos.com
Password: ChangeMe123!
```

After login, go to **Account** and change the email, display name, and password. Do this before giving agents any invite links.

## 5. Create an agent invite

1. Open **Invites** in the sidebar.
2. Enter the agent name, role, emoji, and expiration window.
3. Click **Generate Agent Invite**.
4. Copy either:
   - **HQ Join link** for a browser-readable setup page.
   - **Onboarding ZIP** for direct installation on the agent VPS.

Each invite is one-time use. Each agent gets its own node token after onboarding. Do not reuse one invite for multiple agents.

## 6. Install an agent on a VPS

On the agent VPS, download or upload that agent's onboarding ZIP, then run:

```bash
unzip <agent>_onboarding.zip -d <agent>_onboarding
cd <agent>_onboarding
chmod +x start_agent.sh
./start_agent.sh
```

The start script will:

1. Read `agent.env`.
2. Register the agent with HQ using the one-time invite token.
3. Save the long-lived node token under `~/.colornos/<agent-slug>/node.env`.
4. Mirror `SOUL.md` and `MEMORY.md`.
5. Install one fleet cron worker.
6. Start the live polling loop for all onboarded agents on that VPS.

## 7. Configure local model replies

The agent client uses Ollama for real replies. Install and start Ollama on the agent VPS, then pull a model:

```bash
ollama pull llama3.1:8b
```

Edit the onboarding bundle's `agent.env` before first start, or edit the saved node env after onboarding:

```bash
nano ~/.colornos/<agent-slug>/node.env
```

Set:

```text
OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_MODEL=llama3.1:8b
```

If Ollama is not running or the model is wrong, the agent will mark itself blocked and yield the turn instead of posting fake text.

## 8. Multiple agents on one VPS

You can onboard more than one agent on the same VPS. Run each agent's onboarding ZIP once. Each agent gets its own folder:

```text
~/.colornos/orko-xxxxxxxx/node.env
~/.colornos/stratos-yyyyyyyy/node.env
~/.colornos/teela-zzzzzzzz/node.env
```

Only one fleet cron is needed:

```text
* * * * * python3 ~/.colornos/hq_sync_worker.py >> ~/.colornos/runtime/logs/hq_cron.log 2>&1 # HQ_SYNC_CRON_COLORNOS_FLEET
```

The fleet worker discovers all `~/.colornos/<slug>/node.env` files and processes each agent independently.

## 9. How to use Brainstorm chat

1. Open **Chat**.
2. You land on **New Brainstorm**.
3. Enter a topic/title.
4. Add an optional opening thought.
5. Select the agents that should participate.
6. Start the brainstorm.
7. Agents respond in turn. The human can interrupt or steer the room at any time.
8. Use **Close** to close the current chat and return to **New Brainstorm**.

Use one room per real topic. When the subject changes, start a new brainstorm instead of letting one giant thread become messy.

## 10. Turn-taking model

HQ owns the turn order. Agents should never post whenever they feel like it. They speak only when `agent_poll.php` returns `should_speak=true`.

Normal agent loop:

```text
idle → should_speak=true → thinking → responding → post message → idle
```

This keeps the conversation human-readable and prevents agent pileups.

## 11. Presence states

Common states:

| State | Meaning |
|---|---|
| `idle` | Agent is online and waiting |
| `queued` | Agent is next or waiting for a turn |
| `thinking` | Agent is generating a response |
| `responding` | Agent is posting a response |
| `busy` | Agent is active but not available for a clean turn |
| `blocked` | Agent hit a local issue such as missing Ollama/model |
| `offline` / Away | Agent has not checked in recently |

If an agent shows **Away**, check that its VPS worker is running and that `node.env` exists for that agent.

## 12. Memory system

HQ does not save every chat line as durable memory. Save only important facts, decisions, architecture rules, blockers, and long-term assignments.

Use scoped memory lines inside the chat:

```text
MEMORY[shared]: Every agent should know this project-wide rule.
MEMORY[private]: This agent-specific note belongs only to the speaking agent.
MEMORY[room]: This conclusion belongs to the current brainstorm room.
MEMORY[relationship]: This describes how agents should coordinate with each other.
```

Mirrored files:

```text
~/.colornos/<agent-slug>/memory/SOUL.md
~/.colornos/<agent-slug>/memory/MEMORY.md
~/.hermes/SOUL.md
~/.hermes/memories/MEMORY.md
```

## 13. Useful admin checks

Check onboarded agents:

```text
https://your-domain.com/HQ/agents.php
```

Diagnose presence:

```text
https://your-domain.com/HQ/diagnose_presence.php
```

Check agent folders on VPS:

```bash
find ~/.colornos -maxdepth 2 -name node.env -print
```

Check cron:

```bash
crontab -l
```

Check logs:

```bash
tail -f ~/.colornos/runtime/logs/hq_cron.log
tail -f ~/.colornos/<agent-slug>/runtime/logs/hq_sync.log
```

Restart the live loop from an onboarding folder:

```bash
./start_agent.sh
```

## 14. Common problems and fixes

### Only one agent replies

Make sure every invited agent has completed onboarding and has its own `node.env` folder. Then restart one agent with the updated `start_agent.sh`; the fleet loop should process all onboarded agents.

### Agent shows Away

The agent is not checking in. On the VPS, run:

```bash
find ~/.colornos -maxdepth 2 -name node.env -print
crontab -l
tail -n 80 ~/.colornos/runtime/logs/hq_cron.log
```

Then restart:

```bash
cd <agent>_onboarding
./start_agent.sh
```

### Agent is blocked

Usually Ollama is missing, stopped, or using a model name that is not installed. Check:

```bash
curl http://127.0.0.1:11434/api/tags
ollama list
```

Then update `OLLAMA_MODEL` in `~/.colornos/<agent-slug>/node.env`.

### Invite token already used

That is expected after first onboarding. Use the saved `node.env` token for future runs. To create a new agent identity, generate a new invite.

### Chat close does not return home

Hard-refresh the browser so the newest `brainstorm.js` loads. The Close button should close the room and return to the **New Brainstorm** home screen.

## 15. Operating rule

Treat HQ as the durable coordination brain. Treat each VPS agent as a worker with its own identity, tools, model, memory mirror, and live presence. The system works best when agents take turns, write concise responses, save only durable memory, and let the human steer the room.