@tpsdev-ai/flair 0.31.1 → 0.33.0

package/docs/standalone-local.md

@@ -0,0 +1,243 @@
+# Standalone Local Deployment
+
+`flair init` installs and runs its own Harper process. This is the default path and what most operators use: a single process on a single machine, no Fabric, no external services.
+
+If you're starting from zero, begin with the [quickstart](quickstart.md). This page covers the full lifecycle: install, configuration, authentication, verification, and upgrade.
+
+---
+
+## Install & deploy
+
+**Prerequisites:** Node.js 22+ (LTS or current). No Docker, no database, no API keys.
+
+### 1. Install the CLI
+
+Use a **user-writable npm prefix** so the package directory is owned by you. A root-owned install (`sudo npm install -g`) breaks the embeddings component at runtime:
+
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+export PATH="$HOME/.npm-global/bin:$PATH"  # add to your shell rc to persist
+
+npm install -g @tpsdev-ai/flair
+```
+
+> ⚠️ **Never `sudo npm install -g @tpsdev-ai/flair`.** A root-owned install makes the package directory unwritable by the user Harper runs as. At runtime the embeddings component gets `EACCES` and semantic search silently degrades to keyword-only. `flair init` and `flair doctor` will warn you loudly.
+
+### 2. Bootstrap the instance
+
+```bash
+flair init
+```
+
+`flair init` does everything in one step:
+
+1. Installs the embedded Harper (memory store) into `~/.flair/data/`.
+2. Downloads the local embedding model (~80 MB — first run only).
+3. Starts Flair as a launchd / systemd service on port `19926`.
+4. Creates a default agent identity (Ed25519 keypair, stored at `~/.flair/keys/<agent>.key`).
+5. Runs a smoke test to confirm semantic search works.
+
+Useful flags:
+
+```bash
+flair init --agent mybot           # name the agent (--agent-id also works)
+flair init --client claude-code    # wire one specific MCP client
+flair init --no-mcp                # instance + agent only, skip MCP wiring
+flair init --skip-smoke            # skip the MCP smoke test
+flair init --port 8000             # use a non-default port
+```
+
+> **Non-interactive shell:** bare `flair init` with no `--agent` bootstraps the instance only and skips agent registration, MCP client wiring, and the smoke test. Pass flags explicitly: `flair init --agent <id> --client all`.
+
+### 3. Lifecycle management
+
+```bash
+flair status        # check everything is working
+flair stop          # stop the service (keeps data)
+flair restart       # restart the service
+flair uninstall     # remove the service (keeps data + keys)
+flair uninstall --purge   # remove everything including data and keys
+```
+
+On macOS the service is a launchd plist at `~/Library/LaunchAgents/ai.tpsdev.flair.plist`. On Linux it is a systemd unit at `~/.config/systemd/user/flair.service`. Both auto-start on login/boot and restart on crash.
+
+### Docker
+
+Flair does not have a foreground daemon mode today (`flair start` has no `--foreground` option and `flair init` always installs a service manager unit). There is no supported Docker recipe — run Flair directly on the host or use [Harper Fabric](https://www.harperdb.io/) for managed hosting.
+
+Embeddings run on CPU in any containerized environment (no Metal acceleration). Performance is acceptable for small-to-medium memory stores (< 10K memories).
+
+See also: [system-requirements.md](system-requirements.md) for measured resource usage.
+
+---
+
+## Configuration
+
+All configuration lives in `~/.flair/`:
+
+```
+~/.flair/
+├── config.yaml          # port, host, embedding model
+├── data/                # Harper database (RocksDB)
+├── keys/                # Ed25519 keypairs per agent (mode 0600)
+└── backups/             # flair backup output
+```
+
+### Key config options (`~/.flair/config.yaml`)
+
+```yaml
+http:
+  port: 19926            # API port (ops port = this - 1)
+  host: 127.0.0.1        # bind address (0.0.0.0 for remote access)
+
+clustering:
+  nodeName: flair
+
+logging:
+  level: warn
+  stdStreams: true
+```
+
+### Environment variables
+
+| Variable | What it does | When to set it |
+|----------|--------------|----------------|
+| `FLAIR_PUBLIC_URL` | The URL operators reach this Flair on. Used by OAuth metadata and A2A discovery. | Set on VPS / internet-facing deployments. |
+| `HDB_ADMIN_PASSWORD` | Bootstrap password for the embedded Harper. After first start, the persisted user record is the source of truth. | Set at install time. See [secrets-and-keys.md](secrets-and-keys.md) for rotation. |
+| `FLAIR_KEY_PASSPHRASE` | Passphrase for AES-256-GCM encryption of federation private-key seeds. | Set explicitly for production federation deployments. |
+| `FLAIR_URL` | Override the Flair base URL for CLI commands (points to a remote instance). | When connecting from a different machine. |
+
+---
+
+## Agent authentication
+
+Agents authenticate with **Ed25519 per-agent keys**:
+
+```bash
+# Register an agent (generates Ed25519 keypair at ~/.flair/keys/myagent.key)
+flair agent add myagent
+
+# List registered agents
+flair agent list
+```
+
+Every request to Flair is signed with the agent's private key. The signed payload is `agentId:timestamp:nonce:METHOD:/path` with a 30-second replay window and nonce deduplication. Unsigned requests are rejected.
+
+This guarantees **write isolation** (no agent can write as another) and identity-verified reads. Reads are intentionally more open: any verified agent on the same instance can read any other agent's non-private memories. Only `visibility: private` memories are owner-only. See [SECURITY.md](../SECURITY.md) for the full model.
+
+### The private key
+
+- Lives at `~/.flair/keys/<agent>.key` (PKCS8 base64, mode `0600`).
+- **Stays on the host that owns the agent.** Don't copy it to another machine — register a new agent identity there.
+- **Don't check it into git.** Rotate first if compromised: `flair agent rotate-key <id>`.
+- `flair backup` excludes private keys by default. Back them up separately if you want offsite recovery.
+
+See [secrets-and-keys.md](secrets-and-keys.md) for the full threat model and key lifecycle.
+
+---
+
+## Verify it works
+
+### Quick health check
+
+```bash
+flair status
+```
+
+The **🟢** icon means everything is healthy. A **🟡** means something worth looking at; **🔴 unreachable** means the server isn't running.
+
+```bash
+flair status --agent local     # full detail: memory counts, soul entries
+flair doctor                   # automated diagnosis + fix suggestions
+```
+
+### End-to-end smoke test
+
+```bash
+# Write a memory
+flair memory add --agent myagent "Harper v5 sandbox blocks node:module but process.dlopen works"
+
+# Find it by meaning (not keywords)
+flair memory search --agent myagent "native addon loading in sandboxed runtimes"
+# → [0.67] Harper v5 sandbox blocks node:module but process.dlopen works
+```
+
+### Connectivity
+
+```bash
+curl http://localhost:19926/Health              # public, no auth needed
+flair doctor                                    # checks embeddings, auth, connectivity
+```
+
+See [troubleshooting.md](troubleshooting.md) for common issues and fixes.
+
+---
+
+## Upgrade
+
+`flair upgrade` is install → restart → verify → rollback-on-failure in one step:
+
+```bash
+# 1. Back up first, always
+flair backup --output ~/flair-backup-$(date +%Y%m%d).json --admin-pass-file ~/.flair/admin-pass
+
+# 2. Check what's outdated (doesn't install anything)
+flair upgrade --check
+
+# 3. Upgrade — installs, restarts, and verifies in one step
+flair upgrade
+
+# 4. Verify
+flair status
+flair doctor
+```
+
+Optional: `flair upgrade --snapshot` takes a byte-exact snapshot of `~/.flair/data` before upgrading, so you can restore the physical data directory if the new version writes data the old version can't read.
+
+See [upgrade.md](upgrade.md) for the full walkthrough including re-embedding, rollback, and downgrade.
+
+---
+
+## Backup & restore
+
+```bash
+# Backup all data (agents, memories, souls)
+flair backup --output ~/flair-backup-$(date +%Y%m%d).json
+
+# Restore to a fresh instance
+flair restore ~/flair-backup-20260405.json
+```
+
+Always backup before upgrades. `flair backup` excludes private keys.
+
+---
+
+## Federation
+
+Available. Pair a local instance as a hub or spoke with another Flair instance:
+
+```bash
+# On the hub — generate a one-time pairing token triple
+FLAIR_ADMIN_PASS=<hub-admin-password> flair federation token > triple.json
+
+# On the spoke — pair to the hub
+flair federation pair <hub-url> --token-from ./triple.json
+
+# Sync (one-shot)
+flair federation sync --admin-pass-file ~/.flair/admin-pass
+```
+
+Full walkthrough: [federation.md](federation.md).
+
+---
+
+## See also
+
+- [deployment-shapes.md](deployment-shapes.md) — choose your shape
+- [quickstart.md](quickstart.md) — zero to working in 5 minutes
+- [upgrade.md](upgrade.md) — full upgrade mechanics (re-embedding, rollback, downgrade)
+- [federation.md](federation.md) — hub-and-spoke sync between instances
+- [troubleshooting.md](troubleshooting.md) — common issues and automated diagnosis
+- [system-requirements.md](system-requirements.md) — measured resource usage
+- [secrets-and-keys.md](secrets-and-keys.md) — agent keys, admin password, threat model

package/docs/the-team.md

@@ -15,7 +15,7 @@ If you're trying to run your own multi-agent team using Flair as the memory laye
 | **Pulse** | EA / intel scanning / coordination | OpenClaw | Claude API | cloud VM |
 | **Nathan** | Founder / product owner / human-in-the-loop | (human) | (human) | wherever |
 
-Every agent has its own Ed25519 identity in Flair. They sign every memory write and every read. **Writes are isolated at the Flair API layer** — Sherlock can't accidentally (or maliciously) write into Pulse's memory, because the signature won't verify for anyone but Pulse. Reads are a different story: within one Flair instance, any verified agent can read any other agent's **non-private** memory — that's the shipped model (open-within-org read, no grant needed), not a gap. An agent keeps something genuinely sensitive owner-only by writing it with `visibility: private`. The hard access boundary is the **federation edge** (a separate Flair instance), not reads within one.
+Every agent has its own Ed25519 identity in Flair. They sign every memory write and every read. **Writes are isolated at the Flair API layer** — Sherlock can't accidentally (or maliciously) write into Pulse's memory, because the signature won't verify for anyone but Pulse. Reads are a different story: within one Flair instance, any verified agent can read any other agent's **non-private** memory — that's the shipped model (open-within-org read, no grant needed), not a gap. Which memories are non-private is decided at write time: visibility defaults from durability, so `permanent`/`persistent` writes land `shared` and `standard`/`ephemeral` writes land `private`. A teammate's scratch context is therefore owner-only until someone shares it deliberately, and an agent keeps something genuinely sensitive owner-only regardless of durability by writing it with `visibility: private`. The hard access boundary is the **federation edge** (a separate Flair instance), not reads within one.
 
 ## How memory flows
 
@@ -41,10 +41,14 @@ Every agent has its own Ed25519 identity in Flair. They sign every memory write
                                    │
                        (every agent can read every other
                         agent's non-private memories —
-                        `visibility: private` stays owner-only)
+                        permanent/persistent land shared,
+                        standard/ephemeral land private,
+                        and private stays owner-only)
 ```
 
