scriptoriumadmin/openpetswithchatandmcp
1
0
Fork 0
Code Issues Pull requests 6 Projects Releases Packages Wiki Activity Actions

Consolidate FamiliarOS workflows and harden catalog surfaces

Browse source
This commit is contained in:
OpenPets Dev 2026-06-18 02:12:31 +00:00
parent bb915ddc55
commit edfad055a0
38 changed files with 3248 additions and 148 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.gitnexus/.gitignore vendored Normal file
View file

@ -0,0 +1 @@
*

78
.sentrux/rules.toml Normal file
View file

@ -0,0 +1,78 @@
[constraints]
no_god_files = true
[scan]
exclude = [
"node_modules",
"dist",
"dist/**",
"**/dist/**",
"build",
"build/**",
"**/build/**",
"coverage",
"coverage/**",
"**/coverage/**",
".test-dist",
".test-dist/**",
"**/.test-dist/**",
"dist-electron",
"dist-electron/**",
"dist-electron-win",
"dist-electron-win/**",
"website/dist",
"website/dist/**",
"website/coverage",
"website/coverage/**"
]
[[layers]]
name = "shared-packages"
paths = [
"packages/*/src/*"
]
order = 0
[[layers]]
name = "desktop-runtime"
paths = [
"apps/desktop/src/*",
"apps/desktop/contracts/*",
"apps/desktop/tests/*"
]
order = 1
[[layers]]
name = "plugin-runtime"
paths = [
"plugins/official/*/*"
]
order = 2
[[layers]]
name = "website-runtime"
paths = [
"website/src/*",
"website/server/*"
]
order = 3
[[boundaries]]
from = "website/src/*"
to = "apps/desktop/src/*"
reason = "The public site must not directly import Electron desktop runtime code. Shared logic belongs in packages or explicit API contracts."
[[boundaries]]
from = "website/src/*"
to = "plugins/official/*"
reason = "The public site must not depend on packaged plugin runtime internals."
[[boundaries]]
from = "packages/*/src/*"
to = "apps/desktop/src/*"
reason = "Reusable packages should remain host-agnostic and must not import desktop app internals."
[[boundaries]]
from = "plugins/official/*"
to = "apps/desktop/src/*"
reason = "Official plugins must bind through the plugin SDK and host contracts, not desktop private modules."

3
FEATURE_REGISTRY.md
View file

@ -1,6 +1,6 @@
# FamiliarOS Feature Registry
This is the canonical feature registry for the VectorShell working fork of FamiliarOS. It maps every user-facing capability to the files, branches/PRs, and commits that implement it. It is kept in addition to `FEATURES.md` and `FEATURES_OUR_CHANGES.md` so that feature ownership, status, and history can be traced quickly.
This is the canonical feature registry for the FamiliarOS working repo. It maps every user-facing capability to the files, branches/PRs, and commits that implement it. It is kept in addition to `FEATURES.md` and `FEATURES_OUR_CHANGES.md` so that feature ownership, status, and history can be traced quickly.
- **Current branch:** `feat/familiaros-rebrand`
- **Current HEAD:** `69d3046`
@ -26,6 +26,7 @@ This is the canonical feature registry for the VectorShell working fork of Famil
| Virtual-familiar context menu | shipped | `pr/virtual-familiar-context-menu` + `refactor/virtual-familiar-context-menu` | `98b7875`, `ab62d9c`, `35e4d74` | `plugins/official/familiaros.virtual-familiar/index.js`, `plugins/official/familiaros.virtual-familiar/locales/en.json` | HUD moved from triple-click overlay to right-click context menu; care actions reordered/renamed. |
| 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. |
## 2. Floating chat / prompt window

60
apps/desktop/catalog.v2.fixture.json
View file

@ -3,39 +3,49 @@
"generatedAt": "2026-05-05T08:55:53.722Z",
"familiars": [
{
"id": "snoopy",
"displayName": "Snoopy",
"description": "A tiny black-and-white beagle with a red collar for calm coding sessions.",
"preview": "https://familiaros.dev/familiars/snoopy-23e05847/spritesheet.webp",
"zip": "https://zip.familiaros.dev/familiars/snoopy-23e05847/snoopy.zip"
"id": "lantern",
"displayName": "Lantern",
"description": "A calm desk companion with a soft glow and rounded paper-cut silhouette.",
"preview": "https://familiaros.dev/familiars/lantern-23e05847/spritesheet.webp",
"zip": "https://zip.familiaros.dev/familiars/lantern-23e05847/lantern.zip",
"category": "western",
"original": true
},
{
"id": "clippit",
"displayName": "Clippy",
"description": "A classic paperclip assistant rebuilt from Microsoft Agent animation frames.",
"preview": "https://familiaros.dev/familiars/clippit-904b393f/spritesheet.webp",
"zip": "https://zip.familiaros.dev/familiars/clippit-904b393f/clippit.zip"
"id": "moss",
"displayName": "Moss",
"description": "A tiny green studio spirit with leaf-soft idle motion and quiet focus energy.",
"preview": "https://familiaros.dev/familiars/moss-904b393f/spritesheet.webp",
"zip": "https://zip.familiaros.dev/familiars/moss-904b393f/moss.zip",
"category": "western",
"original": true
},
{
"id": "tux",
"displayName": "Tux",
"description": "A tiny pixel-adjacent Linux mascot penguin for calm coding sessions.",
"preview": "https://familiaros.dev/familiars/tux-de2f300f/spritesheet.webp",
"zip": "https://zip.familiaros.dev/familiars/tux-de2f300f/tux.zip"
"id": "orbit",
"displayName": "Orbit",
"description": "A compact star-tracker familiar with a gentle scan loop and bright focus ring.",
"preview": "https://familiaros.dev/familiars/orbit-de2f300f/spritesheet.webp",
"zip": "https://zip.familiaros.dev/familiars/orbit-de2f300f/orbit.zip",
"category": "western",
"featured": true
},
{
"id": "wall-e",
"displayName": "Wall-E",
"description": "A tiny weathered trash-compactor robot companion with binocular eyes, treads, and a gentle waving arm.",
"preview": "https://familiaros.dev/familiars/wall-e-779d5202/spritesheet.webp",
"zip": "https://zip.familiaros.dev/familiars/wall-e-779d5202/wall-e.zip"
"id": "ember",
"displayName": "Ember",
"description": "A warm little spark familiar with crisp motion beats for active work states.",
"preview": "https://familiaros.dev/familiars/ember-779d5202/spritesheet.webp",
"zip": "https://zip.familiaros.dev/familiars/ember-779d5202/ember.zip",
"category": "asian",
"original": true
},
{
"id": "dobby",
"displayName": "Dobby",
"description": "An earnest, genuinely helpful tiny house-elf Codex familiar with huge ears, wide kind eyes, and a simple worn tunic.",
"preview": "https://familiaros.dev/familiars/dobby-3f6746e0/spritesheet.webp",
"zip": "https://zip.familiaros.dev/familiars/dobby-3f6746e0/dobby.zip"
"id": "rivulet",
"displayName": "Rivulet",
"description": "A flowing ink-drop companion built for softer waiting, review, and memory moments.",
"preview": "https://familiaros.dev/familiars/rivulet-3f6746e0/spritesheet.webp",
"zip": "https://zip.familiaros.dev/familiars/rivulet-3f6746e0/rivulet.zip",
"category": "asian",
"featured": true
}
]
}

11
apps/desktop/contracts/catalog-fixture.contract.ts
View file

@ -3,7 +3,16 @@ import { readFile } from "node:fs/promises";
import { validateCatalogV2 } from "../src/catalog-validation.js";
const fixture = JSON.parse(await readFile("catalog.v2.fixture.json", "utf8")) as unknown;
validateCatalogV2(fixture);
const validated = validateCatalogV2(fixture);
if (!validated.familiars.some((familiar) => familiar.original === true)) {
throw new Error("Catalog fixture lost original familiar metadata.");
}
if (!validated.familiars.some((familiar) => familiar.featured === true)) {
throw new Error("Catalog fixture lost featured familiar metadata.");
}
if (!validated.familiars.every((familiar) => familiar.category === "western" || familiar.category === "asian")) {
throw new Error("Catalog fixture lost category metadata.");
}
const generatedAt = new Date().toISOString();

1
apps/desktop/scripts/run-tests.mjs
View file

