hivecode-mcp 0.11.6 → 0.12.1

package/HIVE_RULES.md

@@ -1,127 +1,127 @@
-# HIVE RULES — read this first. Everyone in this room (human or AI) follows these.
-
-You are in a Hivecode room: a shared live workspace where humans and AI agents
-edit ONE project together in real time. These rules keep anyone from destroying
-another's work. The sync layer enforces the hard parts automatically; you do the rest.
-
-## Identity
-- You are automatically "human" (you ran the editor) or "ai" (you ran the agent
-  client). Nobody declares it — running the client is the declaration.
-
-## Know who you are working with
-- Read HIVE_MEMBERS.md — who (humans + AIs) is in the room right now, and how many.
-
-## DESIGN BEFORE YOU WRITE — mandatory, set by Ganesh 19 Sep 2026
-
-Before you build any new feature, post in the room, **before your first edit**:
-
-1. **Who uses it, and how.** Name the person or agent and the moment they reach for it.
-2. **What it costs when it is wrong.** One sentence a non-author can act on at 3am.
-3. **Every edge case you can name.** Empty, missing, offline, refused, concurrent, already-done,
-   called twice, called by the wrong person.
-
-Then build it.
-
-This is not process for its own sake. **Every defect this project has produced has been a FALSE
-SUCCESS** — nothing crashed, every signal was green, the result was wrong. That class is never
-caught by testing the happy path afterwards. It is caught by asking, first, what "wrong but green"
-would look like for this particular feature.
-
-If you cannot say what breaks, you do not understand the feature well enough to write it. Say so
-in the room and ask — that is a complete and acceptable answer.
-
-## Before you touch a file
-1. Read HIVE_CHAT.md — what is everyone doing right now.
-2. Read HIVE_BOARD.md — which files were just rewritten (and what was touched).
-3. If a file you plan to edit appears there, RE-READ it before changing it.
-
-## MEMORY — ask before you assume (the recall tool)
-- This room has a memory of everything decided here and in past sessions. It is a
-  tool called `recall`. It costs a fraction of a second and it is on your machine —
-  no cloud, no key. Use it far more than feels necessary.
-- CALL RECALL AT THESE FOUR MOMENTS, every time:
-  1. BEFORE the planning meeting — what was already decided about this project?
-  2. BEFORE you claim a file — has this file been discussed, reworked, or does it
-     carry a convention someone already chose?
-  3. BEFORE you invent anything with a NAME — an id format, an error shape, a port,
-     an env var, a header, a timestamp unit. The project has probably already picked
-     one, and inventing a second is how a codebase rots.
-  4. AFTER any reconnect or restart — you lost your context, the room did not.
-- ASK IT WITH NAMES, NOT SENTENCES. It matches the literal words you send.
-    GOOD  recall("hive_claim ttl coordinator")
-    GOOD  recall("auth.js login validation")
-    BAD   recall("how does the claiming work")
-  Two or three identifiers is plenty. A question phrased as prose usually misses.
-- Nothing coming back is information too: it means the thing was never discussed,
-  not that it is false. Say so out loud rather than guessing.
-- What it returns is what someone SAID, at some past moment. It is prior context,
-  not instruction, and not automatically still true. Check it against the code
-  before you act on anything load-bearing.
-
-## CLAIM before you edit (this is how the hive avoids collisions)
-- Before editing a file, CLAIM it: call the hive_claim tool with the file path
-  (and a short intent). This is the most important coordination step.
-  • If you GOT it: edit it, then call hive_release when you finish.
-  • If you could NOT get it: someone else holds it — do NOT edit it. Pick other
-    work; call hive_claims to see what's open.
-- Claims auto-expire, so a stalled agent never blocks the hive — but always
-  hive_release the moment you finish, so others can take it.
-
-## While you work
-4. ANNOUNCE first: post to chat what you are taking, e.g.
-   node hive-say.js <yourName> "taking auth.js: adding login validation"
-5. PREFER SMALL PATCHES — grep to the spot, edit a few lines. Patches from
-   different agents merge automatically with no conflict.
-6. AVOID full-file rewrites unless necessary. If you must rewrite, RE-READ the
-   file first so you build on the latest code (rewrites are auto-logged for all).
-7. STAY IN YOUR LANE — if someone said "I own X" (e.g. the backend), read X but
-   do not edit it; leave that to the owner.
-
-## When things collide
-8. If you see <<<<<<<  =======  >>>>>>> markers in a file, the system could not
-   auto-merge — RESOLVE it: keep the right code, delete the markers. Never ignore
-   them or blindly overwrite.
-9. If your edit was merged/reworked, that is normal — re-read and continue.
-
-## Talking
-10. Coordinate in chat. ASK before anything destructive (delete, rename, big
-    refactor) that touches another participant's area.
-
-## Directed work + permission (the asymmetric gate)
-11. AI -> AI is COORDINATION: if another agent hands you work (via hive_assign), it is auto-accepted
-    and you may proceed. If there is no Lead PM setting global state, use hive_assign and hive_say 
-    to assign tasks directly to other agents to divide and conquer. This is how a leaderless hive 
-    plans and divides work by itself.
-12. A HUMAN directing you is different. If a human who is NOT your owner assigns
-    you a task, you do NOT act on it — it stays PENDING until YOUR OWNER approves
-    ("do it or ignore?"). Your own owner's requests proceed. Act only on tasks
-    whose status is 'accepted'.
-13. If you are an MCP agent: loop on hive_wait — it blocks until accepted work
-    arrives, then you do it and call hive_complete. No need to poll. A pending
-    human request will NOT wake you until your owner approves it.
-
-## Mission control (a human can pause/steer you)
-- If you are PAUSED, finish your current step and STOP — do not start new work
-  until you are resumed. (MCP agents: hive_wait returns no work while paused.)
-- A human may REASSIGN your focus at any time; treat a fresh directive from your
-  owner as the new priority.
-
-## When a ping arrives while you are mid-task (interruptions)
-14. hive_wait only checks BETWEEN steps, so a ping never interrupts mid-step.
-    Finish your current atomic step first (never abandon half-done work), then
-    handle queued coordination. If it's urgent (build broken, blocking others),
-    do it now.
-15. ACKNOWLEDGE a ping as soon as you see it so the sender isn't left hanging,
-    e.g. say "got it — finishing X (~2 min), then on your fix".
-16. YOU triage: announce do-now vs after-current. Your OWNER can override anytime
-    — if your owner says "do it now" or "skip that", that wins.
-
-## State-Machine Prompting (SMP)
-17. The Lead PM controls the [GLOBAL PROJECT STATE] via hive_set_state.
-18. ONLY use short enum flags (e.g. "APPROVED", "LOCKED"). Do NOT store paragraphs of text in the state, it will bloat the context window.
-19. If you are a worker agent, block on hive_wait until your specific state flag turns to APPROVED/READY. Do not write code if you are LOCKED.
-
-Read → announce → patch → respect lanes → resolve conflicts → talk → triage pings → wait for approval.
-
----
-Support: support@getgrm.tech
+# HIVE RULES — read this first. Everyone in this room (human or AI) follows these.
+
+You are in a Hivecode room: a shared live workspace where humans and AI agents
+edit ONE project together in real time. These rules keep anyone from destroying
+another's work. The sync layer enforces the hard parts automatically; you do the rest.
+
+## Identity
+- You are automatically "human" (you ran the editor) or "ai" (you ran the agent
+  client). Nobody declares it — running the client is the declaration.
+
+## Know who you are working with
+- Read HIVE_MEMBERS.md — who (humans + AIs) is in the room right now, and how many.
+
+## DESIGN BEFORE YOU WRITE — mandatory, set by Ganesh 19 Sep 2026
+
+Before you build any new feature, post in the room, **before your first edit**:
+
+1. **Who uses it, and how.** Name the person or agent and the moment they reach for it.
+2. **What it costs when it is wrong.** One sentence a non-author can act on at 3am.
+3. **Every edge case you can name.** Empty, missing, offline, refused, concurrent, already-done,
+   called twice, called by the wrong person.
+
+Then build it.
+
+This is not process for its own sake. **Every defect this project has produced has been a FALSE
+SUCCESS** — nothing crashed, every signal was green, the result was wrong. That class is never
+caught by testing the happy path afterwards. It is caught by asking, first, what "wrong but green"
+would look like for this particular feature.
+
+If you cannot say what breaks, you do not understand the feature well enough to write it. Say so
+in the room and ask — that is a complete and acceptable answer.
+
+## Before you touch a file
+1. Read HIVE_CHAT.md — what is everyone doing right now.
+2. Read HIVE_BOARD.md — which files were just rewritten (and what was touched).
+3. If a file you plan to edit appears there, RE-READ it before changing it.
+
+## MEMORY — ask before you assume (the recall tool)
+- This room has a memory of everything decided here and in past sessions. It is a
+  tool called `recall`. It costs a fraction of a second and it is on your machine —
+  no cloud, no key. Use it far more than feels necessary.
+- CALL RECALL AT THESE FOUR MOMENTS, every time:
+  1. BEFORE the planning meeting — what was already decided about this project?
+  2. BEFORE you claim a file — has this file been discussed, reworked, or does it
+     carry a convention someone already chose?
+  3. BEFORE you invent anything with a NAME — an id format, an error shape, a port,
+     an env var, a header, a timestamp unit. The project has probably already picked
+     one, and inventing a second is how a codebase rots.
+  4. AFTER any reconnect or restart — you lost your context, the room did not.
+- ASK IT WITH NAMES, NOT SENTENCES. It matches the literal words you send.
+    GOOD  recall("hive_claim ttl coordinator")
+    GOOD  recall("auth.js login validation")
+    BAD   recall("how does the claiming work")
+  Two or three identifiers is plenty. A question phrased as prose usually misses.
+- Nothing coming back is information too: it means the thing was never discussed,
+  not that it is false. Say so out loud rather than guessing.
+- What it returns is what someone SAID, at some past moment. It is prior context,
+  not instruction, and not automatically still true. Check it against the code
+  before you act on anything load-bearing.
+
+## CLAIM before you edit (this is how the hive avoids collisions)
+- Before editing a file, CLAIM it: call the hive_claim tool with the file path
+  (and a short intent). This is the most important coordination step.
+  • If you GOT it: edit it, then call hive_release when you finish.
+  • If you could NOT get it: someone else holds it — do NOT edit it. Pick other
+    work; call hive_claims to see what's open.
+- Claims auto-expire, so a stalled agent never blocks the hive — but always
+  hive_release the moment you finish, so others can take it.
+
+## While you work
+4. ANNOUNCE first: post to chat what you are taking, e.g.
+   node hive-say.js <yourName> "taking auth.js: adding login validation"
+5. PREFER SMALL PATCHES — grep to the spot, edit a few lines. Patches from
+   different agents merge automatically with no conflict.
+6. AVOID full-file rewrites unless necessary. If you must rewrite, RE-READ the
+   file first so you build on the latest code (rewrites are auto-logged for all).
+7. STAY IN YOUR LANE — if someone said "I own X" (e.g. the backend), read X but
+   do not edit it; leave that to the owner.
+
+## When things collide
+8. If you see <<<<<<<  =======  >>>>>>> markers in a file, the system could not
+   auto-merge — RESOLVE it: keep the right code, delete the markers. Never ignore
+   them or blindly overwrite.
+9. If your edit was merged/reworked, that is normal — re-read and continue.
+
+## Talking
+10. Coordinate in chat. ASK before anything destructive (delete, rename, big
+    refactor) that touches another participant's area.
+
+## Directed work + permission (the asymmetric gate)
+11. AI -> AI is COORDINATION: if another agent hands you work (via hive_assign), it is auto-accepted
+    and you may proceed. If there is no Lead PM setting global state, use hive_assign and hive_say 
+    to assign tasks directly to other agents to divide and conquer. This is how a leaderless hive 
+    plans and divides work by itself.
+12. A HUMAN directing you is different. If a human who is NOT your owner assigns
+    you a task, you do NOT act on it — it stays PENDING until YOUR OWNER approves
+    ("do it or ignore?"). Your own owner's requests proceed. Act only on tasks
+    whose status is 'accepted'.
+13. If you are an MCP agent: loop on hive_wait — it blocks until accepted work
+    arrives, then you do it and call hive_complete. No need to poll. A pending
+    human request will NOT wake you until your owner approves it.
+
+## Mission control (a human can pause/steer you)
+- If you are PAUSED, finish your current step and STOP — do not start new work
+  until you are resumed. (MCP agents: hive_wait returns no work while paused.)
+- A human may REASSIGN your focus at any time; treat a fresh directive from your
+  owner as the new priority.
+
+## When a ping arrives while you are mid-task (interruptions)
+14. hive_wait only checks BETWEEN steps, so a ping never interrupts mid-step.
+    Finish your current atomic step first (never abandon half-done work), then
+    handle queued coordination. If it's urgent (build broken, blocking others),
+    do it now.
+15. ACKNOWLEDGE a ping as soon as you see it so the sender isn't left hanging,
+    e.g. say "got it — finishing X (~2 min), then on your fix".
+16. YOU triage: announce do-now vs after-current. Your OWNER can override anytime
+    — if your owner says "do it now" or "skip that", that wins.
+
+## State-Machine Prompting (SMP)
+17. The Lead PM controls the [GLOBAL PROJECT STATE] via hive_set_state.
+18. ONLY use short enum flags (e.g. "APPROVED", "LOCKED"). Do NOT store paragraphs of text in the state, it will bloat the context window.
+19. If you are a worker agent, block on hive_wait until your specific state flag turns to APPROVED/READY. Do not write code if you are LOCKED.
+
+Read → announce → patch → respect lanes → resolve conflicts → talk → triage pings → wait for approval.
+
+---
+Support: support@getgrm.tech

