Adopt FamiliarOS GitNexus refactor lane

.gitignore

@@ -9,6 +9,7 @@ apps/desktop/dist-electron
 *.tsbuildinfo
 .DS_Store
 local/
+local-tools/
 .slim/deepwork/
 docs
 !website/docs
@@ -17,3 +18,4 @@ MERGE_NOTES.md
 NEW_FILES.txt
 PULL_REQUEST.md
 README_OUR_CHANGES.md
+.gitnexus

FEATURE_REGISTRY.md

@@ -27,6 +27,7 @@ This is the canonical feature registry for the FamiliarOS working repo. It maps
 | FamiliarOS rebrand | **merged** | `feat/familiaros-rebrand` | current | repo-wide | App identity, package scopes, plugin IDs, state filenames, preload names, and user-facing strings updated from OpenPets to FamiliarOS. |
 | Custom Familiar name | **merged** | `feat/familiaros-rebrand` | current | `apps/desktop/src/app-state.ts`, `apps/desktop/src/tray.ts`, `apps/desktop/src/renderer/src/main.tsx` | User-defined name for the default Familiar appears in tray tooltip and context menu. |
 | Curated familiar catalog safety | **merged** | `feat/familiaros-rebrand` | current | `apps/desktop/src/catalog.ts`, `apps/desktop/src/catalog-validation.ts`, `apps/desktop/catalog.v2.fixture.json`, `apps/desktop/contracts/catalog-fixture.contract.ts` | Curated catalog metadata now preserves `original` / `featured` / category fields end-to-end, uses IP-safer FamiliarOS fixture familiars, and keeps surfaceable pagination totals aligned with the real searchable set. |
+| Control Center bridge hardening | **merged** | `feat/familiaros-rebrand` | current | `apps/desktop/src/renderer/src/main.tsx`, `apps/desktop/tests/plugin-ui-static.test.ts` | The Control Center API bridge now resolves to a required `ControlCenterApi` once at startup instead of leaking optionality through the whole renderer, and the static validation was updated to the stricter bridge shape. |
 
 ## 2. Floating chat / prompt window
 

apps/desktop/src/renderer/src/main.tsx

@@ -209,10 +209,17 @@ const apiBridge = window as unknown as {
   openPetsControlCenter?: ControlCenterApi;
 };
 
-const api = apiBridge.familiarOSControlCenter ?? apiBridge.openPetsControlCenter;
+const api = resolveControlCenterApi(apiBridge);
 