@ -27,6 +27,7 @@ const behaviorTests = [
".test-dist/tests/onboarding-state.test.js",
".test-dist/tests/update-version.test.js",
".test-dist/tests/reaction-animation-mapping.test.js",
".test-dist/tests/catalog-surfaceable.test.js",
".test-dist/tests/zip-safety.test.js",
".test-dist/tests/tts-engine.test.js",
".test-dist/tests/codex-familiars.test.js",

21
apps/desktop/src/catalog-surfaceable.ts Normal file
View file

@ -0,0 +1,21 @@
export interface SurfaceableCatalogPet {
readonly original?: boolean;
readonly featured?: boolean;
}
export function isSurfaceablePet(familiar: SurfaceableCatalogPet): boolean {
return familiar.original === true || familiar.featured === true;
}
export function filterSurfaceablePets<T extends SurfaceableCatalogPet>(familiars: readonly T[]): readonly T[] {
return familiars.filter(isSurfaceablePet);
}
export function summarizeSurfaceablePets<T extends SurfaceableCatalogPet>(familiars: readonly T[], pageSize: number): { readonly total: number; readonly pageCount: number } {
if (!Number.isInteger(pageSize) || pageSize < 1) throw new Error("Surfaceable page size must be a positive integer.");
const total = filterSurfaceablePets(familiars).length;
return {
total,
pageCount: Math.ceil(total / pageSize),
};
}

6
apps/desktop/src/catalog-validation.ts
View file

@ -186,13 +186,17 @@ function validateCatalogPet(value: unknown, ids: Set<string>): CatalogPetV2 {
if (ids.has(id)) throw new Error(`Duplicate catalog familiar id: ${id}`);
ids.add(id);
return {
const entry: CatalogPetV2 = {
id,
displayName: validateString(value.displayName, "displayName", 120),
description: validateString(value.description, "description", 500),
preview: validateCatalogUrl(value.preview, "preview"),
zip: validateCatalogUrl(value.zip, "zip"),
...(value.spritesheet === undefined ? {} : { spritesheet: validateCatalogUrl(value.spritesheet, "preview") }),
...(value.category === undefined ? {} : { category: validateCategory(value.category) }),
...(value.subcategory === undefined ? {} : { subcategory: validateString(value.subcategory, "subcategory", 80) }),
};
return withCatalogMeta(entry, value);
}
function validateCatalogV3Pet(value: unknown, ids: Set<string>): CatalogPetV3 {

30
apps/desktop/src/catalog.ts
View file

@ -3,6 +3,7 @@ import { join } from "node:path";
import { app } from "electron";
import { filterSurfaceablePets, isSurfaceablePet, summarizeSurfaceablePets } from "./catalog-surfaceable.js";
import { validateCatalogV2, validateCatalogV3Index, validateCatalogV3Page, validateCatalogV3SearchIndex, validateCatalogV3SearchPage, type CatalogPetV2, type CatalogV2, type CatalogV3Index, type CatalogV3SearchPet } from "./catalog-validation.js";
export const catalogUrl = "https://familiaros.dev/familiars/catalog.v2.json";
@ -45,15 +46,16 @@ export async function getCatalogUiState(): Promise<CatalogUiState> {
if (remoteV3.ok) {
const firstPage = await tryLoadSurfaceableCatalogV3Page(0, remoteV3.index);
if (!firstPage.ok) return await getV2OrFixtureCatalogUiState(`v3 page unavailable: ${firstPage.error}`);
const surfaceableStats = summarizeSurfaceablePets(await getRemoteCatalogV3Search(remoteV3.index), remoteV3.index.pageSize);
return {
source: "remote",
familiars: filterSurfaceablePets(firstPage.familiars),
generatedAt: remoteV3.index.generatedAt,
version: 3,
total: surfaceableTotal(remoteV3.index),
total: surfaceableStats.total,
categories: remoteV3.index.filters.categories,
page: 0,
pageCount: surfaceablePageCount(remoteV3.index),
pageCount: surfaceableStats.pageCount,
supportsCategories: true,
originalsCount: remoteV3.index.filters.originalsCount,
featuredCount: remoteV3.index.filters.featuredCount,
@ -67,7 +69,8 @@ export async function getCatalogPageUiState(page: number): Promise<CatalogUiStat
if (!Number.isInteger(page) || page < 0) throw new Error("Catalog page must be a non-negative integer.");
const remoteV3 = await tryLoadRemoteCatalogV3Index();
if (!remoteV3.ok) return { source: "error", familiars: [], error: remoteV3.error };
if (page >= surfaceablePageCount(remoteV3.index)) throw new Error("Catalog page is out of range.");
const surfaceableStats = summarizeSurfaceablePets(await getRemoteCatalogV3Search(remoteV3.index), remoteV3.index.pageSize);
if (page >= surfaceableStats.pageCount) throw new Error("Catalog page is out of range.");
const pageResult = await tryLoadSurfaceableCatalogV3Page(page, remoteV3.index);
if (!pageResult.ok) return { source: "error", familiars: [], error: pageResult.error };
@ -76,10 +79,10 @@ export async function getCatalogPageUiState(page: number): Promise<CatalogUiStat
familiars: filterSurfaceablePets(pageResult.familiars),
generatedAt: remoteV3.index.generatedAt,
version: 3,
total: surfaceableTotal(remoteV3.index),
total: surfaceableStats.total,
categories: remoteV3.index.filters.categories,
page,
pageCount: surfaceablePageCount(remoteV3.index),
pageCount: surfaceableStats.pageCount,
supportsCategories: true,
originalsCount: remoteV3.index.filters.originalsCount,
featuredCount: remoteV3.index.filters.featuredCount,
@ -127,7 +130,6 @@ export async function getCatalogPet(petId: string): Promise<CatalogPetV2> {
}
async function getV2OrFixtureCatalogUiState(remoteV3Error: string): Promise<CatalogUiState> {
const remote = await tryLoadRemoteCatalog();
if (remote.ok) {
@ -162,14 +164,6 @@ async function getV2OrFixtureCatalogUiState(remoteV3Error: string): Promise<Cata
};
}
function filterSurfaceablePets<T extends { readonly original?: boolean; readonly featured?: boolean }>(familiars: readonly T[]): readonly T[] {
return familiars.filter(isSurfaceablePet);
}
function isSurfaceablePet(familiar: { readonly original?: boolean; readonly featured?: boolean }): boolean {
return familiar.original === true || familiar.featured === true;
}
function getSurfaceableSearchPets(familiars: readonly CatalogV3SearchPet[], index: CatalogV3Index): readonly CatalogV3SearchPet[] {
return filterSurfaceablePets(familiars).map((familiar, surfaceIndex) => ({
...familiar,
@ -177,14 +171,6 @@ function getSurfaceableSearchPets(familiars: readonly CatalogV3SearchPet[], inde
}));
}
function surfaceableTotal(index: CatalogV3Index): number {
return (index.filters.originalsCount ?? 0) + (index.filters.featuredCount ?? 0);
}
function surfaceablePageCount(index: CatalogV3Index): number {
return Math.ceil(surfaceableTotal(index) / index.pageSize);
}
async function tryLoadRemoteCatalogV3Index(): Promise<{ readonly ok: true; readonly index: CatalogV3Index } | { readonly ok: false; readonly error: string }> {
try {
const index = await getRemoteCatalogV3Index();

30
apps/desktop/tests/catalog-surfaceable.test.ts Normal file
View file

@ -0,0 +1,30 @@
import assert from "node:assert/strict";
import { filterSurfaceablePets, isSurfaceablePet, summarizeSurfaceablePets } from "../src/catalog-surfaceable.js";
const familiars: readonly { readonly id: string; readonly original?: boolean; readonly featured?: boolean }[] = [
{ id: "lantern", original: true },
{ id: "orbit", featured: true },
{ id: "ember", original: true, featured: true },
{ id: "shadow" },
];
assert.equal(isSurfaceablePet(familiars[0]), true);
assert.equal(isSurfaceablePet(familiars[1]), true);
assert.equal(isSurfaceablePet(familiars[2]), true);
assert.equal(isSurfaceablePet(familiars[3]), false);
assert.deepEqual(
filterSurfaceablePets(familiars).map((familiar) => familiar.id),
["lantern", "orbit", "ember"],
);
assert.deepEqual(
summarizeSurfaceablePets(familiars, 2),
{ total: 3, pageCount: 2 },
"A familiar that is both original and featured must only count once.",
);
assert.throws(() => summarizeSurfaceablePets(familiars, 0));
console.log("Catalog surfaceable stats validation passed.");

12
apps/desktop/tests/lease-manager.test.ts
View file

@ -25,21 +25,21 @@ assert.equal(defaultLease.targetKind, "default", "Default lease targetKind shoul
manager.release(defaultLease.leaseId);
assert.equal(closed.length, 0, "Default release closed a temp familiar.");
const first = manager.acquire("snoopy");
const second = manager.acquire("snoopy");
assert.equal(opened.join(","), "snoopy", "Explicit familiar did not open once for multiple leases.");
const first = manager.acquire("lantern");
const second = manager.acquire("lantern");
assert.equal(opened.join(","), "lantern", "Explicit familiar did not open once for multiple leases.");
manager.release(first.leaseId);
assert.equal(closed.length, 0, "Explicit familiar closed before final lease release.");
manager.release(first.leaseId);
manager.release(second.leaseId);
assert.equal(closed.join(","), "snoopy", "Explicit familiar did not close after final release.");
assert.equal(closed.join(","), "lantern", "Explicit familiar did not close after final release.");
const missing = manager.acquire("missing");
assert.equal(missing.fallbackReason, "pet_not_installed", "Missing familiar did not fall back to default.");
assert.equal(missing.usingDefaultPet, true, "Missing familiar should use default.");
manager.release(missing.leaseId);
const expiring = manager.acquire("tux");
const expiring = manager.acquire("orbit");
now += 50;
manager.heartbeat(expiring.leaseId);
now += 75;
@ -47,7 +47,7 @@ assert.equal(manager.cleanupExpired().length, 0, "Heartbeat did not extend lease
now += 50;
assert.equal(manager.cleanupExpired().length, 1, "Expired lease was not cleaned up.");
const expiredBeforeHeartbeat = manager.acquire("dobby");
const expiredBeforeHeartbeat = manager.acquire("moss");
now += 200;
assert.throws(() => manager.heartbeat(expiredBeforeHeartbeat.leaseId));
assert.equal(manager.get(expiredBeforeHeartbeat.leaseId), null, "Expired lease was still readable before cleanup.");

92
docs/Design Language and Marketing/FAMILIAROS_OPENPETS_FAMILIAR_REUSE_AND_IP_ASSESSMENT_2026-06-18.md Normal file
View file

@ -0,0 +1,92 @@
# FamiliarOS OpenPets Familiar Reuse And IP Assessment
**Date:** 2026-06-18
## Question
Can FamiliarOS safely reuse legacy OpenPets familiars just because the repo is
MIT licensed?
## Short Answer
No, not categorically.
The OpenPets codebase being MIT licensed does **not** automatically mean every
gallery familiar, community familiar, or recognizable character-based familiar
is safe for FamiliarOS redistribution or first-party branding.
## Evidence Checked
### 1. OpenPets live site and legal pages
The current OpenPets site states that:
- OpenPets is free, open source, and MIT licensed at the code level.
- Some familiars/pets may be unofficial fan-made content.
- OpenPets is not affiliated with or endorsed by third-party rights holders.
- Rights owners can request removal.
- Personal desktop customization does not grant rights to third-party characters, brands, artwork, trademarks, or other protected material.
- Submitters should only submit original work, properly licensed work, or content they have permission to share.
- Fan-made or non-commercial status is not itself a license grant.
### 2. Sample pack metadata (`pet.json`)
Two sampled public OpenPets familiar packs were inspected:
- `tmuxai`
- `raccoon`
Observed metadata shape:
- `id`
- `displayName`
- `description`
- `spritesheetPath`
- sometimes `sourceUrl`
- sometimes category metadata
Important finding: the pack metadata does **not** itself provide a durable,
uniform license field proving redistribution rights for FamiliarOS.
### 3. Local FamiliarOS software fixtures
The actual FamiliarOS repo still carried legacy sample familiar/catalog IDs
such as third-party character references. Those were treated as avoidable IP
risk and replaced with neutral first-party sample familiars in the software
fixtures/contracts during this pass.
## Interpretation
The live OpenPets legal posture separates two questions that must not be
collapsed:
1. **Can FamiliarOS reuse or continue code lineage?**
- Usually yes, because the repo code license is MIT.
2. **Can FamiliarOS reuse every familiar asset or recognizable character pack?**
- No, not without pack-specific rights confirmation.
## Safe Route For FamiliarOS
Treat legacy OpenPets familiar assets using this rule set:
- **Safe-er / candidate for reuse:** clearly original first-party or clearly permissioned packs with traceable provenance and no third-party character/trademark dependency.
- **Unsafe by default:** fan-made, unofficial, community, or recognizable third-party character packs unless explicit rights are verified.
- **Recommended default FamiliarOS route:** create or commission first-party FamiliarOS familiars and use OpenPets packs only as inspiration, temporary local-dev references, or pack-by-pack verified exceptions.
## Product Consequence
FamiliarOS should maintain two separate tracks:
1. code-side continuation and hardening of the MIT software lineage
2. first-party familiar art, animation, and mascot replacement where rights or completeness are uncertain
This is especially important because several legacy packs also have incomplete
animation coverage, so even a legally reusable pack may still be a weak
first-party FamiliarOS runtime asset.
## Operational Conclusion
For FamiliarOS planning and shipping purposes, assume that **legacy OpenPets
familiars are replace-or-verify assets, not automatically reusable first-party
FamiliarOS familiars**.

19
docs/REPO_LICENSE_TRACKING.md Normal file
View file

@ -0,0 +1,19 @@
# FamiliarOS Repo License Tracking
**Last updated:** 2026-06-18
| Source | Scope | License / Rights Read | Confidence | Route | Notes |
|--------|-------|------------------------|------------|-------|-------|
| `FamiliarOS` | first-party repo code | MIT (`/home/dev/src/FamiliarOS/LICENSE`) | `high` | `direct first_party_owner` | Current repo code is clearly MIT licensed. |
| `alvinunreal/openpets` | upstream code lineage | MIT (repo + homepage statements) | `high` | `direct lineage / bounded review` | Code license is permissive and compatible with the existing FamiliarOS fork history. |
| `OpenPets` catalog/community familiar assets | distributed familiar packs and gallery media | mixed / pack-specific / not automatically covered by code MIT | `medium` | `replace_or_verify_pack_by_pack` | OpenPets legal and terms pages explicitly state some familiars may be unofficial fan-made content and rights remain with respective owners. Do not assume gallery familiars are safe for FamiliarOS redistribution without pack-specific rights confirmation. |
| `ScriptoriumAI` root `.gitnexus` state | repo-local analysis index, not product runtime | repo-specific generated state | `high` | `scaffold_only / regenerate_locally` | The Scriptorium root `.gitnexus` data points at `C:\ScriptoriumAI`; it is not safe to treat as a valid FamiliarOS index. Use only as workflow reference and regenerate repo-local state. |
## Operational Rule
When code license and asset rights diverge, the stricter surface wins for the
asset-distribution question.
That means FamiliarOS may continue code-side lineage work while still treating
legacy OpenPets familiar packs as replace-or-verify material instead of
automatic first-party FamiliarOS assets.

58
docs/consolidated_workflows/INDEX.md
View file

@ -1,10 +1,11 @@
# FamiliarOS Workflow Integration Index
**Last updated:** 2026-06-17
**Last updated:** 2026-06-18
**Purpose:** Canonical home for the FamiliarOS-branded workflow manual assembled
from current FamiliarOS reality plus the most reusable operating doctrine
patterns previously consolidated in ScriptoriumAI, HyperTwist, and VectorShell.
**Purpose:** Canonical home for the FamiliarOS workflow manual assembled from
current FamiliarOS reality plus the most reusable operating doctrine already
compacted through the recent ScriptoriumAI, HyperTwist, and VectorShell
consolidation work.
## Canonical Rule
@ -12,38 +13,61 @@ Read the docs under `docs/consolidated_workflows/familiaros/` first.
- Those files are the live, FamiliarOS-branded operating surface.
- Donor project names should appear there only in provenance notes.
- This pack exists to keep FamiliarOS from drifting back into OpenPets,
ScriptoriumAI, or legacy parallel-surface wording.
- The `shared/` folder retains generic cross-project doctrine that FamiliarOS now uses directly.
## Canonical FamiliarOS Workflow Manual
| Canonical Doc | Purpose |
|---------------|---------|
| `familiaros/README.md` | Front-door guide for the integrated workflow pack |
| `familiaros/PROJECT_AUTHORITY_AND_RECONCILIATION.md` | Current-source-first truth, donor precedence, and parallel-surface reconciliation |
| `familiaros/DESKTOP_COMPANION_AND_FRONT_DOOR_DOCTRINE.md` | Canonical product-surface doctrine across desktop companion, control panel, website, and agent bridge |
| `familiaros/DECISION_GATES_FRONT_DOOR_AND_REMOTE_EXECUTION.md` | User decision-gate handling, single-front-door rule, and remote execution boundaries |
| `familiaros/MODEL_A_B_FULL_SEQUENCE_CANON.md` | Full generic Model A / Model B sequence set retained in canonical form |
| `familiaros/PROJECT_AUTHORITY_AND_RECONCILIATION.md` | Current-source-first truth, donor precedence, and selective backfill rules |
| `familiaros/DESKTOP_COMPANION_AND_FRONT_DOOR_DOCTRINE.md` | Canonical product-surface doctrine across desktop companion, control center, website, and agent bridge |
| `familiaros/REPO_EVALUATION_AND_CLEAN_ROOM_PLAYBOOK.md` | Repo intake, phased evaluation, donor-fit analysis, and clean-room handling for FamiliarOS |
| `familiaros/LICENSE_CUSTODY_AND_EVIDENCE_WORKFLOW.md` | License, custody, asset-rights, and evidence workflow |
| `familiaros/FEATURE_REGISTRY_AND_DEEP_SOURCE_CLOSEOUT.md` | Closeout checklist for feature-registry, roadmap, and evidence-surface synchronization |
| `familiaros/IMPLEMENTATION_BATCHING_AND_DISPOSITION.md` | FamiliarOS-first batching, anchor handling, and retained-value disposition rules |
| `familiaros/OPERATOR_WORKBENCH_AND_VISUALIZATION_DOCTRINE.md` | Control-center, familiar, website, and operator-surface composition doctrine |
| `familiaros/MEMORY_CONTINUITY_AND_ASSISTIVE_OPTIONALITY_DOCTRINE.md` | Bounded memory/knowledge/continuity lane rules and assistive optionality doctrine |
| `familiaros/PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE.md` | First-party provider-neutral routing and BYOK custody doctrine for FamiliarOS chat, plugin AI, and voice/provider surfaces |
| `familiaros/ARTIFACT_STORAGE_AND_RUNTIME_BOUNDARIES.md` | Source-vs-build-vs-backup-vs-archive distinctions and cleanup rules |
| `familiaros/HIGH_IMPORTANCE_TRANSFER_GAP_AUDIT_2026-06-17.md` | Compact audit of what still mattered enough to promote into a FamiliarOS front-door pack |
| `familiaros/DECISION_GATES_FRONT_DOOR_AND_REMOTE_EXECUTION.md` | User decision-gate handling, single-front-door rule, and remote execution boundaries |
| `familiaros/HIGH_IMPORTANCE_TRANSFER_GAP_AUDIT_2026-06-18.md` | Compact audit of what broader workflow doctrine was missing and what this follow-up promoted |
## Shared Workflow Adjuncts
These docs remain project-agnostic and reusable.
| Path | Role |
|------|------|
| `shared/BACKFILL_PROCEDURES.md` | Cross-project retroactive backfill and correction procedure |
| `shared/CROSS_LANE_AUTHORITY_HIERARCHY.md` | Generic A / R / F authority model for overlapping repos and capabilities |
| `shared/LICENSE_TRACKING_WORKFLOW.md` | Generic tracker and evidence-audit workflow for repo/license classification |
| `shared/MODEL_A_B_CLEAN_ROOM_PROMPTS.md` | Generic clean-room prompt surfaces and role separation support |
| `shared/REPO_EVALUATION_MODUS_OPERANDI.md` | Generic repo-evaluation execution baseline |
## Maintenance Rules
1. Update the FamiliarOS-branded docs before editing donor-provenance notes.
1. Update the FamiliarOS-branded docs before editing upstream provenance notes.
2. Keep FamiliarOS product language in headings, summaries, and decision rules.
3. Use donor names only in provenance sections, source maps, or explicit historical notes.
4. When current FamiliarOS source contradicts donor wording, current FamiliarOS source wins.
5. When future cleanup revisits parallel surfaces, record the canonical winner here instead of leaving the answer implicit.
5. When a donor-source correction changes live guidance, patch the FamiliarOS canonical doc and then record the source delta.
6. Deep-source closure must also reconcile `FEATURE_REGISTRY.md`, `docs/REPO_LICENSE_TRACKING.md`, roadmap notes, and relevant ops/asset-rights docs when applicable.
7. The full generic Model A / Model B sequence set must remain stored in canonical form at `docs/consolidated_workflows/familiaros/MODEL_A_B_FULL_SEQUENCE_CANON.md`.
8. When a later comparison asks what still remained missing from the front-door pack, refresh the latest high-importance gap audit note rather than leaving that answer implicit.
## Source Mapping Summary
| Source Family | Main Value Preserved For FamiliarOS |
|---------------|--------------------------------------|
| Current FamiliarOS repo | Product truth, desktop runtime, website, auth, plugin, and ops reality |
| ScriptoriumAI consolidation pack | Workflow-pack structure, authority formatting, and compact front-door doctrine style |
| HyperTwist / VectorShell doctrines | Reusable decision-gate, front-door, remote-execution, and artifact-boundary rules |
| Current FamiliarOS repo | Product truth, desktop runtime, Control Center, plugin platform, memory/knowledge, provider, and ops reality |
| ScriptoriumAI consolidation pack | Workflow-pack structure, compact doctrine shape, Model A / Model B canonical retention, and closeout discipline |
| HyperTwist / VectorShell doctrines | Reusable clean-room, authority, decision-gate, remote-execution, batching, artifact, and continuity rules |
## Status
- `familiaros/` is now the canonical workflow home for FamiliarOS.
- The pack is intentionally compact and operational.
- It is not a substitute for sensitive runbooks or live secret custody.
- The pack no longer stops at the earlier compact mini-layer; it now covers the broader workflow doctrine families the user requested.
- `shared/` is retained locally for generic support doctrine.
- Donor-specific product identity remains outside the FamiliarOS front door.

7
docs/consolidated_workflows/familiaros/DECISION_GATES_FRONT_DOOR_AND_REMOTE_EXECUTION.md
View file

@ -31,17 +31,18 @@ When FamiliarOS needs remote or host-specific execution:
## Current Reverse-Sync Correction
The 2026-06-17 audit found:
The 2026-06-18 verification found:
- no FamiliarOS-specific Linux cron job on this machine
- no FamiliarOS-specific systemd timer on this machine
- the active reverse-sync automation pattern currently lives in Windows
scheduled-task scripts under `ScriptoriumAI/ops/ssh/`
- the discovered workspace map omits `FamiliarOS`
- the live workspace map now includes `FamiliarOS`
So present-tense truth is:
- FamiliarOS is not currently wired into the discovered live reverse-sync task
- FamiliarOS is wired into the discovered shared reverse-sync task through the
Scriptorium-owned Windows automation lane
## Closeout Shape

94
docs/consolidated_workflows/familiaros/FEATURE_REGISTRY_AND_DEEP_SOURCE_CLOSEOUT.md Normal file
View file

@ -0,0 +1,94 @@
# FamiliarOS Feature Registry And Deep-Source Closeout
## Purpose
This document makes the deep-source closeout lane explicit for FamiliarOS.
It exists so repo-evaluation, donor-integration, asset-rights, and workflow
transfer work does not stop after:
- a packet
- a one-off summary
- a legal note
- a temporary implementation decision
## Canonical Closeout Rule
When work touches repo evaluation, repo custody, legal evidence, governance
state, retained capability classification, or mascot/asset-reuse decisions,
the pass is not complete until the canonical FamiliarOS surfaces are checked
and updated when applicable.
## Mandatory Closeout Surfaces
1. `FEATURE_REGISTRY.md`
2. `docs/plan/FAMILIAROS_PRODUCT_ROADMAP_2026-06-17.md`
3. `docs/plan/FAMILIAROS_REBRAND_PROGRESS.md`
4. `docs/REPO_LICENSE_TRACKING.md`
5. `docs/Design Language and Marketing/FAMILIAROS_OPENPETS_FAMILIAR_REUSE_AND_IP_ASSESSMENT_2026-06-18.md` when familiar asset-rights truth changed
6. `docs/consolidated_workflows/familiaros/MODEL_A_B_FULL_SEQUENCE_CANON.md` if Model A / Model B sequence truth was touched
7. `docs/consolidated_workflows/familiaros/HIGH_IMPORTANCE_TRANSFER_GAP_AUDIT_2026-06-18.md` if front-door workflow doctrine changed
8. `docs/ops/FAMILIAROS_VPS_AND_REMOTE_SYNC_RUNBOOK_2026-06-17.md` if remote-sync or VPS truth changed
## Feature Registry Synchronization Rule
After deep-source closure, decide whether the result changes FamiliarOS's
normalized feature surface.
### Update The Feature Registry When
- a capability is newly implemented
- a retained external capability is newly proven or intentionally rejected
- a shallow placeholder should be upgraded or downgraded
- a previous feature claim needs to be narrowed or corrected
- a risky legacy surface is replaced by a safer first-party path
### Do Not Update The Feature Registry When
- the work is pure historical cleanup with no capability consequence
- a donor was inspected but produced no retained feature value
- wording changed without changing capability truth
## Root License Ledger Synchronization Rule
If a deep-source pass makes a concrete license, custody, or asset-rights
decision, update `docs/REPO_LICENSE_TRACKING.md`.
That includes:
- new source rows
- route changes
- confidence upgrades or downgrades
- mixed-custody discoveries
- mascot/asset reuse restrictions or replacements
## Deep-Source Packet Completion Checklist
Before calling the pass closed, answer:
1. Was the current primary source verified?
2. Was the donor or repo evaluated against the real current FamiliarOS product?
3. Did authority, route, width, or disposition change?
4. Does the feature registry need a status update?
5. Does the root license ledger need a row update?
6. Do roadmap, rebrand, or ops docs need a note?
7. If nothing changed, is that explicitly stated?
## Relationship To The Compacted Workflow Pack
The FamiliarOS workflow pack is intentionally more compact than the raw donor
corpus.
That compacting is acceptable only because:
- shared generic doctrine is still retained under `docs/consolidated_workflows/shared/`
- current product-truth docs still preserve FamiliarOS-specific feature, roadmap, and ops truth
- the root license ledger now exists as the concrete row-level surface for current custody findings
- the full generic Model A / Model B sequence set remains stored in canonical form
## Provenance
This closeout rule is assembled from the ScriptoriumAI, HyperTwist, and
VectorShell deep-source, backfill, and registry-discipline workflow patterns,
then rewritten for FamiliarOS-specific feature, roadmap, and asset-rights
closure.

111
docs/consolidated_workflows/familiaros/HIGH_IMPORTANCE_TRANSFER_GAP_AUDIT_2026-06-18.md Normal file
View file

@ -0,0 +1,111 @@
# FamiliarOS High-Importance Transfer Gap Audit
**Date:** 2026-06-18
## Purpose
Record what broader workflow doctrine was still missing from the FamiliarOS
front-door pack after the earlier compact transfer pass, and identify which
high-importance lanes were promoted during this follow-up.
## Comparison Basis
This audit compared:
1. the current FamiliarOS front-door pack that existed before this pass
2. the recent ScriptoriumAI canonical workflow pack
3. nearby VectorShell and HyperTwist doctrine surroundings for missed lanes
4. current FamiliarOS implementation, roadmap, and asset-rights reality
## What Was Already Covered Before This Pass
The earlier FamiliarOS transfer already covered the following high-value
doctrine families:
- current authority and parallel-surface truth
- single desktop-companion/front-door product identity
- decision-gated deletion and remote-execution boundaries
- artifact, archive, and cleanup boundary language
- product roadmap direction for spinners, motion, background video, and hardening
## What Was Still Missing Before This Pass
The main missing high-importance doctrine lanes were:
1. **Full Model A / Model B sequence retention**
- The earlier compact pass did not bring over the full generic clean-room sequence canon.
- The Scriptorium pack already preserved that artifact in full, so FamiliarOS could import it directly instead of re-consolidating donor prompt history from scratch.
2. **Repo evaluation and clean-room playbook**
- FamiliarOS had phase specs and planning notes but no short first-party playbook for repo intake, donor-fit reasoning, and clean-room triggers.
3. **License, custody, and evidence workflow**
- FamiliarOS had legal and rebrand discussion fragments, but no canonical workflow tying repo-license truth, asset-rights questions, and evidence discipline together.
4. **Feature-registry and deep-source closeout discipline**
- The repo had a feature registry and roadmap, but no front-door rule stating which surfaces must be updated before calling a repo-custody or donor-eval pass closed.
5. **Implementation batching and disposition doctrine**
- FamiliarOS needed a product-native batch map so future donor or refactor packets stop defaulting to donor family language.
6. **Operator workbench and visualization doctrine**
- The earlier pass named the desktop companion and front door, but it did not elevate the deeper rule set for how tray, familiar windows, Control Center, floating chat, plugins, and website should cohere.
7. **Memory continuity and assistive optionality doctrine**
- FamiliarOS already ships durable memory, knowledge store, MCP memory tools, and provider-assisted chat, but it lacked a front-door doctrine that separates raw authority from derived assistive state.
8. **Provider-neutrality and BYOK doctrine**
- FamiliarOS already exposes provider presets, custom endpoints, plugin AI routing, and voice/provider choice, but it lacked a first-party doctrine for why those surfaces must remain normalized and not vendor-owned.
9. **Shared support doctrine families**
- The compact mini-pack did not locally retain the shared backfill, cross-lane authority, license-tracking, clean-room prompt, and generic repo-evaluation adjunct docs that Scriptorium already had available.
## What Was Intentionally Not Transferred
The comparison also confirmed that some donor doctrines should remain donor-only
and must not be promoted as FamiliarOS truth:
- VectorShell's XR, Unreal-shell, and world-first identity
- HyperTwist's puzzle, trainer, and coaching-product taxonomy
- ScriptoriumAI's research-writing, corpus, and publication-product identity
FamiliarOS should inherit the documentation rigor and reusable doctrine
patterns, not donor product identity.
## Files Promoted In This Pass
The following FamiliarOS-branded docs were added or promoted to close the
remaining high-importance gap:
- `MODEL_A_B_FULL_SEQUENCE_CANON.md`
- `REPO_EVALUATION_AND_CLEAN_ROOM_PLAYBOOK.md`
- `LICENSE_CUSTODY_AND_EVIDENCE_WORKFLOW.md`
- `FEATURE_REGISTRY_AND_DEEP_SOURCE_CLOSEOUT.md`
- `IMPLEMENTATION_BATCHING_AND_DISPOSITION.md`
- `OPERATOR_WORKBENCH_AND_VISUALIZATION_DOCTRINE.md`
- `MEMORY_CONTINUITY_AND_ASSISTIVE_OPTIONALITY_DOCTRINE.md`
- `PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE.md`
- local shared workflow adjuncts under `../shared/`
## Practical Reading Order After This Pass
When the question is "what important workflow doctrine is still missing?",
read in this order:
1. `README.md`
2. `HIGH_IMPORTANCE_TRANSFER_GAP_AUDIT_2026-06-18.md`
3. the canonical FamiliarOS workflow pack
4. the shared adjunct docs
5. donor-specific upstream packs only if finer-grained source tracing is needed
## Operational Conclusion
The important missing transfer for FamiliarOS was no longer just the earlier
compact front-door operating layer.
The remaining gap was the absence of the broader workflow doctrine families
that the user explicitly wanted to inherit from the recent ScriptoriumAI
consolidation work: clean-room sequence retention, repo-eval hygiene,
license/custody workflow, closeout discipline, batching doctrine, operator
surface doctrine, memory doctrine, provider doctrine, and shared support
doctrine.

101
docs/consolidated_workflows/familiaros/IMPLEMENTATION_BATCHING_AND_DISPOSITION.md Normal file
View file

@ -0,0 +1,101 @@
# FamiliarOS Implementation Batching And Disposition
## Core Rule
Not every tracked source deserves sovereign ownership inside FamiliarOS.
Every source should be implementation-accounted for, but only a minority
should become first-party runtime owners.
## Implemented Anchor Rule
If FamiliarOS already has an implemented first-party seam, treat that seam as
an anchor.
Do not:
- silently demote it back into unresolved donor speculation
- replace it by narrative drift alone
- treat a new donor as a fresh blank-slate owner without additive comparison
## Suggested FamiliarOS Batch Families
When a new multi-slice implementation lane is needed, default to
FamiliarOS-native batch families rather than donor-product families.
| Family | Scope |
|--------|-------|
| `F1` | familiar runtime, motion, bubbles, reactions, windowing, and default/agent familiar behavior |
| `F2` | Control Center, settings, dashboards, and operator-facing desktop UI surfaces |
| `F3` | local IPC, MCP, CLI, editor integrations, and external-agent bridges |
| `F4` | plugin platform, official plugins, panel runtime, and host capabilities |
| `F5` | memory, knowledge, voice, chat, provider routing, and assistive companion systems |
| `F6` | website, front door, download/auth/account-adjacent, and public conversion surfaces |
| `F7` | ops, deployment, reverse-sync, backup, diagnostics, and governance-support surfaces |
The exact family map can be adjusted per lane, but it should stay
FamiliarOS-first.
## Required Batch Dossier
Each implementation batch should capture:
1. scope owned
2. scope explicitly not owned
3. current anchor or sovereign owner
4. donor map
5. integration boundaries
6. acceptance criteria
7. omissions and retained-value notes
8. clean-room reservoir follow-ups
## Disposition Model
Use richer outcomes than just `include` or `omit`.
| Disposition | Meaning |
|-------------|---------|
| `first_party_owner` | FamiliarOS owns the slice directly |
| `bounded_runtime_contributor` | bounded runtime value under a first-party owner |
| `second_party_integration` | embedded surface backed by another system or package |
| `external_provider` | oracle, scanner, renderer, or service used through a boundary |
| `clean_room_reservoir` | valuable behavior queued for first-party restatement |
| `pattern_reference` | conceptual or methodological value only |
| `replace_or_rebuild` | externally useful but safer to replace with first-party FamiliarOS assets or semantics |
| `hard_omit` | low-yield or architecturally harmful for the current lane |
## Omission Screens
Before excluding a source from first-party ownership, check:
1. does it create a duplicate sovereign owner?
2. does it try to become a second product inside FamiliarOS?
3. is the operational weight much larger than the retained value?
4. is the real value just a bounded panel, provider, or sidecar seam?
5. is the value better preserved as a clean-room reservoir or first-party replacement?
If the answer to any of those is yes, do not jump straight to `hard_omit`.
## Second-Party Integration Rule
Second-party integration is legitimate when:
- FamiliarOS keeps the user-facing contract
- another system supplies backend or specialist behavior
- the imported system does not become the new center of gravity
## Revisit Triggers
Revisit a disposition when:
- an anchor changes materially
- a provider boundary proves too weak
- a clean-room reservoir is selected for implementation
- a legacy asset or mascot lane is ruled unusable and needs first-party replacement
- a supposedly omitted source later reveals a unique bounded seam
## Provenance
Translated from the VectorShell implementation-phase, anchor-registry,
omission, and retained-value doctrines through the ScriptoriumAI
consolidation pass, then rewritten into a FamiliarOS-native batch map.

95
docs/consolidated_workflows/familiaros/LICENSE_CUSTODY_AND_EVIDENCE_WORKFLOW.md Normal file
View file

@ -0,0 +1,95 @@
# FamiliarOS License, Custody, And Evidence Workflow
## Core Rule
License posture and custody truth must be evidenced, not assumed.
For every meaningful donor, dependency, asset-pack, or tool-custody decision,
verify:
- what the current source actually is
- what license grant is actually present
- whether the source is clean, mixed, mirrored, repackaged, community-submitted, or placeholder-only
- whether the route is direct, bounded, clean-room, pattern-only, replace, or omit
## Evidence Order
Use this evidence order when classifying a source:
1. root `LICENSE` or equivalent grant file
2. root package metadata with explicit license declaration
3. per-file or per-asset notices for mixed-custody detection
4. product legal/terms pages if distribution behavior matters
5. README statement only if stronger evidence is absent
## Current-Source And Mirror Rule
Do not answer present-tense custody from stale packet text alone.
1. Check whether the claimed mirror or local source path is real and populated.
2. If it is empty, placeholder-only, or clearly stale, treat it as unavailable for current truth.
3. Verify current upstream or current primary source next.
4. Use historical tracker rows only as supporting history after that check.
## Confidence Levels
| Level | Meaning |
|-------|---------|
| `high` | clear root license grant and source continuity |
| `medium` | structured metadata or legal-page evidence with weaker file-level certainty |
| `low` | README-only or partially ambiguous signals |
| `unresolved` | no reliable grant, conflicting evidence, or asset-rights uncertainty |
## Boundary-Sensitive Flags
Treat a source as boundary-sensitive when it shows any of the following:
- strong copyleft or hosted-service-triggered obligations
- proprietary or no-grant posture
- mixed custody
- metadata-only license claims with weak evidence
- fan-made, unofficial, trademark-bearing, or character-bearing asset posture
- brand/trademark conditions that complicate FamiliarOS reuse or redistribution
Boundary-sensitive does not mean low value. It means the realization route
must be more careful.
## Canonical Outputs
Track decisions in two layers:
1. `docs/REPO_LICENSE_TRACKING.md` for concrete row-level source truth
2. evidence notes for major review waves or special asset-rights questions
Evidence outputs should include:
- markdown narrative summary
- anomaly/correction notes
- route changes
- confidence upgrades or downgrades
- asset-rights replacement guidance when redistribution is unsafe
## Route Interpretation
License posture changes route, not capability authority.
- permissive: direct or bounded use may be acceptable
- attribution or file-level copyleft: boundary discipline required
- strong copyleft / no-grant / proprietary / asset-rights uncertainty: clean-room, replace, pattern-only, or omit depending on fit and feasibility
## Required Notes For Repackaged Or Community Sources
If a source has been mirrored, repackaged, or community-submitted:
- record whether upstream provenance is preserved
- record whether authorship trail survived
- record whether metadata was rewritten
- record whether pack-level rights differ from the code license
- prefer the clean original upstream or first-party replacement when the repackaged copy is provenance-thin
## Provenance
Adapted from the HyperTwist and VectorShell license trackers and
evidence-audit workflow through the ScriptoriumAI consolidation pass, then
reframed for FamiliarOS with explicit asset-rights and mascot-custody
emphasis.

205
docs/consolidated_workflows/familiaros/MEMORY_CONTINUITY_AND_ASSISTIVE_OPTIONALITY_DOCTRINE.md Normal file
View file

@ -0,0 +1,205 @@
# FamiliarOS Memory Continuity And Assistive Optionality Doctrine
## Purpose
Define one FamiliarOS-safe doctrine for:
- long-term memory and knowledge surfaces
- session continuity
- raw versus derived state
- assistive reducers, compactors, tools, and helpers
This doctrine exists because FamiliarOS already ships memory capture, chat
history, knowledge-store workflows, MCP memory tools, plugin-side AI and
memory-adjacent surfaces, and assistant-integration continuity flows. Those
capabilities need one clear canonical rule set.
## Core Thesis
FamiliarOS should not behave as if it has one monolithic memory blob.
It should preserve a federation of bounded lanes with explicit rules for:
- authority
- derivation
- replay
- provenance
- optional assistive transformation
The product becomes stronger when it keeps:
- raw chat and event history
- long-term memory entries
- knowledge-store files and search state
- plugin-derived or provider-derived suggestions
- user-authored notes and operator actions
- assistive or compacted views
distinct from one another.
## Governing Rules
1. raw authority remains authoritative
2. derived memory remains derived
3. session continuity is not the same thing as durable memory
4. user-authored notes and operator actions stay distinct from machine-derived summaries
5. provenance must survive every reduction, compaction, or export step
6. assistive compactors, reducers, tools, and helpers remain optional
7. disabling assistive features must not break the core product
8. cost or token savings do not outrank authority
9. contradiction visibility is mandatory where memory claims diverge
10. lane-local ownership is better than one flattened memory abstraction
## Canonical Lane Taxonomy
### 1. Identity And Policy Lane
Role:
- preferences
- retention posture
- provider settings
- feature gates
- privacy and consent posture
Primary FamiliarOS anchors:
- Settings
- plugin platform settings
- provider and voice configuration
### 2. Workspace Recall Lane
Role:
- last active route and UI context
- tray/control-center continuity
- operator return-to-context behavior
- recent/switcher continuity
This lane helps the operator resume work without pretending to be cognitive
memory.
### 3. Session Conversation Lane
Role:
- current conversation transcript
- multi-conversation history
- prompt-window continuity
- agent or MCP interaction continuity
### 4. Durable Memory Lane
Role:
- stored preferences, identity facts, notes, and long-term memory entries
- MCP memory read/write surfaces
- durable familiar-side recall that should survive app restarts
Primary FamiliarOS anchors:
- `apps/desktop/src/familiaros-memory.ts`
- `packages/mcp/src/tools.ts`
### 5. Knowledge Lane
Role:
- uploaded files
- extracted text
- relevance search
- retrieval context assembly
Primary FamiliarOS anchors:
- `apps/desktop/src/knowledge-store-core.ts`
- `apps/desktop/src/knowledge-store.ts`
### 6. Assistive Derived Lane
Role:
- relevance-ranked context packs
- helper summaries
- prompt-shaping aids
- plugin or provider generated convenience overlays
- broader assistive retrieval
This lane is useful, but it must never silently replace raw authority.
## Raw Versus Derived Rule
If FamiliarOS produces:
- a summary
- a reduction
- a compact context pack
- a convenience retrieval view
- a helper-generated memory suggestion
the operator must be able to tell that it is derived rather than canonical.
Examples of canonical raw state include:
- full conversation history
- raw long-term memory entries
- raw knowledge-store file records
- direct plugin or app settings state
- durable file or memory exports intentionally preserved by the operator
## Continuity And Retrieval Rule
FamiliarOS may provide richer or more economical context assembly.
That is acceptable only when:
- raw authority remains recoverable
- retrieval remains provenance-aware
- contradictions remain visible
- stricter retrieval remains available where needed
## Assistive Optionality Rule
Compactors, reducers, helpers, tools, recommendations, and similar adjuncts
must remain optional and user-deactivatable.
This includes, where applicable:
- automatic memory capture aids
- broader assistive retrieval overlays
- prompt-shaping helpers
- plugin-side AI convenience layers
- provider-specific convenience overlays
## Core-Product Invariants
FamiliarOS must still work correctly when assistive adjuncts are disabled.
That means turning them off must not break:
- familiar reactions and chat
- memory list/search/store/delete flows
- knowledge-store upload and retrieval
- MCP familiar control
- plugin runtime safety
- provider or voice settings
- session restore and route continuity
## Product-Truth Anchors Inside FamiliarOS
Current FamiliarOS evidence for this doctrine already exists in:
- `apps/desktop/src/familiaros-memory.ts`
- `apps/desktop/src/knowledge-store.ts`
- `apps/desktop/src/openapi-chat.ts`
- `apps/desktop/src/prompt-window.ts`
- `packages/mcp/src/tools.ts`
- `FEATURE_REGISTRY.md`
## Provenance Note
This FamiliarOS doctrine adapts the strongest reusable rules from the
HyperTwist continuity and optional-assistive doctrines through the
ScriptoriumAI workflow consolidation pass, then retargets them to FamiliarOS
memory, knowledge, chat, and plugin-adjacent reality.

697
docs/consolidated_workflows/familiaros/MODEL_A_B_FULL_SEQUENCE_CANON.md Normal file
View file

@ -0,0 +1,697 @@
## Prompt for Model A
You are acting as a **clean-room-oriented analysis model**.
Your task is **not** to help reproduce, paraphrase, translate, restyle, or preserve the original source code. Your task is to inspect the provided software artifact and produce a **sanitized, high-level, user-visible functional specification** that can later be handed to a separate implementation model or developer who must **not** see the original code.
The goal is to extract only the software’s **ideas, behavior, functionality, interface expectations, user-observable logic, input/output requirements, constraints, and acceptance-level requirements**, while **excluding all source-derived expressive material**.
This is a strict transformation task. You must behave as a **specification distillation layer**, not as a reverse-engineering copier.
### Core Objective
Produce a detailed, lucid, comprehensive, long-form functional specification that answers:
* What does the software do?
* What can the user see and do?
* What inputs does it accept?
* What outputs, state changes, and visible behaviors occur?
* What modes, views, tools, workflows, and user-facing operations exist?
* What external behaviors or compatibility requirements appear necessary?
* What constraints, invariants, and edge-case behaviors are implied?
* What should an independent implementer build, at the level of product behavior and requirements, without inheriting the original code’s structure or wording?
### Absolute Prohibitions
You must **not** include any of the following unless explicitly unavoidable because they are part of an external public standard, protocol, or user-visible contractual interface:
1. **No code snippets**
2. **No pseudocode that mirrors the original implementation**
3. **No function names, method names, class names, variable names, internal identifiers, or file names from the source**
4. **No module structure, architecture skeleton, directory layout, or internal decomposition copied from the source**
5. **No direct quotes from comments, docs, inline strings, or error text unless the exact wording is externally required**
6. **No source-like sequencing that effectively reconstructs the implementation**
7. **No copied tests, assertions, fixtures, snapshots, regexes, internal constants, lookup tables, or data schemas unless they are clearly external/public requirements**
8. **No distinctive algorithmic implementation detail when a higher-level behavioral description is sufficient**
9. **No line-by-line paraphrase of the code**
10. **No description that would allow someone to recreate the original source structure rather than independently designing a fresh implementation**
If you find yourself producing something that sounds like disguised source code, stop and abstract it upward.
### What You May Preserve
You may preserve only the following categories of information:
* User-visible features
* User workflows
* Interface behavior
* Functional requirements
* Input and output behavior
* State transitions at a product or behavior level
* Externally visible modes and views
* Validation rules visible from usage or required by external compatibility
* Data entities at a conceptual level
* External interoperability requirements
* Performance expectations only if clearly behaviorally relevant
* Edge cases only at the behavior level
* Acceptance criteria
* Compatibility targets
* High-level safety or correctness invariants
* Domain logic expressed generically and behaviorally
### Required Abstraction Rule
Whenever you encounter implementation detail, transform it upward using this priority:
1. **User-visible behavior**
2. **Functional requirement**
3. **Conceptual rule**
4. **Acceptance criterion**
5. **Open design constraint for independent implementer**
Never descend back into source-derived wording or internal structure.
### Transformation Standard
Your output must read like a **product requirements document** or **functional design specification**, not like notes from someone who inspected code.
That means:
* Use long-form paragraph prose where appropriate
* Be comprehensive
* Be explicit
* Be structured
* Be behavior-centric
* Be implementation-agnostic
* Be lucidly composed
* Be neutral in tone
* Do not romanticize, speculate wildly, or fill gaps with invention
* Distinguish clearly between:
* directly evidenced behavior,
* strong inference,
* uncertainty,
* open implementation choice
### Handling Uncertainty
If the source suggests a feature but does not fully establish it, do not invent specifics.
Use one of these labels:
* **Directly evidenced**
* **Strongly implied**
* **Uncertain / requires independent product decision**
* **Externally required if compatibility is desired**
Whenever precision would force you to expose source-derived expression, abstract further and mark the area as requiring independent design.
### If External Standards Are Involved
If the software interacts with public standards, public file formats, public APIs, hardware conventions, or well-known protocols, you may refer to those standards **at the public-interface level**.
However:
* do not reproduce internal wrappers around them,
* do not preserve code-specific naming,
* do not mirror source-specific adapter structure,
* do not convert proprietary internal logic into thinly disguised prose.
### Output Format
Produce the output in the following structure.
## 1. Executive Functional Overview
Write a long-form overview explaining what the software appears to be, what primary problem it solves, what the major user-facing capabilities are, and what kind of independent reimplementation would need to preserve at the level of behavior and product function.
## 2. Feature Inventory
List every substantial user-visible or externally relevant feature. For each feature, include:
* Feature name expressed generically
* What the feature enables the user to do
* When or where it appears
* What inputs it accepts
* What visible outputs or changes it produces
* Any visible modes, options, or settings
* Any notable constraints or boundaries
* Whether it is directly evidenced or inferred
Do **not** use names lifted from the code unless they are unavoidable public-facing product labels.
## 3. User Workflows and Interaction Narratives
Describe the major flows in paragraph form. Cover how a user likely moves through the software from beginning to end.
Examples of workflow categories include:
* startup / initialization behavior
* opening or creating a working state
* interacting with the main visual area
* changing modes or views
* editing / manipulating content
* triggering computations, transformations, or actions
* saving, exporting, syncing, or resetting
* responding to errors or invalid input
Each workflow must be described behaviorally, not architecturally.
## 4. Interface and View Behavior
Describe the visible interface structure only at a user-facing level.
Include:
* main regions or panels
* controls
* overlays
* toggles
* inspectors
* sidebars
* toolbars
* canvases
* status displays
* view modes
* orientation / navigation affordances
* feedback signals such as highlighting, animation, previewing, warnings, or state indicators
Do not describe component hierarchies as they exist in the source. Describe what the user experiences.
## 5. Core Domain Logic
Describe the software’s conceptual logic in generic terms.
Focus on:
* the domain objects or entities the software manipulates
* their visible properties
* how actions transform state
* what rules govern valid and invalid operations
* what outcomes must remain consistent
* what the user would expect to stay invariant
If the code contains sophisticated logic, do not mirror the implementation. Instead describe the governing behavior, constraints, and expected results.
## 6. Inputs, Outputs, and State
Describe:
* what inputs the user or system can provide
* what outputs the software emits or displays
* what persistent or transient state appears to exist
* what user actions update that state
* what resets it
* what should survive across sessions, if applicable
* what state transitions are user-visible
Use conceptual terms. Avoid source schema reproduction.
## 7. Validation, Constraints, and Edge Cases
Describe behavior around:
* invalid actions
* invalid inputs
* impossible states
* limits
* fallback behavior
* empty states
* first-use states
* partial-completion states
* interruption states
* conflict states
* recovery conditions
* visible error prevention or correction behavior
Again, keep it behavioral rather than source-structural.
## 8. External Interfaces and Compatibility Expectations
Describe any external requirements or interoperability behaviors that an independent reimplementation would likely need to preserve.
Examples:
* file import/export expectations
* protocol compatibility
* hardware input behavior
* browser or platform assumptions
* persistence expectations
* public integration touchpoints
Do not expose internal adapters, wrappers, or source-derived interface structure.
## 9. Non-Functional Requirements
Only include these if genuinely evidenced:
* responsiveness expectations
* stability expectations
* precision or correctness requirements
* real-time update expectations
* animation smoothness requirements
* persistence reliability expectations
* usability expectations implied by the software’s behavior
Do not invent performance numbers unless directly evidenced and externally meaningful.
## 10. Acceptance Criteria for Independent Reimplementation
For each major feature or workflow, provide behavioral acceptance criteria in plain language.
These must answer questions like:
* What would it mean for a new implementation to be functionally faithful?
* What must the user be able to do?
* What visible outcome must occur?
* What must remain consistent or correct?
Acceptance criteria must be phrased as user-observable tests, not source tests.
## 11. Open Design Space
Explicitly identify what remains free for a clean independent implementer to decide.
Examples:
* internal architecture
* data structures
* algorithms
* component boundaries
* naming
* rendering strategy
* storage layout
* event model
* error-handling internals
* abstractions
This section is important. It should make clear that the output is a behavioral specification, not an implementation blueprint copied from the source.
## 12. Sanitization Audit
At the end, include a final section called:
**Sanitization Audit**
In that section, explicitly confirm that you have checked for and removed:
* source identifiers
* copied wording
* code-like phrasing
* module/file structure
* implementation-specific sequencing
* source-derived pseudocode
* reconstructive detail
* copied internal terminology
Also list any places where you had to abstract aggressively in order to avoid leaking source expression.
### Writing Style Requirements
Your output must be:
* elaborate
* comprehensive
* detailed
* lucid
* orderly
* sober
* plain in diction
* free of unnecessary bullet fragmentation when paragraph prose is better
* clear about evidence versus inference
* free of code or code-adjacent formatting unless unavoidable for public-interface naming
### Additional Filtering Rules
Apply the following filters before finalizing:
#### Filter A: Expression Leakage Check
Ask yourself whether any sentence could help reconstruct the original code’s internal structure. If yes, rewrite it more abstractly.
#### Filter B: Identifier Leakage Check
Remove or generalize all names not required for public-facing accuracy.
#### Filter C: Sequence Leakage Check
If you are describing a process in a sequence that mirrors source order rather than user logic, rewrite it around user experience or functional causality.
#### Filter D: Architecture Leakage Check
If a paragraph sounds like a developer commentary on how the code is organized, replace it with what the software accomplishes.
#### Filter E: Reimplementation Freedom Check
Ensure that a competent engineer could build the same functionality in a materially different architecture from your output.
### Examples of Good Transformation
Bad:
“The application uses [internal module name] to map rotations through [internal state object] and then triggers [internal render function].”
Good:
“When the user initiates a rotation, the visible state of the interactive object updates to reflect the new orientation and face-color arrangement, and the display refreshes accordingly.”
Bad:
“The left panel is rendered by [component name] and stores mode state in [hook/store name].”
Good:
“A side panel allows the user to switch between viewing modes and adjust the way information is presented.”
Bad:
“The solver runs in three passes using [internal function names].”
Good:
“A solving or analysis action appears to process the current state and return a result based on defined transformation rules. The user-visible requirement is that the result be consistent and reproducible for the same input state.”
### Final Instruction
Do not implement anything.
Do not suggest code.
Do not write pseudocode.
Do not preserve source expression.
Do not compress this into a short summary.
Produce a **full, carefully sanitized, behavior-level functional specification** suitable for handoff to a separate independent implementation process.
---
## Optional companion instruction for extra strictness
You can append this at the end if you want the filter to be even stricter:
**Strict separation clause:**
Assume that a second model, developer, or team will rely exclusively on your output and must not inherit any protected expressive structure from the inspected source. Therefore, whenever there is tension between completeness and abstraction, preserve completeness at the level of behavior, but abstract away all source-derived expression, naming, structure, and implementation detail.
---
## Optional short wrapper you can place above it
Use this if you want to frame the task even more plainly before the main prompt:
“Inspect the source code only to determine what the software does from a user-visible and product-functional perspective. Then convert that into a sanitized behavioral specification. Do not preserve the code’s expression, wording, names, architecture, sequence, or structure.”
-----
Understood. From now on, when I generate a Model A prompt for this kind of workflow, I will also generate the matching Model B prompt by default.
Below is a ready-to-paste **Model B** prompt that pairs with the Model A prompt I gave you above.
---
## Prompt for Model B
You are acting as an **independent clean-room implementation model**.
You have **not** seen the original source code and must **not** request, infer, reconstruct, mimic, or recover it. Your only permitted input is a **sanitized functional specification** prepared by a separate analysis process. Your task is to design and implement a fresh solution based solely on that behavioral specification.
Your goal is to create an **independently designed implementation** that reproduces the required **functionality, user-visible behavior, compatibility targets, and acceptance criteria**, while avoiding any inheritance of the original program’s protected expression, internal structure, naming, sequencing, or architecture.
You are not a restoration model.
You are not a paraphrase model.
You are not a source reconstruction model.
You are an **independent implementer**.
### Core Objective
Build the requested software or software component from the sanitized specification alone.
You must preserve only:
* user-visible behavior
* functional requirements
* external inputs and outputs
* compatibility requirements
* acceptance criteria
* behavioral constraints
* correctness requirements
* evident domain rules
You must independently choose:
* architecture
* modules
* file structure
* naming
* algorithms
* abstractions
* component boundaries
* state management strategy
* rendering strategy
* storage layout
* event flow
* error-handling internals
* testing strategy
### Absolute Prohibitions
You must **not** do any of the following:
1. Do not ask to see the original code.
2. Do not ask for excerpts, snippets, function names, file names, class names, or internal identifiers from the original source.
3. Do not attempt to reconstruct the original architecture.
4. Do not mirror naming conventions from the original implementation.
5. Do not request line-by-line behavior if doing so would effectively recreate source structure.
6. Do not produce code that intentionally imitates a presumed original layout.
7. Do not state or imply that the best way is to inspect the old code.
8. Do not try to infer hidden implementation details unless required by the functional specification.
9. Do not treat unspecified internals as fixed; treat them as open design space.
10. Do not produce “translation-style” code that feels like a disguised rewrite of an unseen original.
If there is any gap in the specification, resolve it through **independent engineering judgment**, not through speculation about the original code.
### Governing Principle
Treat the sanitized specification as a **product requirements document**, not as a compressed representation of prior source code.
Your job is to create a **fresh implementation** that satisfies the required behavior while remaining materially independent in design.
### Required Design Posture
You must operate with the following mindset:
* Behavior fidelity, not expression fidelity
* Product equivalence, not code resemblance
* Functional satisfaction, not structural recovery
* Independent engineering judgment, not reverse reconstruction
Whenever multiple valid designs could satisfy the requirements, prefer the design that is:
* clear
* maintainable
* conventional
* testable
* internally coherent
* independently justifiable
### Handling Specification Gaps
If the sanitized specification leaves details open, do the following:
1. Preserve all explicit requirements exactly at the behavioral level.
2. Identify what is unspecified.
3. Choose a reasonable independent design.
4. Mark those choices clearly as implementation decisions rather than source-derived facts.
5. Avoid overfitting to what the original software might have done internally.
Use the following labels where appropriate:
* **Specified requirement**
* **Independent implementation choice**
* **Assumption made for completeness**
* **Open configuration point**
* **Needs confirmation only if materially important**
Do not halt on every ambiguity. Make grounded choices unless the missing information would make the output unusable.
### Output Modes
Depending on the user’s request, produce one or more of the following:
* implementation plan
* architecture proposal
* module breakdown
* data model
* UI design plan
* algorithm selection rationale
* code
* tests
* documentation
* migration notes
* validation checklist
However, all such outputs must remain independently designed and must not attempt to track any unseen original source layout.
### If Asked to Write Code
When writing code:
* use fresh names
* choose your own file organization
* choose your own abstractions
* prefer standard, readable conventions
* include comments only where genuinely helpful
* do not write code that appears reverse-translated from another implementation
* do not introduce oddly specific structure unless the spec truly requires it
* ensure the result could plausibly have been built from the specification alone
### If Asked to Propose Architecture First
When first designing the solution, structure the response as follows:
## 1. Functional Restatement
Briefly restate the required behavior in your own words based solely on the sanitized specification.
## 2. Independent Design Strategy
Explain how you intend to satisfy the requirements without assuming any prior internal structure.
## 3. Proposed Architecture
Describe the major parts of the implementation using fresh, independently chosen boundaries and names.
## 4. Data and State Design
Describe what state must exist, what data must be tracked, and how the system will manage updates.
## 5. Interaction or Processing Flow
Explain how the system behaves during the major workflows, using your own design logic.
## 6. Edge Cases and Validation
Show how your implementation will address invalid inputs, unusual states, and recovery conditions.
## 7. Testing Strategy
Describe how you will verify functional fidelity using behavior-based tests rather than source-derived tests.
## 8. Open Choices
Explicitly list implementation decisions that are independent choices rather than requirements imposed by the specification.
### If Asked to Write Tests
Write tests against:
* user-visible behavior
* required outputs
* invariants
* edge cases
* acceptance criteria
* compatibility expectations
Do not write tests that assume hidden internal functions or structures unless those are part of your own independent design.
### If Asked to Build UI Logic
Design the UI from the user-visible requirements alone.
You may preserve:
* required panels
* controls
* views
* visible feedback
* workflow structure
* necessary mode switching
You must independently choose:
* component structure
* naming
* event wiring
* rendering model
* organization of presentation logic
### If Asked to Implement Domain Logic
Implement the domain rules described in the specification, but do so from first principles.
Do not attempt to “guess the original algorithm.”
Instead, ask:
* What behavior must be true?
* What invariants must hold?
* What outputs are required for given inputs?
* What design best satisfies those rules?
Then implement accordingly.
### Independence Check
Before finalizing any output, apply the following checks:
#### Check A: Reconstruction Drift
Does any part of this output seem aimed at recovering an unseen original implementation rather than solving the stated problem independently? If yes, rewrite it.
#### Check B: Naming Independence
Are the identifiers fresh and self-justifying? If not, rename them.
#### Check C: Structural Independence
Could this implementation plausibly have been designed from the specification alone? If not, redesign the structure.
#### Check D: Behavioral Sufficiency
Does the implementation satisfy the functional requirements and acceptance criteria without relying on presumed hidden details? If not, strengthen the design.
#### Check E: Open-Space Respect
Have you treated unspecified implementation details as open design space rather than frozen constraints? If not, revise accordingly.
### Required Style
Your responses must be:
* lucid
* technically competent
* deliberate
* independent in reasoning
* explicit about assumptions
* explicit about implementation choices
* free of source-reconstruction language
* behavior-focused
* grounded in software engineering best practice
### Final Instruction
You must work **only** from the sanitized functional specification.
You must not request or recreate the original source.
You must not optimize for resemblance to an unseen implementation.
You must optimize for **functional fidelity through independent design**.
Where the specification is precise, follow it.
Where the specification is open, choose well.
Where uncertainty exists, make independence-preserving engineering decisions.
---
## Optional strict add-on
You can append this if you want the separation enforced even more strongly:
**Strict independence clause:**
Assume the original source is legally and operationally unavailable. Any attempt to recover its naming, structure, sequencing, or design would be a workflow failure. Therefore, implement only the behavior described in the sanitized specification, and treat all internal design matters as open unless explicitly constrained by external requirements.
---
## Best paired wrapper for both models
You can use this two-step framing across sessions:
**Model A:** inspect source, produce sanitized behavior-level specification only.
**Model B:** implement independently from sanitized specification only.
---
There is also a useful short version you can prepend when you want speed:
**Short Model B wrapper:**
“Implement this as a fresh design from the sanitized functional specification alone. Do not request or reconstruct original source details. Preserve behavior and acceptance criteria, but independently choose names, architecture, modules, algorithms, and internal structure.”
If you want, I can also merge both prompts into one **paired reusable master template** with clear separators for Model A and Model B so you can paste a single block and reuse it every time.

180
docs/consolidated_workflows/familiaros/OPERATOR_WORKBENCH_AND_VISUALIZATION_DOCTRINE.md Normal file
View file

@ -0,0 +1,180 @@
# FamiliarOS Operator Workbench And Visualization Doctrine
## Purpose
Define how FamiliarOS should behave as a unified desktop companion platform
and how its multi-surface UI should stay coherent across the desktop app,
Control Center, familiar windows, plugins, and website front door.
This doctrine exists to keep future implementation, documentation, and
cleanup work aligned on:
- operator-first control
- companion-centered multi-surface composition
- route and pane handoff discipline
- attention routing
- layout and focus restoration
- motion and visual-language guardrails
## Core Stance
FamiliarOS is not:
- a generic Electron shell with a mascot bolted on
- a website-first SaaS wrapper with a desktop afterthought
- a donor-branded shell under a new name
- a pane farm of disconnected mini-apps
FamiliarOS is:
- a local-first desktop companion platform
- a living familiar system with operator tooling around it
- a multi-surface control plane for familiars, integrations, plugins, memory, voice, and chat
## Operator-First Rule
AI helpers, plugins, agent bridges, and automation surfaces may propose,
stream, preflight, or prepare work.
They do not replace the operator as the final owner of:
- approval
- intervention
- configuration changes
- memory retention decisions
- plugin enablement and permissions
- provider and credential routing
- deletion, cleanup, or remote-sync decisions
## Attention Model
Every meaningful action should land in one of these classes:
1. background
2. queued attention
3. notification
4. approval or intervention
5. blocking interrupt
Do not collapse all operator signals into one generic alert lane.
Typical examples:
- catalog refresh, plugin sync, and idle provider checks belong to background or queued attention
- installation/update failures, broken familiars, and lease-routing problems belong to approval or intervention
- provenance failures, asset-rights contradictions, or destructive cleanup questions may justify blocking interrupt treatment
## Canonical Workbench Surfaces
### 1. Tray And Familiar Surface
Should expose the living companion itself plus the fastest top-level actions:
- show/hide familiar
- pause/resume familiars
- open Control Center
- open floating chat or prompt surface
- reveal important status without making the familiar unreadable
### 2. Control Center Surface
The Control Center is the canonical operator workbench inside the desktop app.
It should carry the durable control rails:
- Dashboard
- Familiars
- Integrations
- Plugins
- Settings
### 3. Familiar Window Surface
The familiar window remains the emotional and ambient center of gravity.
Its main role is:
- reaction and animation display
- safe short speech and status cues
- pinned or transient plugin bubbles
- light interaction that supports the operator instead of fighting for focus
### 4. Floating Chat And Knowledge Surface
Should support:
- direct FamiliarOS conversation
- memory and knowledge retrieval
- MCP tool use for built-in chat
- file attachment and knowledge-store workflows
### 5. Website Front Door
The website is a front door, not a second sovereign product shell.
It should feel like a coherent extension of the desktop product identity and
hand off cleanly into download, trust, docs, and account-adjacent flows.
## Layout And Reconfiguration Rules
FamiliarOS should support:
- route-targeted Control Center entry
- focus restoration
- keyboard-driven or quick-open route switching where practical
- persistent preferences for the operator's last useful state
- reduced-motion-safe transitions
Reconfiguration is valid only when:
- session identity remains shared
- the familiar remains the product's emotional center of gravity
- route handoff remains reversible
- hidden panels preserve state safely
- no duplicate parallel truth model is created
## Motion And Visual-Language Rule
FamiliarOS should feel calm, alive, and companion-like.
Prefer:
- sparse chrome
- expressive motion with bounded amplitude
- intentional ambient motion over constant dashboard noise
- stateful loaders and indicators that communicate meaning cleanly
- premium but readable familiar windows and plugin bubbles
Avoid:
- a permanently saturated UI
- donor-branded visual identity
- motion that competes with the familiar itself
- a website or settings panel that feels detached from the desktop companion concept
## Non-Drift Rules
Do not let the workbench drift into:
- donor-branded UI language
- a website-first center of gravity
- a generic settings dashboard detached from the living companion
- a chat-first posture that demotes the familiar and Control Center to accessories
## Product-Truth Anchors Inside FamiliarOS
Current FamiliarOS evidence for this doctrine already exists in:
- `apps/desktop/src/windows.ts`
- `apps/desktop/src/familiar-window.ts`
- `apps/desktop/src/renderer/src/main.tsx`
- `apps/desktop/src/prompt-window.ts`
- `website/`
- `docs/plan/FAMILIAROS_PRODUCT_ROADMAP_2026-06-17.md`
## Provenance Note
This FamiliarOS doctrine reuses the strongest general patterns from the
VectorShell operator-model and visual-language doctrine and the ScriptoriumAI
workbench-consolidation pass. It does not adopt donor XR, research-writing,
or training-product identity as FamiliarOS truth.

142
docs/consolidated_workflows/familiaros/PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE.md Normal file
View file

@ -0,0 +1,142 @@
# FamiliarOS Provider Neutrality And BYOK Doctrine
## Purpose
Define the canonical FamiliarOS rule for provider routing, BYOK custody, and
provider-neutral product contracts.
This doctrine exists because FamiliarOS already ships or exposes:
- OpenAPI-compatible chat routing
- provider presets and custom endpoints
- plugin AI gateway provider selection
- BYOK-style credential storage for chat and plugin AI
- voice/TTS provider choice
- operator-facing provider and status surfaces in Settings
Those capabilities need one first-party doctrine that explains how they
should remain product-safe.
## Interpretation Rule
When FamiliarOS uses the language:
- `OpenAPI chat`
- `provider`
- `custom endpoint`
- `BYOK`
the intended meaning is provider-neutral model or voice access with
first-party custody over the user's routing profile, not product-wide lock-in
to one upstream vendor.
## Core Rule
FamiliarOS must remain provider-neutral at the top-level product-contract
layer.
That means:
- no single-provider donor or adapter may define the product contract
- operator-visible routing, health, usage, and model-choice surfaces must read normalized first-party provider state
- provider-specific behavior may survive only as bounded adapter or overlay logic
## First-Party Ownership Lanes
The following lanes remain first-party FamiliarOS responsibilities:
1. provider contract lane
2. routing and policy lane
3. provider-profile and BYOK custody lane
4. normalized usage, quota, and cost lane where exposed
5. operator-facing routing status lane
6. privacy, storage, and safety lane
Provider-specific integrations may contribute bounded implementation detail.
They do not own the top-level contract.
## Required Provider Classes
FamiliarOS's normalized provider model should continue to support at least:
1. official direct providers
2. OpenAI-compatible custom endpoints
3. user-supplied BYOK profiles
4. local or self-hosted providers
5. bounded non-LLM adjunct services where routing policy also matters
## Normalized Contract Rule
Operator-facing UI should be able to reason about at least:
- provider identity
- profile identity
- model or voice identity
- endpoint class
- auth source
- capability flags
- health state
- usage or cost state where available
- quota or rate-limit state where available
- routing or fallback state
The UI should not need to hard-code one vendor's worldview.
## BYOK Rule
BYOK is a first-party capability, not a donor side effect.
That means:
- user-supplied keys remain under first-party FamiliarOS custody rules
- custom endpoint definitions remain first-party
- model/profile mapping remains first-party
- provider-specific adapters must plug into the first-party profile model instead of creating parallel custody systems
## Anti-Lock-In Rules
1. no core product flow should assume one provider exists
2. no premium or advanced surface should present one vendor as the only normal path when a normalized first-party path is available
3. provider-specific enhancements must degrade gracefully when that provider is disabled or absent
4. routing and fallback policy should remain visible rather than implicit
## Operator-Surface Rule
Routing, BYOK, and provider state are not purely backend concerns.
The operator should be able to inspect:
- what route is active
- whether a BYOK bridge is active
- what capability set is available
- whether fallback preserved or reduced capability
- whether upgrade or policy gating is the real blocker
## Product-Truth Anchors Inside FamiliarOS
Current FamiliarOS evidence for this doctrine already exists in:
- `apps/desktop/src/openapi-chat.ts`
- `apps/desktop/src/plugin-ai-gateway.ts`
- `apps/desktop/src/plugin-platform-settings.ts`
- `apps/desktop/src/tts-engine.ts`
- `apps/desktop/src/renderer/src/main.tsx`
- `FEATURE_REGISTRY.md`
## Implementation-Order Rule
The safe order remains:
1. normalized first-party contract
2. first-party profile and BYOK custody
3. routing and fallback policy
4. usage and quota visibility where applicable
5. operator-facing control and status surfaces
6. bounded provider-specific overlays
## Provenance Note
This FamiliarOS doctrine adapts the strongest reusable rules from the
HyperTwist provider-neutrality and BYOK doctrine through the ScriptoriumAI
consolidation pass, then applies them to FamiliarOS chat, plugin AI, and
voice/provider reality.

74
docs/consolidated_workflows/familiaros/README.md
View file

@ -1,28 +1,47 @@
# FamiliarOS Workflow Manual
This folder is the canonical, FamiliarOS-branded home for the integrated
workflow doctrine needed to operate, harden, and reconcile the product without
falling back to donor-project identity.
workflow doctrine needed to operate, evaluate, harden, and reconcile the
product without drifting back into donor-project identity.
## How To Use This Pack
Start here when the task is about:
- product-truth precedence
- leftover parallel surfaces
- desktop companion vs website vs control-panel ownership
- rebranding corrections
- remote execution and reverse-sync boundaries
- archive, backup, or artifact cleanup
- strategic cleanup choices that should not be silently auto-decided
- current product-truth precedence
- desktop companion versus website versus control-center ownership
- repo intake, donor evaluation, or clean-room implementation planning
- Model A / Model B sequence and clean-room handoff discipline
- license, custody, asset-rights, or evidence workflow questions
- feature-registry closeout and roadmap reconciliation
- implementation batching and retained-value disposition
- operator workbench, animation, and surface-composition doctrine
- memory, knowledge, continuity, or assistive optionality rules
- provider-neutral, BYOK, or local-versus-cloud routing decisions
- archive, backup, artifact, cleanup, or remote-execution boundaries
## High-Importance Gap Audit
If the question is "what important doctrine was still missing after the first
FamiliarOS transfer pass, and what was promoted now?", read:
- `HIGH_IMPORTANCE_TRANSFER_GAP_AUDIT_2026-06-18.md`
## Canonical Reading Order
1. `PROJECT_AUTHORITY_AND_RECONCILIATION.md`
2. `DESKTOP_COMPANION_AND_FRONT_DOOR_DOCTRINE.md`
3. `DECISION_GATES_FRONT_DOOR_AND_REMOTE_EXECUTION.md`
4. `ARTIFACT_STORAGE_AND_RUNTIME_BOUNDARIES.md`
5. `HIGH_IMPORTANCE_TRANSFER_GAP_AUDIT_2026-06-17.md`
1. `MODEL_A_B_FULL_SEQUENCE_CANON.md`
2. `PROJECT_AUTHORITY_AND_RECONCILIATION.md`
3. `DESKTOP_COMPANION_AND_FRONT_DOOR_DOCTRINE.md`
4. `REPO_EVALUATION_AND_CLEAN_ROOM_PLAYBOOK.md`
5. `LICENSE_CUSTODY_AND_EVIDENCE_WORKFLOW.md`
6. `FEATURE_REGISTRY_AND_DEEP_SOURCE_CLOSEOUT.md`
7. `IMPLEMENTATION_BATCHING_AND_DISPOSITION.md`
8. `OPERATOR_WORKBENCH_AND_VISUALIZATION_DOCTRINE.md`
9. `MEMORY_CONTINUITY_AND_ASSISTIVE_OPTIONALITY_DOCTRINE.md`
10. `PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE.md`
11. `ARTIFACT_STORAGE_AND_RUNTIME_BOUNDARIES.md`
12. `DECISION_GATES_FRONT_DOOR_AND_REMOTE_EXECUTION.md`
13. `HIGH_IMPORTANCE_TRANSFER_GAP_AUDIT_2026-06-18.md`
## Scope Boundary
@ -30,13 +49,28 @@ These docs are written for FamiliarOS.
- They may cite OpenPets, ScriptoriumAI, HyperTwist, or VectorShell as source provenance.
- They should not treat donor product identity as FamiliarOS product truth.
- If donor guidance conflicts with current FamiliarOS implementation reality,
current FamiliarOS reality wins and the conflict should be documented.
- If donor guidance conflicts with current FamiliarOS implementation reality, current FamiliarOS reality wins and the conflict should be documented explicitly.
## Provenance Boundary
Reusable generic support docs are retained locally under:
- `../shared/`
Donor-specific extraction context still lives primarily in the upstream
ScriptoriumAI, VectorShell, and HyperTwist documentation surfaces. FamiliarOS
imports the reusable operating doctrine, not donor product identity.
## Compacting Rule
This FamiliarOS pack is intentionally compact.
This FamiliarOS front-door pack is intentionally compacted relative to the raw
donor corpus, but broader than the earlier mini-pack.
- It is for day-to-day execution and cleanup decisions.
- It does not replace detailed phase specs, code docs, or sensitive ops material.
- When a later pass needs deeper donor tracing, use the retained upstream packs rather than re-expanding this front door into a donor mirror.
- The canonical FamiliarOS docs are for day-to-day execution.
- The shared adjunct docs preserve reusable cross-project workflow doctrine.
- If a later pass needs finer-grained donor tracing, expand from the retained shared docs and upstream donor authorities rather than pretending the detail was discarded.
Exception:
- `MODEL_A_B_FULL_SEQUENCE_CANON.md` is intentionally retained in full because the generic Model A / Model B handoff sequence is itself a reusable operating artifact rather than only a doctrine summary.
- `HIGH_IMPORTANCE_TRANSFER_GAP_AUDIT_2026-06-18.md` remains a compact audit note so later passes can answer what was missing and why it was promoted.

107
docs/consolidated_workflows/familiaros/REPO_EVALUATION_AND_CLEAN_ROOM_PLAYBOOK.md Normal file
View file

@ -0,0 +1,107 @@
# FamiliarOS Repo Evaluation And Clean-Room Playbook
## Purpose
Use this playbook when FamiliarOS evaluates external repos, donor codebases,
or large reference systems for possible adoption, bounded integration, or
clean-room reimplementation.
## Evaluation Pipeline
Run the evaluation in explicit phases.
| Phase | Goal |
|-------|------|
| `P0` | Intake the repo, scope the question, and capture the current source location |
| `P1` | Establish product-fit hypotheses for FamiliarOS specifically |
| `P2` | Inspect real source, architecture, tests, assets, and external contracts |
| `P3` | Classify authority, route, realization width, and likely disposition |
| `P4` | Decide between direct use, bounded integration, provider use, or clean-room restatement |
| `P5` | Produce implementation dossier, omissions, and follow-up queue |
| `P6` | Reconcile tracker rows, evidence artifacts, roadmap notes, and canonical docs |
Do not stop at README-level impressions when architecture, asset-rights, or
capability questions remain open.
## FamiliarOS Product-Fit Rule
Evaluate from FamiliarOS's actual product seams first:
- desktop familiar runtime and interaction model
- Control Center and operator surfaces
- local IPC, MCP, and coding-agent integrations
- plugin platform, official plugins, and extension boundaries
- memory, knowledge, voice, and provider-routing systems
- website/front-door, download, and account-adjacent surfaces
- ops, deployment, remote-sync, and documentation custody surfaces
Do not import another product's shell identity, vocabulary, or center of
gravity just because it has useful subsystems.
## Model A / Model B Separation
Use distinct roles when the source is boundary-sensitive or the feature is
large enough to need clean-room handling.
### Model A
- reads donor/source material
- extracts capability, structure, constraints, tests, and hidden seams
- writes a neutral implementation dossier
- does not author the final first-party code
### Model B
- implements from the clean-room dossier
- does not consult restricted donor material directly
- treats FamiliarOS terminology, contracts, runtime boundaries, and current product identity as authoritative
## Clean-Room Trigger Rule
Prefer a clean-room route when any of these are true:
- the source is restrictive, mixed-custody, or no-grant
- the feature is donor-distinctive rather than generic
- the source would otherwise pull in a second product identity
- the implementation would depend on donor naming, factoring, or product semantics
- asset, mascot, or trademark posture would contaminate first-party FamiliarOS redistribution
### Tiny Generic Feature Exception
Direct first-party implementation without a separate clean-room lane is
acceptable only when the feature is:
1. tiny
2. generic
3. describable without donor taxonomy
4. implementable without donor semantics or structure
If any one of those is unclear, keep it in the clean-room lane.
## Required Dossier Outputs
Every serious repo evaluation should produce a dossier with:
- source location and source-truth note
- capability summary
- hidden high-value seams
- FamiliarOS product-fit read
- authority/route/width classification
- preferred realization path
- omissions and retained-value notes
- clean-room requirements, if applicable
- follow-up tests or validation gates
## What Not To Do
- Do not answer product-fit from donor branding alone.
- Do not treat restrictive as equivalent to valueless.
- Do not flatten bounded integration candidates into hard omits prematurely.
- Do not let donor shell identity silently rewrite FamiliarOS product language.
## Provenance
Restated from the project-agnostic repo-evaluation packs, the HyperTwist
clean-room doctrine, and the shared Model A / Model B prompt lineage, then
translated into FamiliarOS-first operating language through the recent
ScriptoriumAI consolidation pass.

181
docs/consolidated_workflows/shared/BACKFILL_PROCEDURES.md Normal file
View file

@ -0,0 +1,181 @@
# Backfill Procedures
**Consolidated from:**
- `HyperTwist/docs/ops/HYPERTWIST_RETROACTIVE_AUTHORITY_AND_CLEANUP_BACKFILL_2026-05-20.md`
- `VectorShell/docs/ops/VECTORSHELL_0R_C_RETROACTIVE_A_R_F_BACKFILL_2026-05-19.md`
- `VectorShell/docs/ops/VECTORSHELL_0R_C_RETROACTIVE_SKILLIZATION_BACKFILL_2026-05-21.md`
- `VectorShell/docs/ops/VECTORSHELL_A1_TO_A14_POST_OMISSION_AND_DISPOSITION_BACKFILL_2026-06-01.md`
**Purpose:** Define the canonical rules for retroactive authority backfill, cleanup backfill, skillization backfill, and post-omission disposition backfill across a closed corpus of evaluated repositories.
---
## Core Governing Rule
> Do not do fake whole-corpus rewrites. Do not do blind full resets. Do not invent certainty for older ambiguous packets.
Backfill is **selective, comparative, and operational** — not cosmetic.
The correct target is the **contested slice** or **relied-on ambiguity**, not blanket relabeling.
---
## Backfill Class A: Authority Backfill
### Trigger Conditions
Authority backfill is triggered when:
- A later same-family repo materially changes a contested capability slice.
- An older packet's winner versus adjunct versus reference versus pattern split is ambiguous.
- A restrictive or otherwise harder-route repo appears to be the stronger authority and was previously softened incorrectly.
### Requirements
1. Reopen the earlier affected packet or standing note **selectively**.
2. Name the **exact earlier packet or standing note** reopened.
3. State the **exact contested slice**.
4. Preserve valid repo-local extraction unless later evidence materially changes it.
5. State whether the change is:
- repo-local extraction changed
- cross-lane authority changed
- only wording changed
### Non-Permissions
Authority backfill is **not** permission to:
- Reset an entire family cluster by default.
- Relabel every older packet for appearance.
- Flatten preserved secondary value from non-winners into exclusion.
---
## Backfill Class B: Cleanup Backfill
### Trigger Conditions
Cleanup backfill is triggered when an older packet or workflow doc is still operationally relied on but is ambiguous about:
- Temporary root used.
- Whether cleanup happened.
- Whether retained residue was intentional.
- Whether remaining dirt is packet-created or pre-existing.
### Requirements
1. Mark the ambiguity **explicitly** instead of inventing certainty.
2. Backfill only where the ambiguity still matters operationally.
3. Name the exact earlier packet, standing note, or workflow doc reopened.
4. State whether the change is:
- cleanup interpretation changed
- only wording changed
- packet truth itself changed
### Non-Permissions
Cleanup backfill is **not** permission to:
- Bulk-rewrite older closeouts for appearance.
- Claim a repo was clean when only packet dirt was removed.
- Erase plausible pre-existing residue by narrative rewrite.
---
## Backfill Class C: Skillization Backfill
### Purpose
Make the skillization doctrine operational across a closed corpus without pretending every retained repo should become a live skill.
### Method
1. Inventory the full closed corpus.
2. Classify each repo into one primary future skillization posture.
3. Assign a skillization class describing what must happen before or instead of live skill wrapping.
4. Preserve packet truth for route and lane boundaries.
### Skillization Postures
| Posture | Meaning |
|---------|---------|
| `feature_first` | Build the product capability or service first; skill wrapper deferred |
| `live_wrapper_candidate` | A first-party skill wrapper can later sit on normalized commands/services |
| `command_contract_pending` | Valuable, but a first-party command contract must be defined first |
| `clean_room_spec_pending` | Restrictive/mixed/boundary-sensitive; clean-room command design must come first |
| `domain_pack_donor` | Donates a bounded domain pack or skill corpus into the future skill registry |
| `pattern_only` | Pattern or reference lineage only; no live command adoption |
### Global Conclusions (from VectorShell 0R-C corpus)
1. **Most of the corpus should not become direct skills.** The dominant result is `feature_first`, not universal skillization.
2. **The strongest skill lanes are narrow and operational** — refactor helpers, memory/continuity helpers, browser/docs/design helpers, workflow/review helpers, provider/ops helpers, domain-pack skill corpora.
3. **Restrictive rows still require first-party command truth** before any skill wrapping.
4. **Skillization is lane-local, not winner-take-all.** It records which repos sit in which future lane without reopening the A/R/F hierarchy.
---
## Backfill Class D: Post-Omission Disposition Backfill
### Purpose
After implementation packets have landed, state the full post-batch omission and value-preservation interpretation explicitly.
### Three Questions Answered
1. How should each completed batch be interpreted under the omission and value-preservation doctrine?
2. Which omitted or bounded values remain as second-party integration candidates, external providers, or clean-room reservoirs?
3. Is any immediate code backfill actually warranted?
### Canonical Correction
- Non-sovereign donor value must not be flattened into "not used."
- Restrictive donor value must not be flattened into "not valuable."
- Large or product-shaped donors must still be screened for second-party and provider-backed use.
- Immediate code backfill should happen only if the new doctrine invalidates a landed sovereign owner or reveals a missing essential seam.
### Batch-by-Batch Ledger Template
For each implementation batch (A1, A2, ... A14, I1, I2, I3...):
| Field | Content |
|-------|---------|
| Sovereign owner | What first-party packet owns this slice? |
| Omitted-but-retained value | What donor value was omitted but remains relevant? |
| Governing omission screens | Which screens fired to produce the omission? |
| Retained disposition | clean-room reservoir / bounded contributor / external provider / second-party integration / doctrine/manual only |
| Immediate code backfill | `none` or specific seam |
| Future revisit trigger | Under what condition should this batch be revisited? |
### Global Code-Backfill Decision Rule
After docs-first review, code backfill is warranted only if:
1. A provider seam is missing where second-party integration is now canonically expected.
2. A clean-room reservoir feature has been explicitly selected for realization.
3. A current packet is missing a boundary marker needed to preserve sovereign ownership.
4. An existing record family is too thin to carry the newly retained bounded value.
If none of these apply, the correct output is **tracking updates only**, not urgent code correction.
---
## Prioritization Order (Universal)
When any backfill is needed, prioritize in this order:
1. Contested slices that affect current implementation routing.
2. Older packets whose authority/adjunct/reference/pattern split is ambiguous.
3. Cleanup-ambiguous packets still relied on in workflow or state reporting.
4. Family clusters with dense overlap and high donor value.
5. Lower-risk historical packets only if still active in planning or doctrine.
---
## Practical Interpretation Rule
If later evidence changes a contested slice:
- Reopen only the earlier affected slice-local packet or standing note.
- Preserve valid earlier value explicitly.
- Patch current routing from the corrected result.
If later evidence does **not** change the contested slice:
- Do **not** reopen the earlier packet just to harmonize wording.
If cleanup posture is ambiguous but no current routing depends on it:
- Record that the ambiguity exists and **defer** the backfill.

130
docs/consolidated_workflows/shared/CROSS_LANE_AUTHORITY_HIERARCHY.md Normal file
View file

@ -0,0 +1,130 @@
# Cross-Lane Authority Hierarchy and Reconciliation
**Consolidated from:**
- `HyperTwist/docs/ops/HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md`
- `VectorShell/docs/ops/VECTORSHELL_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-19.md`
**Purpose:** This document defines the canonical three-axis model for resolving capability ownership when multiple repositories overlap in the same functional domain. It is project-agnostic and applies to any multi-repo evaluation and implementation pipeline.
---
## The Three-Axis Model: A / R / F
When multiple repositories claim overlapping capabilities, resolve authority using three independent axes:
| Axis | Meaning | Values |
|------|---------|--------|
| **A** — Authority tier | Which repo is the strongest primary authority for a contested slice? | A1 (primary), A2 (secondary), A3 (tertiary), A4 (reference/pattern only) |
| **R** — Execution route | What legal/operational route must implementation take? | R1 (direct permissive), R2 (attribution required), R3 (clean-room required), R4 (pattern-only), R5 (omit) |
| **F** — Realization width | How much of the donor's surface should be realized? | F1 (narrow bounded slice), F2 (moderate width), F3 (broad subsystem), F4 (full product) |
### Critical Doctrine: License Posture Decides Route, Not Rank
A restrictive repo can still be **A1** (primary authority) even though its route is **R3** (clean-room required).
- **Do not demote** a stronger restrictive repo to A2 merely because a weaker permissive repo is easier to adopt.
- **Do not promote** a permissive repo to A1 merely because it is easier to implement.
- The cost of a harder-license winner is a harder **route** (R2 or R3), not a lower **rank** (A2 or A3).
### Realization Width is Independent
- F1 means realize only the exact contested slice.
- F2 means realize the contested slice plus closely adjacent value.
- F3/F4 are rare and require explicit justification.
---
## Authority Backfill Rules
Retroactive backfill is triggered when later same-family evidence materially changes a contested capability slice. Backfill must be:
1. **Selective** — reopen only the exact contested slice or standing note.
2. **Comparative** — preserve valid earlier value explicitly.
3. **Operational** — patch current routing from the corrected result.
4. **Non-cosmetic** — do not do fake whole-corpus rewrites or blanket relabeling.
### Backfill Classes
**A. Authority backfill** — triggered when:
- A later same-family repo materially changes a contested capability slice.
- An older packet's winner/adjunct/reference/pattern split is ambiguous.
- A restrictive repo appears to be the stronger authority and was previously softened incorrectly.
**B. Cleanup backfill** — triggered when an older packet is still operationally relied on but is ambiguous about:
- Temporary root used.
- Whether cleanup happened.
- Whether retained residue was intentional.
- Whether remaining dirt is packet-created or pre-existing.
### Prioritization Order
1. Contested slices that affect current implementation routing.
2. Older packets whose authority/adjunct/reference/pattern split is ambiguous.
3. Cleanup-ambiguous packets still relied on in workflow or state reporting.
4. Family clusters with dense overlap and high donor value.
5. Lower-risk historical packets only if still active in planning or doctrine.
---
## Family Reconciliation Pattern
For each contested functional family, produce a reconciliation table:
| Contested Slice | A1 Owner | Route | Width | Preserved Secondary Value |
|-----------------|----------|-------|-------|---------------------------|
| (slice description) | (repo name) | (R1–R5) | (F1–F4) | (A2/A3 repos and what they still own) |
Rules for the table:
- State the exact contested slice, not the whole repo.
- Name the A1 owner explicitly.
- Preserve adjacent value from neighbors; do not flatten non-winners into exclusion.
- If a repo is A1 for one slice, it can be A2 for another slice in the same family.
---
## Disposition and Omission Doctrine
"Omit" is a non-binary disposition. A repo may be omitted as a sovereign first-party owner while still remaining valid as:
- A **second-party embedded integration** target.
- An **external provider** (scanner, oracle, benchmark).
- A **clean-room feature reservoir**.
### Omission Screens
Before omitting a repo from first-party ownership, check:
1. Is it a duplicate sovereign owner?
2. Is its operational weight larger than its first-party value?
3. Does it create a "second product inside the product"?
4. Does it assume broad hosted-service infrastructure?
If any screen fires, the repo is omitted from first-party ownership but may still be retained in a secondary disposition.
---
## Required Outputs for Every Reconciliation Pass
Every authority backfill or family reconciliation pass must output:
- Exact earlier packet(s) reopened.
- Exact standing note(s) reopened when applicable.
- Exact reason the backfill was triggered.
- Whether repo-local extraction changed, cross-lane authority changed, cleanup interpretation changed, or only wording changed.
- What remained valid and was preserved.
- What changed and why.
- Whether more selective backfill remains.
If no backfill was actually triggered, state that explicitly.
---
## Relationship to Other Doctrines
This hierarchy document governs behavior across:
- Retroactive backfill doctrine
- Cleanup and rebuildable artifact hygiene doctrine
- Canonical compact closeout format
- Worktree placement and validation artifact policy
- Model A / Model B coordinator doctrine
- Clean-room operator sequences and handoffs
- Implementation disposition and omission doctrine
- Second-party integration candidate ledgers
- Clean-room feature reservoir ledgers

128
docs/consolidated_workflows/shared/LICENSE_TRACKING_WORKFLOW.md Normal file
View file

@ -0,0 +1,128 @@
# License Tracking Workflow
**Consolidated from:**
- `HyperTwist/docs/REPO_LICENSE_TRACKING.md` (4,617 lines)
- `HyperTwist/docs/ops/HYPERTWIST_REPO_LICENSE_EVIDENCE_AUDIT_*` (2026-05-26, 05-27, 05-28)
- `VectorShell/docs/REPO_LICENSE_TRACKING.md` (28,014 lines)
- `VectorShell/docs/ops/VECTORSHELL_REPO_LICENSE_EVIDENCE_AUDIT_2026-05-26.md`
- `VectorShell/docs/generated/license_audit/VECTORSHELL_REPO_LICENSE_EVIDENCE_AUDIT_2026-05-26.csv`
- `VectorShell/docs/v6_5_deep_manual_pack/*/LICENSETRACKING.md` (policy-only)
**Purpose:** Define the canonical pattern for tracking, auditing, and reconciling open-source license posture across a large evaluated repo corpus.
---
## Two-Tier Structure
### Tier 1: Concrete Repo-Row Legal Ledger (Root Level)
**Location:** `docs/REPO_LICENSE_TRACKING.md` at project root.
This is the operational ledger. Every evaluated repo gets a row containing:
| Field | Description |
|-------|-------------|
| `repo` | Full `owner/name` identifier |
| `license` | Detected license SPDX identifier or raw text |
| `license_source` | Where the license was found (root `LICENSE`, `package.json`, `Cargo.toml`, `pyproject.toml`, header comments, etc.) |
| `custody_confidence` | `high` / `medium` / `low` / `unresolved` |
| `mixed_custody` | Yes/No — does the repo contain files under different licenses? |
| `boundary_sensitive` | Yes/No — does the repo require clean-room or restrictive handling? |
| `route` | R1–R5 assignment based on license posture |
| `evaluation_packet` | Link to the evaluation packet that produced this row |
| `notes` | Any anomalies, missing grants, metadata-only declarations, etc. |
### Tier 2: Policy Categories (Deep Manual Pack)
**Location:** `docs/v6_5_deep_manual_pack/*/LICENSETRACKING.md`.
These documents contain **policy-only** categories:
- How to classify permissive vs. copyleft vs. proprietary.
- What custody signals are considered authoritative.
- How to handle metadata-only license declarations.
- When to escalate to legal review.
**Rule:** Policy docs do not contain repo rows. Repo rows live only in the root tracker.
---
## Evidence Audit Bundle Pattern
### Generated Audit Bundles
After every major evaluation wave, produce:
1. **Markdown evidence audit** — narrative summary of license findings, anomalies, and corrections.
2. **CSV audit** — machine-readable row-by-row license evidence export.
**Location pattern:**
- `docs/ops/*REPO_LICENSE_EVIDENCE_AUDIT_YYYY-MM-DD.md`
- `docs/generated/license_audit/*REPO_LICENSE_EVIDENCE_AUDIT_YYYY-MM-DD.csv`
### Audit Contents
The markdown audit must cover:
- Total repos evaluated.
- License distribution breakdown (MIT, Apache-2.0, GPL-3.0, AGPL, proprietary, unresolved, etc.).
- Anomalies found (metadata-only declarations, missing root license, mixed custody, sublicensing concerns).
- Corrections made to prior tracker rows.
- Boundary-sensitive rows flagged for clean-room handling.
- Rows where custody confidence was upgraded or downgraded.
The CSV must contain:
- `repo`, `license_detected`, `license_source`, `confidence`, `mixed`, `boundary_sensitive`, `route`, `packet_reference`, `anomaly_flag`, `notes`
---
## License Detection Rules
### Authoritative Sources (in priority order)
1. **Root `LICENSE` or `LICENSE.txt` file** — highest authority.
2. **Root `COPYING` file** — equivalent to root license.
3. **`package.json` / `Cargo.toml` / `pyproject.toml` / `setup.py` `license` field** — valid if no root file exists.
4. **Per-file header comments** — used only for mixed-custody detection.
5. **`README.md` explicit declaration** — acceptable only if no structured metadata exists.
### Confidence Levels
| Level | Criteria |
|-------|----------|
| `high` | Standalone root license file with clear SPDX identifier |
| `medium` | Structured metadata field with clear identifier, but no standalone root file |
| `low` | README declaration only, or ambiguous identifier |
| `unresolved` | No license found, or conflicting signals that cannot be reconciled |
### Boundary-Sensitive Flags
A repo is **boundary-sensitive** (requires R2–R4) if any of the following apply:
- GPL-3.0, AGPL-3.0, or SSPL detected.
- Proprietary / "all rights reserved" detected.
- Mixed custody where some files are permissive and others are not.
- Metadata-only declaration with no standalone root grant.
- Hosted-service dependency (relies on external API keys, enterprise gating, or cloud backend).
- Trademark-encumbered name or branding.
---
## Reconciliation with A/R/F Hierarchy
License posture feeds directly into the **Route** axis:
| License Posture | Typical Route | Notes |
|-----------------|---------------|-------|
| MIT, Apache-2.0, BSD-2/3-Clause, ISC | R1 | Direct adoption with attribution |
| MPL-2.0, EPL-2.0 | R2 | File-level copyleft; attribution and boundary required |
| GPL-3.0, AGPL-3.0, SSPL | R3 | Clean-room required; do not adopt source directly |
| Proprietary / no grant / unresolved | R4–R5 | Pattern-only or omit |
**Critical rule:** A restrictive repo can still be **A1** (primary authority) for its contested slice. The route being R3 does not demote its authority rank. The clean-room requirement is a cost of adoption, not a judgment on capability strength.
---
## Maintenance Rules
1. **Update the root tracker** whenever a new repo is evaluated or an existing row is corrected.
2. **Append new audit bundles** rather than overwriting old ones. Old audits are evidence of decision provenance.
3. **Do not delete rows** when a repo is omitted. Change its disposition to `omitted` with a reason.
4. **Link every row** to its evaluation packet. The packet is the authoritative source of the license call.
5. **Reconcile** the root tracker against the CSV audit after every wave. Discrepancies must be resolved and documented.

265
docs/consolidated_workflows/shared/MODEL_A_B_CLEAN_ROOM_PROMPTS.md Normal file
View file

@ -0,0 +1,265 @@
# Model A / Model B Clean-Room Implementation Prompts
> Canonical full-sequence location:
> `docs/consolidated_workflows/scriptorium/MODEL_A_B_FULL_SEQUENCE_CANON.md`
>
> This shared document is now an abridged working guide. It preserves the main generic prompts and helper wrappers, but it is no longer the authoritative "full in one place" copy.
**Consolidated from:**
- `HyperTwist/Model A & B Clean-Room Implementation Prompts.txt` (697 lines)
- `VectorShell/Model A & B Clean-Room Implementation Prompts.txt` (697 lines, identical)
- `ScriptoriumAI/docs/feature extension/hypertwist_parse_csv_and_feature_implementation_handoff/HyperTwist-Portfolio-Handoff-2026-04-25/14-clean-room-model-a-model-b-prompts.md` (157 lines, repo-specific variant)
- `ScriptoriumAI/docs/feature extension/hypertwist_parse_csv_and_feature_implementation_handoff/Repo-Evaluation-Workflow-Pack-2026-04-25/04-generic-model-a-model-b-clean-room-prompts.md` (78 lines, generic variant)
**Purpose:** Provide an abridged, reusable working guide for clean-room reimplementation workflows. Use the full canonical sequence when exact preservation of the generic Model A / Model B prompt set matters.
---
## Separation Rule
- **Model A** may inspect the protected or restrictive source.
- **Model B** must **not** inspect the protected or restrictive source.
- **Model B** may only receive:
- Scrubbed functional specification
- Black-box acceptance tests
- Lawful public compatibility requirements
- The **same model/session should not perform both roles**.
---
## Full Model A Prompt
```text
You are acting as a clean-room-oriented analysis model (Model A).
Your task is NOT to help reproduce, paraphrase, translate, restyle, or preserve the original source code. Your task is to inspect the provided software artifact and produce a sanitized, high-level, user-visible functional specification that can later be handed to a separate implementation model or developer who must NOT see the original code.
The goal is to extract only the software's ideas, behavior, functionality, interface expectations, user-observable logic, input/output requirements, constraints, and acceptance-level requirements, while excluding all source-derived expressive material.
This is a strict transformation task. You must behave as a specification distillation layer, not as a reverse-engineering copier.
### Core Objective
Produce a detailed, lucid, comprehensive, long-form functional specification that answers:
- What does the software do?
- What can the user see and do?
- What inputs does it accept?
- What outputs, state changes, and visible behaviors occur?
- What modes, views, tools, workflows, and user-facing operations exist?
- What external behaviors or compatibility requirements appear necessary?
- What constraints, invariants, and edge-case behaviors are implied?
- What should an independent implementer build, at the level of product behavior and requirements, without inheriting the original code's structure or wording?
### Absolute Prohibitions
You must NOT include any of the following unless explicitly unavoidable because they are part of an external public standard, protocol, or user-visible contractual interface:
1. No code snippets
2. No pseudocode that mirrors the original implementation
3. No function names, method names, class names, variable names, internal identifiers, or file names from the source
4. No module structure, architecture skeleton, directory layout, or internal decomposition copied from the source
5. No direct quotes from comments, docs, inline strings, or error text unless the exact wording is externally required
6. No source-like sequencing that effectively reconstructs the implementation
7. No copied tests, assertions, fixtures, snapshots, regexes, internal constants, lookup tables, or data schemas unless they are clearly external/public requirements
8. No distinctive algorithmic implementation detail when a higher-level behavioral description is sufficient
9. No line-by-line paraphrase of the code
10. No description that would allow someone to recreate the original source structure rather than independently designing a fresh implementation
### What You May Preserve
- User-visible features
- User workflows
- Interface behavior
- Functional requirements
- Input and output behavior
- State transitions at a product or behavior level
- Externally visible modes and views
- Validation rules visible from usage or required by external compatibility
- Data entities at a conceptual level
- External interoperability requirements
- Performance expectations only if clearly behaviorally relevant
- Edge cases only at the behavior level
- Acceptance criteria
- Compatibility targets
- High-level safety or correctness invariants
- Domain logic expressed generically and behaviorally
### Required Abstraction Rule
Whenever you encounter implementation detail, transform it upward using this priority:
1. User-visible behavior
2. Functional requirement
3. Conceptual rule
4. Acceptance criterion
5. Open design constraint for independent implementer
### Output Structure
1. **Executive Functional Overview** — what the software is, what problem it solves, major capabilities
2. **Feature Inventory** — every substantial user-visible feature with inputs, outputs, constraints
3. **User Workflows and Interaction Narratives** — major flows in paragraph form
4. **Interface and View Behavior** — visible interface structure at user-facing level
5. **Core Domain Logic** — conceptual logic in generic terms
6. **Inputs, Outputs, and State** — conceptual description of state and transitions
7. **Validation, Constraints, and Edge Cases** — behavioral handling of invalid/unusual states
8. **External Interfaces and Compatibility Expectations** — interoperability requirements
9. **Non-Functional Requirements** — responsiveness, stability, precision (only if evidenced)
10. **Acceptance Criteria for Independent Reimplementation** — user-observable tests
11. **Open Design Space** — what remains free for the implementer to decide
12. **Sanitization Audit** — explicit confirmation that source identifiers, copied wording, code-like phrasing, module structure, and reconstructive detail have been removed
### Evidence Labels
Use these labels where appropriate:
- Directly evidenced
- Strongly implied
- Uncertain / requires independent product decision
- Externally required if compatibility is desired
### Final Instruction
Do not implement anything. Do not suggest code. Do not write pseudocode. Do not preserve source expression. Produce a full, carefully sanitized, behavior-level functional specification suitable for handoff to Model B.
```
---
## Full Model B Prompt
```text
You are acting as an independent clean-room implementation model (Model B).
You have NOT seen the original source code and must NOT request, infer, reconstruct, mimic, or recover it. Your only permitted input is a sanitized functional specification prepared by Model A. Your task is to design and implement a fresh solution based solely on that behavioral specification.
Your goal is to create an independently designed implementation that reproduces the required functionality, user-visible behavior, compatibility targets, and acceptance criteria, while avoiding any inheritance of the original program's protected expression, internal structure, naming, sequencing, or architecture.
You are not a restoration model. You are not a paraphrase model. You are not a source reconstruction model. You are an independent implementer.
### Core Objective
Build the requested software or component from the sanitized specification alone.
You must preserve only:
- User-visible behavior
- Functional requirements
- External inputs and outputs
- Compatibility requirements
- Acceptance criteria
- Behavioral constraints
- Correctness requirements
- Evident domain rules
You must independently choose:
- Architecture, modules, file structure, naming
- Algorithms, abstractions, component boundaries
- State management strategy, rendering strategy, storage layout
- Event flow, error-handling internals, testing strategy
### Absolute Prohibitions
1. Do not ask to see the original code.
2. Do not ask for excerpts, snippets, function names, file names, class names, or internal identifiers.
3. Do not attempt to reconstruct the original architecture.
4. Do not mirror naming conventions from the original implementation.
5. Do not request line-by-line behavior if doing so would effectively recreate source structure.
6. Do not produce code that intentionally imitates a presumed original layout.
7. Do not state or imply that the best way is to inspect the old code.
8. Do not try to infer hidden implementation details unless required by the functional specification.
9. Do not treat unspecified internals as fixed; treat them as open design space.
10. Do not produce "translation-style" code that feels like a disguised rewrite.
### Governing Principle
Treat the sanitized specification as a product requirements document, not as a compressed representation of prior source code. Your job is to create a fresh implementation that satisfies the required behavior while remaining materially independent in design.
### Required Design Posture
- Behavior fidelity, not expression fidelity
- Product equivalence, not code resemblance
- Functional satisfaction, not structural recovery
- Independent engineering judgment, not reverse reconstruction
When multiple valid designs exist, prefer the design that is:
- Clear, maintainable, conventional, testable, internally coherent, independently justifiable
### Handling Specification Gaps
If the spec leaves details open:
1. Preserve all explicit requirements exactly at the behavioral level.
2. Identify what is unspecified.
3. Choose a reasonable independent design.
4. Mark those choices clearly as implementation decisions.
5. Avoid overfitting to what the original software might have done.
Use these labels:
- Specified requirement
- Independent implementation choice
- Assumption made for completeness
- Open configuration point
- Needs confirmation only if materially important
### Independence Checks (apply before finalizing)
- **Reconstruction Drift:** Does any output seem aimed at recovering an unseen original rather than solving the problem independently?
- **Naming Independence:** Are identifiers fresh and self-justifying?
- **Structural Independence:** Could this plausibly have been designed from the spec alone?
- **Behavioral Sufficiency:** Does it satisfy requirements without relying on presumed hidden details?
- **Open-Space Respect:** Are unspecified internals treated as open design space?
### Final Instruction
You must work ONLY from the sanitized functional specification. You must not request or recreate the original source. You must optimize for functional fidelity through independent design.
Where the specification is precise, follow it. Where it is open, choose well. Where uncertainty exists, make independence-preserving engineering decisions.
```
---
## Speed Variants
### Short Model A Wrapper
```text
Inspect the source code only to determine what the software does from a user-visible and product-functional perspective. Then convert that into a sanitized behavioral specification. Do not preserve the code's expression, wording, names, architecture, sequence, or structure.
```
### Short Model B Wrapper
```text
Implement this as a fresh design from the sanitized functional specification alone. Do not request or reconstruct original source details. Preserve behavior and acceptance criteria, but independently choose names, architecture, modules, algorithms, and internal structure.
```
---
## Recommended Handoff Bundle
For a defensible clean-room workflow, hand Model B only:
1. The scrubbed specification (Model A output)
2. Black-box acceptance tests
3. Product constraints from the target project
4. Stack and architecture constraints for the target subsystem
Do **not** hand Model B:
1. The protected source
2. Source-derived file names
3. Source-derived function names
4. Source excerpts
5. Distinctive implementation notes unnecessary for black-box behavior
---
## Per-Repo Model A Dossier Pattern
For complex restrictive repos, create a repo-specific exposed-side dossier:
1. One repo-specific Model A dossier (scrubbed spec)
2. One later isolated Model B implementation track
3. No mixed-role session doing both jobs
The dossier should include:
- Executive summary
- Protected-source exposure note
- Product behaviors that must be reproduced
- Behaviors that are optional or not worth carrying forward
- State model, interaction model, domain-specific models
- Step-detection or algorithm acceptance criteria
- Rendering and interaction expectations at black-box level
- Test cases
- No-copy guardrails for Model B

201
docs/consolidated_workflows/shared/REPO_EVALUATION_MODUS_OPERANDI.md Normal file
View file

@ -0,0 +1,201 @@
# Project-Agnostic Repository Evaluation Modus Operandi
**Consolidated from:**
- `VectorShell/docs/06-project-agnostic-repo-evaluation-modus-operandi.md`
- `HyperTwist/docs/06-project-agnostic-repo-evaluation-modus-operandi.md`
- `ScriptoriumAI/docs/feature extension/hypertwist_parse_csv_and_feature_implementation_handoff/Repo-Evaluation-Workflow-Pack-2026-04-25/02-project-agnostic-repo-evaluation-modus-operandi.md`
**Purpose:** Define the canonical workflow for evaluating third-party repositories at scale, determining their authority rank, execution route, and realization width, and producing actionable evaluation packets.
---
## Phase Overview
The evaluation pipeline operates in sequential phases. Each phase produces a specific artifact. Skipping phases produces incomplete or misleading results.
| Phase | Name | Output |
|-------|------|--------|
| P0 | Inventory | Raw list of candidate repos with source URLs |
| P1 | Shallow Screening | Metadata-level pass: license, activity, size, language, README quality |
| P2 | Deep Source Read | File-by-file inspection of source-bearing surfaces |
| P3 | Capability Extraction | Identified seams, owned slices, user-visible behaviors |
| P4 | Authority Assignment | A/R/F classification, family reconciliation, hierarchy tables |
| P5 | Disposition Decision | Retain/omit/second-party/provider/pattern-only call |
| P6 | Packet Closeout | Canonical compact closeout with evidence summary |
---
## P0: Inventory
**Goal:** Build a complete, deduplicated list of candidate repos without premature filtering.
**Rules:**
- Capture every repo mentioned in any context (prior lists, user requests, dependency chains, related work citations).
- Deduplicate by `owner/name`.
- Note the provenance of each entry (where did this repo come from?).
- Do not filter at this stage. A repo that looks irrelevant may become relevant in P2.
**Artifact:** `repo_inventory_YYYY-MM-DD.csv` or equivalent.
---
## P1: Shallow Screening
**Goal:** Eliminate obvious non-candidates and flag boundary concerns before investing deep-read time.
**Checks (per repo):**
| Check | Method | Reject If |
|-------|--------|-----------|
| License | Root `LICENSE`, `package.json`, README | No grant found, or grant is proprietary/no-use |
| Activity | Last commit date, issue/PR velocity | Abandoned (>2 years inactive, no releases) |
| Size | LOC, file count | Too small to carry meaningful seam (<100 LOC for non-trivial domains) |
| Language | Primary language | Not applicable to target stack (with exceptions for reference value) |
| README quality | Completeness, examples, API docs | No README, or README is marketing-only with no technical content |
| Hostile signals | Malware, coin miners, credential leaks | Any security red flag |
**Output:** Screened list with `pass`, `flag`, or `reject` for each check.
---
## P2: Deep Source Read
**Goal:** Inspect the actual source to find real capability seams, not marketing claims.
**Method:**
1. Identify source-bearing directories (exclude `node_modules`, `vendor`, `.git`, build artifacts, test fixtures unless they demonstrate behavior).
2. Read entry points, core modules, and API surfaces.
3. Look for:
- Actual implemented features (not TODO comments)
- User-facing commands, interfaces, or workflows
- Data models and state management
- External integrations and protocol handling
- Error handling and edge cases
- Performance-critical paths
4. Cross-check README claims against source reality.
**Sampling strategy for very large repos:**
- Read all files in the top-level source directory.
- Read a representative sample from each major subdirectory.
- Read all files referenced in the README's "getting started" or API docs.
- Read test files to understand intended behavior.
- Flag any area that was sampled rather than fully read.
**Artifact:** `deep_read_notes.md` per repo, with file paths read and findings.
---
## P3: Capability Extraction
**Goal:** Translate source findings into behavior-level capability descriptions.
**For each identified seam, document:**
- **What it does** — user-visible behavior, not internal mechanism.
- **Who would use it** — operator, end user, developer, agent.
- **What inputs it accepts** — files, commands, API calls, events.
- **What outputs it produces** — files, displays, state changes, notifications.
- **What constraints apply** — platform, dependency, permission, rate limits.
- **Evidence quality** — directly evidenced, strongly implied, inferred from tests/docs.
**Rules:**
- Use generic language. Do not copy function names or internal identifiers.
- Separate "what the code does" from "what the README claims it does."
- Note any discrepancy between documentation and implementation.
---
## P4: Authority Assignment (A / R / F)
**Goal:** Place the repo in the cross-lane hierarchy relative to already-evaluated repos in the same functional family.
**Steps:**
1. Identify the functional family(ies) this repo belongs to.
2. Compare its extracted capabilities against the existing family reconciliation table.
3. Determine:
- **A rank:** Is it A1, A2, A3, or A4 for each contested slice?
- **R route:** What legal/operational route applies?
- **F width:** How much of the repo's surface should be realized?
4. Update the family reconciliation table with the new repo.
5. If the new repo displaces an existing A1, trigger selective authority backfill for the displaced repo's packet.
**Family Reconciliation Table Template:**
| Contested Slice | A1 Owner | Route | Width | Preserved Secondary Value |
|-----------------|----------|-------|-------|---------------------------|
| (description) | (repo) | (R1–R5) | (F1–F4) | (A2/A3 repos and their retained slices) |
---
## P5: Disposition Decision
**Goal:** Make the final retain/omit call and assign a secondary disposition if omitted.
**Decision tree:**
```
Is the repo A1 for any contested slice?
├── YES → Retain for first-party implementation (route = R1–R3)
└── NO → Is the repo A2/A3 with real secondary value?
├── YES → Retain as second-party integration candidate or external provider
└── NO → Is the repo pattern/reference only (A4)?
├── YES → Retain as pattern/reference; do not integrate directly
└── NO → Omit entirely
```
**Secondary dispositions for omitted repos:**
- `second_party_embedded` — can be integrated as a dependency or service
- `external_provider` — used as oracle, benchmark, or scanner
- `clean_room_reservoir` — behavior patterns extracted for clean-room reimplementation
- `bounded_contributor` — narrow value preserved for later adjunct use
- `doctrine_manual_only` — conceptual value only; no code integration
---
## P6: Packet Closeout
**Goal:** Produce a canonical, compact closeout that preserves decision provenance.
**Required closeout fields:**
| Field | Content |
|-------|---------|
| Packet ID | `PROJECT_PHASE_REPO_EVALUATION_YYYY-MM-DD` |
| Repo | `owner/name` |
| Evaluation date | `YYYY-MM-DD` |
| Evaluator | Instance/session identifier |
| Shallow screen result | Pass/fail per check |
| Deep read scope | Files/directories inspected |
| Extracted capabilities | Behavior-level capability list |
| A / R / F assignment | Per contested slice |
| Family reconciliation | Updated family table |
| Disposition | Retain / omit + secondary disposition |
| Skillization posture | `feature_first` / `live_wrapper` / `command_pending` / `clean_room` / `domain_pack` / `pattern_only` |
| Evidence quality | High / medium / low per major claim |
| Anomalies | Any discrepancies, missing grants, mixed custody |
| Dependencies | External dependencies and their license posture |
| Notes | Any other material information |
---
## Quality Gates
Before a packet is considered closed, verify:
1. **Source-first:** Was the deep read actually performed, or was the packet written from README/marketing material?
2. **Behavior-level:** Are capabilities described in user-visible terms, not internal architecture?
3. **License-grounded:** Is the route assignment justified by the actual detected license?
4. **Comparative:** Was the repo compared against existing family members, or evaluated in isolation?
5. **Consistent:** Does the A/R/F assignment agree with the disposition and skillization posture?
6. **Traceable:** Can every major claim be traced to a specific file or behavior observed in the source?
---
## Scaling Rules
For large corpuses (100+ repos):
1. **Batch in fives:** Process repos in groups of five. Close each group before starting the next.
2. **Bookmark backfill:** After every five-repo closure, append a summary to the canonical backfill document.
3. **Cross-lane sweep:** After every 20–30 repos, perform a family reconciliation sweep to catch emerging overlaps.
4. **Confidence decay:** Revisit low-confidence rows after the initial wave. Stale confidence markers are common.
5. **No fake resets:** A later clarification does not justify rewriting the entire corpus. Use selective backfill.

52
docs/ops/FAMILIAROS_GITNEXUS_AND_SENTRUX_REFACTORING_BASELINE_2026-06-18.md Normal file
View file

@ -0,0 +1,52 @@
# FamiliarOS GitNexus And Sentrux Refactoring Baseline
**Date:** 2026-06-18
## Purpose
Record the safe FamiliarOS interpretation of the Scriptorium-root GitNexus and
Sentrux surfaces requested for codebase refactoring and hardening work.
## Verified Surfaces
Inside `/home/dev/src/ScriptoriumAI`, the relevant root-level analyzer surfaces are:
- `.gitnexus/`
- `.sentrux/rules.toml`
- `sentrux.exe`
These are distinct from the donor/runtime-oriented `mirrors/GitNexus` repo.
## GitNexus Interpretation Rule
The Scriptorium root `.gitnexus` directory is a **repo-local generated index**.
It currently points at `C:\ScriptoriumAI` in `meta.json`, so it must **not** be
copied into FamiliarOS as if it were a valid FamiliarOS analysis result.
Safe FamiliarOS rule:
1. keep a repo-local `.gitnexus/` scaffold in FamiliarOS
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
## Sentrux Interpretation Rule
The useful transferable part of the root Scriptorium Sentrux surface is the
repo-local rule posture, not the donor repo assumptions.
For FamiliarOS, the correct move is to carry a FamiliarOS-specific `.sentrux`
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
## 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.

24
docs/ops/FAMILIAROS_VPS_AND_REMOTE_SYNC_RUNBOOK_2026-06-17.md
View file

@ -44,7 +44,7 @@ From the current FamiliarOS ops docs:
## Nightly Reverse-Sync Audit Result
The 2026-06-17 audit checked:
The 2026-06-18 verification checked:
- local `crontab`
- systemd timers
@ -57,6 +57,8 @@ Result:
- the discovered active reverse-sync automation pattern currently lives under:
- `/home/dev/src/ScriptoriumAI/ops/ssh/run-vps-remote-dev-reverse-sync.ps1`
- `/home/dev/src/ScriptoriumAI/ops/ssh/install-vps-remote-dev-reverse-sync-task.ps1`
- the live workspace map in `run-vps-remote-dev-reverse-sync.ps1` now includes
`FamiliarOS`
## Reverse-Sync Wiring Status
@ -66,21 +68,19 @@ Current discovered workspace map in the live Windows-script lane includes:
- `VectorShell`
- `HyperTwist`
- `ScriptoriumAI`
- `FamiliarOS`
- `VerticalTension`
- `NyxOS`
- `Workspaces`
Current discovered workspace map does **not** include:
- `FamiliarOS`
Present-tense conclusion:
- FamiliarOS is not currently wired into the discovered live nightly reverse-sync task.
- FamiliarOS is wired into the discovered shared nightly reverse-sync workspace
map through the Scriptorium-owned Windows scheduled-task lane.
## Required FamiliarOS Reverse-Sync Entry
## Current FamiliarOS Reverse-Sync Entry
To add FamiliarOS to the existing Windows reverse-sync map, the missing row is:
Current live Windows-script mapping:
```text
Name = FamiliarOS
@ -89,13 +89,13 @@ RelativePath = FamiliarOS
RemotePath = /home/dev/src/FamiliarOS
```
## Recommended Next-Step Options
## Automation Ownership Options
### Option A: extend the current shared scheduled-task lane
Patch the current `ScriptoriumAI` reverse-sync script to add the `FamiliarOS`
workspace entry, then let the existing scheduled task continue owning all
workspace sync.
Keep the current `ScriptoriumAI` reverse-sync script as the shared owner of the
workspace map and continue using the live FamiliarOS entry already present
there.
### Option B: create a FamiliarOS-owned scheduled-task lane

28
docs/plan/FAMILIAROS_PRODUCT_ROADMAP_2026-06-17.md
View file

@ -53,6 +53,11 @@ Planned work:
- remove or quarantine leftover cross-product language that still reads like a
different app family
- document deployment, auth, and route ownership from the monorepo root
- retain the Scriptorium-derived workflow pack locally in FamiliarOS so future
repo-custody, clean-room, and closeout work does not depend on donor repo
memory
- establish FamiliarOS-local `.gitnexus/` and `.sentrux/` scaffolds rather
than treating donor analysis state as current product truth
### 2. Website foundation and conversion path
@ -146,7 +151,21 @@ Recommended later animation ideas:
- contextual mood or energy transitions that feel readable, not noisy
- onboarding reveal moments when the Familiar is first named or first speaks
### 7. Full codebase hardening program
### 7. First-party familiar asset and IP-safe catalog program
Goal:
- move FamiliarOS toward first-party familiar ownership instead of relying on
ambiguous legacy pack rights
Planned work:
- treat inherited OpenPets familiar packs as `replace-or-verify`, not blanket
redistributable first-party assets
- create or commission a first-party FamiliarOS familiar starter set with
complete animation coverage
- keep temporary/dev fixture familiars neutral and clearly first-party-safe
- document pack-by-pack verification rules when exceptions are justified
### 8. Full codebase hardening program
Goal:
- parse the full product codebase end-to-end and reduce risk before broader
@ -166,6 +185,8 @@ Hardening themes:
- accessibility and reduced-motion compliance
- busy-state consistency
- bridge/API naming cleanup where safe
- FamiliarOS-local analyzer regeneration with the Scriptorium-root GitNexus
workflow and FamiliarOS-specific Sentrux rules
- CSP and sandbox posture verification
- dependency/update pressure review
- test-gap identification and patching
@ -178,8 +199,9 @@ Recommended immediate sequence:
2. public-site copy and loader consistency pass
3. control-center loading-state polish and spinner unification
4. auth/account readiness packet
5. website background video design packet
6. broader codebase hardening audit packets
5. first-party familiar asset and rights packet
6. website background video design packet
7. broader codebase hardening audit packets
## Explicitly not immediate unless requested

4
docs/plan/FAMILIAROS_REBRAND_PROGRESS.md
View file

@ -84,8 +84,8 @@ This pass moved the repo from "merged but still visually confusing" to
- confirmed the real live website source remains `FamiliarOS/website`
- audited every public website route against a built preview and cleared the
remaining auth-preview console noise on `/login` and `/register`
- documented the current reverse-sync truth: FamiliarOS is not yet present in
the discovered shared nightly Windows reverse-sync workspace map
- verified the shared nightly Windows reverse-sync workspace map now includes
`FamiliarOS` via `ScriptoriumAI/ops/ssh/run-vps-remote-dev-reverse-sync.ps1`
---

78
docs/user/memory-triggers.md Normal file
View file

@ -0,0 +1,78 @@
# FamiliarOS Memory System
FamiliarOS has **two kinds of memory** that work together:
1. **Triggered Memory** — explicit facts you teach the Familiar using trigger phrases
2. **Chat History Memory** — the full transcript of every conversation, searchable across sessions
---
## 1. Triggered Memory (Explicit)
These are stored when you use specific phrases in your prompts. The Familiar extracts the fact and saves it permanently.
### Trigger Phrases
| Phrase | Example | What gets stored |
|--------|---------|------------------|
| `Remember that ...` | "Remember that I have two dogs" | Note: "User has two dogs." |
| `My name is ...` | "My name is Alice" | Identity: "User's name is Alice." |
| `Call me ...` | "Call me Bob" | Identity: "User's name is Bob." |
| `My favorite ... is ...` | "My favorite color is blue" | Preference: "User's favorite color is blue." |
| `I prefer ...` | "I prefer dark mode" | Preference: "User prefers dark mode." |
### How triggered memory works
- Each trigger phrase is matched with a regex on every message you send
- Extracted facts are deduplicated by normalized text
- Stored in `familiaros-memory.json` in your user data directory
- Injected into the system prompt when relevant to your current query
- You can view, edit, and delete memories in **Settings → Memory**
### Tips for best results
- Use simple, declarative sentences
- One fact per message works best
- The Familiar does **not** automatically extract facts from free-form chat — you must use trigger phrases
---
## 2. Chat History Memory (Automatic)
Every conversation is saved automatically. You can browse past conversations and the Familiar can reference them.
### What is saved
- Every message you send
- Every reply the AI gives
- System messages and error states
- Timestamps for each entry
### How chat history memory works
- Conversations are stored in `familiaros-chat-history.json`
- Conversation metadata (title, date, message count) is stored in `familiaros-chat-conversations.json`
- When building context for the AI, both triggered memories **and** relevant past conversation excerpts are searched
- This gives the Familiar "memory" across multiple chat sessions without requiring explicit triggers
### Browsing history
- Click the **History** button in the prompt window to see a list of all conversations
- Click any conversation to open it
- The **Editor** button shows the current conversation's message list
---
## File Locations
| File | Platform | Path |
|------|----------|------|
| Triggered memories | Windows | `%APPDATA%/FamiliarOS/familiaros-memory.json` |
| Triggered memories | Linux | `~/.config/FamiliarOS/familiaros-memory.json` |
| Chat history | Windows | `%APPDATA%/FamiliarOS/familiaros-chat-history.json` |
| Chat history | Linux | `~/.config/FamiliarOS/familiaros-chat-history.json` |
| Conversations | Windows | `%APPDATA%/FamiliarOS/familiaros-chat-conversations.json` |
| Conversations | Linux | `~/.config/FamiliarOS/familiaros-chat-conversations.json` |
Legacy `openpets-*.json` files are still migrated on load for compatibility,
but FamiliarOS writes the new `familiaros-*.json` filenames going forward.

40
packages/claude/src/check-claude-code.ts
View file

@ -8,45 +8,45 @@ assert.deepEqual(defaultPreview.remove.args, ["mcp", "remove", "--scope", "user"
assert.deepEqual(defaultPreview.mcpJson.mcpServers.familiaros.args, ["-y", "@familiaros/mcp"]);
assert.equal(formatCommandForDisplay(defaultPreview.add), "claude mcp add --scope user familiaros -- npx -y @familiaros/mcp");
const petPreview = buildClaudeMcpPreview("snoopy");
assert.deepEqual(petPreview.add.args, ["mcp", "add", "--scope", "user", "familiaros", "--", "npx", "-y", "@familiaros/mcp", "--familiar", "snoopy"]);
assert.deepEqual(petPreview.mcpJson.mcpServers.familiaros.args, ["-y", "@familiaros/mcp", "--familiar", "snoopy"]);
const petPreview = buildClaudeMcpPreview("lantern");
assert.deepEqual(petPreview.add.args, ["mcp", "add", "--scope", "user", "familiaros", "--", "npx", "-y", "@familiaros/mcp", "--familiar", "lantern"]);
assert.deepEqual(petPreview.mcpJson.mcpServers.familiaros.args, ["-y", "@familiaros/mcp", "--familiar", "lantern"]);
assert.deepEqual(buildClaudeMcpGetCommand().args, ["mcp", "get", "familiaros"]);
const localPreview = buildClaudeMcpPreview("snoopy", "local");
assert.deepEqual(localPreview.add.args, ["mcp", "add", "--scope", "user", "familiaros", "--", "node", getLocalMcpEntryPath(), "--familiar", "snoopy"]);
const localPreview = buildClaudeMcpPreview("lantern", "local");
assert.deepEqual(localPreview.add.args, ["mcp", "add", "--scope", "user", "familiaros", "--", "node", getLocalMcpEntryPath(), "--familiar", "lantern"]);
assert.equal(localPreview.mcpJson.mcpServers.familiaros.command, "node");
assert.deepEqual(localPreview.mcpJson.mcpServers.familiaros.args, [getLocalMcpEntryPath(), "--familiar", "snoopy"]);
assert.deepEqual(localPreview.mcpJson.mcpServers.familiaros.args, [getLocalMcpEntryPath(), "--familiar", "lantern"]);
assert.throws(() => validateFamiliarOSPetArg("Bad Familiar"));
assert.throws(() => validateFamiliarOSPetArg("bad/familiar"));
assert.equal(validateFamiliarOSPetArg("snoopy"), "snoopy");
assert.equal(validateFamiliarOSPetArg("lantern"), "lantern");
assert.equal(parseClaudeMcpListOutput("familiaros: npx -y @familiaros/mcp").present, true);
assert.equal(parseClaudeMcpListOutput("No MCP servers configured").present, false);
const jsonGet = parseClaudeMcpGetOutput(JSON.stringify({ command: "npx", args: ["-y", "@familiaros/mcp", "--familiar", "snoopy"] }), "snoopy");
const jsonGet = parseClaudeMcpGetOutput(JSON.stringify({ command: "npx", args: ["-y", "@familiaros/mcp", "--familiar", "lantern"] }), "lantern");
assert.equal(jsonGet.present, true);
assert.equal(jsonGet.verified, true);
assert.equal(jsonGet.matchesExpected, true);
const localGet = parseClaudeMcpGetOutput(JSON.stringify({ command: "node", args: [getLocalMcpEntryPath(), "--familiar", "snoopy"] }), "snoopy", "local");
const localGet = parseClaudeMcpGetOutput(JSON.stringify({ command: "node", args: [getLocalMcpEntryPath(), "--familiar", "lantern"] }), "lantern", "local");
assert.equal(localGet.matchesExpected, true);
const bundledPreview = buildClaudeMcpPreview("snoopy", "bundled");
assert.deepEqual(bundledPreview.add.args, ["mcp", "add", "--scope", "user", "familiaros", "--", "node", getBundledMcpEntryPath(), "--familiar", "snoopy"]);
const bundledPreview = buildClaudeMcpPreview("lantern", "bundled");
assert.deepEqual(bundledPreview.add.args, ["mcp", "add", "--scope", "user", "familiaros", "--", "node", getBundledMcpEntryPath(), "--familiar", "lantern"]);
assert.equal(bundledPreview.mcpJson.mcpServers.familiaros.command, "node");
assert.deepEqual(bundledPreview.mcpJson.mcpServers.familiaros.args, [getBundledMcpEntryPath(), "--familiar", "snoopy"]);
const bundledGet = parseClaudeMcpGetOutput(JSON.stringify({ command: "node", args: [getBundledMcpEntryPath(), "--familiar", "snoopy"] }), "snoopy", "bundled");
assert.deepEqual(bundledPreview.mcpJson.mcpServers.familiaros.args, [getBundledMcpEntryPath(), "--familiar", "lantern"]);
const bundledGet = parseClaudeMcpGetOutput(JSON.stringify({ command: "node", args: [getBundledMcpEntryPath(), "--familiar", "lantern"] }), "lantern", "bundled");
assert.equal(bundledGet.matchesExpected, true);
const customNode = "/Users/test/Library/Application Support/Herd/config/nvm/versions/node/v22.22.2/bin/node";
const customNodePreview = buildClaudeMcpPreview("snoopy", "bundled", customNode);
const customNodePreview = buildClaudeMcpPreview("lantern", "bundled", customNode);
assert.equal(customNodePreview.mcpJson.mcpServers.familiaros.command, customNode);
assert.equal(parseClaudeMcpGetOutput(JSON.stringify({ command: customNode, args: [getBundledMcpEntryPath(), "--familiar", "snoopy"] }), "snoopy", "bundled", customNode).matchesExpected, true);
assert.equal(parseClaudeMcpGetOutput(JSON.stringify({ command: customNode, args: [getBundledMcpEntryPath(), "--familiar", "lantern"] }), "lantern", "bundled", customNode).matchesExpected, true);
const spacedPath = "/Applications/FamiliarOS Test.app/Contents/Resources/app/node_modules/@familiaros/mcp/dist/index.js";
assert.equal(formatCommandForDisplay({ command: "node", args: [spacedPath, "--familiar", "snoopy"] }), 'node "/Applications/FamiliarOS Test.app/Contents/Resources/app/node_modules/@familiaros/mcp/dist/index.js" --familiar snoopy');
const spacedTextGet = parseClaudeMcpGetOutput(`familiaros\nCommand: node\nArgs: "${getBundledMcpEntryPath()}" --familiar snoopy`, "snoopy", "bundled");
assert.equal(formatCommandForDisplay({ command: "node", args: [spacedPath, "--familiar", "lantern"] }), 'node "/Applications/FamiliarOS Test.app/Contents/Resources/app/node_modules/@familiaros/mcp/dist/index.js" --familiar lantern');
const spacedTextGet = parseClaudeMcpGetOutput(`familiaros\nCommand: node\nArgs: "${getBundledMcpEntryPath()}" --familiar lantern`, "lantern", "bundled");
assert.equal(spacedTextGet.matchesExpected, true);
assert.equal(formatCommandForDisplay({ command: "node", args: ["C:\\Program Files\\FamiliarOS\\resources\\app\\node_modules\\@familiaros\\mcp\\dist\\index.js"] }), 'node "C:\\\\Program Files\\\\FamiliarOS\\\\resources\\\\app\\\\node_modules\\\\@familiaros\\\\mcp\\\\dist\\\\index.js"');
assert.equal(mapAsarPathToUnpacked("/Applications/FamiliarOS.app/Contents/Resources/app.asar/node_modules/@familiaros/mcp/dist/index.js"), "/Applications/FamiliarOS.app/Contents/Resources/app.asar.unpacked/node_modules/@familiaros/mcp/dist/index.js");
@ -54,17 +54,17 @@ assert.equal(mapAsarPathToUnpacked("C:\\Program Files\\FamiliarOS\\resources\\ap
assert.equal(mapAsarPathToUnpacked("/Applications/app.asarish/FamiliarOS.app/Contents/Resources/app.asar/node_modules/@familiaros/mcp/dist/index.js"), "/Applications/app.asarish/FamiliarOS.app/Contents/Resources/app.asar.unpacked/node_modules/@familiaros/mcp/dist/index.js");
assert.equal(mapAsarPathToUnpacked("/tmp/app.asar.unpacked/node_modules/@familiaros/mcp/dist/index.js"), "/tmp/app.asar.unpacked/node_modules/@familiaros/mcp/dist/index.js");
const textGet = parseClaudeMcpGetOutput("familiaros\nCommand: npx\nArgs: -y @familiaros/mcp --familiar snoopy", "snoopy");
const textGet = parseClaudeMcpGetOutput("familiaros\nCommand: npx\nArgs: -y @familiaros/mcp --familiar lantern", "lantern");
assert.equal(textGet.present, true);
assert.equal(textGet.verified, true);
assert.equal(textGet.matchesExpected, true);
const different = parseClaudeMcpGetOutput(JSON.stringify({ command: "node", args: ["server.js"] }), "snoopy");
const different = parseClaudeMcpGetOutput(JSON.stringify({ command: "node", args: ["server.js"] }), "lantern");
assert.equal(different.present, true);
assert.equal(different.verified, true);
assert.equal(different.matchesExpected, false);
const unverifiable = classifyClaudeMcpStatus("familiaros", "Name: familiaros\nTransport: stdio", "snoopy");
const unverifiable = classifyClaudeMcpStatus("familiaros", "Name: familiaros\nTransport: stdio", "lantern");
assert.equal(unverifiable.present, true);
assert.equal(unverifiable.verified, false);
assert.equal(unverifiable.matchesExpected, false);

4
packages/mcp/src/args.ts
View file

@ -22,12 +22,12 @@ export function parseMcpArgs(argv: readonly string[]): McpCliOptions {
if (arg === "--familiar") {
const next = argv[index + 1];
if (!next) throw new Error("--familiar requires a familiar id.");
petId = validateRawPetArg(next);
petId = validatePetId(validateRawPetArg(next));
index += 1;
continue;
}
if (arg.startsWith("--familiar=")) {
petId = validateRawPetArg(arg.slice("--familiar=".length));
petId = validatePetId(validateRawPetArg(arg.slice("--familiar=".length)));
continue;
}
throw new Error(`Unknown argument: ${arg}`);

26
packages/mcp/src/check-mcp-contract.ts
View file

@ -10,15 +10,15 @@ import { parseMcpArgs } from "./args.js";
import { createFamiliarOSMcpServer } from "./server.js";
import { createMcpStatus, sanitizeUnavailableReason, type FamiliarOSMcpStatus } from "./tools.js";
parseMcpArgs(["--familiar", "snoopy"]);
parseMcpArgs(["--familiar=snoopy"]);
parseMcpArgs(["--familiar", "Bad Familiar"]);
parseMcpArgs(["--familiar", "lantern"]);
parseMcpArgs(["--familiar=lantern"]);
parseMcpArgs(["--help"]);
assertRejects(() => parseMcpArgs(["--familiar", "Bad Familiar"]));
assertRejects(() => parseMcpArgs(["--familiar", "bad/familiar"]));
assertRejects(() => parseMcpArgs(["--agent", "claude"]));
const unavailableStatus = createMcpStatus({ ok: false, appRunning: false, unavailableReason: "/Users/alvin/.config/FamiliarOS/runtime/ipc.json ENOENT" }, "snoopy");
if (unavailableStatus.routingImplemented !== true || unavailableStatus.configuredPetId !== "snoopy") {
const unavailableStatus = createMcpStatus({ ok: false, appRunning: false, unavailableReason: "/Users/alvin/.config/FamiliarOS/runtime/ipc.json ENOENT" }, "lantern");
if (unavailableStatus.routingImplemented !== true || unavailableStatus.configuredPetId !== "lantern") {
throw new Error("MCP status did not preserve configured familiar during degraded status.");
}
if (unavailableStatus.unavailableReason?.includes("/Users/")) {
@ -40,10 +40,10 @@ console.error("MCP contract validation passed.");
async function checkMcpServerContract(): Promise<void> {
const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
const fakeClient = {
status: async () => ({ ok: true, appRunning: true, defaultPet: { id: "snoopy", displayName: "Snoopy" } }),
status: async () => ({ ok: true, appRunning: true, defaultPet: { id: "lantern", displayName: "Lantern" } }),
listPets: async () => ({ ok: true as const, familiars: [], defaultPetId: "builtin" }),
installPet: async () => { throw new Error("unused"); },
acquireLease: async () => ({ leaseId: "lease-1", requestedPetId: "snoopy", targetKind: "explicit" as const, actualTargetPetId: "snoopy", actualTargetPetName: "Snoopy", usingDefaultPet: false, expiresAt: Date.now() + 15_000, leaseActive: true }),
acquireLease: async () => ({ leaseId: "lease-1", requestedPetId: "lantern", targetKind: "explicit" as const, actualTargetPetId: "lantern", actualTargetPetName: "Lantern", usingDefaultPet: false, expiresAt: Date.now() + 15_000, leaseActive: true }),
heartbeatLease: async (leaseId: string) => ({ leaseId, expiresAt: Date.now() + 15_000 }),
releaseLease: async () => ({ released: true }),
react: async (reaction: string, options?: { readonly leaseId?: string }) => ({ ok: true, reaction, leaseId: options?.leaseId }),
@ -57,7 +57,7 @@ async function checkMcpServerContract(): Promise<void> {
deleteMemory: async (id: string) => ({ ok: true as const, id, deleted: true }),
hello: async () => ({ ok: true }),
};
const server = createFamiliarOSMcpServer({ configuredPetId: "snoopy", client: fakeClient, lease: { lease: await fakeClient.acquireLease() }, leaseReady: Promise.resolve() });
const server = createFamiliarOSMcpServer({ configuredPetId: "lantern", client: fakeClient, lease: { lease: await fakeClient.acquireLease() }, leaseReady: Promise.resolve() });
const client = new Client({ name: "familiaros-contract", version: "0.0.0" });
await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
@ -70,7 +70,7 @@ async function checkMcpServerContract(): Promise<void> {
const status = await client.callTool({ name: "familiaros_status", arguments: {} }, CallToolResultSchema);
const structured = status.structuredContent as unknown as FamiliarOSMcpStatus;
if (!structured.ok || structured.configuredPetId !== "snoopy" || structured.routingImplemented !== true || structured.actualTargetPetId !== "snoopy") {
if (!structured.ok || structured.configuredPetId !== "lantern" || structured.routingImplemented !== true || structured.actualTargetPetId !== "lantern") {
throw new Error("Status tool returned unexpected structured content.");
}
@ -99,7 +99,7 @@ async function checkMcpServerContract(): Promise<void> {
const memoryForget = await client.callTool({ name: "familiaros_memory_forget", arguments: { id: "mem-2" } }, CallToolResultSchema);
if (memoryForget.isError) throw new Error("Memory forget unexpectedly failed.");
const stale = createMcpStatus({ ok: false, appRunning: true, leaseId: "missing", leaseActive: false, staleReason: "unknown_lease" }, "snoopy", undefined, "missing", "missing");
const stale = createMcpStatus({ ok: false, appRunning: true, leaseId: "missing", leaseActive: false, staleReason: "unknown_lease" }, "lantern", undefined, "missing", "missing");
if (stale.leaseActive !== false || stale.staleReason !== "unknown_lease" || stale.ok !== false) {
throw new Error("Stale MCP lease status was not preserved.");
}
@ -112,7 +112,7 @@ async function checkMcpServerContract(): Promise<void> {
async function checkStdioServerContract(): Promise<void> {
const transport = new StdioClientTransport({
command: process.execPath,
args: [join("dist", "index.js"), "--familiar", "snoopy"],
args: [join("dist", "index.js"), "--familiar", "lantern"],
env: { ...process.env, FAMILIAROS_DISCOVERY_FILE: join(process.cwd(), ".missing-familiaros-discovery.json") },
stderr: "pipe",
});
@ -129,11 +129,11 @@ async function checkStdioServerContract(): Promise<void> {
const content = Array.isArray(status.content) ? status.content : [];
const first = content[0] as { readonly type?: unknown; readonly text?: unknown } | undefined;
const text = first?.type === "text" && typeof first.text === "string" ? first.text : "";
if (!text.includes("Configured --familiar snoopy") || !text.includes("actual target is unavailable")) {
if (!text.includes("Configured --familiar lantern") || !text.includes("actual target is unavailable")) {
throw new Error("Unavailable stdio status did not explain configured familiar and unavailable target.");
}
const structured = status.structuredContent as unknown as FamiliarOSMcpStatus;
if (structured.appRunning !== false || structured.configuredPetId !== "snoopy" || structured.routingImplemented !== true) {
if (structured.appRunning !== false || structured.configuredPetId !== "lantern" || structured.routingImplemented !== true) {
throw new Error("Unavailable stdio status returned unexpected structured content.");
}
} finally {