@niroai/niro 0.3.1 → 0.3.2

package/README.md

@@ -12,9 +12,27 @@ One package gives you three things:
 
 > **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](https://unpkg.com/@niroai/niro/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).
 
 ---
 

package/docs/working-on-branches.md

@@ -1,135 +1,86 @@
-# Working on branches — how Niro keeps up with you
+# Working on branches with Niro
 
-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.
+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.
 
-This page explains, in plain words, what Niro does about that.
+## The short version
 
-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.
+There is one command to remember:
 
----
+    niro new-temp-project
 
-## The one-sentence version
+Run it in your repo folder when Niro asks for it. That is all.
 
-> 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 you will see
 
----
+You create a branch and start changing code.
+Then you ask your AI assistant something about the code.
 
-## What happens on each branch state
+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:
 
-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:
+    I cannot answer this safely. Your branch has diverged
+    from the branch Niro indexed.
 
-| 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). |
+Your assistant will offer to fix this by running:
 
-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.
+    niro new-temp-project
 
-## What a refusal looks like
+Say yes, or run it yourself in the repo folder. It takes a few seconds.
 
-When Niro refuses, your assistant receives a structured message with three options:
+## What the command does
 
-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.
+It creates your own private copy of the project inside Niro.
 
-Most assistants will simply ask you which way to go, or run the recommended command themselves if
-you've allowed that.
+- 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.
 
-## Temporary projects in 60 seconds
+From then on, answers come from YOUR code.
 
-A **temporary project** is your private copy of the team's Niro project:
+## Switching branches
 
-- **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.
+Nothing to do. Niro checks which branch you are on for every question.
 
-### Working across several repositories
+- On your feature branch: answers come from your private copy.
+- Back on main: answers come from the shared project.
 
-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.
+## When your work is merged
 
-Repos you *haven't* branched come along as read-only snapshots, so the full picture stays intact.
+Run this in the repo folder:
 
-### When you're done
+    niro discard-temp-project
 
-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.
+It deletes your private copy. Your local files are never touched.
+If you forget, Niro deletes unused copies by itself after two weeks.
 
-Two safety nets:
+## A feature that spans several repos
 
-- **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.
+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.
 
-## The `.niro-project` file
+## Common questions
 
-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.
+Can teammates see my unfinished code?
+No. Your copy is private to you.
 
-Two things worth knowing:
+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).
 
-- **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.
+Is creating a copy slow?
+No. Niro copies the existing index instead of re-reading your code.
+It normally takes seconds.
 
-## Quick reference
+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.
 
-```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.
+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.1",
+  "version": "0.3.2",
   "description": "Niro — one package: the niro CLI plus the Niro MCP server (code intelligence for AI coding assistants).",
   "keywords": [
     "niro",