@tpsdev-ai/flair 0.44.12 → 0.44.13

package/README.md

@@ -347,7 +347,7 @@ flair agent add otherbot --target https://your-server:19926
 
 ### Harper Fabric
 
-Managed hosting with multi-region replication and failover. Federation runs against Harper Fabric hubs — pair your local instance to sync memories across nodes. Full guide: **[docs/deploying-on-fabric.md](docs/deploying-on-fabric.md)**.
+Managed hosting with multi-region replication and failover. Need a public URL for Cursor / Grok Bot / cloud agents? Start at **[docs/quickstart-fabric.md](docs/quickstart-fabric.md)**. Federation, pairing, and operator detail: **[docs/deploying-on-fabric.md](docs/deploying-on-fabric.md)**.
 
 ## Security
 

package/dist/resources/SemanticSearch.js

@@ -126,29 +126,26 @@ export class SemanticSearch extends Resource {
         let temporalBoost = 1.0;
         if (q && !sinceDate) {
             const lq = String(q).toLowerCase();
+            // flair#1245: a text-derived temporal match must ONLY nudge recency in
+            // ranking (temporalBoost, a soft multiplier applied in
+            // semantic-retrieval-core.ts) — it must NEVER derive a hard `sinceDate`
+            // exclusion. An incidental temporal word in the query TEXT (the #1245
+            // canary carried "today" inside a slogan) otherwise silently dropped
+            // every candidate older than the window → 0 results. Only the explicit
+            // `since` API param (set above, untouched here) still hard-filters.
             if (/\btoday\b|\bthis morning\b|\bthis afternoon\b/.test(lq)) {
-                const d = new Date();
-                d.setHours(0, 0, 0, 0);
-                sinceDate = d;
                 temporalBoost = 1.5;
             }
             else if (/\byesterday\b/.test(lq)) {
-                const d = new Date();
-                d.setDate(d.getDate() - 1);
-                d.setHours(0, 0, 0, 0);
-                sinceDate = d;
                 temporalBoost = 1.3;
             }
             else if (/\bthis week\b|\blast few days\b/.test(lq)) {
-                sinceDate = new Date(Date.now() - 7 * 24 * 3600_000);
                 temporalBoost = 1.2;
             }
             else if (/\blast week\b/.test(lq)) {
-                sinceDate = new Date(Date.now() - 14 * 24 * 3600_000);
                 temporalBoost = 1.1;
             }
             else if (/\brecently\b|\blately\b/.test(lq)) {
-                sinceDate = new Date(Date.now() - 3 * 24 * 3600_000);
                 temporalBoost = 1.3;
             }
         }

package/docs/deploying-on-fabric.md

@@ -21,6 +21,9 @@ you already have, [Remote Server](../README.md#remote-server) is simpler and kee
 
 ## Quickstart
 
+New user who just needs a reachable `FLAIR_URL` for Cursor / Grok Bot? Start at
+[quickstart-fabric.md](quickstart-fabric.md). This page is the operator path.
+
 ### 1. Deploy the component
 
 ```bash

package/docs/deployment-shapes.md

@@ -5,7 +5,7 @@ Flair runs in one of three shapes. Pick yours and follow only that path.
 | You want to... | Shape | Start here |
 |---|---|---|
 | Run Flair on your own machine or VPS. `flair init` installs Harper, creates your agent identity, and you're running. | **Standalone local** | [standalone-local.md](standalone-local.md) |
-| Run Flair on [Harper Fabric](https://www.harperdb.io/) — managed hosting, multi-region replication, no shell on the node. You deploy a component; agents connect over HTTPS. | **Hosted on Fabric** | [hosted-on-fabric.md](hosted-on-fabric.md) |
+| Run Flair on [Harper Fabric](https://www.harperdb.io/) — managed hosting, multi-region replication, no shell on the node. You deploy a component; agents connect over HTTPS. | **Hosted on Fabric** | [quickstart-fabric.md](quickstart-fabric.md) (new-user URL) · [hosted-on-fabric.md](hosted-on-fabric.md) |
 | Load Flair into a Harper instance you already run. In-process calls — no HTTP, no second process, no key to distribute. Over HTTP it is one memory API among many. | **Embedded in a Harper app** | [embedding-in-a-harper-app.md](embedding-in-a-harper-app.md) |
 
 ---

package/docs/deployment.md

@@ -116,10 +116,11 @@ Note: embeddings run on CPU in Docker (no Metal acceleration). Performance is ac
 
 Deploying to a Harper Fabric cluster is a different mechanism from the installs above — `flair deploy` pushes Flair as a cluster component instead of `npm install -g`. To upgrade an already-deployed Fabric instance in place, use `FABRIC_USER=<admin> FABRIC_PASSWORD=<pass> flair upgrade --target <fabric-url>` (or `--fabric-password-file <path>` in place of the env var), not the local upgrade path. Inline `--fabric-user`/`--fabric-password` flags also work but are discouraged — both leak to shell history and `ps`. See [`docs/upgrade.md` — Upgrading a Fabric-deployed instance](upgrade.md#upgrading-a-fabric-deployed-instance) for the full walkthrough, including the automatic post-deploy fleet-convergence sweep.
 
-For the hosted shape end to end — when to choose it, ports and auth against a managed
-Fabric endpoint, pairing local spokes to a hosted hub, and what you can and cannot
-observe without a shell on the node — see
-[`docs/deploying-on-fabric.md`](deploying-on-fabric.md).
+New user who needs a reachable `FLAIR_URL` for Cursor / Grok Bot? Start at
+[`docs/quickstart-fabric.md`](quickstart-fabric.md). For the hosted shape end to
+end — when to choose it, ports and auth against a managed Fabric endpoint, pairing
+local spokes to a hosted hub, and what you can and cannot observe without a shell
+on the node — see [`docs/deploying-on-fabric.md`](deploying-on-fabric.md).
 
 ---
 

package/docs/hosted-on-fabric.md

@@ -2,6 +2,8 @@
 
 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.
 
+Need a public URL for Cursor / Grok Bot / cloud agents? Start at [quickstart-fabric.md](quickstart-fabric.md).
+
 ---
 
 ## Deploy

package/docs/integrations.md

@@ -195,7 +195,8 @@ If it has a custom memory protocol, the adapter pattern is small (~200 lines). L
 
 ## See also
 
-- [Quickstart](quickstart.md) — `flair init` to working memory in 30 seconds
+- [Quickstart](quickstart.md) — `flair init` to working memory on a laptop
+- [Fabric Quickstart](quickstart-fabric.md) — `flair deploy` to a reachable Harper Fabric URL
 - [Embedding in a Harper app](embedding-in-a-harper-app.md) — run Flair as a component of your own Harper instance and call it in-process
 - [Memory bridges](bridges.md) — import/export Flair ↔ Mem0, ChatGPT, claude-project, markdown, agentic-stack (five bridges shipped)
 - [Federation](federation.md) — pair instances peer-to-peer for cross-machine sync

package/docs/quickstart-fabric.md

@@ -0,0 +1,106 @@
+# Fabric Quick Start
+
+From zero to a **reachable** Flair URL — so Cursor, Grok Bot, and cloud agents can actually hit it.
+
+Laptop Flair from [`docs/quickstart.md`](quickstart.md) listens on `127.0.0.1:19926`. That loopback origin is not reachable from Grok Bot or Cursor cloud agents. This page is the start path when you need a public HTTPS origin.
+
+Fabric is **Harper-hosted**, not a Flair-operated cloud. You deploy Flair as a component onto [Harper Fabric](https://www.harperdb.io/).
+
+## 0. Prerequisites
+
+**Node.js 22 or newer**, a user-writable npm global prefix (do not install with `sudo` — same rule as the [local Quick Start](quickstart.md#0-prerequisites)), and **a Harper Fabric account** ([harperdb.io](https://www.harperdb.io/)). You need the org name, cluster name, and admin credentials for that account.
+
+```bash
+node --version   # v22.x.x or newer
+npm i -g @tpsdev-ai/flair
+```
+
+Lead with environment credentials so they stay out of `ps` and shell history:
+
+```bash
+export FABRIC_USER=<admin>
+export FABRIC_PASSWORD=<pass>
+```
+
+Scripting? Use `--fabric-password-file <path>` (mode `0600`) instead of `FABRIC_PASSWORD`. Inline `--fabric-password` works and leaks — do not lead with it.
+
+`FABRIC_ORG` / `FABRIC_CLUSTER` can stand in for the flags below. `--fabric-token` is accepted but **fails** — Fabric `deploy_component` is Basic-auth only.
+
+## 1. Deploy
+
+```bash
+# Validate args and package layout without deploying
+flair deploy --fabric-org <org> --fabric-cluster <cluster> --dry-run
+
+flair deploy --fabric-org <org> --fabric-cluster <cluster>
+```
+
+The target defaults to `https://<cluster>.<org>.harperfabric.com`. Override with `--target` if your instance URL is different. `flair deploy` writes `FLAIR_PUBLIC_URL` to that same origin so OAuth and A2A discovery do not advertise loopback.
+
+## 2. What success looks like
+
+```
+→ Deploying flair to https://<cluster>.<org>.harperfabric.com
+
+✓ Flair vX.Y.Z deployed and verified serving
+
+  URL:     https://<cluster>.<org>.harperfabric.com
+  Project: flair
+```
+
+A fleet-verify table follows. That HTTPS origin is your `FLAIR_URL`.
+
+Then set an admin password in Fabric Studio (Cluster Settings → Admin). `flair agent add` against a remote instance requires `--admin-pass` — it will not reuse `~/.flair/admin-pass` or `FLAIR_ADMIN_PASS` from your laptop.
+
+## 3. Register an agent against the remote instance
+
+`flair agent add` takes a positional id and `--target`. There is no `--remote` flag on this command (`--remote` belongs to `flair init`).
+
+On Fabric, ops lives on the **same hostname at port 9925**, not the CLI's default "data port − 1" derivation (that would be `:442`, where nothing answers). Pass `--ops-target` explicitly: <!-- docs-freshness-allow: Fabric ops API port, not legacy data port -->
+
+```bash
+export FLAIR_URL=https://<cluster>.<org>.harperfabric.com
+
+# Fabric ops is :9925 on the same host, not derived :442. docs-freshness-allow: Fabric ops API
+flair agent add mybot --target "$FLAIR_URL" --ops-target https://<cluster>.<org>.harperfabric.com:9925 --admin-pass <fabric-admin-password>
+```
+
+```
+Keypair written: ~/.flair/keys/mybot.key
+✅ Agent 'mybot' (mybot) registered (ops: https://<cluster>.<org>.harperfabric.com:9925) <!-- docs-freshness-allow: Fabric ops API -->
+   Private key: ~/.flair/keys/mybot.key
+```
+
+The private key stays on **this machine**. The Fabric node stores only the public key.
+
+## 4. Point the Cursor plugin at it
+
+This is why Fabric is the recommended start for **Grok Bot / Cursor cloud agents**: they cannot see your laptop's `127.0.0.1:19926`.
+
+In Cursor: **Plugins → Configure**
+
+| Variable | Value |
+|---|---|
+| `FLAIR_URL` | `https://<cluster>.<org>.harperfabric.com` |
+| `FLAIR_AGENT_ID` | `mybot` (the id you just added) |
+
+Those are the two plugin schema fields. Local Cursor's `npx` can use the key from step 3 at `~/.flair/keys/mybot.key`. A cloud agent's `npx` runs on a different machine — that VM needs the key (or host-env admin credentials). See [`packages/cursor-flair/README.md`](../packages/cursor-flair/README.md).
+
+## 5. Verify
+
+```bash
+flair status --target "$FLAIR_URL"
+FLAIR_URL="$FLAIR_URL" flair memory add --agent mybot "Fabric Quick Start is reachable"
+```
+
+`flair memory add` has no `--target`; it honors `FLAIR_URL`. Then in Cursor:
+
+> Load my Flair bootstrap, then store a test memory
+
+You should see `bootstrap` return soul + memories, then `memory_store` confirm an id.
+
+## What's next
+
+Federation, pairing spokes, upgrades (`flair upgrade --target`), ports, and what you can observe without a shell on the node: **[docs/deploying-on-fabric.md](deploying-on-fabric.md)**.
+
+Still on a laptop only, no public URL needed: **[docs/quickstart.md](quickstart.md)**.

package/docs/quickstart.md

@@ -2,6 +2,8 @@
 
 From zero to a persistent agent memory in five minutes.
 
+> **Need a reachable URL (Cursor cloud / Grok Bot / another machine)?** This guide is the laptop path — `flair init` binds `127.0.0.1:19926`, which those clients cannot see. Deploy on Harper Fabric instead: **[docs/quickstart-fabric.md](quickstart-fabric.md)**.
+
 ## 0. Prerequisites
 
 **Node.js 22 or newer.** No Docker, no database to install, no API keys — Flair runs in a single process and computes embeddings locally.

package/docs/standalone-local.md

@@ -235,7 +235,8 @@ 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
+- [quickstart.md](quickstart.md) — zero to working in 5 minutes (laptop)
+- [quickstart-fabric.md](quickstart-fabric.md) — reachable Harper Fabric URL for Cursor cloud / Grok Bot
 - [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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.44.12",
+  "version": "0.44.13",
   "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",