npm - @niroai/niro - Versions diffs - 0.10.0 → 0.11.0 - Mend

@niroai/niro 0.10.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/CHANGELOG.md +117 -0
package/README.md +185 -249
package/docs/working-on-branches.md +55 -0
package/package.json +1 -1
package/src/commands/cleanup.js +689 -0
package/src/commands/info.js +51 -2
package/src/commands/release.js +13 -60
package/src/commands/takeover.js +52 -2
package/src/commands/watch.js +93 -25
package/src/index.js +23 -3
package/src/lib/folderSync.js +6 -0
package/src/lib/periodicClaim.js +100 -0
package/src/lib/printError.js +46 -0
package/src/lib/takeoverRestore.js +156 -0
package/src/mcp/setup.js +178 -13

package/README.md CHANGED Viewed

@@ -1,367 +1,303 @@
-# niro — MCP server + CLI (@niroai/niro)
+# niro: CLI + MCP server (`@niroai/niro`)
-The command-line tool **and** MCP server for [Niro](https://niroai.dev) — the AI code-intelligence platform.
+Command-line tool and MCP server for [Niro](https://niroai.dev). Niro reads your code and builds
+a map of how it fits together, so your AI assistant answers from that map instead of guessing.
-One package gives you three things:
+One package installs three things: the `niro` command, the MCP server your assistant talks to,
+and two agent skills so you can ask for Niro tasks in plain English.
-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](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.
+Requires Node.js 18 or newer. Niro is in private beta: you need an access code, which you get
+from the **Request Access** button at [www.niro.ai](https://www.niro.ai).
-> **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 branches
+---
-Your projects cover the repos and branches you chose to index. On every question, Niro routes
-to the project matching your repo and current branch. When you are on a branch **no project
-covers** (with real changes), Niro refuses to answer from stale code. Your assistant offers the fix:
+## Get started
 ```bash
-niro new-temp-project     # run once in the repo folder
+cd ~/code/my-service
+npx @niroai/niro start
 ```
-This creates your own private copy of the project that follows your branch and your
-uncommitted edits, live (keep `niro watch` running). Your original project is not changed.
-Switching branches needs nothing: Niro answers from your copy on the new
-branch, and from the matching indexed project on branches you already cover. When your branch
-is merged:
+Signs you in, installs itself, shows you what it is about to index and asks first, builds the
+graph, and connects your assistant. Run it again in any other repo; it skips what is done.
-```bash
-niro discard-temp-project
-```
+Then restart your assistant and ask it something:
-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).
+```
+"What breaks if I change PaymentService.refund?"
+```
 ---
-## Install
-```bash
-npm install -g @niroai/niro
-niro --version
-```
-Requires **Node.js 18+**. Background auto-sync of local folders uses [PM2](https://pm2.keymetrics.io/) — `niro init` offers to install it for you (or run `npm install -g pm2` yourself).
+## What you can ask for
-By default the CLI talks to Niro's cloud (`https://aiorchestrator.niroai.dev`) and the MCP server to `https://aiassistant.niroai.dev`. To point at your own instance, set `NIRO_API_URL`, and pass `--url <url>` to `niro mcp install` (or set `NIRO_MCP_SERVER_URL`).
+| | |
+|---|---|
+| Anything about your code | call chains, structure, entry points, API endpoints |
+| What breaks if you change something | blast radius across services, including callers a search cannot find |
+| A standing review | issues already in the code, by severity, in the browser |
+| Root causes from your alerts | connect Sentry, Slack, Jira, Linear or CloudWatch and an alert arrives as a bug with the analysis done |
 ---
-## 60-second setup
+## Everyday commands
 ```bash
-cd ~/code/my-service
-npx @niroai/niro start
+niro status
 ```
+Is my index up to date?
-That is the whole thing. `niro start` signs you in (browser), installs itself properly,
-shows you what it is about to index and asks before uploading anything, builds the graph,
-connects your AI assistant, and finally offers to measure what difference Niro makes
-(Scenario 12; optional, defaults to no). Run it again in any other repo; it skips whatever
-is already done.
+```bash
+niro start
+```
+Index another repo. Cross-service answers need more than one.
-Niro is in private beta, so `start` asks for an **access code** first (the browser signup form
-asks for it under that name). No code yet? Go to [www.niro.ai](https://www.niro.ai) and click
-**Request Access**. Answering "no" stops the setup immediately, having installed nothing.
+```bash
+niro info
+```
+What does Niro know about this folder: repo, branch, which project it maps to.
-Prefer the individual commands (or scripting it)? They all still work, and take flags:
+```bash
+niro projects
+```
+Every project in your account.
 ```bash
-niro login            # opens your browser to approve this device
-cd ~/code/my-service
-niro init             # onboard this folder: create project, upload, build the graph
-niro mcp install      # connect one AI assistant — pick it at the prompt, or pass --client
+niro build
 ```
+Rebuild the index by hand and watch it finish.
-`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.
+```bash
+niro doctor
+```
+Check this machine against the server and repair what is safe to repair. Today that is
+`niro doctor sync-registry`, which fixes folders and `.niro-project` files left pointing at projects
+that have gone or been renamed. The background watcher runs it for you every six hours.
 ---
-## Scenario 1 — Log in
+## Working on a branch
-`niro login` opens a browser, you approve the device, and a long-lived credential is stored at `~/.niro/credentials.json` (mode `0600`). Short-lived tokens refresh automatically.
+Your index covers the branches you chose to build. On a branch nothing covers, Niro says so
+rather than answering from stale code.
-**Terminal**
 ```bash
-niro login                              # browser device flow (default)
-niro whoami                             # who am I logged in as?
-niro logout                             # revoke + remove local credentials
+niro new-temp-project
 ```
+Run once in the repo folder. Makes a private copy that follows your branch and uncommitted
+edits. Your shared project is untouched.
-**Ask the agent**
-> "Am I logged in to Niro?" — the agent runs `niro whoami`. If you're not, it will **ask you to run `niro login` yourself** in your terminal (it can't drive a browser sign-in or handle your credentials).
----
-## Scenario 2 — Onboard a folder you're working in
-`niro init` does the whole thing end-to-end: detect the repo, **upload its source + config files**, create a Niro project, scan for environment variables, build the graph, and (optionally) keep it synced.
-**Terminal**
 ```bash
-cd ~/code/my-service
-niro init                       # onboard the current folder
-niro init ./api                 # onboard a specific path
-niro init --defaults            # accept discovered defaults, don't prompt
-niro init -X '**/test/**' -F '**/*.spec.ts'   # exclude modules / files
+niro discard-temp-project
 ```
+Run when the branch is merged. Forgotten copies are cleaned up after two weeks.
-During `init` you'll be asked, **per environment variable**, which value to use — and when a variable is defined in more than one config file you pick which file drives it (see Scenario 6).
+If a copy is deleted for you, or a project is renamed, your machine is not told and the folder keeps
+pointing at something that is gone. `niro doctor sync-registry` sorts that out, and the background
+watcher runs it every six hours — see [When a project is deleted](#when-a-project-is-deleted).
-**Ask the agent**
-> "Onboard this folder into Niro." The `niro-cli` skill checks auth, runs `niro info` to see if it's already indexed, then runs `niro init` for you and walks you through the env-var values in chat.
+Full guide: [docs/working-on-branches.md](https://unpkg.com/@niroai/niro/docs/working-on-branches.md)
-**Note for cloud:** Niro indexes your folder by **uploading its files** (it can't read your laptop's disk). Source and committed config files (`package.json`, `pom.xml`, `application.yml`, …) are uploaded; anything your repo `.gitignore`s (like a real `.env`) is **never** uploaded. One caveat: that filtering needs the folder to be a git repository. If you onboard a plain folder that is not a git repository, there is no `.gitignore` to honour and only the filename rules apply, so keep secrets out of it.
+---
-**What can be onboarded:** the folder has to look like a project — a build file (`package.json`, `pom.xml`, `go.mod`, `*.csproj`, …) at the folder itself or just below it. A monorepo root whose build files sit one or two levels down is fine. A folder with no build file is refused; pass `--force` if you really mean it. Your home folder, the filesystem root and system folders are refused outright, and `--force` does not override that — onboarding one of those would upload source from every project on the machine.
+## When a project is deleted
----
+Delete a project, or let an unused private copy expire, and your machine is not told. The folder
+carries on pointing at something that is no longer there.
-## Scenario 3 — "What does Niro know about this folder?"
+That is not just untidy. It is what makes `niro new-temp-project` in another folder say the slot is
+already taken, naming a copy that no longer exists. And a `.niro-project` file left naming a deleted
+project keeps answering, because it is read before your git remote.
-**Terminal**
-```bash
-niro info                # repo URL, branch, which project(s) map here, index status
-niro info --json         # machine-readable
-niro status              # live build status for the pinned project
-niro status my-service --json
-```
+The background watcher checks every six hours and sorts this out for you. `niro
+doctor sync-registry` does the same thing on demand.
-If a folder maps to **more than one** project, `info` lists them and (in the terminal) `build`/`edit`/`remove` ask you to pick one.
+What it does depends on what went missing:
-**Ask the agent**
-> "What does Niro know about this folder?" / "Is this repo indexed?" — the agent runs `niro info --json` and explains it.
+| What is gone | What happens to your folder |
+|---|---|
+| A private copy of a project | Goes back to the original project and carries on syncing |
+| The project itself | Left alone if the repo still exists; unregistered only when both are gone |
+| Neither, just a stale `.niro-project` | Repaired if your git remote says which project it should name; removed if it names nothing and is not shared; otherwise you are told |
----
+It never deletes anything on the server, and it never touches a `.niro-project` file. Everything it
+acts on has already gone. It only acts on what it can check, too: a folder git cannot read, or a
+project it could not reach, is left exactly as it is and reported. A bad connection can never cost
+you a working folder.
-## Scenario 4 — See all your projects
+**How it decides what to do with a stale `.niro-project`.** That file can hold a project's name
+rather than its id, so a renamed project looks exactly like a deleted one. Niro uses a second signal:
+your folder's git remote. If the remote points at exactly one project, the pin is rewritten to that
+project's id, which cannot be broken by a future rename. If the remote points at nothing either, the
+pin identifies nothing and is removed.
-**Terminal**
-```bash
-niro projects            # account-wide list (alias: `niro ls`)
-niro projects --json
-```
+**Unless the file is committed.** A `.niro-project` in git is shared with everyone who clones the
+repo, and what looks like a dead project to you may be a colleague's. Niro never changes a committed
+one for you. It tells you, and you decide.
-**Ask the agent**
-> "List my Niro projects." — runs `niro projects --json`.
+`niro info` also mentions it when you are standing in an affected folder, so you do not have to go
+looking.
----
+## When you run out of private copies
-## Scenario 5 — Rebuild the index after changes
+You get a limited number of private copies of each project. If you hit that limit, Niro tells you
+which branches are holding them, and the CLI adds where each one is checked out:
-**Terminal**
-```bash
-niro build               # full rebuild of the project pinned to this folder
-niro build my-service    # by alias or id
-niro build --no-full-rebuild   # incremental
-niro build --no-watch          # trigger and return immediately
 ```
+You already have 5 working copies of this project, which is the limit (5).
+They are for: feature/a, feature/b, feature/c, feature/d, feature/e.
-**Ask the agent**
-> "Rebuild the Niro index for this project." — runs `niro build`.
+    You have 5 working copies of this project on this machine:
+      feature/a    /home/you/work/service
+      feature/b    /home/you/work/service-wt2
+      ...
+```
-*(If you set up auto-sync in Scenario 8, you rarely need to rebuild by hand.)*
+Run `niro discard-temp-project` in one you have finished with, then try again. Copies nobody has
+touched for a while are also cleared automatically.
 ---
-## Scenario 6 — Manage environment variables (and pick which file drives each)
-Niro discovers env-var **names** from your code and their **default values** from committed config files. When the same variable appears in several files (e.g. `application.yml` vs `application-prod.yml`), you choose which file's value to use — the same as the web UI.
+## Measure what Niro changes
-**Terminal**
 ```bash
-niro edit --list-env                       # show vars, which file drives each, "appears in N files"
-niro edit --list-env --json                # machine-readable (secret values masked)
-niro edit --set-env PORT=9000              # set a value directly (never printed back)
-niro edit --set-env-from PORT=application-prod.yml   # adopt that file's value for PORT
-niro edit --rescan-env                     # re-scan after adding config files
+niro ab enable
 ```
+Runs Niro **off** for half your sessions for 14 days, so you can compare. Applies to your whole
+account, and asks before it starts.
-Secret values are always masked (`****`) — whether the variable *name* looks secret (`DB_PASSWORD`) **or** its *value* embeds credentials (`DATABASE_URL=postgres://user:pass@host`). You pick those by file name; the value is never shown.
-**Ask the agent**
-> "Set PORT from application-prod.yml" or "What env vars does this project have?" — the agent runs `niro edit --list-env --json`, shows you the choices, and applies your pick with `--set-env-from`. It chooses **by file name** and never handles raw secret values.
----
-## Scenario 7 — Rename a project, or add/remove a repo
-**Terminal**
 ```bash
-niro edit --alias new-name                 # rename the project
-niro edit --add-repo <gitId>               # map a registered repo into the project
-niro edit --remove-repo <gitId>            # unmap a repo (non-destructive)
-niro edit --project my-service --alias renamed   # target a project explicitly
+niro ab report
 ```
+The with-Niro and without-Niro comparison.
-**Ask the agent**
-> "Rename this Niro project to `payments-api`." / "Remove repo X from this project."
+```bash
+niro ab disable
+```
+Stop early. Every session uses Niro again.
 ---
-## Scenario 8 — Keep a local folder auto-synced
-`niro init` and `niro add repo` install a background daemon (via PM2) that re-uploads your changes and keeps the graph fresh — honoring `.gitignore` so secrets never leave your machine.
+## Connect another assistant
-**Terminal**
 ```bash
-niro service install     # install + start the niro-watch daemon (auto-starts on login)
-niro service status
-niro service uninstall
-niro watch               # run a watch in the foreground (debugging / no PM2)
+niro mcp install
 ```
+Pick from the list, or `--client <id>` to skip the prompt. Restart the assistant afterwards.
----
-## Scenario 9 — Remove a project or detach a repo
-**Terminal**
 ```bash
-niro remove --unmap-repo <gitId>                         # detach one repo (non-destructive)
-niro remove --project --confirm-name my-service          # delete the WHOLE project (guarded)
+niro mcp install --list
 ```
+All 14 supported clients and the file each one is configured through.
-`--project` is destructive, so it **requires** `--confirm-name` to exactly match the project's alias or id.
+```bash
+niro mcp uninstall --all -y
+```
+Removes everything install added: MCP config, hooks and skills. Leaves you logged in.
-**Ask the agent**
-> "Remove the Niro project `my-service`." — the agent confirms with you, then runs `niro remove --project --confirm-name my-service`.
+Per-client details: [docs/connect-your-ai-assistant.md](https://unpkg.com/@niroai/niro/docs/connect-your-ai-assistant.md)
 ---
-## Scenario 10 — Ask your AI assistant about your code
-After `niro mcp install` (and a restart of your assistant), the `niro-skill` routes code questions through Niro's graph instead of grep:
-> "What calls `chargeCard()`?"
-> "What breaks if I change the `Invoice` schema?"
-> "Where is the auth middleware wired up?"
-> "Is there existing code that parses webhooks before I write a new one?"
-This works in any folder that resolves to a Niro project (via its git remote or a `.niro-project` pin).
+## Managing projects
-**Where does the MCP point?**
-> "Which backend is my Niro MCP connected to?" — the `niro-cli` skill inspects your editor's MCP config and reports the URL + connection status.
----
-## Scenario 11 — Disconnect an AI assistant (uninstall the MCP)
+```bash
+niro edit --list-env
+```
+Environment variables Niro found, with secret values masked.
-`niro mcp uninstall` is the exact inverse of `niro mcp install`: it removes the MCP server registration and everything install added for that editor — the niro hooks in `~/.claude/settings.json`, the `## Niro MCP` section in `CLAUDE.md` / `AGENTS.md`, the generated `niro-skill` / `niro-cli` skills, and Cursor's allowlist entry + project rule. It only touches niro's own entries; your other hooks, MCP servers, and notes are left intact.
+```bash
+niro edit --set-env KEY=VALUE
+```
+Set one. The value is never printed or logged.
-**Terminal**
 ```bash
-niro mcp uninstall                      # interactive: pick client(s) (or "all")
-niro mcp uninstall --client claude-code # remove from one editor, no prompt
-niro mcp uninstall --client claude-code,codex  # remove from several in one go
-niro mcp uninstall --all -y             # remove from every editor, skip the confirm
+niro edit --alias new-name
 ```
+Rename a project.
-It does **not** sign you out — your `niro login` session in `~/.niro/credentials.json` is kept (run `niro logout` to clear it), and the `niro` command itself stays installed (remove it with `npm rm -g @niroai/niro`). The shared `~/.agents/skills` (used by both Codex and Windsurf) is only deleted once the last of those two editors is disconnected, so uninstalling one never breaks the other.
+```bash
+niro remove --unmap-repo <gitId>
+```
+Detach a repo from a project. Nothing is deleted.
-**Ask the agent**
-> "Disconnect Niro from Claude Code." / "Uninstall the Niro MCP from all my editors."
+```bash
+niro remove --project --confirm-name <name>
+```
+Delete a whole project. Destructive, hence the confirmation.
 ---
-## Scenario 12 — Measure what Niro actually changes
+## Keeping in sync
-Rather than take our word for it, you can have Niro run **itself off** for half your sessions
-and compare the two halves. While a window is open, each MCP session is put in an "on" or
-"off" bucket by a deterministic 50/50 split; the "off" half works without Niro. `niro ab
-report` then shows the two side by side.
-Two things to know before you start one:
+```bash
+niro service status
+```
+Is the background watcher running? It syncs your indexed folders as you edit.
-- It applies to your **whole account**, not just the repo you are standing in.
-- It runs for a fixed window, **14 days** by default, and you can stop it at any time.
+```bash
+niro service install
+```
+Start it and have it come back on login. Needs PM2 (`npm install -g pm2`).
-**Terminal**
 ```bash
-niro ab                      # is a window open, and until when?
-niro ab enable               # start a 14-day window (states the scope, asks first)
-niro ab enable --days 30 --name "Q3 trial"
-niro ab enable --yes         # skip the confirm (scripts / CI)
-niro ab report               # the with-Niro / without-Niro comparison
-niro ab report --json        # same, machine-readable
-niro ab disable              # stop early; every session uses Niro again
+niro watch
 ```
+Watch this folder in the foreground instead, for one session.
-The report compares session count, median session time, median tool calls per session, median
-Niro tool calls, and median context size. A figure the server has not recorded reads
-`not measured` rather than `0`, because `0` is a real result here: an off-bucket session
-genuinely makes zero Niro tool calls.
+---
-`niro start` offers this once, at the end of your first setup, and defaults to no.
+## Reference
-**Ask the agent**
-> "Is Niro A/B measurement on?" / "Show me the A/B comparison." — the agent runs `niro ab`.
+Add `--help` to any command for its flags. Add `--json` to `whoami`, `info`, `status`,
+`projects`, `build`, `ab report`, `edit --list-env` and `doctor sync-registry` for machine-readable
+output.
----
+| File | What it holds |
+|---|---|
+| `~/.niro/credentials.json` | Your login, mode `0600` |
+| `~/.niro/config.json` | Backend URLs saved during setup |
+| `~/.niro/projects.json` | Per-folder sync state |
+| `.niro-project` | Pins a repo folder to a Niro project |
-## Command reference
+| Variable | What it sets | Default |
+|---|---|---|
+| `NIRO_API_URL` | Backend the CLI talks to | `https://aiorchestrator.niroai.dev` |
+| `NIRO_MCP_SERVER_URL` | Backend the MCP server talks to | `https://aiassistant.niroai.dev` |
+| `NIRO_API_KEY` | Read by the MCP server when running headless. For CI, prefer `niro login --api-key` | none |
+| `NIRO_UPLOAD_CONCURRENCY` / `_TIMEOUT_MS` / `_MAX_TOTAL_BYTES` / `_MAX_FILES` | Tune the first upload | 4 / 60000 / 1 GiB / 50000 |
-| Command | What it does |
-|---|---|
-| `niro start [path]` | First-time setup end to end: sign in, onboard this folder, connect an assistant |
-| `niro login` / `logout` / `whoami` | Authenticate / sign out / show current account |
-| `niro init [path]` | Onboard a folder end-to-end (upload, project, env scan, build, watch) |
-| `niro info [path]` | What Niro knows about this folder (repo, branch, project(s), status) |
-| `niro projects` (`niro ls`) | List all projects in your account |
-| `niro status [project]` | Live build status for a project |
-| `niro build [project]` | Trigger a rebuild and stream progress |
-| `niro edit …` | Rename, map/unmap repos, manage env vars (incl. `--set-env-from`) |
-| `niro remove …` | Delete a project (`--project`, guarded) or detach a repo (`--unmap-repo`) |
-| `niro add repo [path\|url]` | Register a local folder or remote git URL |
-| `niro add project` | Create a project from registered repos |
-| `niro watch [path]` / `niro service …` | Foreground watch / manage the auto-sync daemon |
-| `niro mcp install` | Connect an AI assistant + install the agent skills (one per run; `--client <id>` to skip the prompt, `--url <url>` for your own backend) |
-| `niro mcp uninstall` | Disconnect an AI assistant — reverses `mcp install` (`--client <id>` / `--all`, `-y` to skip confirm) |
-| `niro ab status\|enable\|disable\|report` | Run Niro off for half your sessions for a fixed window, then compare (`--days`, `--name`, `--yes`, `--json`) |
-| `niro delete [project]` | Older whole-project delete (prefer `niro remove --project`) |
-Add `--json` to `whoami`, `info`, `status`, `projects`, `build`, `ab report`, and `edit --list-env` for machine-readable output. Add `--help` to any command for its full flags.
+Running your own instance? Set `NIRO_API_URL` before `niro login`, and pass `--url <url>` to
+`niro mcp install`.
 ---
-## Config & local state
+## What leaves your machine
-| Location | Purpose |
-|---|---|
-| `~/.niro/credentials.json` | Auth credential + token (mode `0600`) |
-| `~/.niro/config.json` | `apiUrl` / `mcpServerUrl` saved during setup |
-| `~/.niro/projects.json` | Per-folder sync state (gitId, patterns, file hashes) |
-| `.niro-project` (in a repo) | Pins that folder to a Niro project (single line: project id or alias) |
+Source and config files from the folder you confirmed, and nothing else. `.gitignore` is
+honoured, so a gitignored `.env` is never sent. Raw `.env` and `*.properties` files are not in
+the upload set; committed files like `application.yml` and `.env.example` are, because they hold
+defaults rather than secrets.
-| Environment variable | Purpose | Default |
-|---|---|---|
-| `NIRO_API_URL` | CLI → ai-orchestrator base URL | `https://aiorchestrator.niroai.dev` |
-| `NIRO_MCP_SERVER_URL` | MCP server (ai-assistant) base URL | `https://aiassistant.niroai.dev` |
-| `NIRO_API_KEY` | Read by the **MCP server** (e.g. headless `niro mcp serve`) — not a CLI-command auth path; for CI use `niro login --api-key` | — |
-| `NIRO_UPLOAD_CONCURRENCY` / `NIRO_UPLOAD_TIMEOUT_MS` / `NIRO_UPLOAD_MAX_TOTAL_BYTES` / `NIRO_UPLOAD_MAX_FILES` | Tune the initial upload | 4 / 60000 / 1 GiB / 50000 |
+Secret values are never printed: `--set-env` does not echo them, and `--list-env` masks anything
+that looks like a secret by name or by content.
 ---
-## Security notes
+## If something is wrong
-- **Secrets stay on your machine.** Uploads honor `.gitignore` (and `.git/info/exclude` / global excludes), so a gitignored `.env` is never sent. Raw `.env`/`*.properties` files aren't in the upload set; committed config files (`application.yml`, `.env.example`, …) are, because they hold *behavioral* defaults, not secrets.
-- **Secret values are never printed.** `--set-env` / `--set-env-from` never echo a value, and `--list-env` masks any value that looks like a secret — by key name *or* by content (connection strings, keys).
-- **The agent never handles raw secret values.** It picks env sources *by file name*; you type any real secret yourself.
+**The assistant ignores Niro.** Restart it. Skills load at startup, so a fresh `niro mcp install`
+does nothing until you do.
----
+**`niro: command not found`.** Your global npm bin is not on `PATH`. Check with `npm bin -g`.
-## Troubleshooting
+**This folder maps to several projects.** Pass `--project <alias|id>`, or pick one when asked.
-- **The agent doesn't run Niro commands** — restart your AI assistant after `niro mcp install` (skills load at startup). Re-running `niro mcp install` refreshes the skills if they've been updated.
-- **`niro` not found** — ensure your global npm bin is on `PATH` (`npm bin -g`).
-- **A folder maps to multiple projects** — pass `--project <alias|id>` (or pick one when prompted).
-- **Auto-sync isn't running** — install PM2 (`npm install -g pm2`) then `niro service install`.
+**Auto-sync is not running.** `npm install -g pm2`, then `niro service install`.
----
+**A folder was refused.** Niro will not index your home folder, or a folder with no build file
+in it. Point it at the repo you meant.
-## License
+---
 MIT

package/docs/working-on-branches.md CHANGED Viewed

@@ -63,6 +63,61 @@ Run this in the repo folder:
 It deletes your private copy. Your local files are never touched.
 If you forget, Niro deletes unused copies by itself after two weeks.
+## Tidying up copies that were deleted for you
+When a copy goes after two weeks, or somebody deletes it in the web app,
+your machine is not told. The folder is left pointing at a copy that is
+no longer there. Nothing breaks, but "niro new-temp-project" in another
+worktree of the same repo will say the slot is already taken.
+Run this from anywhere to sort it out:
+    niro doctor sync-registry
+You will rarely need to type it. The background watcher runs the same
+check every six hours by itself.
+It sorts out three things, and treats them differently:
+- A folder pointing at a private copy that has gone goes back to the
+  original project, and carries on syncing.
+- A folder pointing at a project that has gone is only unregistered when
+  the repo has gone too. A project can be deleted while its repos are
+  moved somewhere else, and that folder is still syncing perfectly well.
+- A ".niro-project" file naming something the server does not know is
+  repaired where possible. That file can hold a project's NAME rather
+  than its id, so a renamed project looks exactly like a deleted one.
+  Niro checks your folder's git remote instead: if that points at one
+  project, the file is rewritten to that project's id, which a future
+  rename cannot break. If the remote points at nothing either, the file
+  names nothing and is removed.
+  Not if the file is committed to git, though. Then it is shared with
+  everyone who clones the repo, and a project that means nothing to you
+  may be a colleague's. Niro tells you and leaves the choice to you.
+  "niro info" mentions it too, when you are standing in that folder.
+Copies that are still there are left alone, and so is anything it could
+not check, so a dropped connection never costs you a working folder. Add
+"--dry-run" to see the list without changing anything.
+## When you run out of private copies
+You get a limited number of private copies of each project. When you hit
+the limit, Niro says which branches are holding them, and the CLI adds
+where each one is checked out on this machine:
+    You already have 5 working copies of this project, which is
+    the limit (5). They are for: feature/a, feature/b, ...
+        You have 5 working copies of this project on this machine:
+          feature/a    /home/you/work/service
+          feature/b    /home/you/work/service-wt2
+Run "niro discard-temp-project" in one you have finished with, then try
+again. Copies nobody has touched for a while are cleared automatically,
+so this usually sorts itself out.
 ## A feature that spans several repos
 Run "niro new-temp-project" in each repo folder you branch.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@niroai/niro",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Niro — one package: the niro CLI plus the Niro MCP server (code intelligence for AI coding assistants).",
   "keywords": [
     "niro",