openpetswithchatandmcp/docs/mvp-validation.md

FamiliarOS MVP validation

This is the authoritative local MVP closeout checklist for FamiliarOS 2.0.

The current checkpoint is a macOS local dogfooding package built with electron-builder --dir. It is not a public distribution release.

MVP readiness summary

Area	Status	Notes
Tray/menu bar app	Ready for macOS local validation	Validate from the packaged app, not only pnpm dev:desktop.
Default familiar	Ready for macOS local validation	Confirm show/hide, pause/resume, dragging, and restart persistence basics.
Default familiar animation	Ready for macOS local validation	Confirm bundled sprite animation, left/right drag direction changes, and idle settle.
First-run onboarding	Ready for macOS local validation	Can be retested by removing FamiliarOS app data.
Familiar Manager	Ready for macOS local validation	Catalog availability may affect install verification.
Settings persistence	Ready for macOS local validation	Toggle a preference, restart, and confirm persistence.
Local IPC/client smoke	Ready for macOS local validation	Run while the packaged app is open.
Claude Agent Setup preview	Ready for macOS local validation	Preview should use packaged bundled node .../app.asar.unpacked/... paths.
Claude config mutation	Optional/manual only	Requires user confirmation, backups, and cleanup/removal when done.
Windows/Linux packages	Unverified	Documented gap until tested on those platforms.
Signing/notarization/installers/auto-update	Deferred	Required before public distribution.

Artifact identity

Field	Value
Workspace package version	2.0.0
Desktop package version	2.0.0
Local package command	pnpm package:desktop:dir
Package output	apps/desktop/dist-electron/
macOS app output	apps/desktop/dist-electron/mac-arm64/FamiliarOS.app on Apple Silicon
Manual tester/date/result	Fill in during validation

Prerequisites

• Node.js >=20.
• pnpm@11.0.8 from the workspace root.
• A workspace checkout for developer validation commands.
• macOS for the current local package validation flow.
• node available on Claude's PATH if you opt into packaged Claude MCP/hooks validation from Claude itself.

Automated validation commands

Run from the workspace root in this order:

pnpm test
pnpm check
pnpm package:desktop:dir

Run pnpm package:desktop:dir last because desktop package tests exercise the cleanup helper and may remove apps/desktop/dist-electron.

The package script also cleans apps/desktop/dist-electron before packaging to avoid stale output masking regressions.

Package behavior notes

