feat(hardening): taglines, MCP Toolkit Guide rebrand, Windows bubble fix, name test

- Rename UI panel to "MCP Toolkit Guide" with a plainer description. - Apply taglines to README.md and package.json descriptions. - Gate pinned-bubble backdrop-filter on Windows to avoid gray rectangles. - Add packaging-contract assertions for pinned bubble and new description. - Add custom-familiar-name.test.ts covering normalizeFamiliarName. - Sync docs (FEATURES, README_OUR_CHANGES, FEATURES_OUR_CHANGES, PULL_REQUEST, FEATURE_REGISTRY, bug-squashing, rebrand plan, pr-chat-memory-mcp-toolkit).
2026-06-17 06:01:15 +00:00 · 2026-06-17 06:01:15 +00:00 · 4d99cd32fe
commit 4d99cd32fe
parent 9bf7ca2210
13 changed files with 53 additions and 30 deletions
--- a/FEATURES.md
+++ b/FEATURES.md
@ -5,7 +5,7 @@ It combines:

 - the shipped baseline described in `README.md`
 - the chat, memory, and prompt-window work from this implementation thread
- the curated MCP toolkit surface added in the desktop app
+- the MCP Toolkit Guide surface added in the desktop app

 > Looking for an isolated view of only our additions? See:
 > - [`FEATURES_OUR_CHANGES.md`](FEATURES_OUR_CHANGES.md)
@ -249,9 +249,9 @@ The MCP Tool Servers panel gives the built-in floating chat the ability to do re
 - Tools run through an internal stdio MCP client in the main process
 - Supported tools: filesystem, terminal, memory, fetch-web, sequential-thinking, playwright, git, github, docker, sqlite

-## Curated MCP Toolkit Surface
+## MCP Toolkit Guide Surface

-The control-center Integrations page includes a **Curated MCP Toolkit** panel. It is not an automatic installer; it is a permission-aware reference that explains what popular MCP tools do, what permissions they need, and how to set them up manually or as a persistent bundle in supported hosts. Each entry includes copy-paste snippets and guidance so you can adopt the MCP ecosystem deliberately.
+The control-center Integrations page includes an **MCP Toolkit Guide** panel. It is not an automatic installer; it is a hand-picked reference that explains what popular MCP tools do, what permissions they need, and how to set them up manually or as a persistent bundle in supported hosts. Each entry includes copy-paste snippets and guidance so you can adopt the MCP ecosystem deliberately.

 ### Starter Stack In The Toolkit

--- a/FEATURES_OUR_CHANGES.md
+++ b/FEATURES_OUR_CHANGES.md
@ -87,10 +87,10 @@ This document lists only the features, UI surfaces, and capabilities added by ou
 - One-click **Test Server** health check.
 - One-click **Copy MCP JSON** for external hosts.

-## Curated MCP Toolkit Integration
+## MCP Toolkit Guide Integration

- Curated MCP Toolkit panel inside Control Center → Integrations.
- Permission-aware reference surface, not an automatic installer.
+- MCP Toolkit Guide panel inside Control Center → Integrations.
+- Hand-picked reference surface, not an automatic installer.
 - Each entry explains what the tool does, what permissions it needs, and how to set it up manually or as a persistent bundle in supported hosts.
 - Multi-select chips by tier (Starter, Terminal & Systems, Advanced).
 - Copy-paste snippets and docs links for deliberate adoption.
--- a/FEATURE_REGISTRY.md
+++ b/FEATURE_REGISTRY.md
@ -103,7 +103,7 @@ This is the canonical feature registry for the VectorShell working fork of Famil
 | Server health test | shipped | main PR | current | `apps/desktop/src/agent-setup.ts`, `apps/desktop/src/windows.ts` | `--version` smoke test via IPC. |
 | MCP JSON copy | shipped | main PR | current | `apps/desktop/src/renderer/src/main.tsx` | One-click copy of the `mcpServers.familiaros` entry. |

-### 6d. Curated MCP Toolkit
+### 6d. MCP Toolkit Guide

 | Feature | Status | PR / Branch | Key commits | Key files | Notes |
 |---------|--------|-------------|-------------|-----------|-------|
