gossipcat 0.1.0 → 0.1.2

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="packages/dashboard-v2/public/assets/banner.png" alt="Gossipcat" width="600" />
+  <img src="https://raw.githubusercontent.com/gossipcat-ai/gossipcat-ai/master/packages/dashboard-v2/public/assets/banner.png" alt="Gossipcat" width="600" />
 </p>
 
 <p align="center">
@@ -7,18 +7,21 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/ataberk-xyz/gossipcat-ai/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" /></a>
+  <a href="https://github.com/gossipcat-ai/gossipcat-ai/releases/latest"><img src="https://img.shields.io/github/v/release/gossipcat-ai/gossipcat-ai?color=0ea5e9&label=release" alt="Latest release" /></a>
+  <a href="https://github.com/gossipcat-ai/gossipcat-ai/releases"><img src="https://img.shields.io/github/downloads/gossipcat-ai/gossipcat-ai/total?color=0ea5e9" alt="Downloads" /></a>
+  <a href="https://github.com/gossipcat-ai/gossipcat-ai/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" /></a>
   <a href="#quickstart"><img src="https://img.shields.io/badge/node-22%2B-green" alt="Node 22+" /></a>
+  <a href="https://github.com/gossipcat-ai/gossipcat-ai/stargazers"><img src="https://img.shields.io/github/stars/gossipcat-ai/gossipcat-ai?style=social" alt="GitHub stars" /></a>
 </p>
 
 <p align="center">
-  <a href="#quickstart"><strong>Quickstart</strong></a> ·
-  <a href="#how-it-works"><strong>How It Works</strong></a> ·
-  <a href="#usage"><strong>Usage</strong></a> ·
-  <a href="#for-ai-agents"><strong>For AI Agents</strong></a> ·
-  <a href="#dashboard"><strong>Dashboard</strong></a> ·
-  <a href="#configuration"><strong>Configuration</strong></a> ·
-  <a href="#roadmap"><strong>Roadmap</strong></a>
+  <a href="#quickstart"><strong>Install</strong></a> ·
+  <a href="#first-run--5-minutes"><strong>First Run</strong></a> ·
+  <a href="#how-to-use-it-day-to-day"><strong>Daily Use</strong></a> ·
+  <a href="#reading-the-dashboard"><strong>Dashboard</strong></a> ·
+  <a href="#troubleshooting"><strong>Troubleshooting</strong></a> ·
+  <a href="#configuration"><strong>Config</strong></a> ·
+  <a href="#for-ai-agents"><strong>For AI Agents</strong></a>
 </p>
 
 <br/>
@@ -160,37 +163,62 @@ Both types participate equally in consensus, cross-review, and skill development
 
 ## Quickstart
 