-No agent can write into another agent's memory — that's enforced server-side by signature verification, no exceptions. Reads are intentionally open within the org: when Flint commits a piece of strategy, any agent can find it on `memory_search` unless Flint marked it `private`. **By design** — the goal is relevance and findability across the team, not secrecy between roles. An agent that genuinely needs something to stay owner-only (a draft not ready for the team, a sensitive finding pre-disclosure) marks it `visibility: private`; everything else is fair game for any teammate to search.
+No agent can write into another agent's memory — that's enforced server-side by signature verification, no exceptions. Reads are intentionally open within the org: when Flint commits a piece of strategy as a `permanent` or `persistent` memory, it lands `shared` and any agent can find it on `memory_search`. **By design** — the goal is relevance and findability across the team, not secrecy between roles.
+
+The reverse also holds, and it is the part worth internalising: a `standard` or `ephemeral` write lands `private`, so an agent's day-to-day working context is *not* team-searchable by default. Commit something at `permanent`/`persistent` durability, or pass `visibility: shared`, when you mean the team to find it. An agent that needs something owner-only whatever its durability (a draft not ready for the team, a sensitive finding pre-disclosure) marks it `visibility: private` explicitly.
 
 When agents need to *coordinate* — a direct, targeted handoff rather than ambient searchable memory — they pass **explicit messages** through TPS mail (a separate signed delivery channel; see [tpsdev-ai/cli](https://github.com/tpsdev-ai/cli)). That's a different concern from memory visibility: TPS mail is for "I need you, specifically, to see this now"; Flair memory is the shared, searchable record everyone (except where `private`) can draw on later.
 
@@ -106,7 +110,7 @@ The MCP server (`@tpsdev-ai/flair-mcp`) is what makes this orchestrator-agnostic
 
 ## What we deliberately don't do
 
-- **No shared write identity.** Every memory is written and owned by exactly one agent's Ed25519 key — there's no merged "team" identity that can write on another agent's behalf. Reads are a separate story: within the org, any agent can search any other's non-private memory by default (see [SECURITY.md](../SECURITY.md)) — that's intentional, not a leak. TPS mail is still how agents route a message to a *specific* teammate; it's for targeted delivery, not for gating ambient visibility.
+- **No shared write identity.** Every memory is written and owned by exactly one agent's Ed25519 key — there's no merged "team" identity that can write on another agent's behalf. Reads are a separate story: within the org, any agent can search any other's non-private memory by default (see [SECURITY.md](../SECURITY.md)) — that's intentional, not a leak. "Non-private" is set at write time from durability, not by a per-pair grant. TPS mail is still how agents route a message to a *specific* teammate; it's for targeted delivery, not for gating ambient visibility.
 - **No silent LLM-driven memory extraction.** Each agent decides what it remembers. No background "summarize and persist" on every turn — that's how memory drifts away from intent.
 - **No multiple agents on one identity.** "Anvil" and "Anvil-2" would be two separate agentIds with two separate keys. Same workload, different identities, separately-owned memories.
 - **No replay-safe-but-otherwise-unsigned reads.** Every Flair request is Ed25519-signed and verified, including reads. Even on a private network we don't trust the network.

package/docs/troubleshooting.md

@@ -150,7 +150,7 @@ flair agent list
 **Possible causes:**
 1. **Hash-fallback embeddings:** Check `flair status` — if embeddings are in hash mode, semantic search won't work properly. Fix with `flair reembed`.
 2. **Content safety flags:** The memory might have been flagged. Search for it directly: `flair memory list --agent <id>`.
-3. **`visibility: private`:** Reads are open within the org by default — any agent can find any other agent's non-private memories. If the memory was written with `visibility: private`, only its author can find it; search as that agent instead.
+3. **`visibility: private`:** Only its author can find a `private` memory. This is the most common cause when one agent wrote the memory and another is searching for it, because **`private` is what a bare write lands on**: visibility defaults from durability (`permanent`/`persistent` → `shared`, `standard`/`ephemeral` → `private`), and a write with no `--durability` is `standard`. Check what the memory landed on with `flair memory list --agent <author> --json` (the table view doesn't show visibility, the JSON records do), then either search as its author, or rewrite it with `--visibility shared` so every agent on the instance can find it (no grant needed — non-private reads are open within the instance).
 4. **Dedup threshold:** If the content is very similar to an existing memory, it may have been deduplicated. Check with `flair memory list`.
 
 ### High memory usage

package/docs/upgrade.md

@@ -17,7 +17,11 @@ There are two things you might be upgrading:
 
 ```bash
 # 1. Back up first, always
-flair backup > ~/flair-backup-$(date +%Y%m%d).json
+#    --admin-pass-file keeps the secret out of ps and shell history.
+#    --output is required — the archive goes to a file, not stdout.
+flair backup \
+  --output ~/flair-backup-$(date +%Y%m%d).json \
+  --admin-pass-file ~/.flair/admin-pass
 
 # 2. Check what's outdated (doesn't install anything)
 flair upgrade --check
@@ -352,7 +356,7 @@ npm install -g @tpsdev-ai/flair@<previous-version>
 flair restart
 
 # If data looks wrong, restore from your pre-upgrade backup
-flair restore < ~/flair-backup-<date>.json
+flair restore ~/flair-backup-<date>.json
 ```
 
 `flair upgrade` does this automatically on a failed post-restart verification — see

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.31.1",
+  "version": "0.33.0",
   "packageManager": "bun@1.3.10",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",
@@ -25,6 +25,12 @@
     "llm",
     "openclaw"
   ],
+  "main": "./dist/resources/in-process-api.js",
+  "exports": {
+    ".": "./dist/resources/in-process-api.js",
+    "./server": "./dist/resources/in-process.js",
+    "./package.json": "./package.json"
+  },
   "bin": {
     "flair": "dist/cli-shim.cjs"
   },