--- a/PULL_REQUEST.md
+++ b/PULL_REQUEST.md
@ -1,6 +1,6 @@
-# Pull Request: FamiliarOS Rebrand, Custom Familiar Naming, Floating Chat, Memory, Knowledge Store, MCP Servers, Curated MCP Toolkit, TTS Phase 2 & Familiar Sizing
+# Pull Request: FamiliarOS Rebrand, Custom Familiar Naming, Floating Chat, Memory, Knowledge Store, MCP Servers, MCP Toolkit Guide, TTS Phase 2 & Familiar Sizing

-**Title:** feat(desktop): rebrand to FamiliarOS, add custom Familiar naming, floating chat, local memory, Knowledge Store, MCP Tool Servers, FamiliarOS MCP Server panel, Curated MCP Toolkit, Text-to-Speech Phase 2, expanded familiar sizing, and multi-screen support
+**Title:** feat(desktop): rebrand to FamiliarOS, add custom Familiar naming, floating chat, local memory, Knowledge Store, MCP Tool Servers, FamiliarOS MCP Server panel, MCP Toolkit Guide, Text-to-Speech Phase 2, expanded familiar sizing, and multi-screen support

 **Author:** VectorShell working fork
 **Base:** upstream `main` at `cba81b7`
@ -112,7 +112,7 @@ This PR adds the FamiliarOS rebrand from OpenPets, a user-editable custom Famili

 ### Updated files

- `README.md` — added floating chat, memory, MCP Tool Servers, FamiliarOS MCP Server, and Curated MCP Toolkit bullets.
+- `README.md` — added floating chat, memory, MCP Tool Servers, FamiliarOS MCP Server, and MCP Toolkit Guide bullets.
 - `FEATURES.md` — comprehensive inventory of new capabilities.
 - `docs/pr-chat-memory-mcp-toolkit.md` — implementation explainer.
 - `docs/phases/phase-14-familiar-scale-setting.md` — expanded with new sizes and drag resize.
@ -164,7 +164,7 @@ All existing tests pass. Additional manual verification:
 5. Open Settings > Memory — the memory should be searchable, editable, and deletable.
 6. Open Integrations > MCP Tool Servers — activate Filesystem + Fetch/Web, then chat "list my home directory files" — tools should run.
 7. Open Integrations > FamiliarOS MCP Server — choose a command mode, click Test Server, and verify the server responds.
-8. Open Integrations > Curated MCP Toolkit to browse copy-paste snippets and optional persistent bundles.
+8. Open Integrations > MCP Toolkit Guide to browse copy-paste snippets and optional persistent bundles.
 9. Open Settings > Text-to-Speech, choose System voice, click **Speak** — the familiar should speak the test phrase.
 10. Add an OpenAI TTS key, select a voice, click **Speak** — audio should play through the familiar window.
 11. Store a `.txt` file in Settings > Knowledge Store and ask the assistant about its content — the reply should reference the stored file.
--- a/README.md
+++ b/README.md
@ -3,19 +3,19 @@
 </p>

 <p align="center">
-  <strong>Your AI Companion That Lives With You.</strong>
+  <strong>Create your Familiar.</strong>
 </p>

 <p align="center">
-  Most AI assistants live in a browser tab. Most AI agents live in a terminal. <strong>FamiliarOS lives on your desktop.</strong>
+  Your Familiar remembers, speaks, and acts across your system.
 </p>

 <p align="center">
-  At its heart is your <strong>Familiar</strong>: a persistent AI companion that remembers who you are, learns your preferences, speaks with you, helps with everyday tasks, and can grow into a powerful local agent with access to tools, knowledge, and workflows.
+  <sub>A local-first AI companion with memory, voice, knowledge, and tools.</sub>
 </p>

 <p align="center">
-  <sub>This fork includes a <strong>floating chat surface</strong>, <strong>local memory</strong>, <strong>Knowledge Store</strong>, <strong>MCP Tool Servers</strong>, a <strong>FamiliarOS MCP Server</strong> panel, a <strong>Curated MCP Toolkit</strong>, <strong>Text-to-Speech</strong>, <strong>Familiar naming</strong>, and <strong>expanded familiar sizing</strong>. See <code>FEATURES.md</code>, <code>FEATURE_REGISTRY.md</code>, and <code>PULL_REQUEST.md</code> for details.</sub>
+  <sub>This fork includes a <strong>floating chat surface</strong>, <strong>local memory</strong>, <strong>Knowledge Store</strong>, <strong>MCP Tool Servers</strong>, a <strong>FamiliarOS MCP Server</strong> panel, an <strong>MCP Toolkit Guide</strong>, <strong>Text-to-Speech</strong>, <strong>Familiar naming</strong>, and <strong>expanded familiar sizing</strong>. See <code>FEATURES.md</code>, <code>FEATURE_REGISTRY.md</code>, and <code>PULL_REQUEST.md</code> for details.</sub>
 </p>

 <p align="center">
