@tpsdev-ai/flair 0.44.11 → 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/Memory.js

@@ -7,6 +7,7 @@ import { scanFields, isStrictMode } from "./content-safety.js";
 import { invalidEntitiesResponse } from "./entity-vocab.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
 import { assertValidVisibility } from "./memory-visibility.js";
+import { assertValidDurability } from "./memory-durability.js";
 import { DEDUP_COSINE_THRESHOLD_DEFAULT, DEDUP_LEXICAL_THRESHOLD_DEFAULT, DEDUP_MIN_CONTENT_LENGTH, computeMatchConfidence, cosineSimilarity, isConservativeMatch, } from "./dedup.js";
 import { buildProvenance, makeAuthGate, makeReadScope, makeByIdReadGate, makeScopedSearch, resolveAuthGate, stampAttribution, FORBIDDEN, UNAUTH, } from "./record-type-kit.js";
 import { RECORD_TYPES } from "./record-types.js";
@@ -599,6 +600,19 @@ export class Memory extends databases.flair.Memory {
         const usedMemoryIds = content?.usedMemoryIds;
         if (content && typeof content === "object")
             delete content.usedMemoryIds;
+        // ── flair#1238: refuse an unrecognised durability BEFORE defaulting ──
+        // defaultVisibilityForDurability treats any non-permanent/persistent string
+        // as the private branch, so an unknown durability via raw REST (or a future
+        // non-Python adapter) is silently accepted and lands on the narrower private
+        // branch by accident — fail-safe, but unvalidated by contract. Refusing at
+        // the schema boundary makes it safe by construction (mirrors the visibility
+        // guard below). Absent durability is accepted and defaulted to "standard".
+        {
+            const durabilityError = assertValidDurability(content.durability);
+            if (durabilityError) {
+                return new Response(JSON.stringify({ error: "invalid_durability", message: durabilityError }), { status: 400, headers: { "content-type": "application/json" } });
+            }
+        }
         content.durability ||= "standard";
         content.createdAt = new Date().toISOString();
         content.updatedAt = content.createdAt;
@@ -789,6 +803,17 @@ export class Memory extends databases.flair.Memory {
         const usedMemoryIds = content?.usedMemoryIds;
         if (content && typeof content === "object")
             delete content.usedMemoryIds;
+        // ── flair#1238: refuse an unrecognised durability (mirrors post()) ──
+        // put() is the other HTTP-reachable write path (fresh create via CLI, and
+        // the update/patch path). Same guard as post(): a present-but-unknown
+        // durability is refused with 400; absent is accepted (no default stamped
+        // here — put() leaves durability untouched for updates).
+        {
+            const durabilityError = assertValidDurability(content.durability);
+            if (durabilityError) {
+                return new Response(JSON.stringify({ error: "invalid_durability", message: durabilityError }), { status: 400, headers: { "content-type": "application/json" } });
+            }
+        }
         const now = new Date().toISOString();
         content.updatedAt = now;
         // Set defaults that post() sets — put() is also used for new records via CLI

package/dist/resources/MemoryBootstrap.js

@@ -142,6 +142,35 @@ const MAX_COLLISION_ENTRIES = 10;
 // null` (no relevance score to band), which is CORRECT (Kern's #1220 ruling),
 // never a scoring failure — see the `matchQualityNote` in the response tail.
 const LIFECYCLE_SECTIONS = new Set(["permanent", "recent", "predicted"]);
+// flair#1199 trust-admission — build the EXACT trust entry that ships for one
+// included memory (id + section + block + the conditional matchQualityNote), so
+// the admission loop can charge its REAL serialized cost at the same moment it
+// charges the content cost. Single source of truth: the response tail reuses
+// this same builder, so the charged size and the shipped size can never drift
+// (the #1226 "charge what ships" principle, extended to the per-item trust
+// block). The block is assembled purely for SIZING + the response — its content
+// never enters any authority/scope/attribution/dedup decision (the #735/#744
+// zero-authority invariant).
+//
+// flair#1225 — Kern ruled (on #1220) that a null `matchQuality` on an own-recent
+// (lifecycle) entry is CORRECT: lifecycle sections (permanent/recent/predicted)
+// are a window LOAD, not a retrieval surface, so there is no similarity to band
+// — the null means "not scored here", never a scoring failure on the caller's
+// own records (the #1201 misread: own-recent null beside a teammate band).
+// Behavior is unchanged (per Kern); the matchQualityNote only makes the null
+// self-describing in the payload — Fix 3's "any absent field says why" — so a
+// connector reads it right without knowing the #1201 contract.
+function buildTrustEntry(m, section) {
+    const block = buildTrustBlock(m);
+    const matchQualityNote = block.matchQuality === null
+        ? (LIFECYCLE_SECTIONS.has(section)
+            ? `matchQuality is null because '${section}' is a lifecycle-window section, not a retrieval `
+                + `surface — there is no relevance score to band. This is correct (per flair#1225), not a scoring failure.`
+            : "matchQuality is null because no semantic similarity was attached to this result "
+                + "(e.g. a by-id read or a keyword-only degraded match).")
+        : undefined;
+    return { id: m.id, section, ...block, ...(matchQualityNote ? { matchQualityNote } : {}) };
+}
 // flair#1199/#1206 — the default cap on how many org events bootstrap ships.
 // Overridable per-request via `maxEvents`. Event slots are scarce AND (as of
 // #1199) token-charged, so this bounds both the count and the spend; the shared
@@ -670,12 +699,17 @@ export class BootstrapMemories extends Resource {
             // on the REST path); see contentCost. #1207 stays honored: on the prose
             // path this is still the prose-line cost, so REST recall is unchanged.
             const cost = contentCost(struct, line);
-            if (cost <= tokenBudget) {
+            // flair#1199 trust-admission — charge the trust block's real serialized
+            // cost at the same moment as the content cost (per-item trust is CONTENT,
+            // not fixed scaffolding; see buildTrustEntry).
+            const trustEntry = includeTrust ? buildTrustEntry(m, "permanent") : null;
+            const trustCost = trustEntry ? estimateTokens(JSON.stringify(trustEntry)) : 0;
+            if (cost + trustCost <= tokenBudget) {
                 sections.permanent.push(line);
                 includedOwnMemories.push(struct);
-                if (includeTrust)
-                    includedTrustMemories.push({ m, section: "permanent" });
-                tokenBudget -= cost;
+                if (trustEntry)
+                    includedTrustMemories.push(trustEntry);
+                tokenBudget -= cost + trustCost;
                 includedOwnIds.add(m.id); // #1207 — count by unique own-memory id
             }
             else {
@@ -743,16 +777,20 @@ export class BootstrapMemories extends Resource {
             const line = formatMemory(m, agentId);
             const struct = leanMemory(m, "recent");
             const cost = contentCost(struct, line); // #1199 (0.44.11) — charge what ships; see contentCost
-            if (recentSpent + cost > recentBudget) {
+            // flair#1199 trust-admission — charge the trust block's real serialized
+            // cost against BOTH the recent sub-budget and the shared tokenBudget.
+            const trustEntry = includeTrust ? buildTrustEntry(m, "recent") : null;
+            const trustCost = trustEntry ? estimateTokens(JSON.stringify(trustEntry)) : 0;
+            if (recentSpent + cost + trustCost > recentBudget) {
                 truncatedOwnIds.add(m.id); // #1207 — budget-skip; may still be admitted later via the task-relevant loop (deduped at the end)
                 continue;
             }
             sections.recent.push(line);
             includedOwnMemories.push(struct);
-            if (includeTrust)
-                includedTrustMemories.push({ m, section: "recent" });
-            recentSpent += cost;
-            tokenBudget -= cost;
+            if (trustEntry)
+                includedTrustMemories.push(trustEntry);
+            recentSpent += cost + trustCost;
+            tokenBudget -= cost + trustCost;
             includedOwnIds.add(m.id); // #1207 — count by unique own-memory id
         }
         // --- 3b. Subject-predicted context ---
@@ -787,16 +825,20 @@ export class BootstrapMemories extends Resource {
                 const line = formatMemory(m, agentId);
                 const struct = leanMemory(m, "predicted");
                 const cost = contentCost(struct, line); // #1199 (0.44.11) — charge what ships; see contentCost
-                if (predictedSpent + cost > predictedBudget) {
+                // flair#1199 trust-admission — charge the trust block's real serialized
+                // cost against BOTH the predicted sub-budget and the shared tokenBudget.
+                const trustEntry = includeTrust ? buildTrustEntry(m, "predicted") : null;
+                const trustCost = trustEntry ? estimateTokens(JSON.stringify(trustEntry)) : 0;
+                if (predictedSpent + cost + trustCost > predictedBudget) {
                     truncatedOwnIds.add(m.id); // #1207 — budget-skip (deduped against inclusions at the end)
                     continue;
                 }
                 sections.predicted.push(line);
                 includedPredicted.push(struct);
-                if (includeTrust)
-                    includedTrustMemories.push({ m, section: "predicted" });
-                predictedSpent += cost;
-                tokenBudget -= cost;
+                if (trustEntry)
+                    includedTrustMemories.push(trustEntry);
+                predictedSpent += cost + trustCost;
+                tokenBudget -= cost + trustCost;
                 includedOwnIds.add(m.id); // #1207 — count by unique own-memory id; also the task-relevant loop's exclusion set (no predicted→relevant double-admit)
             }
         }
@@ -985,7 +1027,13 @@ export class BootstrapMemories extends Resource {
                         }
                         : leanMemory(m, "relevant");
                     const cost = contentCost(struct, line);
-                    if (cost > tokenBudget) {
+                    // flair#1199 trust-admission — charge the trust block's real serialized
+                    // cost at the same moment as the content cost. The section (teammate vs
+                    // relevant) is decided by `m._source`, so build the entry with the right
+                    // section before the budget check.
+                    const trustEntry = includeTrust ? buildTrustEntry(m, m._source ? "teammate" : "relevant") : null;
+                    const trustCost = trustEntry ? estimateTokens(JSON.stringify(trustEntry)) : 0;
+                    if (cost + trustCost > tokenBudget) {
                         // flair#1207 — a size-skip in the score-ordered task-relevant loop
                         // is no longer silent: record it on the denominator matching the
                         // record's origin (own → truncatedOwnIds, teammate → the separate
@@ -1006,9 +1054,9 @@ export class BootstrapMemories extends Resource {
                         // memoriesIncluded — that different-denominator mix is what let
                         // included exceed available.
                         includedTeammateFindings.push(struct);
-                        if (includeTrust)
-                            includedTrustMemories.push({ m, section: "teammate" });
-                        tokenBudget -= cost;
+                        if (trustEntry)
+                            includedTrustMemories.push(trustEntry);
+                        tokenBudget -= cost + trustCost;
                         teammateFindingsIncluded++;
                     }
                     else {
@@ -1016,9 +1064,9 @@ export class BootstrapMemories extends Resource {
                         // flair#1182 — own task-relevant records join the `memories`
                         // container.
                         includedOwnMemories.push(struct);
-                        if (includeTrust)
-                            includedTrustMemories.push({ m, section: "relevant" });
-                        tokenBudget -= cost;
+                        if (trustEntry)
+                            includedTrustMemories.push(trustEntry);
+                        tokenBudget -= cost + trustCost;
                         includedOwnIds.add(m.id); // #1207 — count by unique own-memory id
                     }
                 }
@@ -1346,28 +1394,12 @@ export class BootstrapMemories extends Resource {
         // caller's own records. flair#1225 (0.44.11) — the null on a lifecycle
         // section is now SELF-EXPLAINING (matchQualityNote below), not just legible
         // via `section`.
-        const trust = includeTrust
-            ? includedTrustMemories.map(({ m, section }) => {
-                const block = buildTrustBlock(m);
-                // flair#1225 — Kern ruled (on #1220) that a null `matchQuality` on an
-                // own-recent (lifecycle) entry is CORRECT: lifecycle sections
-                // (permanent/recent/predicted) are a window LOAD, not a retrieval
-                // surface, so there is no similarity to band — the null means "not
-                // scored here", never a scoring failure on the caller's own records
-                // (the #1201 misread: own-recent null beside a teammate band). Behavior
-                // is unchanged (per Kern); this only makes the null self-describing in
-                // the payload — Fix 3's "any absent field says why" — so a connector
-                // reads it right without knowing the #1201 contract.
-                const matchQualityNote = block.matchQuality === null
-                    ? (LIFECYCLE_SECTIONS.has(section)
-                        ? `matchQuality is null because '${section}' is a lifecycle-window section, not a retrieval `
-                            + `surface — there is no relevance score to band. This is correct (per flair#1225), not a scoring failure.`
-                        : "matchQuality is null because no semantic similarity was attached to this result "
-                            + "(e.g. a by-id read or a keyword-only degraded match).")
-                    : undefined;
-                return { id: m.id, section, ...block, ...(matchQualityNote ? { matchQualityNote } : {}) };
-            })
-            : undefined;
+        // flair#1199 trust-admission — the trust entries were built (and their real
+        // serialized cost charged) at admission time via buildTrustEntry, so the
+        // response tail just ships them as-is. The #1225 matchQualityNote logic now
+        // lives in buildTrustEntry (single source of truth — the charged size and
+        // the shipped size can never drift).
+        const trust = includeTrust ? includedTrustMemories : undefined;
         // flair#744 slice 2 — opt-in abstention verdict for the task-relevance
         // surface. Present ONLY when `abstain` is requested (byte-identical to
         // pre-slice-2 otherwise); scoped to whether any memory covered

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/dist/resources/memory-durability.js

@@ -0,0 +1,40 @@
+/**
+ * ─── The single "is this a valid durability" writer-intent guard ────────────
+ *
+ * Mirror of resources/memory-visibility.ts's assertValidVisibility, for the
+ * durability enum. Same asymmetry, same reason:
+ *
+ *   - READING an unknown durability must be permissive. A row written before a
+ *     tier existed (or by a non-Python adapter) may hold anything, and the read
+ *     side must keep resolving it exactly as before — defaultVisibilityForDurability
+ *     treats any non-permanent/persistent string as the private branch, and that
+ *     fail-safe must not change.
+ *   - WRITING an unknown durability must be refused. Today an unknown value via
+ *     raw REST (or a future non-Python adapter) is silently accepted and lands on
+ *     the narrower private branch by accident — fail-safe, but unvalidated by
+ *     contract. Refusing at the schema boundary makes it safe by construction and
+ *     makes adk-flair's "validated server-side" claim true as written (flair#1238,
+ *     from Sherlock's #1237 review).
+ *
+ * Deliberately has ZERO imports — same load-bearing reason as memory-visibility.ts:
+ * this module is a pure function + constant that any caller can import without
+ * dragging in "harper".
+ */
+/** The only values a WRITER may supply. */
+export const WRITABLE_DURABILITIES = ["permanent", "persistent", "standard", "ephemeral"];
+/**
+ * Reject a durability a writer supplied that is not one of the four valid values.
+ * Returns an error message, or null when the value is acceptable.
+ *
+ * `undefined`/`null` are accepted: omitting the field is how a caller asks for
+ * the default ("standard"), and that is a documented, intentional path.
+ */
+export function assertValidDurability(durability) {
+    if (durability === undefined || durability === null)
+        return null;
+    if (typeof durability === "string" && WRITABLE_DURABILITIES.includes(durability)) {
+        return null;
+    }
+    return (`durability must be ${WRITABLE_DURABILITIES.map((v) => `"${v}"`).join(" or ")} ` +
+        `(got: ${JSON.stringify(durability)}). Omit it to use the default "standard".`);
+}

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.11",
+  "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",