@tpsdev-ai/flair 0.15.0 → 0.16.0

package/README.md

@@ -178,31 +178,82 @@ Pluggable import/export to foreign memory systems. Every agent-memory format (ag
 ## Quick Start
 
 ### Prerequisites
-- [Node.js 22+](https://nodejs.org/)
+
+**1. Node.js 22+.** On a fresh box, install a current Node — the version in some distro repos is too old.
+
+```bash
+# Linux (Debian/Ubuntu) — NodeSource:
+curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs
+
+# macOS / Linux — nvm (no root, recommended):
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
+# restart your shell, then:
+nvm install 22
+
+# Verify:
+node --version   # → v22.x or newer
+```
+
+**2. A user-writable npm global prefix (avoid `sudo`).** Installing globally with `sudo` makes the package root-owned. Flair's in-process embeddings component downloads/symlinks a model file under the package at runtime; when Harper later runs as **you** (not root) it gets `EACCES` and **semantic search silently degrades to keyword-only**. Point npm's global prefix at your home dir instead:
+
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+# add to your shell rc (~/.bashrc, ~/.zshrc) so it persists:
+export PATH="$HOME/.npm-global/bin:$PATH"
+```
+
+> ⚠️ **Do not `sudo npm install -g @tpsdev-ai/flair`.** A root-owned install breaks the embeddings component (the package dir isn't writable by the user Harper runs as), and you'll get the loud `Semantic search DEGRADED` warning from `flair init` / `flair doctor`. Use the user-writable prefix above instead. `nvm` installs already give you a user-owned prefix, so no `sudo` is needed there.
 
 ### Install & Run
 
+`flair init` is the front door. The mental model is git's: install the CLI globally, then `init`. One command does everything: installs and starts Harper, creates your agent's Ed25519 identity, verifies semantic search actually works, detects and wires your MCP clients (Claude Code / Cursor / Codex / Gemini) to the zero-install `npx -y @tpsdev-ai/flair-mcp` server, and runs a smoke test.
+
 ```bash
-# Install
+# Install the CLI (no sudo — see prereqs above)
 npm install -g @tpsdev-ai/flair
 
-# Bootstrap a Flair instance (installs Harper, creates database, starts service)
+# One command: instance + agent + semantic-search check + MCP wiring + smoke test
 flair init
+```
 
-# Register your first agent
-flair agent add mybot --name "My Bot" --role assistant
+That's it. Your agent now has identity and memory, and any detected MCP client is wired up. Restart your MCP client (e.g. Claude Code) to pick up the new config, then ask the agent "what do you remember about me?"
 
-# Check everything is working
-flair status
+Useful flags:
+
+```bash
+flair init --agent mybot           # name the agent (--agent-id also works)
+flair init --client claude-code    # wire one specific client (claude-code, codex, gemini, cursor, all, none)
+flair init --no-mcp                # instance + agent only, skip MCP wiring
+flair init --skip-smoke            # skip the MCP smoke test
+```
 
-# Lifecycle management
+Lifecycle management:
+
+```bash
+flair status        # Check everything is working
 flair stop          # Stop the Flair instance
 flair restart       # Restart the Flair instance
 flair uninstall     # Remove the service (keeps data)
 flair uninstall --purge  # Remove everything including data and keys
 ```
 
-That's it. Your agent now has identity and memory.
+### Advanced / manual setup
+
+Prefer to drive each step yourself, or scripting an unattended setup? Run `flair init --no-mcp` to bootstrap the instance + agent without wiring any MCP clients, then drive each step on its own:
+
+```bash
+# Bootstrap a Flair instance without registering an agent or wiring MCP
+flair init --no-mcp
+
+# Register your first agent (generates an Ed25519 keypair, registers it)
+flair agent add mybot --name "My Bot"
+
+# Check everything is working
+flair status
+```
+
+`flair init --agent mybot --no-mcp` bootstraps the instance and registers an agent in one step without touching any MCP client config. To wire clients later, re-run `flair init --agent mybot --client <name>`, or wire them manually using the snippets in **[docs/mcp-clients.md](docs/mcp-clients.md)** — all of them use the `npx -y @tpsdev-ai/flair-mcp` zero-install form.
 
 ## Integration
 
@@ -331,6 +382,12 @@ curl -H "Authorization: TPS-Ed25519 mybot:$TS:$NONCE:$SIG" \
 
 Auth is Ed25519 — sign `agentId:timestamp:nonce:METHOD:/path` with your private key. See [SECURITY.md](SECURITY.md) for the full protocol.
 
+### Auth across surfaces
+
+The default, secure path everywhere is **Ed25519 per-agent**: each agent holds its own key (`~/.flair/keys/<agent>.key`), signs every request, and the server refuses cross-agent reads. The CLI, the `flair-mcp` server, and the OpenClaw / pi / Hermes plugins all use it.
+
+One exception: the **`n8n-nodes-flair`** community node authenticates with the Harper **admin password** (Basic auth), which grants **whole-instance read/write** access — not per-agent isolation. That's acceptable only on a single-tenant, operator-controlled n8n with trusted workflow inputs; otherwise prefer the CLI/SDK Ed25519 path. Full breakdown in **[docs/auth.md](docs/auth.md#auth-across-surfaces-read-this-first)**.
+
 ## Architecture
 
 ```