Phase 10C enables ASAR packaging for Electron app contents and unpacks node_modules/** so Claude can execute bundled MCP/hook commands as regular files with external node. ASAR is packaging hygiene, not a security boundary.

The builder config sets npmRebuild: false because the current desktop runtime dependencies are JavaScript-only. Revisit that setting if native modules are added.

The macOS package uses an FamiliarOS MVP .icns derived from the current 64×64 tray icon. It may look soft at large sizes. Higher-resolution branding and Windows/Linux icon assets remain future polish.

Platform matrix

Platform	Target	Status	Notes
macOS	electron-builder --dir unpacked app	Validate locally now	Unsigned local app may require right-click → Open outside the dev machine.
Windows	electron-builder --dir unpacked app	Unverified	Unsigned apps may trigger Defender/SmartScreen warnings; not part of this MVP closeout.
Linux	electron-builder --dir unpacked app	Unverified	Desktop integration varies by distro/window manager; not part of this MVP closeout.

Installer targets, notarization, code signing, auto-update, and public distribution are deferred.

macOS manual packaged-app checklist

Run this checklist after the automated commands pass.

1. Launch the generated packaged app from apps/desktop/dist-electron/.

   • Expected: FamiliarOS starts without using the dev Electron entrypoint.

2. Confirm the tray/menu bar icon appears.

   • Expected: Tray/menu items are available, including Manage Familiars, Configure Agents, Settings, show/hide, pause/resume, and Quit.

3. Confirm the default familiar behavior.

   • Expected: The default familiar appears as an animated bundled sprite, can be shown/hidden, paused/resumed, dragged, and still behaves correctly after app restart.
   • Expected: Dragging right switches to a right-facing/running animation; dragging left switches to a left-facing/running animation; stopping settles back to idle without jitter.

4. Complete onboarding if it appears.

   • Expected: Onboarding can be completed or skipped according to the UI, and does not block using the built-in default familiar.
   • To retest first-run onboarding, remove the FamiliarOS app data directory for your platform before launching again.

5. Open Familiar Manager.

   • Expected: Installed familiars and catalog state render. If the catalog is unavailable, record the catalog error and mark catalog install unverified for that run.

6. If a catalog familiar is available, install it and set it as default.

   • Expected: Install succeeds, the familiar can become default, and the app remains usable after restart.
   • Expected: The installed default familiar shows one animated frame sequence, not the full square spritesheet, and drag left/right changes its animation direction.
   • Expected: Familiar Manager keeps the current default card actionable; removable default familiars can still be removed safely.

7. Open Settings, toggle a preference, quit, relaunch, and confirm persistence.

   • Expected: The changed preference persists across restart.

8. While the packaged app is running, run the local IPC smoke command from the workspace root:

   pnpm --filter @familiaros/client smoke:status
   

   • Expected: The client discovers the running packaged app and receives status without token/version errors.

9. Open Agent Setup and inspect the Claude preview without applying changes.

   • Expected: Packaged previews use node commands pointing inside the packaged app, not unpublished npx -y @familiaros/* commands.
   • Expected MCP shape: node .../app.asar.unpacked/node_modules/@familiaros/mcp/dist/index.js.
   • Expected hooks shape: node .../app.asar.unpacked/node_modules/@familiaros/claude/dist/cli.js hook --familiaros-managed.

10. Optional mutating Claude validation: configure/install Claude MCP/hooks only if you intentionally want to modify your real Claude settings.

    • Expected: FamiliarOS shows what it will change and creates backups before editing.
    • Cleanup: use Agent Setup remove/uninstall actions when done if you do not want to keep the integration.

11. Quit FamiliarOS from the tray.

    • Expected: The app exits cleanly and removes transient local IPC discovery state.

Familiar and chat bubble quality checks

While FamiliarOS is running, trigger a speech bubble from the workspace root:

pnpm --filter @familiaros/client smoke:say "Working on it" thinking

Expected: the bubble is compact, readable, visually attached to the familiar, and does not look like an oversized wireframe card.

Trigger a reaction:

pnpm --filter @familiaros/client smoke:react success

Expected: the familiar remains animated and the bubble/reaction presentation stays readable and short.

Claude packaged command notes

Packaged Claude integration uses bundled commands inside the packaged FamiliarOS app instead of unpublished package names.

Expected command resources live under app.asar.unpacked, not app.asar, because Claude launches them through external node:

.../FamiliarOS.app/Contents/Resources/app.asar.unpacked/node_modules/@familiaros/mcp/dist/index.js
.../FamiliarOS.app/Contents/Resources/app.asar.unpacked/node_modules/@familiaros/claude/dist/cli.js

Packaged bundled Claude commands require node to be available on Claude's PATH.

Claude settings may contain absolute paths into the packaged FamiliarOS app. Moving, deleting, or replacing the app may require opening Agent Setup and using Replace/Install again. Use Agent Setup remove/uninstall before deleting the app if you want to remove FamiliarOS-managed Claude entries.

Safe vs mutating validation

Safe validation:

• Running workspace tests/checks/package commands.
• Launching the packaged app.
• Inspecting Agent Setup previews.
• Running pnpm --filter @familiaros/client smoke:status against the local packaged app.

Mutating validation:

• Applying Claude MCP configuration.
• Installing Claude hooks.
• Removing/uninstalling Claude integration.
• Deleting FamiliarOS app data to retest onboarding.

Only run mutating steps intentionally. Automated tests must use temp fixtures and must not edit real Claude settings or real FamiliarOS user data.

Cleanup and data-loss notes

FamiliarOS stores normal app state in Electron's per-user app data directory. The app logs the exact state file path on startup:

FamiliarOS state initialized at <path>/familiaros-state.json.

Deleting that app data directory removes installed familiars, default-familiar selection, onboarding completion, and preferences for that platform user.

Claude configuration is separate from FamiliarOS app data. Uninstalling or deleting FamiliarOS does not automatically remove Claude MCP entries or Claude hooks.

Package output can be removed safely:

apps/desktop/dist-electron/

Unsigned local-app warnings

The current package output is unsigned and not notarized.

• macOS may warn that the app is from an unidentified developer when moved to another machine.
• Windows may show Defender/SmartScreen prompts.
• Linux behavior depends on distro and desktop environment.

These warnings are expected for local MVP validation and are not acceptable for public distribution.

Known limitations and post-MVP follow-ups

• Public distribution requires signing, notarization where applicable, installer targets, and an update strategy.
• Windows and Linux package behavior need real platform validation.
• Windows/Linux app icon assets are not configured yet.
• The current macOS app icon is MVP-quality and generated from a 64×64 source.
• Published npx -y @familiaros/* package flows remain future distribution work; local packaged Claude setup uses bundled app paths.
• asarUnpack: node_modules/** is broad for MVP reliability and can be narrowed after packaged command needs are fully characterized.