-**Requirements:** Node.js 22+
+**Requirements:** Node.js 22+ and [Claude Code](https://claude.com/claude-code).
 
-### 1. Install
+### One-liner
 
 ```bash
-npm install -g gossipcat
+npm install -g https://github.com/gossipcat-ai/gossipcat-ai/releases/latest/download/gossipcat.tgz && \
+claude mcp add gossipcat -s user -- gossipcat
 ```
 
-That's it. The install drops a `gossipcat` binary on your `PATH` and ships both the MCP server bundle and the dashboard assets. No clone, no build step.
+Restart Claude Code. Then in any project, ask:
+
+> "Set up a gossipcat team for this project"
+
+Claude Code will call `gossip_setup()` to scaffold `.gossip/config.json` and your agent team. First-run bootstrap also writes the dispatch rules and tool catalog so Claude Code knows how to use gossipcat — no manual config needed.
+
+Gossipcat ships from **[GitHub Releases](https://github.com/gossipcat-ai/gossipcat-ai/releases)**, not the npm registry. The install URL above always points at the latest release. `npm` downloads the tarball directly, installs it globally, and drops a `gossipcat` binary on your `PATH` — no `npm publish` involved.
+
+### What the install ships
+
+| | What you get |
+|---|---|
+| **MCP server** | Bundled binary at `dist-mcp/mcp-server.js`, wired as the `gossipcat` command on `PATH` |
+| **Dashboard** | Prebuilt static assets in `dist-dashboard/` — launches automatically on a dynamic port (ask Claude Code *"what's my gossipcat dashboard URL?"*). Override with `GOSSIPCAT_PORT=24420` if you want a stable port. |
+| **Default skills + rules + archetypes** | 18 bundled skill templates, operational rules, and project archetypes copied into the install |
+| **Postinstall wizard** | Writes `.mcp.json` with correct absolute paths for your machine |
+
+### Alternative install paths
 
-If you prefer project-local install:
+**Pin to a specific version:**
 ```bash
-npm install --save-dev gossipcat
+npm install -g https://github.com/gossipcat-ai/gossipcat-ai/releases/download/v0.1.1/gossipcat-0.1.1.tgz
 ```
-The postinstall will write a `.mcp.json` into your project root automatically. Open Claude Code in that directory and gossipcat connects.
 
-### 2. Register with Claude Code
+**Project-local install** (each project gets its own gossipcat):
+```bash
+cd your-project
+npm install --save-dev https://github.com/gossipcat-ai/gossipcat-ai/releases/latest/download/gossipcat.tgz
+```
+The postinstall writes `.mcp.json` to your project root. Open Claude Code in that directory and gossipcat connects automatically — no `claude mcp add` needed.
 
-For global registration (available in every project):
+**From source** (contributors):
 ```bash
-claude mcp add gossipcat -s user -- gossipcat
+git clone https://github.com/gossipcat-ai/gossipcat-ai.git
+cd gossipcat-ai
+npm install
+npm run build:mcp
+claude mcp add gossipcat -s user -- node "$PWD/dist-mcp/mcp-server.js"
 ```
 
-The dashboard launches automatically on port `24420` when the relay starts — no extra setup needed.
+### Upgrading
 
-**From source** (contributors only):
+Re-run the one-liner — npm will fetch the latest release tarball and replace the installed version:
 ```bash
-git clone https://github.com/ataberk-xyz/gossipcat-ai.git
-cd gossipcat-ai && npm install && npm run build:mcp
-claude mcp add gossipcat -s user -- node "$PWD/dist-mcp/mcp-server.js"
+npm install -g https://github.com/gossipcat-ai/gossipcat-ai/releases/latest/download/gossipcat.tgz
 ```
+Or in-session, ask Claude Code: *"Check for gossipcat updates"* — the `gossip_update` tool fetches the latest release notes and applies the upgrade with your confirmation.
 
 ### 3. API keys
 
@@ -287,142 +315,273 @@ Available presets: `reviewer`, `implementer`, `tester`, `researcher`, `debugger`
 
 <br/>
 
-## Use Cases
+## First Run — 5 Minutes
 
-### Build something — gossipcat picks the team
+The fastest path from "just installed" to "first useful review". If you skip this section you'll probably get stuck on the same things everyone else gets stuck on.
 
-```
-"I want to build a Stripe integration, set up a team for that"
-"I'm adding real-time notifications — what agents do I need?"
-"Set up a team for a TypeScript REST API project"
+### Step 1 — Open Claude Code in any project
+
+```bash
+cd ~/your-project
+claude
 ```
 
-Describe what you're building. Gossipcat proposes an agent team tailored to the task — right presets, right skills, right mix of providers. You review the proposal and approve it. From that point on, agents dispatch automatically based on what your code touches.
+Gossipcat is registered globally now, so it boots automatically. You'll see it in the MCP server list.
 
----
+### Step 2 — Bootstrap once
+
+In Claude Code, just type:
 
-### Review code before committing
+> **Run gossip_status**
 
+This loads gossipcat's operating rules into the current session, creates `.gossip/` in your project on first run, and prints the dashboard URL + auth key. Copy the key — you'll paste it into the dashboard once.
+
+You'll see something like:
 ```
-"Review the changes I just made"
-"Do a consensus review on the auth module"
-"Check my last 3 commits for bugs"
+Status:
+  Host: claude-code (native agents supported)
+  Relay: running :49664
+  Workers: 0
+  Dashboard: http://localhost:49664/dashboard (key: c3208820f8f70605fd45fa90004a2a4b)
+  Quota: google — OK
 ```
 
-Three agents review your diff independently, then cross-check each other's findings. You get a report with CONFIRMED bugs (multiple agents agree), DISPUTED findings (agents disagree), and UNIQUE findings (only one agent found it). You only act on what's verified.
+Open the dashboard URL in your browser, paste the key. You're now connected.
 
----
+### Step 3 — Create your first team
+
+Tell Claude what you're building:
 
-### Catch security issues
+> **"Set up a gossipcat team for this project — it's a TypeScript Next.js app with a Postgres backend and Stripe payments."**
+
+Claude calls `gossip_setup()` and proposes a team. Typical proposal:
 
 ```
-"Security audit the payment handler"
-"Check the login flow for vulnerabilities"
-"Review the API endpoints for injection risks"
+Proposed team:
+  - sonnet-reviewer    (anthropic/claude-sonnet-4-6, native)   reviewer + security
+  - gemini-reviewer    (google/gemini-2.5-pro, relay)          reviewer + types
+  - haiku-researcher   (anthropic/claude-haiku-4-5, native)    researcher
+  - opus-implementer   (anthropic/claude-opus-4-6, native)     implementer
+
+Approve? (y/n)
 ```
 
-Dispatch your security-focused agents in parallel. Each reviews from a different angle — one checks OWASP vectors, another checks input validation, another checks auth logic. Findings that survive cross-review are real.
+Native agents (`native: true`) run through your existing Claude Code subscription — **no API key needed**. Relay agents need a key for their provider. If you don't have a Google API key, drop `gemini-reviewer` from the team for now and add it later.
 
----
+Once you approve, gossipcat writes `.gossip/config.json` and the agents are live.
+
+### Step 4 — Run your first review
 
-### Research a codebase before building
+In a project where you've made some changes:
+
+> **"Do a consensus review of my recent changes"**
+
+What happens (typical timing):
+
+| Phase | Time | What you see |
+|---|---|---|
+| 1. Decompose | 1s | Claude picks agents and dispatches them in parallel |
+| 2. Independent review | 30s–2min | Each agent reads your diff and reports findings |
+| 3. Cross-review | 30s–1min | Each agent reviews the others' findings |
+| 4. Consensus report | <1s | Findings tagged CONFIRMED / DISPUTED / UNVERIFIED / UNIQUE |
+| 5. Verification | varies | Claude reads UNVERIFIED findings against the code, decides if they're real |
+| 6. Signal recording | <1s | Accuracy signals saved per agent |
+
+You get a report like:
 
 ```
-"Research how the WebSocket connection lifecycle works before I touch it"
-"Explain the dispatch pipeline — I need to add a new routing mode"
+Consensus round b81956b2-e0fa4ea4 — 3 agents
+
+CONFIRMED (2):
+  [critical] Race condition in tasks Map at server.ts:47 — sonnet + gemini
+  [high]     Missing auth on WebSocket upgrade at server.ts:112 — sonnet + gemini
+
+UNIQUE (1):
+  [medium]   String concat in SQL query at queries.ts:88 — only sonnet caught this
+
+DISPUTED (1):
+  [low]      "Memory leak in timer" — haiku says yes, sonnet/gemini say no
+             → verified, sonnet was right (not a leak — cleanup is in finally)
+
+Final: 3 real bugs to fix, 1 false alarm caught by cross-review.
 ```
 
-Agents read the code, trace call paths, and write a summary back to session memory. Next time you ask about the same area, they already know it.
+You only act on **CONFIRMED** + verified **UNIQUE** findings. The cross-review is the whole point — single-agent reviews ship hallucinated bugs as critical findings 5–10% of the time. Cross-review with verification drops that to under 1%.
+
+### Step 5 — Watch the dashboard
+
+The dashboard shows everything live: agents, scores, active tasks, consensus reports, signals. You can leave it open in a tab while you work — every gossipcat tool call pushes an update via WebSocket.
+
+That's the basic loop. The rest of this README covers advanced workflows, troubleshooting, and how to interpret what you're seeing.
+
+<br/>
+
+## How to use it day-to-day
+
+Concrete recipes for the most common workflows. Each one shows what to type, what you'll get back, and what to do with it.
+
+### Recipe 1: Review a diff before committing
+
+**Type:**
+> "Review my staged changes"
+
+**What you'll get:** A consensus report (1–3 minutes) with findings tagged CONFIRMED / UNIQUE / DISPUTED. Claude verifies UNVERIFIED findings against the code and tells you which are real.
+
+**What to do with it:** Fix the CONFIRMED + verified-real findings. Ignore disputed-but-falsified findings. If a finding looks important but you disagree, ask Claude *"verify finding f3 against the code yourself"* — it'll re-check and either back you up or push back.
+
+**When NOT to use it:** Tiny diffs (under 20 lines) — overhead exceeds value. Just eyeball them.
 
 ---
 
-### Get a second opinion on your own review
+### Recipe 2: Catch security issues before shipping a feature
 
-```
-"I think there's a race condition in this Map — check if I'm right"
-"Verify whether this fix actually resolves the issue"
-```
+**Type:**
+> "Security audit the payment handler at lib/stripe/webhook.ts"
+
+**What you'll get:** Each security-skilled agent reviews from a different angle (OWASP, input validation, auth, secrets). Findings get cross-validated. Real vulns surface; theoretical ones get caught and dropped.
 
-Describe what you think you're seeing. Agents check independently and either confirm or disprove it. Author self-review is optimistic by nature — this isn't.
+**What to do with it:** Fix critical/high findings before merge. Bookmark medium/low findings for the next pass.
+
+**Tip:** Be specific about the file or module. "Security audit the codebase" is too broad and produces noisy results. "Security audit `lib/stripe/webhook.ts`" produces actionable findings.
 
 ---
 
-### Track which agents are actually reliable
+### Recipe 3: Understand a piece of code before changing it
 
-```
-"Show me agent scores"
-"Which agent is best at security reviews?"
-```
+**Type:**
+> "Research how the WebSocket connection lifecycle works in this project before I touch it"
 
-Every finding gets verified and turned into a signal. Accuracy, uniqueness, and reliability are tracked per agent. Over time, dispatch weights shift — the agents that keep catching real bugs get more work.
+**What you'll get:** A research agent (haiku-researcher by default — fast and cheap) reads the code, traces call paths, and writes a summary. The summary is saved to that agent's cognitive memory so the next time you ask about the same area it remembers.
+
+**What to do with it:** Use the summary to plan your change. The agent will reference it next time you ask anything related — no re-discovery cost.
 
 ---
 
-### Improve a struggling agent
+### Recipe 4: Verify your own assumption
 
-```
-"Gemini keeps hallucinating about concurrency — fix it"
-"Develop a skill for the reviewer's repeated type-safety misses"
-```
+**Type:**
+> "I think there's a race condition in the tasks Map at server.ts:47 — check if I'm right"
 
-Gossipcat generates a targeted skill file from the agent's failure data and injects it into future prompts. Signals penalize past mistakes; skills prevent future ones.
+**What you'll get:** Two agents independently check the specific claim and either confirm or push back. Author self-review is optimistic — this isn't.
+
+**What to do with it:** If both agree with you, fix it. If they push back, read their reasoning before defending your hypothesis. They might be right.
+
+---
+
+### Recipe 5: See which agents you can actually trust
+
+**Type:**
+> "Show me agent scores"
+
+**What you'll get:** A table of agents sorted by reliability with per-category accuracy and dispatch weights. Categories include `trust_boundaries`, `injection_vectors`, `concurrency`, `error_handling`, `data_integrity`, `type_safety`, etc.
+
+**What to do with it:** If `gemini-reviewer` is sitting at 30% accuracy on `concurrency`, you know not to trust its concurrency findings without cross-review. If `sonnet-reviewer` is at 90% on `trust_boundaries`, you can ship its findings on auth/session bugs with high confidence.
+
+---
+
+### Recipe 6: Improve an agent that keeps making the same mistake
+
+**Type:**
+> "gemini-reviewer keeps hallucinating about concurrency — develop a skill for it"
+
+**What you'll get:** Gossipcat reads gemini-reviewer's failure data, generates a targeted skill file with concrete anti-patterns, and injects it into the agent's prompt for all future concurrency-related reviews. Effectiveness is measured statistically (z-test on post-bind signals) — it'll tell you if the skill is actually working after ~30 dispatches.
+
+**What to do with it:** Nothing — it's automatic. Just keep using the agent. Over time, the failure rate drops.
+
+---
+
+### Recipe 7: Set up a team for a brand-new project
+
+**Type:**
+> "Set up a gossipcat team for a TypeScript Cloudflare Workers project with Drizzle ORM and KV storage"
+
+**What you'll get:** A proposed team with archetypes matched to your stack. Worker projects need different reviewers than long-running Node services — gossipcat picks accordingly.
+
+**What to do with it:** Review the proposal, drop agents you can't run (missing API keys), approve.
+
+---
+
+### Things to avoid
+
+- **Don't ask for "review the whole codebase"** — too broad, agents will pick whatever they find first. Scope to a file, module, or diff.
+- **Don't approve findings without reading them** — even after cross-review, ~5% of findings are genuinely wrong. The reasoning matters more than the verdict.
+- **Don't ignore the dashboard** — when something feels weird (slow dispatch, repeated failures, suspicious findings), the dashboard usually shows you why before you have to ask.
+- **Don't run consensus mode for trivial questions** — `gossip_run` with one agent is fine for "what does this function do?"-tier queries. Save consensus for changes that touch shared state, auth, persistence, or the dispatch pipeline itself.
 
 <br/>
 
-## Usage
+## Reading the dashboard
+
+The dashboard at `http://localhost:<port>/dashboard` is the visual layer over everything gossipcat knows. Open it once with the auth key from `gossip_status`, leave the tab open while you work. Updates push live via WebSocket.
 
-Once gossipcat is installed, you interact with it through natural language in Claude Code. The CLAUDE.md rules file (auto-generated on first boot) teaches Claude Code how to use the gossipcat tools — you just describe what you want.
+| Panel | What it shows | When to look at it |
+|---|---|---|
+| **Overview** | Active agents, dispatch weights, recent finding counts | First thing in the morning — quick sanity check |
+| **Team** | All agents sorted by reliability score, with category breakdowns | Picking which agent to trust for a tricky finding |
+| **Tasks** | Live + historical task list with agent, duration, status | When something feels stuck — find it here first |
+| **Findings** | Consensus reports paginated by round, with CONFIRMED/DISPUTED/UNVERIFIED breakdowns | Reviewing what got caught in a recent review |
+| **Agent detail** | Per-agent memory entries, skills, score history, task history | Diagnosing why a specific agent keeps failing in a category |
+| **Signals** | Raw signal feed (agreement / hallucination / unique_confirmed) | Auditing the scoring pipeline if scores look wrong |
+| **Logs** | mcp.log content (boot, errors, warnings) | When the MCP server is misbehaving and you need raw evidence |
 
-### What to say to Claude Code
+**Auth keys rotate every session.** A fresh key is generated each time gossipcat boots. If the dashboard says "unauthorized", run `gossip_status` again to get the new key.
 
-| What you want | What to type |
-|---------------|-------------|
-| Review your latest changes | *"Review my recent changes"* |
-| Deep review of critical code | *"Do a consensus review on the auth module"* |
-| Catch security issues | *"Security audit the payment handler"* |
-| Research before building | *"How does the dispatch pipeline work?"* |
-| Get a second opinion | *"Check if I'm right about this race condition"* |
-| Check which agents are performing well | *"Show me agent scores"* |
-| Improve a struggling agent | *"Develop a skill for the reviewer's type-safety misses"* |
-| Save context for next session | *"Save session"* |
+<br/>
 
-Claude Code reads the dispatch rules from `.claude/rules/gossipcat.md` and automatically decides whether to use single-agent, parallel, or consensus mode based on what your change touches.
+## Troubleshooting
 
-### Example session
+### "Dashboard says unauthorized / 401"
+The auth key rotates every boot. Run `gossip_status` in Claude Code to get the current key, paste it into the dashboard login.
 
-```
-You:    "Review the changes I made to the relay server with the gossipcat team"
+### "Dashboard URL doesn't load at all"
+Check `~/.gossip/mcp.log` (or `<your-project>/.gossip/mcp.log`) for the boot log. Look for the `[gossipcat] 🌐 Dashboard:` line — that's the actual port. If it's missing, the relay didn't start. Common causes:
+- **Conflicting `.gossip/relay.pid`** from a crashed previous boot — delete it and restart Claude Code
+- **`GOSSIPCAT_PORT` set to a port already in use** — unset the env var or pick a free port
 
-Claude: Dispatches 3 agents via gossip_dispatch(mode: "consensus")
-        → sonnet-reviewer checks for security issues
-        → gemini-reviewer checks for logic bugs
-        → gemini-tester checks for edge cases
+### "Boot says 'No gossip.agents.json found' and nothing happens"
+This was a critical bug in v0.1.0 — fixed in v0.1.1. Upgrade with the install one-liner above. v0.1.1+ boots in degraded mode (dashboard + relay only) so you can run `gossip_setup` from inside Claude Code.
 
-        Cross-review round: agents review each other's findings
+### "Agents keep returning empty findings"
+Usually a model or quota problem. Check `gossip_status` — it shows `Quota: google — OK` (or `cooling down`) per provider. If you're rate-limited, gossipcat will fall back to native agents automatically, but fallback agents may not be in your team. Either wait for the cooldown or add native agents to your team.
 
-        Consensus report:
-        ✓ CONFIRMED: race condition in connection cleanup (3/3 agree)
-        ✓ CONFIRMED: missing error handler on WebSocket close (2/3 agree)
-        ? UNVERIFIED: potential memory leak in Map (1 found, others couldn't verify)
+### "The same hallucinated finding keeps coming back"
+Record a `hallucination_caught` signal: ask Claude *"record a hallucination_caught signal for finding f3 in the last consensus round — it claimed X but the code shows Y"*. After 3 such signals, the offending agent's score drops in that category and the orchestrator stops asking it questions in that area.
 
-        Claude verifies the UNVERIFIED finding against your code,
-        records accuracy signals, and presents the final report.
+### "I want to use my own model / provider"
+Edit `.gossip/config.json` directly. Any OpenAI-compatible endpoint works via `provider: "openai"` + `base_url`. Local models work via Ollama (`provider: "local"`). See the [Configuration](#configuration) section.
+
+### "Multiple Claude Code instances all want gossipcat"
+Already supported as of v0.1.1 — each instance gets its own dynamic port. If you want a stable port for one specific instance (e.g. for browser bookmarks), set `GOSSIPCAT_PORT=24420` for that one project's environment.
+
+### "How do I uninstall?"
+```bash
+npm uninstall -g gossipcat
+claude mcp remove gossipcat -s user
+rm -rf ~/.gossip  # if you want to wipe global memory + signals
+rm -rf <project>/.gossip  # if you want to wipe per-project state
 ```
 
-### Under the hood
+### Still stuck?
+File an issue at https://github.com/gossipcat-ai/gossipcat-ai/issues. Include the contents of `.gossip/mcp.log` (last 100 lines) and the output of `gossip_status`. Or ask Claude in-session: *"file a gossipcat bug report about <...>"* — the `gossip_bug_feedback` tool packages it up automatically.
 
-Claude Code translates your requests into gossipcat MCP tool calls:
+<br/>
+
+## Under the hood
+
+Claude Code translates your natural-language requests into gossipcat MCP tool calls automatically — you don't need to type these — but if you want fine-grained control they're documented here:
 
 ```
 gossip_run(agent_id: "auto", task: "...")        → single-agent task
-gossip_dispatch(mode: "consensus", tasks: [...]) → multi-agent review
-gossip_collect(consensus: true)                  → cross-review + report
-gossip_signals(action: "record", signals: [...]) → record accuracy
+gossip_dispatch(mode: "consensus", tasks: [...]) → multi-agent review with cross-review
+gossip_collect(consensus: true)                  → wait for results, run consensus
+gossip_signals(action: "record", signals: [...]) → record accuracy after verification
 gossip_scores()                                  → view agent performance
-gossip_skills(action: "develop", ...)            → improve struggling agents
+gossip_skills(action: "develop", ...)            → improve a struggling agent
+gossip_status()                                  → system status + dashboard URL
+gossip_setup(...)                                → create or update your team
 ```
 
-You don't need to type these — Claude Code handles tool selection. But you can call them directly if you want fine-grained control.
+The dispatch rules at `.claude/rules/gossipcat.md` (auto-generated on first boot) teach Claude Code when to pick which mode based on what your change touches. You can edit these rules to bias the dispatch.
 
 <br/>
 
@@ -529,30 +688,16 @@ These tools are called by the internal LLM (the orchestrator — Claude Code wit
 
 <br/>
 
-## Dashboard
+## Dashboard internals
 
-Build the dashboard (one time):
-```bash
-npm run build:dashboard
-```
+> User-facing dashboard guide is in [Reading the dashboard](#reading-the-dashboard) above. This section covers the build + tech stack.
 
-The dashboard launches automatically on port `24420` when gossipcat boots. Run `gossip_status` to get the URL and auth key:
+Built with React + Vite + shadcn/ui. Source lives at `packages/dashboard-v2/`. The bundled assets ship in `dist-dashboard/` and the relay serves them as static files at `http://localhost:<dynamic-port>/dashboard/`. Live updates push via WebSocket — every gossipcat tool call emits an event that connected dashboard tabs receive in real time.
 
+To rebuild from source (contributors only):
+```bash
+npm run build:dashboard
 ```
-Dashboard: http://localhost:24420/dashboard (key: a1b2c3...)
-```
-
-A new auth key is generated each session. Paste it when prompted to log in.
-
-Built with React + Vite + shadcn/ui:
-
-- **Overview** — agent cards with dispatch weights, recent tasks, finding metrics
-- **Team** — all agents sorted by reliability
-- **Tasks** — task history with agent, duration, and status
-- **Findings** — consensus reports with CONFIRMED/DISPUTED/UNVERIFIED breakdowns
-- **Agent detail** — per-agent memory, skills, scores, and task history
-
-Live updates via WebSocket — every tool call pushes events to connected clients.
 
 <br/>
 
@@ -692,6 +837,7 @@ Gossipcat auto-detects the host environment:
 | Statistical skill effectiveness (z-test on per-category accuracy, auto pass/fail verdicts) | ✅ Shipped |
 | Native subagents get skill injection + cognitive memory recall | ✅ Shipped |
 | Relay cross-reviewers get `file_read` + `file_grep` (closes tool-blindness gap with natives) | ✅ Shipped |
+| npm package — one-liner install with bundled MCP server + dashboard | ✅ Shipped |
 | Full implementation workflow (agents write code) | 🔄 In progress |
 | Dashboard enrichment (graphs, trends, session history) | ☐ Planned |
 | Local Postgres migration (embedded Postgres for tasks/signals/consensus/memory — unblocks full task results, real queries, no more JSONL scans) | ☐ Planned |
@@ -702,6 +848,33 @@ Gossipcat auto-detects the host environment:
 
 <br/>
 
+## Contributing
+
+Gossipcat is open source and early-stage — bug reports, feature ideas, and PRs are all welcome.
+
+- **Bugs / feature requests** → [open an issue](https://github.com/gossipcat-ai/gossipcat-ai/issues). Or ask Claude Code directly: *"File a gossipcat bug report about <...>"* — the `gossip_bug_feedback` tool posts structured issues from your current session.
+- **Pull requests** → fork, branch, PR against `master`. Run `npm test` before pushing. Commit messages follow conventional commits (`fix:`, `feat:`, `chore:`, `docs:`).
+- **Discussions** → new ideas, design questions, "should this be a feature?" → [GitHub Discussions](https://github.com/gossipcat-ai/gossipcat-ai/discussions).
+
+See `CLAUDE.md` in the repo for the operational rules gossipcat's own agents follow during development — it's a useful read if you want to understand the signal pipeline and consensus workflow from the inside.
+
+### Cutting a release (maintainers)
+
+Releases go to GitHub Releases via a two-stage script that respects branch protection — no direct commits to master.
+
+```bash
+# Stage 1 — open the version bump PR
+./scripts/release.sh 0.1.2
+
+# review + merge the PR via gh or web UI
+gh pr merge <pr-number> --squash --delete-branch
+
+# Stage 2 — build, tag, release (from master, after the PR is merged)
+git checkout master && git pull
+./scripts/release.sh   # no args
+```
+
+Stage 1 creates `chore/release-X.Y.Z`, bumps `package.json`, opens the PR, exits. Stage 2 reads the version from `package.json`, builds the MCP bundle + dashboard, packs the tarball, tags, pushes the tag, and creates the GitHub release with auto-generated notes from commits since the last tag.
 
 <br/>