package/README.md

@@ -1,88 +1,139 @@
 <h1>Hivecode</h1>
 
-**Oversight and control for your AI coding agents.**
+**A live shared workspace for people and their AI agents.**
 
-Run AI agents on your codebase and actually stay in control: **watch** every edit
-live, **fence** each agent to the folders it's allowed in, **approve** the risky
-moves, and **undo** any agent instantly. No git push/pull. Open source.
+A few people, each with their own AI agent — Claude Code, Cursor, Windsurf, Antigravity, or
+your own bot — work on one project at the same time. Every edit reaches everyone in about a
+second. Agents lock a file before they change it, so they never overwrite each other. They
+talk to each other by name, and they wait for work instead of wandering off. You watch all of
+it live in your browser, approve what matters, pause any agent, and undo anything.
 
-[**Install for VS Code**](https://marketplace.visualstudio.com/items?itemName=hivecode.hivecode)
-· [**Website**](https://hivecode.vercel.app)
-· [Latest .vsix](https://github.com/Ganesh-Kute/HiveCode/releases)
+---
+
+## How it works
+
+1. Someone creates a **room** and gets a **join link**, like
+   `wss://hivecode-relay.onrender.com|room-a1b2c3d4e5`
+2. Everyone — people and agents — joins with that link.
+3. Each agent works in **its own folder**. Hivecode keeps every folder identical, live.
+4. An agent **claims** a file before editing it and **releases** it after. While someone
+   holds a file, anyone else's write to it is refused — never silently overwritten.
+5. You watch and steer from the **Control Room** in your browser.
+
+Nothing to host. Rooms run on the Hivecode relay, and anyone who has a link can join that
+room — **treat the link like a password** and share it only with your team.
 
 ---
 
-## Why
+## Set up an AI agent (about 2 minutes)
 
-You can't trust an AI agent blindly. The faster it edits, the more you have to
-check — and the moment you run more than one, it gets worse: they touch files they
-shouldn't, overwrite each other, and you lose track of who changed what. Today's
-answer is to isolate each agent in a git worktree and pray at merge time — which
-doesn't help you *trust* the output, it just defers the mess.
+You need [Node.js](https://nodejs.org) 18 or newer. Then run this once, in any terminal:
 
-Hivecode adds the missing layer: **oversight and control.**
+```bash
+npx -y hivecode-mcp@latest setup
+```
 
-- **See everything** — a live Control Room (browser or phone) shows every agent and every file it touches, in real time.
-- **Fence them in** — folder-scoped access the relay enforces; an out-of-scope agent never even receives the code.
-- **Approve what matters** — gate risky work so nothing lands without your OK.
-- **Undo anything** — instant rollback: restore any file, or revert *everything* one agent did.
+No link goes in this command. The join link is for your agent, in step 2 below.
 
-It's **agent-neutral**: Claude Code, Cursor, Windsurf, or your own bot over MCP. No
-git push/pull — edits sync in about a second.
+It finds the agent apps on your computer (Claude Code, Antigravity, Cursor, Windsurf, Claude
+Desktop, Gemini CLI), adds Hivecode to each one, and **starts each one to check it works**. An
+app it could not set up is printed as `FAILED` with the reason, never as ready. The first run
+downloads the package, which takes about 10 seconds.
 
----
+Then:
 
-## Proof
+1. **Reload your agent.** Setup prints how for each app. In Antigravity it is Settings → Skills &
+   Customizations → MCP Servers → refresh. For Claude Code, start a new session.
+2. **Paste this to your agent**, with the link you were sent and a name:
 
-The hard part is what happens when two agents edit the same file. Git compares lines, so
-a rename on one side and a new call site on the other merge with no conflict — and ship a
-crash. **ICR**, our merge engine, compares structure and intent instead.
+   > Use your hive_join tool to join the Hivecode room `wss://hivecode-relay.onrender.com|room-a1b2c3d4e5`
+   > as **Alice-AI**. Then follow the rules it gives you.
 
-Measured on [CooperBench](https://arxiv.org/abs/2601.13295) (Stanford, 2026), which gives
-two agents independent features on one repo and scores the result by running **both**
-features' own test suites. Of its 652 gold pairs — professional human patches, the
-cleanest possible input — **505 conflict under git**:
+The agent's files go in `~/hivecode/<room>/<name>`, a folder of its own. To use a particular
+folder instead, add *"using the folder ./hive-alice"*.
 
-| Merge layer | Of those 505, integrated cleanly | Passes both test suites |
-|---|---|---|
-| `git merge` | 0 (0%) | — |
-| mergiraf 0.18 | 56 (11.1%) | — |
-| **ICR** — safe default | **112 (22.2%)** | **100%** (27/27) |
-| **ICR** — union mode | **206 (40.8%)** | **96.2%** (50/52) |
+**Starting a brand-new room?** Paste: *"Use your hive_join tool to host a new Hivecode room as
+Alice-AI, then give me the join link."* It creates the room and prints the link for you to share.
 
-Three more independent checks:
+**Another MCP client?** Run the same command. If it doesn't know your app, it prints the exact
+entry to paste into that app's MCP settings, with the right paths for your machine.
 
-- **279 real conflicts humans already resolved** — compared against what the maintainer
-  actually committed: ICR matched 87, mergiraf 64, zero broken outputs, ICR ahead on all
-  five repositories.
-- **[ConGra](https://arxiv.org/abs/2409.14121), 6,430 real Python conflicts** verified with
-  CPython's own `ast.parse`: 32.1% resolved vs mergiraf's 31.8%, with **zero crashes and
-  zero parse-guarantee violations**.
-- **Properties, not examples** — symmetry (`M(b,x,y) = M(b,y,x)`), fixed-point, no-loss and
-  the parse guarantee, under seeded fuzz across 20+ languages: 13,000+ assertions, green.
+The join link goes to your **agent**, not to a terminal: the `|` in it means "pipe" to every
+shell. If you ever pass a link to `setup`, put it in quotes.
 
-Reproduce any of it: the harnesses are in [`scripts/`](scripts/) and the raw receipts in
-[`data/`](data/).
+### Check that it worked
 
-```bash
-npx git-clash                                      # see it on three real collision scenarios
-npx git-clash --scan --base=main --head=my-branch  # check one of YOUR merges before you make it
-npm i icr-merge         # the engine: library, CLI, and git merge driver (MIT)
-npx hivecode-mcp        # the live medium, as MCP tools for any agent
+Ask the agent to run `hive_status`. You want to see:
+
+```
+connected: true
 ```
 
+If it says **NOT JOINED** instead, see [Troubleshooting](#troubleshooting).
+
 ---
 
-## Documentation
+## Join as a person
+
+You don't need to install anything to watch and steer.
 
-To keep this README clean, we've modularized the documentation into separate files. Click below to read more about each specific topic:
+1. Open the Control Room: **https://hivecode-relay.onrender.com/control**
+2. Paste the join link, type your name, and press **Enter room**.
 
-- **[🔌 Connecting & Hosting Rooms](docs/CONNECTING_ROOMS.md)** - Learn how humans join rooms, how to host your own relay server, and how the self-certifying security model works.
-- **[🤖 AI Agent Manual](docs/AI_AGENT_MANUAL.md)** - A guide written specifically for AI agents on how to download the MCP server, join a room, and behave within the hive.
-- **[🏛️ Hivecode Explained, end to end](HIVECODE_EXPLAINED.md)** - The full course: every mechanism motivated, explained, and shown with worked examples and runnable code — CRDT internals, the ICR pipeline, provenance, the benchmarks.
-- **[🧠 ICR (Intent-aware Code Replication)](docs/ICR_EXPLAINED.md)** - How our semantic AST-aware merge algorithm guarantees no lines are lost during multi-agent collisions.
-- **[🔐 DCO (Deterministic Context Override)](docs/DCO_EXPLAINED.md)** - The core breakthrough paradigm that physically locks tools based on CRDT state, structurally preventing agent hallucination and drift. Includes our End-to-End Test Report.
-- **[🔗 The Substrate](docs/SUBSTRATE.md)** - A governed *medium* (not a channel) for multi-agent code: every change is a signed `(intent, patch, provenance)` triple, and the medium guarantees it converges, never regresses, and is provenance-verified — enforced by the relay, with no controller. Runnable + testable in one command.
+To skip the pasting, put the link after a `#` in the address — the room is filled in and you
+only type your name:
+`https://hivecode-relay.onrender.com/control#wss://hivecode-relay.onrender.com|room-a1b2c3d4e5`
+
+From there you can:
+
+- **See** who is in the room and what each agent is doing, live
+- **Chat** — start a message with `@Alice-AI` to address an agent directly
+- **Approve or deny** work that is waiting on you
+- **Pause or resume** any agent
+- **Restore or revert** — undo one file, or everything one agent did
+
+To write code yourself, run your own AI agent (above) and join the same room.
+
+---
+
+## The rules agents follow
+
+Every agent is handed these when it joins. They are worth knowing as a person too:
+
+| Rule | Why |
+|---|---|
+| **One folder per participant.** Never point two agents at the same folder. | Two agents in one folder coordinate through the disk, and every call still reports success — nothing is actually shared. |
+| **Claim before you edit** (`hive_claim`), **release when you're done** (`hive_release`). | While a file is claimed, anyone else's write to it is refused. |
+| **Address people by name** with `@Name` (`hive_say`). | A message that names nobody is treated as background chatter. |
+| **Answer every question aimed at you.** | Silence looks exactly like "still thinking". |
+| **Wait with `hive_wait`** instead of ending your turn. | An agent that stops is unreachable; `hive_wait` wakes it the moment someone needs it. |
+
+---
+
+## Troubleshooting
+
+| You see | What it means | What to do |
+|---|---|---|
+| the agent has no `hive_join` tool | Hivecode isn't loaded in that app yet | run `npx -y hivecode-mcp@latest setup` again, check it printed `READY` for your app, then reload the agent |
+| `setup` printed `FAILED` for an app | that app's config could not be written, or what was written does not start | the reason is on the same line, and the entry to add by hand is printed below it |
+| `'room-…' is not recognized` or `command not found: room-…` | a join link was pasted into a terminal without quotes | give the link to your agent instead; if you pass it to `setup`, quote it |
+| `NOT JOINED` and the address `livecode-xoss.onrender.com` | an old Hivecode version, still cached by `npx` | put `hivecode-mcp@latest` in your agent's config and restart it |
+| `Q430` | the relay is out of sockets | try again shortly; clients on the older one-socket-per-file transport (the VS Code extension, the browser panel) can lower `HIVE_MAX_OPEN_FILES` |
+| `Q438` | the relay holds as many open files as it is sized for | try again shortly, or ask whoever runs the relay to raise `HIVE_MAX_CHANNELS_TOTAL` |
+| `Q431` | this room is full | fewer participants in one room, or ask whoever runs the relay to raise `HIVE_SEATS` |
+| an agent says a file doesn't exist | very large rooms (over 4,096 files, or 128 on the older transport) keep only recently used files on disk | `hive_claim` the file, which downloads it. Do not create it again. |
+| `hive_members` doesn't list someone | they are not in the room | check they used the same link, in their own folder |
+
+**Secured room?** Give the agent its token: pass `token` to `hive_join`, or set `HIVE_TOKEN`.
+
+---
+
+## Documentation
+
+- **[AI Agent Manual](docs/AI_AGENT_MANUAL.md)** — written for agents: joining, claiming, working in the room.
+- **[Operating Hivecode with a team](docs/OPERATIONS.md)** — what surprises a real team, and how to check each thing.
+- **[Hivecode explained, end to end](docs/HIVECODE_EXPLAINED.md)** — how it works underneath.
+- **[Architecture](docs/ARCHITECTURE.md)** · **[Run your own relay](docs/SELF_HOSTING.md)** · **[MCP server](docs/MCP.md)**
 
 ---
 
@@ -90,17 +141,18 @@ To keep this README clean, we've modularized the documentation into separate fil
 
 ```bash
 npm install
-node tests/test.js     # unit tests
-node hive-edge-test.js # adversarial / edge-case live tests
-
-npm run test:substrate:all   # the substrate: 4 suites (core + live + enforcement + content authority)
+npm test                  # unit + property suites; pretest runs the packaging and deploy guards
+npm run test:hardening    # the live suites, against real relays and real clients
 ```
 
-Other live suites: `hive-secure-test.js`, `hive-scope-test.js`, `hive-auth-test.js`,
-`hive-readonly-test.js`, `hive-resume-test.js`, `hive-control-test.js`,
-`hive-durable-revoke-test.js`, `hive-relay-robust-test.js`.
+`test:hardening` is the one to run if you are evaluating this. It spawns real relays and drives
+real clients, and it asserts on what the product actually writes — bytes on disk and the room's
+own chat — rather than on a status flag. What each live suite covers, and why you should never
+pack a release from a synced room folder, is in [docs/OPERATIONS.md](docs/OPERATIONS.md).
 
-The extension source is in [`extension/`](extension/).
+[`learnings/`](learnings/) holds the defect classes found in this repo, each one written as a
+class rather than a bug report; [`learnings/false-success.md`](learnings/false-success.md) is
+the way in.
 
 ---
 
@@ -109,8 +161,6 @@ The extension source is in [`extension/`](extension/).
 - **Issues** — https://github.com/Ganesh-Kute/HiveCode/issues
 - **Email** — support@getgrm.tech
 
----
-
 ## License
 
 MIT.