@ -39,6 +39,8 @@ FamiliarOS is a **local-first AI companion platform**.

 Create your own Familiar: a persistent desktop companion with memory, voice, knowledge, and powerful agent capabilities.

+> **Not just an assistant. A Familiar.**
+
 Your Familiar can:

 - 🧠 **Remember** preferences, facts, notes, identities, and important details across sessions.
@ -119,7 +121,7 @@ The best software creates habits. The best companions create relationships.
 - **Voice** — system voices, OpenAI TTS, ElevenLabs, Piper, or OpenAI-compatible endpoints for speech input and output.
 - **MCP Tool Servers** — activate filesystem, terminal, web, Git, GitHub, Docker, Playwright, SQLite, memory, and reasoning tools directly from chat.
 - **FamiliarOS MCP Server** — external agents (Claude Code, Cursor, OpenCode, Codex CLI) can control your Familiar through a safe, limited tool surface.
- **Curated MCP Toolkit** — a permission-aware reference surface for adopting the broader MCP ecosystem safely.
+- **MCP Toolkit Guide** — a hand-picked guide to popular MCP tools: what each does, what permissions it needs, and how to add it yourself. Nothing installs automatically.
 - **Virtual-Familiar status** — hunger, energy, happiness, bond, mood, and level live in the right-click context menu, never blocking chat clicks.
 - **Privacy-conscious by design** — automatic hook speech is static and local; prompts, code, logs, command output, URLs, paths, and secrets are not shown in bubbles.

@ -179,9 +181,9 @@ The **MCP Tool Servers** panel lets the built-in floating chat do real work. Tur

 The **FamiliarOS MCP Server** panel exposes your Familiar to Claude Code, Cursor, OpenCode, Codex CLI, or any other MCP-capable host. Those agents can then make your Familiar react, speak a safe bubble, or read/write memory. This is a small, controlled bridge — external agents do not get unrestricted access to your desktop.

-### Curated MCP Toolkit — a safe manual for the wider MCP world
+### MCP Toolkit Guide — a safe manual for the wider MCP world

-The **Curated MCP Toolkit** is not an automatic installer. It is a curated reference that explains what popular MCP tools do, what permissions they need, and how to set them up manually or as a persistent bundle in supported hosts. It is designed so you can adopt the MCP ecosystem deliberately instead of clicking "install everything."
+The **MCP Toolkit Guide** is not an automatic installer. It is a hand-picked reference that explains what popular MCP tools do, what permissions they need, and how to set them up manually or as a persistent bundle in supported hosts. It is designed so you can adopt the MCP ecosystem deliberately instead of clicking "install everything."

 ---

--- a/README_OUR_CHANGES.md
+++ b/README_OUR_CHANGES.md
@ -52,9 +52,9 @@ The **FamiliarOS MCP Server** panel exposes your Familiar to Claude Code, Cursor
 - One-click **Copy MCP JSON** for pasting into your agent's MCP configuration.
 - This is a small, controlled bridge: external agents can make your Familiar react, speak a safe bubble, or read/write memory, but they do not get unrestricted access to your desktop.

-## New: Curated MCP Toolkit — A Safe Manual for the Wider MCP World
+## New: MCP Toolkit Guide — A Safe Manual for the Wider MCP World

-The **Curated MCP Toolkit** is a permission-aware reference surface for adopting the broader MCP ecosystem deliberately.
+The **MCP Toolkit Guide** is a hand-picked reference surface for adopting the broader MCP ecosystem deliberately.

 - It is **not** an automatic installer; it explains what popular MCP tools do, what permissions they need, and how to set them up manually.
 - Each entry includes copy-paste snippets and guidance for supported hosts.
