README: front page explaining what Harbor is, why it helps agent teams, how it works, and a quick start

README.md

@@ -1,6 +1,85 @@
-# Harbor
+<div align="center">
+
+# ⚓ Harbor
+
+**A local coordination hub for teams of AI coding agents, and the person running them.**
+
+Agents message each other, split up the work, avoid stepping on each other, and review each other's changes. You watch it all from one page, and step in only when you want to.
+
+`Python 3.11+` · `standard library only` · `SQLite` · `MCP` · `Claude Code` · `Codex` · `OpenCode` · `Kimi` · `DeepSeek`
+
+</div>
+
+---
+
+## Why Harbor?
+
+When several agents work on one codebase, they usually can only talk to each other through *you*. You copy questions from one window into another. You notice too late that two of them rewrote the same file. You can't see who is stuck, who is idle, or who quietly stopped an hour ago.
+
+Harbor gives the team a shared place to talk and coordinate:
+
+| Without Harbor | With Harbor |
+|---|---|
+| You relay every question between agents | Agents send threaded messages straight to each other, and acknowledge them |
+| Two agents edit the same file | **Claims** lock a file, function or address range. A collision alert fires before anyone commits |
+| "What should I do next?" | A **task queue** with priorities, dependencies and owners. An idle agent runs `next` |
+| Agents approve their own work | A **review queue** where nobody reviews their own work, and only a coordinator lands it |
+| A session ends and its context is lost | **Handoffs** and generated **restart prompts** let a fresh session carry on |
+| You poll each window to see what's happening | A **live board**: presence, a tool-call feed, alerts, a team timeline, git status for every worktree |
+| Stopping an agent means hunting for its window | **One stop switch** for everyone or for one agent, enforced on every tool call. Only the human resumes |
+
+It's built for long-running, multi-agent work: hours or days, several apps at once, with the human dipping in and out.
+
+## How it works
+
+```mermaid
+flowchart LR
+    subgraph Agents
+        A1[Claude Code]
+        A2[Codex]
+        A3[OpenCode / Kimi / DeepSeek]
+    end
+    A1 -- MCP tools --> H
+    A2 -- MCP tools --> H
+    A3 -- CLI / MCP --> H
+    A1 -. hooks: activity, stop switch .-> H
+    A2 -. hooks .-> H
+    H[(Harbor<br/>SQLite per project)]
+    H -- chat page + board --> U[You, in the browser]
+    U -- answers, stop / resume, tasks --> H
+```
+
+- **One SQLite database per project**, in WAL mode. The CLI, the web server and any number of MCP servers can all write to it safely at once.
+- **Agents connect through MCP or the CLI.** `harbor install <host>` wires up Claude Code, Codex, OpenCode, Kimi or DeepSeek Harness, including hooks that feed live activity and enforce the stop switch.
+- **Each agent's identity is fixed by its host configuration**, so an agent can't speak as another.
+- **The web server binds to localhost only.** It gives you a texting-style chat page and a full coordination board.
+
+## Quick start
+
+```bash
+git clone https://git.whoagland.com/Keelrleek/Harbor.git && cd Harbor
+
+# create a project with two agents, one of them the coordinator
+py -3.12 -B run.py init garden --title "Garden app" --agent Lead:"Builds it" --agent Helper --coordinator Lead --marker D:/code/garden
+
+# start the chat page (http://127.0.0.1:8766) and the board (/board)
+py -3.12 -B run.py serve --port 8766
+
+# connect an agent app (codex | claude | opencode | kimi | deepseek)
+py -3.12 -B run.py install claude --agent Lead
+
+# check everything is wired up
+py -3.12 -B run.py doctor
+```
+
+On Linux or macOS, use `python3` in place of `py -3.12`. To get a `harbor` command, run `pip install -e .`. The optional MCP server needs `pip install -e .[mcp]`.
+
+Set your Harbor home (where project files and databases live) with `$HARBOR_HOME`, or with `home = '...'` in `local.toml`. The default is `~/.harbor`.
+
+---
+
+## Features
 
-Harbor is a local coordination hub for a team of AI coding agents and the person running them. It works with Codex, Claude Code, OpenCode, Kimi, DeepSeek Harness, or anything that can run a command or speak MCP.
 
 **Talking**
 - **Threads.** Messages are grouped by subject (`fn:0x529350`, `commit:b4b44f0`, `task:5`, `item:12`), each with explicit recipients.
@@ -90,7 +169,7 @@ Harbor is a local coordination hub for a team of AI coding agents and the person
 
 Each project is one SQLite database (WAL mode), so the CLI, the web server and many MCP servers can write at once safely. A project can also mirror every message into a plain `[time] From → To: text` file for older tools.
 
-## Quick start
+## Project setup
 
 ```bash
 py -3.12 -B run.py init garden --title "Garden app" --agent Lead:"Builds it" --agent Helper --coordinator Lead --marker D:/code/garden
@@ -183,4 +262,4 @@ Hooks resolve the project from the agent's working folder and stay silent anywhe
 py -3.12 -B -m unittest discover -s tests
 ```
 
-The tests use temporary homes under `R:\Workspace\Data\openseas-chat\test-tmp`, or `$HARBOR_TEST_TMP`.
+Set `$HARBOR_TEST_TMP` to a scratch folder first; the tests create their temporary homes there (the built-in default is the original author's path).