@niroai/niro 0.3.0 → 0.3.2

package/README.md

@@ -5,16 +5,34 @@ 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.
 
 > **Two ways to do everything:** every task below shows the **terminal** command *and* how you'd **ask the agent**. Pick whichever you prefer — they call the same code.
 
-> **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.
+## Working on branches
+
+Niro indexes your team's code from one branch (usually main). When you work on a feature
+branch, Niro notices and refuses to answer from the old code. Your assistant will offer the fix:
+
+```bash
+niro new-temp-project     # run once in the repo folder
+```
+
+This creates your own private copy of the project that follows your branch and your
+uncommitted edits, live (keep `niro watch` running). Teammates are not affected and cannot
+see your copy. Switching branches needs nothing: Niro answers from your copy on the feature
+branch and from the shared project on main. When your branch is merged:
+
+```bash
+niro discard-temp-project
+```
+
+If you forget, idle copies are cleaned up automatically after two weeks. Full guide:
+[docs/working-on-branches.md](https://unpkg.com/@niroai/niro/docs/working-on-branches.md)
+(plain-text file, ships inside the package too).
 
 ---
 
@@ -40,7 +58,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,86 @@
+# Working on branches with Niro
+
+Niro indexes your team's code from one branch, usually main.
+When you work on your own branch, your code is different from what Niro indexed.
+This page explains what happens then. Two minutes to read.
+
+## The short version
+
+There is one command to remember:
+
+    niro new-temp-project
+
+Run it in your repo folder when Niro asks for it. That is all.
+
+## What you will see
+
+You create a branch and start changing code.
+Then you ask your AI assistant something about the code.
+
+Niro notices your branch is not the one it indexed. Instead of giving you
+a wrong answer based on the old code, it replies with something like:
+
+    I cannot answer this safely. Your branch has diverged
+    from the branch Niro indexed.
+
+Your assistant will offer to fix this by running:
+
+    niro new-temp-project
+
+Say yes, or run it yourself in the repo folder. It takes a few seconds.
+
+## What the command does
+
+It creates your own private copy of the project inside Niro.
+
+- The copy follows your branch, including changes you have not committed.
+- Every save updates the copy, as long as "niro watch" is running.
+- Teammates are not affected. They keep using the shared project.
+- Nobody can see your copy. Not even teammates on your account.
+
+From then on, answers come from YOUR code.
+
+## Switching branches
+
+Nothing to do. Niro checks which branch you are on for every question.
+
+- On your feature branch: answers come from your private copy.
+- Back on main: answers come from the shared project.
+
+## When your work is merged
+
+Run this in the repo folder:
+
+    niro discard-temp-project
+
+It deletes your private copy. Your local files are never touched.
+If you forget, Niro deletes unused copies by itself after two weeks.
+
+## A feature that spans several repos
+
+Run "niro new-temp-project" in each repo folder you branch.
+All of them join the same private copy, so questions that cross repos
+(for example: what breaks in service B if I change service A?) see all
+of your changes together.
+
+## Common questions
+
+Can teammates see my unfinished code?
+No. Your copy is private to you.
+
+Does this work with my AI assistant and my git host?
+Yes. Any assistant that supports MCP (Claude Code, Cursor, Windsurf,
+Codex, and others) and any git server (GitHub, GitLab, Bitbucket,
+self-hosted).
+
+Is creating a copy slow?
+No. Niro copies the existing index instead of re-reading your code.
+It normally takes seconds.
+
+I just created a branch and have not changed anything. Will Niro nag me?
+No. Your code is still identical to what Niro indexed, so Niro answers
+normally. It only steps in once your code actually differs.
+
+What if I really want an answer from the shared project while on my branch?
+Tell your assistant so. The answer will be clearly labeled as describing
+the indexed branch, not your code.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@niroai/niro",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "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": {