@ -110,4 +110,4 @@ No additional setup is required beyond the normal FamiliarOS desktop app. The ne
 - Settings → Knowledge Store for file-based knowledge.
 - Integrations → MCP Tool Servers for built-in chat tool activation.
 - Integrations → FamiliarOS MCP Server for external-agent bridge configuration.
- Integrations → Curated MCP Toolkit for optional persistent bundles and copy-paste snippets.
+- Integrations → MCP Toolkit Guide for optional persistent bundles and copy-paste snippets.
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@ -2,11 +2,11 @@
  "name": "@familiaros/desktop",
  "version": "3.1.0",
  "private": true,
-  "description": "FamiliarOS tray-first desktop companion app.",
+  "description": "Create your Familiar. A local-first AI companion with memory, voice, knowledge, and tools.",
  "license": "MIT",
  "repository": {
    "type": "git",
-    "url": "git+https://github.com/alvinunreal/familiaros.git",
+    "url": "git+https://github.com/verticaltension/familiaros.git",
    "directory": "apps/desktop"
  },
  "author": "FamiliarOS",
--- a/apps/desktop/src/check-packaging-contract.ts
+++ b/apps/desktop/src/check-packaging-contract.ts
@ -16,7 +16,7 @@ const workspaceConfig = readFileSync(join(repoRoot, "pnpm-workspace.yaml"), "utf
 const builderConfigPath = join(appDir, "electron-builder.yml");
 const builderConfig = readFileSync(builderConfigPath, "utf8");

-assert.equal(packageJson.description, "FamiliarOS tray-first desktop companion app.");
+assert.equal(packageJson.description, "Create your Familiar. A local-first AI companion with memory, voice, knowledge, and tools.");
 assert.equal(packageJson.author, "FamiliarOS");
 assert.match(packageJson.scripts?.["dev:debug"] ?? "", /FAMILIAROS_LOG_LEVEL=debug FAMILIAROS_LOG_CONSOLE=1 pnpm dev/, "desktop debug dev script must enable verbose log mirroring.");
 assert.match(packageJson.scripts?.package ?? "", /node scripts\/clean-package-output\.cjs && electron-builder/);
@ -152,6 +152,7 @@ assert.match(petWindowSource, /next\.catch\(\(\) => \{\}\)\.finally/, "familiar
 assert.match(petWindowSource, /destroyed-after-write/, "familiar content reloads must re-check destroyed windows after writing HTML.");
 assert.match(petWindowSource, /process\.platform === "win32" \? "none" : "drop-shadow/, "Windows familiar windows must avoid CSS drop-shadow on transparent layered windows.");
 assert.match(petWindowSource, /process\.platform === "win32" \? "none" : "blur\(10px\)"/, "Windows familiar windows must avoid backdrop-filter on transparent layered windows.");
+assert.match(petWindowSource, /\.bubble\.is-pinned \{[\s\S]*?backdrop-filter: \$\{process\.platform === "win32" \? "none" : "blur\(8px\)"\}/, "Windows pinned bubbles must avoid backdrop-filter on transparent layered windows.");
 assert.match(petWindowSource, /\.familiar-shell[\s\S]*?-webkit-app-region: no-drag; cursor: grab;/, "familiar dragging must avoid Electron draggable regions so right-click context menus work.");
 assert.match(petPreloadSource, /familiaros:familiar-hit-test/, "familiar preload must report visible familiar and bubble hit testing for passthrough.");
 assert.match(petPreloadSource, /familiaros:familiar-ready/, "familiar preload must report readiness after installing mouse handlers.");
--- a/apps/desktop/src/familiar-window.ts
+++ b/apps/desktop/src/familiar-window.ts
@ -1121,7 +1121,7 @@ function createPetWindowCss(paused: boolean, scale: PetScaleValue, layout?: Part
      border: 1px solid rgba(255, 255, 255, 0.7);
      border-radius: 12px;
      box-shadow: 0 4px 10px rgba(15, 23, 42, 0.08), 0 1px 3px rgba(15, 23, 42, 0.04), inset 0 1px 0 rgba(255, 255, 255, 0.5);
-      backdrop-filter: blur(8px);
+      backdrop-filter: ${process.platform === "win32" ? "none" : "blur(8px)"};
      text-align: center;
      max-height: none;
      max-width: none;
--- a/apps/desktop/src/i18n/locales/en.ts
+++ b/apps/desktop/src/i18n/locales/en.ts
@ -566,8 +566,8 @@ export const en = {
  "integrations.familiarosMcpServer.testError": "Server test failed: {error}",
  "integrations.familiarosMcpServer.copyMcpJson": "Copy MCP JSON",
  "integrations.familiarosMcpServer.status": "Ready",
-  "integrations.curatedToolkit.name": "Curated MCP Toolkit",
-  "integrations.curatedToolkit.description": "A permission-aware reference for the wider MCP ecosystem. Browse what popular tools do, what access they need, and how to set them up manually or as a persistent bundle. This is not an automatic installer.",
+  "integrations.curatedToolkit.name": "MCP Toolkit Guide",
+  "integrations.curatedToolkit.description": "A hand-picked guide to popular MCP tools. See what each tool does, what permissions it needs, and copy the setup snippet if you want to add it to your agent. Nothing installs automatically.",
  "integrations.linkToCentralPanel": "Configure the external-agent bridge in the panel above.",

  // --- Settings: Language section (renderer) ---
--- a/apps/desktop/tests/custom-familiar-name.test.ts
+++ b/apps/desktop/tests/custom-familiar-name.test.ts
@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+
+import { normalizeFamiliarName } from "../src/app-state.js";
+
+assert.equal(normalizeFamiliarName("Mochi"), "Mochi");
+assert.equal(normalizeFamiliarName("  Mochi  "), "Mochi");
+assert.equal(normalizeFamiliarName("A".repeat(64)), "A".repeat(64));
+assert.equal(normalizeFamiliarName("A".repeat(65)), "A".repeat(64));
+assert.equal(normalizeFamiliarName(""), undefined);
+assert.equal(normalizeFamiliarName("   "), undefined);
+assert.equal(normalizeFamiliarName("Mochi\n"), undefined);
+assert.equal(normalizeFamiliarName("Mochi\x00"), undefined);
+assert.equal(normalizeFamiliarName("\x7f"), undefined);
+assert.equal(normalizeFamiliarName(undefined), undefined);
+assert.equal(normalizeFamiliarName(null), undefined);
+assert.equal(normalizeFamiliarName(123), undefined);
+assert.equal(normalizeFamiliarName({}), undefined);
+
+console.log("Custom Familiar name validation passed.");
--- a/docs/bug-squashing.md
+++ b/docs/bug-squashing.md
@ -68,7 +68,7 @@ Useful references:

 Try these in order:

-1. Gate/remove `backdrop-filter` on Windows.
+1. Gate/remove `backdrop-filter` on Windows (including `.bubble.is-pinned`).
 2. Gate/remove or simplify `.familiar-shell` `drop-shadow` on Windows.
 3. Delay showing the familiar until first successful load/render (`ready-to-show` or an explicit renderer-ready signal).
 4. If still broken, test Windows-specific GPU/compositor mitigations. Do **not** start with global `app.disableHardwareAcceleration()` unless the safer CSS/lifecycle fixes fail, because it may vary by machine and can regress other rendering.
@ -87,6 +87,7 @@ Ask Windows testers to confirm:
 | Date | Version/Build | Attempt | Local result | Community result | Notes |
 | --- | --- | --- | --- | --- | --- |
 | 2026-05-14 | unreleased | Gate Windows `.familiar-shell` `drop-shadow` and `.bubble` `backdrop-filter` to `none` | Pending checks | Pending | First low-risk compositor mitigation; needs Windows tester confirmation. |
+| 2026-06-17 | unreleased | Also gate `.bubble.is-pinned` `backdrop-filter` on Windows; add packaging contract assertion | Implemented | Pending | Extends compositor mitigation to pinned plugin bubbles; tracked in `check-packaging-contract.ts`. |

 ---

--- a/package.json
+++ b/package.json
@ -2,11 +2,11 @@
  "name": "familiaros-v2-workspace",
  "version": "3.1.0",
  "private": true,
-  "description": "FamiliarOS 2.0 workspace",
+  "description": "FamiliarOS — create your Familiar. A local-first AI companion with memory, voice, knowledge, and tools.",
  "license": "MIT",
  "repository": {
    "type": "git",
-    "url": "git+https://github.com/alvinunreal/familiaros.git"
+    "url": "git+https://github.com/verticaltension/familiaros.git"
  },
  "type": "module",
  "packageManager": "pnpm@11.0.8",