@niroai/niro 0.3.0 → 0.3.1

package/README.md

@@ -5,7 +5,7 @@ The command-line tool **and** MCP server for [Niro](https://niroai.dev) — the
 One package gives you three things:
 
 1. **`niro` CLI** — onboard repos, build the code graph, and manage projects from the terminal.
-2. **A Niro MCP server** — lets an AI assistant answer questions about *your* codebase using Niro's graph. 14 clients supported (Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, GitHub Copilot CLI, Factory, Goose, OpenCode, Cline, Kiro, Antigravity, Claude Desktop) — see **[docs/connect-your-ai-assistant.md](docs/connect-your-ai-assistant.md)** for the exact command per client.
+2. **A Niro MCP server** — lets an AI assistant answer questions about *your* codebase using Niro's graph. 14 clients supported (Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, GitHub Copilot CLI, Factory, Goose, OpenCode, Cline, Kiro, Antigravity, Claude Desktop) — see **[docs/connect-your-ai-assistant.md](https://unpkg.com/@niroai/niro/docs/connect-your-ai-assistant.md)** for the exact command per client.
 3. **Two agent skills** (installed by `niro mcp install`) so you can drive Niro from chat in plain English instead of typing CLI commands:
    - **`niro-skill`** — answers questions about your code (structure, call chains, blast radius) using the Niro MCP tools.
    - **`niro-cli`** — runs the CLI for you (onboard, status, rebuild, edit env vars, remove) from a conversation.
@@ -14,7 +14,7 @@ One package gives you three things:
 
 > **Working on a feature branch?** Niro indexes one branch per repo, but it follows *your* branch
 > and uncommitted edits through **temporary projects** — see
-> **[docs/working-on-branches.md](docs/working-on-branches.md)** for how that works in plain words.
+> **[docs/working-on-branches.md](https://unpkg.com/@niroai/niro/docs/working-on-branches.md)** for how that works in plain words.
 
 ---
 
@@ -40,7 +40,7 @@ niro init             # onboard this folder: create project, upload, build the g
 niro mcp install      # connect one AI assistant — pick it at the prompt, or pass --client
 ```
 
-`niro mcp install` configures **one** assistant per run — pick it at the prompt, or pass `--client <id>`. 14 clients supported; see **[docs/connect-your-ai-assistant.md](docs/connect-your-ai-assistant.md)** for the full list and the exact command for each. Run it once for each assistant you use. The MCP server URL is picked automatically (own instance? pass `--url <url>`). Restart your AI assistant once after, and you're done — ask it about your code, or ask it to run Niro tasks for you.
+`niro mcp install` configures **one** assistant per run — pick it at the prompt, or pass `--client <id>`. 14 clients supported; see **[docs/connect-your-ai-assistant.md](https://unpkg.com/@niroai/niro/docs/connect-your-ai-assistant.md)** for the full list and the exact command for each. Run it once for each assistant you use. The MCP server URL is picked automatically (own instance? pass `--url <url>`). Restart your AI assistant once after, and you're done — ask it about your code, or ask it to run Niro tasks for you.
 
 ---
 

package/docs/connect-your-ai-assistant.md

@@ -0,0 +1,202 @@
+# Connect your AI assistant to Niro
+
+`niro mcp install` configures one AI client at a time to use Niro's MCP server. This page
+lists every supported client, the exact command for each, and what it does. If you'd rather
+drive setup from chat instead of a terminal, see [Scenario 2](../README.md#scenario-2--onboard-a-folder-youre-working-in)
+in the main README — the `niro-cli` skill can run these commands for you.
+
+## Before you start
+
+```bash
+npm install -g @niroai/niro
+niro login              # browser device flow — no API key to copy
+```
+
+After `niro login`, none of the commands below need an API key — the MCP server authenticates
+with your device token. If you'd rather use an API key instead (e.g. a headless CI box), get
+one from **console.niroai.dev > Settings > Account**; the wizard will ask for it when no
+`niro login` session is found.
+
+**Pointing at a different backend?** Every command below defaults to Niro's cloud
+(`https://aiassistant.niroai.dev`). Add `--url <your-backend-url>` to any `niro mcp install`
+command to use a self-hosted or dedicated instance instead (or set `NIRO_MCP_SERVER_URL`).
+
+## All Niro tools are read-only
+
+Every tool Niro exposes over MCP only *reads* your code graph — none can modify your code,
+your projects, or anything else. That's why several of the installers below turn on
+auto-approve for Niro's tools: there's nothing for a read-only tool call to break.
+
+---
+
+## Claude Code
+
+```bash
+niro mcp install --client claude-code
+```
+
+Registers the server (`claude mcp add --scope user`), adds a `PostCompact` + `UserPromptSubmit`
+hook so Claude stays aware of Niro after context compaction, appends a short reminder to
+`~/.claude/CLAUDE.md`, and installs the **`niro-skill`** (routes code questions through the
+graph) and **`niro-cli`** skill (drives the CLI from chat) to `~/.claude/skills/`.
+
+Verify: type `/mcp` inside Claude Code — `niro` should be listed as connected.
+
+## Codex
+
+```bash
+niro mcp install --client codex
+```
+
+Registers the server in `~/.codex/config.toml`, sets `default_tools_approval_mode = "auto"`
+(safe — every niro tool is read-only), appends a reminder to `~/.codex/AGENTS.md`, and installs
+the shared `niro-skill` + `niro-cli` skill to `~/.agents/skills/` (also read by Windsurf).
+
+Verify: `/mcp` inside the Codex TUI.
+
+## Cursor
+
+```bash
+niro mcp install --client cursor
+```
+
+Writes `~/.cursor/mcp.json`, adds `"niro:*"` to `~/.cursor/permissions.json`'s `mcpAllowlist`
+(so Agent doesn't ask before every tool call), and writes a project rule to
+`.cursor/rules/niro.mdc` in the current repo.
+
+Requires Cursor's Agent **Auto-run** mode enabled (Settings) for the allowlist to take effect —
+"Ask every time" ignores it.
+
+## VS Code (GitHub Copilot)
+
+```bash
+niro mcp install --client vscode
+```
+
+Writes the user-profile `mcp.json` (`servers.niro`) — the same file VS Code's
+**MCP: Open User Configuration** command opens.
+
+Verify: run **MCP: List Servers** from the Command Palette, or check the Chat view's tools icon.
+First use of a new server needs a one-time trust confirmation.
+
+## Windsurf
+
+```bash
+niro mcp install --client windsurf
+```
+
+Writes `~/.codeium/windsurf/mcp_config.json`, appends a reminder to
+`~/.codeium/windsurf/memories/global_rules.md`, and installs the shared `niro-skill` +
+`niro-cli` skill to `~/.agents/skills/` (also read by Codex).
+
+## Claude Desktop
+
+```bash
+niro mcp install --client claude-desktop
+```
+
+Writes `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows:
+`%APPDATA%\Claude\`, Linux: `~/.config/claude/`). Restart Claude Desktop after.
+
+## Gemini CLI
+
+```bash
+niro mcp install --client gemini-cli
+```
+
+Runs `gemini mcp add -s user` to register the server (`~/.gemini/settings.json`) and appends a
+reminder to `~/.gemini/GEMINI.md`.
+
+Verify / reload: run `/mcp reload` inside Gemini CLI.
+
+## GitHub Copilot CLI
+
+```bash
+niro mcp install --client copilot-cli
+```
+
+Runs `copilot mcp add` (writes `~/.copilot/mcp-config.json`) and appends a reminder to
+`~/.copilot/copilot-instructions.md`.
+
+Verify: run `/mcp` inside the Copilot CLI — servers are available immediately, no restart needed.
+
+## Factory (droid)
+
+```bash
+niro mcp install --client factory
+```
+
+Runs `droid mcp add` (writes `~/.factory/mcp.json`) and appends a reminder to
+`~/.factory/AGENTS.md`. droid reloads automatically when the config file changes.
+
+## Goose
+
+```bash
+niro mcp install --client goose
+```
+
+Writes an `extensions.niro` entry into `~/.config/goose/config.yaml` (Windows:
+`%APPDATA%\Block\goose\config\config.yaml`). Restart Goose (or start a new session) after.
+
+If your `config.yaml` already has an unusual `extensions:` layout, the installer prints the
+YAML block to paste in by hand instead of guessing at a risky merge.
+
+## OpenCode
+
+```bash
+niro mcp install --client opencode
+```
+
+Writes `~/.config/opencode/opencode.json` (`mcp.niro`) and appends a reminder to
+`~/.config/opencode/AGENTS.md`. Restart OpenCode after.
+
+## Cline
+
+```bash
+niro mcp install --client cline
+```
+
+Writes Cline's `cline_mcp_settings.json` (under VS Code's `globalStorage` for Cline's
+publisher id) and adds a global rule file to Cline's Rules directory.
+
+## Kiro
+
+```bash
+niro mcp install --client kiro
+```
+
+Writes `~/.kiro/settings/mcp.json` with `autoApprove: ["*"]` (safe — niro's tools are
+read-only) and adds a global steering file at `~/.kiro/steering/niro.md`. Kiro reconnects MCP
+servers automatically when you save the config.
+
+## Antigravity
+
+```bash
+niro mcp install --client antigravity
+```
+
+Writes `~/.gemini/config/mcp_config.json`. Reload via **Agent Settings → Customizations →
+Installed MCP Servers → Refresh** (or `/mcp` in the Antigravity CLI).
+
+---
+
+## Test it
+
+After connecting any client, restart it (where noted above) and ask:
+
+> "What calls `chargeCard()`? Use Niro tools."
+> "What breaks if I change the `Invoice` schema?"
+> "Is there existing code that parses webhooks, before I write a new one?"
+
+If the assistant answers from the graph instead of grepping files, you're connected.
+
+## Disconnect
+
+```bash
+niro mcp uninstall --client <id>     # one client
+niro mcp uninstall --all -y          # every client, no confirm
+```
+
+`mcp uninstall` is the exact inverse of `mcp install` for each client — it only removes what
+install added, leaving your own config, rules, and other MCP servers untouched. See the main
+[README](../README.md#scenario-11--disconnect-an-ai-assistant-uninstall-the-mcp) for details.

package/docs/working-on-branches.md

@@ -0,0 +1,135 @@
+# Working on branches — how Niro keeps up with you
+
+Niro indexes your team's code once, on one branch per repository — usually `main`. That shared
+index is what everyone's AI assistant queries. But you don't work on `main`. You work on feature
+branches, with uncommitted edits, sometimes across several repositories at once.
+
+This page explains, in plain words, what Niro does about that.
+
+Everything here works the same whichever AI assistant you use (Claude Code, Cursor, Windsurf,
+Codex, or anything else that speaks MCP) and wherever your git repositories live (GitHub, GitLab,
+Bitbucket, or a self-hosted git server). Niro only needs two things: your repository's git URL and
+the branch you're on.
+
+---
+
+## The one-sentence version
+
+> When you're on a branch Niro hasn't indexed, Niro **refuses to guess**. It asks you to create a
+> **temporary project** — a private copy that follows your branch and your edits live — and from
+> then on, answers come from *your* code, not the team's.
+
+---
+
+## What happens on each branch state
+
+Niro checks your repository's URL, current branch, latest commit, and whether you have uncommitted
+edits — on every question your assistant asks. Then it picks one of four answers:
+
+| Your local state | What Niro does |
+|---|---|
+| On the indexed branch (e.g. `main`), no edits | Answers from the shared team index. Business as usual. |
+| Just created a new branch, no changes yet | Still answers from the team index — your code is *identical* to what's indexed, so the answers are provably correct. No friction for a fresh branch. |
+| On a branch with real changes, **with** a temporary project | Answers from **your temporary project** — your branch, your uncommitted edits, live. |
+| On a branch with real changes, **no** temporary project | **Refuses to answer** and tells your assistant what to do about it (see below). |
+
+The last row is the important one. An answer computed from `main` while you're deep in a feature
+branch *looks* right and is quietly wrong — wrong line numbers, missing methods, dead code that
+you already deleted. Niro treats that as worse than no answer.
+
+## What a refusal looks like
+
+When Niro refuses, your assistant receives a structured message with three options:
+
+1. **Create a temporary project** *(recommended)* — run `niro new-temp-project` in the repo's
+   folder. One command; takes seconds.
+2. **Answer from the team index anyway** — only if *you* explicitly say so. The answer will carry
+   a visible label saying it describes the indexed branch, not your code.
+3. **Skip Niro for this question** — the assistant falls back to reading files directly.
+
+Most assistants will simply ask you which way to go, or run the recommended command themselves if
+you've allowed that.
+
+## Temporary projects in 60 seconds
+
+A **temporary project** is your private copy of the team's Niro project:
+
+- **Private.** Teammates keep seeing the shared project. Nobody sees your copy — not even
+  teammates on the same account. Your half-finished code stays yours.
+- **Live.** Your working tree — including uncommitted edits — is uploaded once, and every save
+  after that streams in automatically (while `niro watch` is running). Ask a question seconds
+  after saving; the answer reflects the save.
+- **Cheap.** Creating one copies the already-computed index. No re-parsing of the whole project,
+  no waiting for a full rebuild.
+- **Branch-aware, automatically.** Once your temporary project exists, you never point anything at
+  it. Niro routes each question by the branch you're on: feature branch → your copy; switch back
+  to `main` → the team index. Switch back and forth all day; it just follows.
+
+### Working across several repositories
+
+Features often span more than one repository — a backend change plus a client change, say. Run
+`niro new-temp-project` in each repo's folder as you branch it. All of them join **one**
+temporary project, so cross-repository answers ("what breaks in service B if I change this in
+service A?") reflect *all* of your local work at once. Each repo can even be on a different
+branch — Niro mirrors whatever your working folders actually look like.
+
+Repos you *haven't* branched come along as read-only snapshots, so the full picture stays intact.
+
+### When you're done
+
+Merge your branch as usual, switch back to the indexed branch, and Niro will nudge your assistant:
+the temporary project has served its purpose — discard it with `niro discard-temp-project`. The
+shared index picks up your merged commits through its normal syncing; nothing else to do.
+
+Two safety nets:
+
+- **Discard won't ambush your other work.** If the temporary project still covers another repo
+  that's mid-feature, both Niro and the CLI warn before deleting it and ask you to confirm.
+- **Forgot to discard?** Idle temporary projects (no edits for N days — 14 by default, and your
+  admin can change it per account or per project) are cleaned up automatically. Only the copy is
+  deleted; your local code is never touched, and a fresh copy is one command away.
+
+## The `.niro-project` file
+
+Some repos carry a small `.niro-project` file at their root. It holds one line: the name of the
+Niro project this folder belongs to. It's useful when one repository is part of several Niro
+projects, or when you start your assistant from a parent folder that isn't itself a repository.
+
+Two things worth knowing:
+
+- **Niro never rewrites it.** It always names the shared team project, so it's safe to commit and
+  share with the team. Temporary projects don't touch it — routing to your copy happens on the
+  server, per question, from your branch.
+- **You don't need it** for the common case: a repo whose URL maps to exactly one Niro project
+  resolves by itself.
+
+## Quick reference
+
+```bash
+niro new-temp-project        # run in a repo folder: make Niro follow this branch + edits
+niro watch                   # keep running: streams every save into your temporary project
+niro discard-temp-project    # after merging: delete the copy; routing falls back by itself
+niro discard-temp-project --project <id>   # discard from another machine / lost local state
+```
+
+And the tool your assistant uses on its own:
+
+- `should_create_temp_project` — a read-only check the assistant calls when it notices you're on a
+  new branch: "does this repo, on this branch, need a temporary project?" You'll rarely call it
+  yourself, but it's why a good assistant offers to run `niro new-temp-project` right when you
+  branch, without you asking.
+
+## Requirements and honest limits
+
+- **Git is required** for branch detection. Folders that aren't git repositories can still be
+  indexed and queried (uploaded as plain folders), but there are no branches to follow — the
+  branch logic on this page doesn't apply to them.
+- **Any git host works.** Matching uses the repository URL and branch name only — nothing
+  GitHub-specific. HTTPS and SSH remotes both work.
+- **Your backend must support routing.** If the server is older than this feature, the CLI warns
+  you loudly at `new-temp-project` time instead of letting answers silently come from the wrong
+  place.
+- **Detached HEAD** (bisecting, checking out a tag): there's no branch to follow, so Niro answers
+  from the team index with an advisory note rather than refusing.
+- **A brand-new repo** created mid-feature (not yet in any Niro project) can't join a temporary
+  project yet — Niro will say so honestly instead of pretending to know it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@niroai/niro",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Niro — one package: the niro CLI plus the Niro MCP server (code intelligence for AI coding assistants).",
   "keywords": [
     "niro",
@@ -26,6 +26,7 @@
   "files": [
     "bin",
     "src",
+    "docs/*.md",
     "README.md"
   ],
   "engines": {