@tpsdev-ai/flair 0.31.0 → 0.32.0

package/docs/hosted-on-fabric.md

@@ -0,0 +1,203 @@
+# Hosted on Harper Fabric
+
+Deploy Flair as a component to a [Harper Fabric](https://www.harperdb.io/) instance. You do not run the Harper process yourself: managed hosting, multi-region replication, no shell on the node.
+
+---
+
+## Deploy
+
+You **deploy** rather than install. `flair deploy` pushes Flair as a Fabric component:
+
+```bash
+export FABRIC_USER=<admin> FABRIC_PASSWORD=<pass>
+
+# Validate args and package layout without deploying
+flair deploy --fabric-org <org> --fabric-cluster <cluster> --dry-run
+
+# Deploy
+flair deploy --fabric-org <org> --fabric-cluster <cluster>
+```
+
+Credentials go via the environment, not argv, so they stay out of `ps`. Use `--fabric-password-file <path>` (mode `0600`) when scripting; inline `--fabric-user`/`--fabric-password` flags leak to shell history and are discouraged.
+
+Target defaults to `https://<cluster>.<org>.harperfabric.com`; override with `--target`. Deploy verifies the served API, waits for replication, and polls for convergence before reporting success.
+
+> `--fabric-token` is accepted but **fails** — `deploy_component` is Basic-auth only.
+
+### Provision the instance
+
+Run **once**, before serving traffic:
+
+```bash
+flair init --target https://<cluster>.<org>.harperfabric.com \
+  --ops-target <ops-url> \
+  --cluster-admin-user <user> --cluster-admin-pass <pass> \
+  --remote --force
+```
+
+- `--force` is required — this writes to a live instance.
+- `--remote` marks it a federation **hub** and creates the `flair_pair_initiator` role; without it, pairing later fails role-not-found.
+- Generated admin password lands in `~/.tps/secrets/flair-fabric-hdb` (mode `0600`); `--flair-admin-pass` to choose your own.
+
+### Port derivation trap
+
+Locally, Flair serves data on `19926` and the ops API on `19925`. The CLI derives **ops = data − 1** everywhere. A managed endpoint is HTTPS on 443 with no port, so derivation produces `:442` — where nothing answers.
+
+**Pass `--ops-target <url>` explicitly** (or set `FLAIR_OPS_TARGET`) on any command that touches the ops API: `init --target`, `agent add --target`, `federation token --target`.
+
+---
+
+## Configuration
+
+On Fabric, configuration goes through the component's environment, not a local `config.yaml`. Set these in the Fabric component env:
+
+| Variable | What it does | When to set it |
+|----------|--------------|----------------|
+| `FLAIR_PUBLIC_URL` | The URL operators reach this Flair on. Surfaced in OAuth metadata and A2A discovery. | **Always set** — or clients see a loopback address. |
+| `HDB_ADMIN_PASSWORD` | Bootstrap password for the embedded Harper. | Set at install time. |
+| `FLAIR_KEY_PASSPHRASE` | Passphrase for federation key encryption. | Set for production federation deployments. |
+
+On Fabric / managed deploys, environment variables are provisioned through Harper's Fabric secrets mechanism (encrypted at rest with `enc:v1:` storage format).
+
+---
+
+## Agent authentication
+
+Agents authenticate with **Ed25519 per-agent keys** — the same model as standalone local. Each agent holds a private key and signs every request.
+
+### Register an agent
+
+```bash
+# Register an agent — --ops-target is required (see Port derivation trap above)
+flair agent add mybot --target "$FLAIR_URL" --ops-target <ops-url>
+```
+
+The private key is stored on the **client machine** at `~/.flair/keys/<agent>.key`, not on the Fabric node. The Fabric node stores only the public key in the `Agent` table.
+
+### Connect a client
+
+```bash
+export FLAIR_URL=https://<cluster>.<org>.harperfabric.com
+
+# Register an agent
+flair agent add mybot --target "$FLAIR_URL" --ops-target <ops-url>
+
+# Use with any MCP client — set FLAIR_AGENT_ID and FLAIR_URL in the client env
+```
+
+Auth is the same protocol as standalone: Ed25519 signature of `agentId:timestamp:nonce:METHOD:/path`, 30-second replay window, nonce deduplication. The difference is purely the transport — HTTPS instead of localhost HTTP.
+
+See [secrets-and-keys.md](secrets-and-keys.md) for the full threat model.
+
+---
+
+## Verify it works
+
+### Health and status
+
+```bash
+curl -sf https://<cluster>.<org>.harperfabric.com/Health
+
+flair status --target https://<cluster>.<org>.harperfabric.com
+flair fleet verify --target https://<cluster>.<org>.harperfabric.com
+```
+
+`fleet verify` checks health, auth, and version across the origin node plus every Flair federation peer on file. Exit codes: 0 = all verified, 1 = origin failed, 2 = peer version skew, 3 = peer unverifiable.
+
+> **A credential mismatch renders as an empty section.** `flair status` reads `/HealthDetail` with `FLAIR_ADMIN_PASS` / `HDB_ADMIN_PASSWORD` / a pinned agent key — **not** the `FABRIC_*` credentials. On failure it renders blank.
+
+### What is available remotely
+
+| Command | Works remotely |
+|---|---|
+| `GET /Health` | Yes — public, no auth |
+| `flair status --target <url>` | Yes — subsystem rollups |
+| `flair quality --target <url>` | Yes — recall/coverage metrics |
+| `flair fleet verify --target <url>` | Yes — origin + Flair peers |
+| `flair federation status\|verify\|reachability --target <url>` | Yes — peer table, sync recency |
+
+### What does **not** work remotely
+
+**`flair doctor`** takes no `--target` — it hardcodes localhost, reads a local PID file, and shells out to `lsof`. Unavailable too: `start`, `stop`, `restart`, `snapshot`, `reembed`, `rem`, `bridge`.
+
+**Fabric's own cluster topology is invisible.** `fleet verify` sweeps *Flair's* federation peer table, not Harper's cluster nodes. `cluster_status` is harper-pro-only. `0 peers known` means "0 on file", never "0 exist."
+
+---
+
+## Upgrade
+
+A Fabric-deployed Flair is a component, not an npm package. Upgrade in place:
+
+```bash
+FABRIC_USER=<admin> FABRIC_PASSWORD=<pass> \
+  flair upgrade --target https://<cluster>.<org>.harperfabric.com
+```
+
+This resolves the target version, stages a clean deployable with the required `@harperfast/harper` version pin, confirms the staged build before deploying, pushes it via `flair deploy`, and verifies the result. After a successful deploy, it runs a fleet convergence sweep across the origin plus every Flair federation peer.
+
+- `--check` shows the version diff and plan without deploying.
+- `--yes` skips the confirmation prompt for scripted use.
+- `--fabric-password-file <path>` reads the password from a file instead of an env var.
+- `--no-fleet-verify` skips the post-deploy fleet sweep.
+
+Inline `--fabric-user`/`--fabric-password` flags also work but are **discouraged** — both leak to shell history and `ps`.
+
+### Backup before upgrading
+
+`flair snapshot` is local-only. Back up before every upgrade:
+
+```bash
+flair backup --url https://<cluster>.<org>.harperfabric.com \
+  --admin-pass-file <path> --output ./flair-backup.json
+```
+
+See [upgrade.md](upgrade.md#upgrading-a-fabric-deployed-instance) for the full walkthrough.
+
+---
+
+## Federation
+
+Available. Pair a local spoke to a Fabric-hosted hub:
+
+```bash
+# On any machine (no shell on the hub) — generate a pairing token triple
+FLAIR_ADMIN_PASS=<hub-admin-password> flair federation token \
+  --target https://<cluster>.<org>.harperfabric.com \
+  --ops-target <ops-url> > ./pair-triple.json
+
+# On the spoke — pair to the Fabric hub
+flair federation pair https://<cluster>.<org>.harperfabric.com \
+  --token-from ./pair-triple.json
+```
+
+### Pairing limitation
+
+The scheduled sync driver (`flair federation sync enable`) writes a launchd job or systemd timer **on the machine running the CLI** — it cannot be installed on a Fabric node. A periodic one-shot from the spoke machine is the workaround.
+
+Full walkthrough: [federation.md](federation.md).
+
+### Multi-region replication
+
+Fabric gives you N regional nodes running one component — **not** N Flair instances. Every node shares one Flair identity (the `Instance` table replicates). You do **not** federate your own regions to each other — Harper replication handles that. Use `flair federation pair` only to reach a **separate** Flair instance.
+
+---
+
+## Known operational limitations
+
+### No disk or quota telemetry
+
+`flair status` reports usage for two directories: no free space, no total, no quota. An instance can hit its quota with nothing saying so. The one indirect signal is a migration halting for space.
+
+### Unbounded npm cache
+
+Every deploy runs a server-side `npm install` using the node's default cache. npm never evicts it, so it grows until it fills the quota. There is no cache flag, alternate location, or cleanup option. [flair#886](https://github.com/tpsdev-ai/flair/issues/886).
+
+---
+
+## See also
+
+- [deployment-shapes.md](deployment-shapes.md) — choose your shape
+- [upgrade.md](upgrade.md#upgrading-a-fabric-deployed-instance) — full Fabric upgrade walkthrough
+- [federation.md](federation.md) — pairing, sync driver, conflict resolution
+- [standalone-local.md](standalone-local.md) — the standalone shape (different upgrade, shell available)
+- [secrets-and-keys.md](secrets-and-keys.md) — admin password, key lifecycle

package/docs/secrets-and-keys.md

@@ -7,11 +7,11 @@ Flair owns **identity**. Flair does **not** own arbitrary secrets. This page dra
 For each registered agent, Flair stores:
 
 - A **public key** in the `Agent` table (server-side; used to verify signed requests).
-- A **private key** at `~/.flair/keys/<agent>.key` on the host that owns that agent (PKCS8 base64). Created by `flair agent add <id>`. Mode `0600`.
+- A **private key** at `~/.flair/keys/<agent>.key` on the host that owns that agent — the raw 32-byte Ed25519 seed. Created by `flair init --agent <id>` or `flair agent add <id>`. Mode `0600`.
 
 Agents sign every request to Flair with this key. Flair refuses unsigned requests and refuses signatures that don't match the registered public key. The signed payload is `<agentId>:<timestamp>:<nonce>:<METHOD>:<path>` with a 30-second replay window and nonce dedup — replays inside that window are rejected.
 
-**This is the only secret material Flair manages.** Lose the key file and the agent is locked out (`flair agent rotate <id>` to issue a new pair).
+**This is the only secret material Flair manages.** Lose the key file and the agent is locked out (`flair agent rotate-key <id>` to issue a new pair).
 
 ## Flair admin password (Harper instance)
 - If not provided via `--admin-pass`, `--admin-pass-file`, `FLAIR_ADMIN_PASS`, or `HDB_ADMIN_PASSWORD`, a random password is generated and written to `~/.flair/admin-pass` (mode `0o600`). The password is **not** printed to the console.
@@ -140,7 +140,7 @@ Hermes uses `~/.hermes/.env` for provider API keys (managed by `hermes auth`). T
 
 - **Stays on the host that owns the agent.** If your agent runs on a given host, the key lives on that host. If you spin up the same agent on another machine, **don't copy the key** — register a new agent identity (`flair agent add <id>-on-<other-host>`) on that machine. Different identities, same Flair instance can store memories for both, you decide cross-agent visibility.
 - **`chmod 600` enforced** by `flair agent add`. Don't relax it.
-- **Don't check it into git.** `.gitignore` should already exclude `~/.flair/keys/`; if you're ever tempted to share keys for "convenience," rotate first (`flair agent rotate <id>`).
+- **Don't check it into git.** `.gitignore` should already exclude `~/.flair/keys/`; if you're ever tempted to share keys for "convenience," rotate first (`flair agent rotate-key <id>`).
 - **Backup separately**, encrypted. The `flair backup` command excludes private keys by default. Roll your own backup of `~/.flair/keys/` via age-encrypted archive if you want offsite recovery.
 
 ## What about a `flair secret` CLI?
@@ -153,7 +153,7 @@ If you find yourself wanting one anyway, your agent can call `security find-gene
 
 | Asset | Owned by | If compromised → |
 |---|---|---|
-| Flair agent private key (`~/.flair/keys/<agent>.key`) | Flair (you, on the host) | Attacker can **write** memories under that agent's identity and read that agent's **`private`**-marked memories until you rotate. Use `flair agent rotate <id>`. Other agents' write identity is unaffected — they can't be impersonated with this key. |
+| Flair agent private key (`~/.flair/keys/<agent>.key`) | Flair (you, on the host) | Attacker can **write** memories under that agent's identity and read that agent's **`private`**-marked memories until you rotate. Use `flair agent rotate-key <id>`. Other agents' write identity is unaffected — they can't be impersonated with this key. |
 | LLM provider API keys (Anthropic, OpenAI, etc.) | OS keyring / 1Password | Standard provider revocation: rotate the key in the provider's console, update keyring entry. |
 | Cross-host secrets (1Password vault, age-sops) | The secret manager itself | Trust falls back to that manager's MFA / key handling. Document recovery in your team's ops runbook. |
 | Memory contents | Flair (server-side) | Write access requires the owning agent's key → see "Per-agent write isolation, org-wide non-private read" below. |

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/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
@@ -188,7 +192,7 @@ FABRIC_USER=<admin> FABRIC_PASSWORD=<pass> \
 
 (or `--fabric-password-file <path>` instead of the `FABRIC_PASSWORD` env var — reads the
 password from a file, chmod 600). This resolves the target version (latest published
-`@tpsdev-ai/flair`, or pin one with `--version`), stages a clean deployable with the
+`@tpsdev-ai/flair`, or pin one with `--flair-version`), stages a clean deployable with the
 required `harper` version pin applied (`--harper-version` to override),
 confirms the staged Harper build before deploying, then reuses `flair deploy` to push it
 and verifies the result. `--check` shows the version diff and plan without deploying
@@ -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.0",
+  "version": "0.32.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"
   },