-if (!api) {
-  throw new Error("FamiliarOS Control Center bridge is unavailable.");
+function resolveControlCenterApi(bridge: {
+  familiarOSControlCenter?: ControlCenterApi;
+  openPetsControlCenter?: ControlCenterApi;
+}): ControlCenterApi {
+  const resolved = bridge.familiarOSControlCenter ?? bridge.openPetsControlCenter;
+  if (!resolved) {
+    throw new Error("FamiliarOS Control Center bridge is unavailable.");
+  }
+  return resolved;
 }
 
 const openApiEndpointPresets: readonly OpenApiEndpointPreset[] = [

apps/desktop/tests/plugin-ui-static.test.ts

@@ -45,7 +45,9 @@ assert.doesNotMatch(controlCenterRendererSource, /OnboardingView|currentRoute ==
 assert.match(controlCenterRendererSource, /materializeListItemDefaults/);
 assert.match(controlCenterRendererSource, /updateCatalogEntry[\s\S]*api\.updateCatalogPlugin/);
 assert.match(controlCenterRendererSource, /installed\.source === "catalog"[\s\S]*updateCatalogEntry/);
-assert.match(controlCenterRendererSource, /familiarOSControlCenter \?\? apiBridge\.openPetsControlCenter/);
+assert.match(controlCenterRendererSource, /const api = resolveControlCenterApi\(apiBridge\);/);
+assert.match(controlCenterRendererSource, /function resolveControlCenterApi\(/);
+assert.match(controlCenterRendererSource, /bridge\.familiarOSControlCenter \?\? bridge\.openPetsControlCenter/);
 
 assert.match(jsHostSource, /FamiliarOSPlugin[\s\S]*register/);
 assert.match(jsHostSource, /start\(sdk\)/);

docs/ops/FAMILIAROS_GITNEXUS_AND_SENTRUX_REFACTORING_BASELINE_2026-06-18.md

@@ -4,8 +4,9 @@
 
 ## Purpose
 
-Record the safe FamiliarOS interpretation of the Scriptorium-root GitNexus and
-Sentrux surfaces requested for codebase refactoring and hardening work.
+Record the safe FamiliarOS interpretation of the Scriptorium-root analyzer
+surfaces and the actual 2026-06-18 GitNexus local-tool adoption path used for
+FamiliarOS refactoring work.
 
 ## Verified Surfaces
 
@@ -15,7 +16,9 @@ Inside `/home/dev/src/ScriptoriumAI`, the relevant root-level analyzer surfaces
 - `.sentrux/rules.toml`
 - `sentrux.exe`
 
-These are distinct from the donor/runtime-oriented `mirrors/GitNexus` repo.
+These are distinct from the actual GitNexus tool repo under:
+
+- `/home/dev/src/ScriptoriumAI/mirrors/GitNexus`
 
 ## GitNexus Interpretation Rule
 
@@ -30,6 +33,30 @@ Safe FamiliarOS rule:
 2. do not trust donor `meta.json` or donor graph blobs as current FamiliarOS truth
 3. regenerate FamiliarOS-specific GitNexus state from the repaired high-load workflow when deeper graph analysis is needed
 
+## Actual GitNexus Tool Adoption
+
+The tool repo used for FamiliarOS was **not** the donor `.gitnexus` index.
+
+Instead, this pass cloned the actual GitNexus repo from:
+
+- `/home/dev/src/ScriptoriumAI/mirrors/GitNexus`
+
+into the FamiliarOS-local tool lane:
+
+- `/home/dev/src/FamiliarOS/local-tools/GitNexus`
+
+Important implementation notes:
+
+- the local clone used the Scriptorium mirror `main` branch, which includes the
+  indexed-guidance refresh on top of upstream
+- the stack-overflow hardening already exists in the adopted tool history at
+  commit `9eeb20b` (`replace Array.push(...spread) with loop to prevent stack overflow`)
+- copied `node_modules` from the donor working tree were **not** safe to reuse
+  because the local GitNexus run initially failed with `invalid ELF header`
+  from `@ladybugdb/core`
+- the correct recovery was to rebuild the local FamiliarOS clone with native
+  Linux dependencies instead of trusting donor binary artifacts
+
 ## Sentrux Interpretation Rule
 
 The useful transferable part of the root Scriptorium Sentrux surface is the
@@ -41,12 +68,48 @@ ruleset that reflects the monorepo's real layers and boundaries.
 ## FamiliarOS Operating Pattern
 
 1. establish or refresh the FamiliarOS-specific `.sentrux` baseline
-2. use repo-local `.gitnexus/` as scaffold only
-3. regenerate a true FamiliarOS GitNexus index before large graph-backed refactor work
-4. treat GitNexus conclusions as analysis support, not as first-party runtime dependency
+2. keep `/home/dev/src/FamiliarOS/local-tools/GitNexus` as the local GitNexus
+   tool surface
+3. use repo-local `.gitnexus/` inside FamiliarOS as generated index state, not
+   as the tool itself
+4. regenerate a true FamiliarOS GitNexus index before large graph-backed
+   refactor work
+5. treat GitNexus conclusions as analysis support, not as first-party runtime
+   dependency
+
+## Current FamiliarOS Index Result
+
+The 2026-06-18 local GitNexus analyze run against `/home/dev/src/FamiliarOS`
+completed successfully and produced:
+
+- `10,383` nodes
+- `26,845` edges
+- `732` clusters
+- `300` flows
+
+Status check after indexing:
+
+- repository: `FamiliarOS`
+- indexed commit: `edfad05`
+- current commit at time of status check: `edfad05`
+- state: `up-to-date`
+
+The resulting FamiliarOS-local generated index now lives in:
+
+- `/home/dev/src/FamiliarOS/.gitnexus/`
 
 ## Current Conclusion
 
-This pass imported the **workflow and scaffold posture** from the Scriptorium
-project root while explicitly rejecting the unsafe shortcut of treating the
-donor `.gitnexus` payload itself as current FamiliarOS analysis truth.
+This pass moved FamiliarOS from "tooling posture only" to a real local analyzer
+lane:
+
+- Sentrux is now represented by a FamiliarOS-specific rules file
+- GitNexus now exists as a FamiliarOS-local tool clone
+- the FamiliarOS repo has been indexed with native local binaries
+- the donor `.gitnexus` payload is still rejected as current truth
+- the correct GitNexus interpretation is now operational rather than merely
+  advisory
+
+For the FamiliarOS-branded GitNexus refactor procedure, read:
+
+- `docs/ops/FAMILIAROS_GITNEXUS_REFACTORING_WORKFLOW_2026-06-18.md`

docs/ops/FAMILIAROS_GITNEXUS_REFACTORING_WORKFLOW_2026-06-18.md

@@ -0,0 +1,120 @@
+# FamiliarOS GitNexus Refactoring Workflow
+
+**Date:** 2026-06-18
+
+## Purpose
+
+Translate the GitNexus refactoring skill into a FamiliarOS-owned operating
+workflow for safe renames, extractions, splits, and renderer/runtime cleanup.
+
+This is not a copy-paste donor skill file. It is the FamiliarOS refactor lane
+that uses the local GitNexus tool surface and the current FamiliarOS index.
+
+## Local Tool Surface
+
+Current local tool path:
+
+- `/home/dev/src/FamiliarOS/local-tools/GitNexus`
+
+Current indexed repo name:
+
+- `FamiliarOS`
+
+When multiple repos are in the GitNexus registry, always pass:
+
+- `-r FamiliarOS`
+
+Otherwise the CLI may resolve against the wrong indexed repo.
+
+## When To Use GitNexus In FamiliarOS
+
+Use GitNexus when the task involves:
+
+- renaming a symbol safely across multiple files
+- extracting code from the giant Control Center renderer
+- splitting a service or route into smaller modules
+- checking blast radius before touching shared desktop/package surfaces
+- confirming whether a refactor is isolated or cross-lane
+
+## FamiliarOS Refactor Sequence
+
+1. identify the target symbol or concept
+2. run `query` to find the relevant flow or file cluster
+3. run `context` on the target symbol to inspect incoming and outgoing refs
+4. run `impact` before editing to estimate blast radius
+5. make the bounded code change
+6. rerun FamiliarOS validation for the affected lane
+7. if the change is substantial, rerun `analyze` so the FamiliarOS index is fresh again
+
+## Core Commands
+
+From `/home/dev/src/FamiliarOS`:
+
+```bash
+node local-tools/GitNexus/gitnexus/dist/cli/index.js status
+node local-tools/GitNexus/gitnexus/dist/cli/index.js analyze /home/dev/src/FamiliarOS --skip-agents-md
+node local-tools/GitNexus/gitnexus/dist/cli/index.js query -r FamiliarOS "control center bridge"
+node local-tools/GitNexus/gitnexus/dist/cli/index.js context -r FamiliarOS -f apps/desktop/src/renderer/src/main.tsx resolveControlCenterApi
+node local-tools/GitNexus/gitnexus/dist/cli/index.js impact -r FamiliarOS --depth 2 resolveControlCenterApi
+```
+
+## FamiliarOS-Specific Risk Rules
+
+### Low-risk
+
+- a helper extraction that remains file-local
+- a type-hardening fix that removes false optionality
+- a renderer-only structural cleanup with no IPC contract change
+
+### Medium-risk
+
+- a rename across renderer, preload, and main-process boundaries
+- a refactor that changes plugin/runtime interfaces
+- changes touching package contracts consumed by multiple surfaces
+
+### High-risk
+
+- edits to IPC route names or payload shape
+- changes to plugin manifest/runtime contracts
+- changes to MCP server tool names, structured content, or CLI surface
+- changes to state-file migration or familiar installation layout
+
+## Applied Example: Control Center Bridge Hardening
+
+This packet used GitNexus on the Control Center renderer bridge area after the
+local FamiliarOS index was built.
+
+Observed result:
+
+- `resolveControlCenterApi` was found in
+  `apps/desktop/src/renderer/src/main.tsx`
+- upstream impact came back as `LOW`
+- the change stayed isolated to the renderer file plus the static test that
+  asserted the old bridge shape
+
+That made the fix an appropriate bounded refactor:
+
+- resolve the bridge once
+- return a required `ControlCenterApi`
+- update the static assertion to the new stricter bridge pattern
+- rerun desktop `check`
+
+## What Not To Do
+
+- do not treat the donor `.gitnexus/meta.json` as if it were the tool
+- do not run multi-repo GitNexus commands without `-r FamiliarOS` once multiple
+  repos are indexed
+- do not trust copied native `node_modules` binaries from another working tree
+- do not treat GitNexus output as a replacement for tests
+
+## Validation Rule
+
+GitNexus is the graph and blast-radius assistant.
+
+FamiliarOS tests and package checks remain the truth gate after the edit.
+
+For desktop renderer/control-center work, the default closeout command is:
+
+```bash
+pnpm --filter @familiaros/desktop check
+```