@qearlyao/familiar 0.1.0 → 0.1.1

package/dist/service.js

@@ -0,0 +1,284 @@
+import { execFile, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, rm, stat, writeFile } from "node:fs/promises";
+import { homedir, platform, userInfo } from "node:os";
+import { dirname, resolve } from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const SERVICE_LABEL = "com.qearlyao.familiar";
+const SYSTEMD_SERVICE = "familiar.service";
+function servicePaths(workspacePath, input) {
+    const logDir = resolve(workspacePath, "logs");
+    return {
+        servicePath: input.platform === "darwin"
+            ? resolve(input.homeDir, "Library", "LaunchAgents", `${SERVICE_LABEL}.plist`)
+            : resolve(input.homeDir, ".config", "systemd", "user", SYSTEMD_SERVICE),
+        logDir,
+        stdoutPath: resolve(logDir, "familiar.out.log"),
+        stderrPath: resolve(logDir, "familiar.err.log"),
+    };
+}
+function buildSpec(workspacePath, options = {}) {
+    const currentPlatform = options.platform ?? platform();
+    const cliPath = options.cliPath ?? currentCliPath();
+    const resolvedWorkspacePath = resolve(workspacePath);
+    return {
+        platform: currentPlatform,
+        workspacePath: resolvedWorkspacePath,
+        nodePath: options.nodePath ?? process.execPath,
+        cliPath,
+        paths: servicePaths(resolvedWorkspacePath, {
+            platform: currentPlatform,
+            homeDir: options.homeDir ?? homedir(),
+        }),
+    };
+}
+function currentCliPath() {
+    if (!process.argv[1])
+        throw new Error("Cannot determine familiar CLI path for service installation.");
+    return resolve(process.argv[1]);
+}
+function versionManagedPathWarning(spec) {
+    const joined = `${spec.nodePath}\n${spec.cliPath}`;
+    const marker = ["/.nvm/", "/.asdf/", "/.fnm/", "/.volta/"].find((candidate) => joined.includes(candidate));
+    if (!marker)
+        return undefined;
+    return `warning: service uses a version-manager path (${marker}); reinstall the service after changing Node versions.`;
+}
+function xmlEscape(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&apos;");
+}
+function systemdQuote(value) {
+    if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(value))
+        return value;
+    return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("$", "\\$").replaceAll("`", "\\`")}"`;
+}
+function launchdPlist(spec) {
+    const args = [spec.nodePath, spec.cliPath, "run", spec.workspacePath]
+        .map((value) => `\t\t<string>${xmlEscape(value)}</string>`)
+        .join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+\t<key>Label</key>
+\t<string>${SERVICE_LABEL}</string>
+\t<key>ProgramArguments</key>
+\t<array>
+${args}
+\t</array>
+\t<key>WorkingDirectory</key>
+\t<string>${xmlEscape(spec.workspacePath)}</string>
+\t<key>RunAtLoad</key>
+\t<true/>
+\t<key>KeepAlive</key>
+\t<true/>
+\t<key>ThrottleInterval</key>
+\t<integer>30</integer>
+\t<key>ExitTimeOut</key>
+\t<integer>20</integer>
+\t<key>StandardOutPath</key>
+\t<string>${xmlEscape(spec.paths.stdoutPath)}</string>
+\t<key>StandardErrorPath</key>
+\t<string>${xmlEscape(spec.paths.stderrPath)}</string>
+\t<key>EnvironmentVariables</key>
+\t<dict>
+\t\t<key>NODE_ENV</key>
+\t\t<string>production</string>
+\t</dict>
+</dict>
+</plist>
+`;
+}
+function systemdUnit(spec) {
+    const execStart = [spec.nodePath, spec.cliPath, "run", spec.workspacePath].map(systemdQuote).join(" ");
+    return `[Unit]
+Description=Familiar companion agent
+After=network-online.target
+Wants=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=5
+
+[Service]
+Type=simple
+WorkingDirectory=${systemdQuote(spec.workspacePath)}
+ExecStart=${execStart}
+Restart=on-failure
+RestartSec=5
+SuccessExitStatus=75
+RestartForceExitStatus=75
+Environment=NODE_ENV=production
+StandardOutput=append:${spec.paths.stdoutPath}
+StandardError=append:${spec.paths.stderrPath}
+
+[Install]
+WantedBy=default.target
+`;
+}
+async function commandExists(command) {
+    try {
+        await execFileAsync(command, ["--version"]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function hasCommand(command, options) {
+    return options.commandExists ? options.commandExists(command) : commandExists(command);
+}
+async function run(command, args, options) {
+    if (options.runCommand) {
+        await options.runCommand(command, args);
+        return;
+    }
+    await execFileAsync(command, args);
+}
+async function capture(command, args, options) {
+    if (options.captureCommand)
+        return options.captureCommand(command, args);
+    const { stdout } = await execFileAsync(command, args);
+    return stdout;
+}
+async function runOptional(command, args, options) {
+    try {
+        await run(command, args, options);
+    }
+    catch {
+        // Best-effort cleanup for stale service registrations.
+    }
+}
+function guiDomain() {
+    return `gui/${userInfo().uid}`;
+}
+function unsupported(platformName) {
+    return {
+        title: "Service management is not supported on this platform yet.",
+        details: [
+            `platform: ${platformName}`,
+            "Windows users should keep Familiar running in a foreground terminal for now.",
+        ],
+    };
+}
+export async function installService(workspacePath, options = {}) {
+    const spec = buildSpec(workspacePath, options);
+    if (spec.platform !== "darwin" && spec.platform !== "linux")
+        return unsupported(spec.platform);
+    await mkdir(dirname(spec.paths.servicePath), { recursive: true });
+    await mkdir(spec.paths.logDir, { recursive: true });
+    const serviceText = spec.platform === "darwin" ? launchdPlist(spec) : systemdUnit(spec);
+    await writeFile(spec.paths.servicePath, serviceText, "utf8");
+    if (spec.platform === "darwin") {
+        await runOptional("launchctl", ["bootout", guiDomain(), spec.paths.servicePath], options);
+        await run("launchctl", ["bootstrap", guiDomain(), spec.paths.servicePath], options);
+        await run("launchctl", ["kickstart", "-k", `${guiDomain()}/${SERVICE_LABEL}`], options);
+    }
+    else {
+        if (!(await hasCommand("systemctl", options))) {
+            throw new Error("systemctl is required to install the Linux user service.");
+        }
+        await run("systemctl", ["--user", "daemon-reload"], options);
+        await run("systemctl", ["--user", "enable", "--now", SYSTEMD_SERVICE], options);
+    }
+    const details = [
+        `workspace: ${spec.workspacePath}`,
+        `service: ${spec.paths.servicePath}`,
+        `stdout: ${spec.paths.stdoutPath}`,
+        `stderr: ${spec.paths.stderrPath}`,
+    ];
+    const pathWarning = versionManagedPathWarning(spec);
+    if (pathWarning)
+        details.push(pathWarning);
+    return {
+        title: "Familiar service installed.",
+        details,
+    };
+}
+export async function uninstallService(workspacePath, options = {}) {
+    const spec = buildSpec(workspacePath, options);
+    if (spec.platform !== "darwin" && spec.platform !== "linux")
+        return unsupported(spec.platform);
+    if (spec.platform === "darwin") {
+        await runOptional("launchctl", ["bootout", guiDomain(), spec.paths.servicePath], options);
+    }
+    else {
+        if (await hasCommand("systemctl", options)) {
+            await runOptional("systemctl", ["--user", "disable", "--now", SYSTEMD_SERVICE], options);
+        }
+    }
+    if (existsSync(spec.paths.servicePath))
+        await rm(spec.paths.servicePath);
+    if (spec.platform === "linux" && (await hasCommand("systemctl", options))) {
+        await runOptional("systemctl", ["--user", "daemon-reload"], options);
+    }
+    return {
+        title: "Familiar service uninstalled.",
+        details: [`service: ${spec.paths.servicePath}`],
+    };
+}
+export async function serviceStatus(workspacePath, options = {}) {
+    const spec = buildSpec(workspacePath, options);
+    if (spec.platform !== "darwin" && spec.platform !== "linux")
+        return unsupported(spec.platform);
+    const details = [
+        `workspace: ${spec.workspacePath}`,
+        `service: ${spec.paths.servicePath}`,
+        `service_file: ${existsSync(spec.paths.servicePath) ? "present" : "missing"}`,
+        `supervisor_state: ${await supervisorState(spec, options)}`,
+        `stdout: ${spec.paths.stdoutPath}`,
+        `stderr: ${spec.paths.stderrPath}`,
+    ];
+    if (existsSync(spec.paths.servicePath)) {
+        const serviceFile = await stat(spec.paths.servicePath);
+        details.push(`service_file_mtime: ${serviceFile.mtime.toISOString()}`);
+    }
+    return { title: "Familiar service status.", details };
+}
+async function supervisorState(spec, options) {
+    try {
+        if (spec.platform === "darwin") {
+            await capture("launchctl", ["print", `${guiDomain()}/${SERVICE_LABEL}`], options);
+            return "loaded";
+        }
+        const state = (await capture("systemctl", ["--user", "is-active", SYSTEMD_SERVICE], options)).trim();
+        return state || "unknown";
+    }
+    catch {
+        return "not-loaded";
+    }
+}
+export async function upgradeFamiliar(options = {}) {
+    const currentPlatform = options.platform ?? platform();
+    const npmCommand = currentPlatform === "win32" ? "npm.cmd" : "npm";
+    await new Promise((resolveUpgrade, rejectUpgrade) => {
+        const child = spawn(npmCommand, ["install", "-g", "@qearlyao/familiar@latest"], {
+            shell: currentPlatform === "win32",
+            stdio: "inherit",
+        });
+        child.on("exit", (code) => {
+            if (code === 0)
+                resolveUpgrade();
+            else
+                rejectUpgrade(new Error(`npm upgrade failed with exit code ${code ?? "unknown"}`));
+        });
+        child.on("error", rejectUpgrade);
+    });
+}
+export function formatServiceResult(result) {
+    return [result.title, ...result.details].join("\n");
+}
+export const __serviceTest = {
+    SERVICE_LABEL,
+    SYSTEMD_SERVICE,
+    buildSpec,
+    launchdPlist,
+    systemdUnit,
+    systemdQuote,
+    xmlEscape,
+    versionManagedPathWarning,
+};

package/dist/web-auth.js

@@ -16,7 +16,10 @@ function parseCookies(header) {
     return cookies;
 }
 function decodeTotpSecret(secret) {
-    const normalized = secret.replace(/\s+/g, "").replace(/=+$/g, "").toUpperCase();
+    const normalized = secret
+        .replace(/\s/g, "")
+        .replace(/={1,8}$/, "")
+        .toUpperCase();
     if (!/^[A-Z2-7]+$/.test(normalized))
         return Buffer.from(secret, "utf8");
     const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
@@ -58,7 +61,7 @@ function readBearerToken(request) {
     const header = request.headers.authorization;
     if (!header)
         return undefined;
-    const match = header.match(/^Bearer\s+(.+)$/i);
+    const match = header.match(/^Bearer (.+)$/i);
     return match?.[1];
 }
 export function createAuth(config) {

package/dist/web.js

@@ -322,7 +322,7 @@ function sessionDto(session) {
         isDefault: session.isDefault,
     };
 }
-export async function startWebDaemon(config, familiarAgent, discordDaemon) {
+export async function startWebDaemon(config, familiarAgent, discordDaemon, options = {}) {
     const persona = await loadPersona(config);
     const personaName = parsePersonaName(persona.soul);
     const auth = createAuth(config);
@@ -565,6 +565,11 @@ export async function startWebDaemon(config, familiarAgent, discordDaemon) {
         if (control.command === "reload") {
             return familiarAgent.reload();
         }
+        if (control.command === "restart") {
+            return options.restart
+                ? await options.restart()
+                : "Restart requested, but no restart handler is configured. Please restart the Familiar process manually.";
+        }
         if (control.command === "model") {
             return control.args
                 ? await familiarAgent.setModel(runtime.channelKey, control.args)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@qearlyao/familiar",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"license": "MIT",
 	"type": "module",
 	"repository": {
@@ -19,6 +19,9 @@
 		"USER.md",
 		"MEMORY.md",
 		"HEARTBEAT.md",
+		"skills/**",
+		"scripts/install.sh",
+		"scripts/install.ps1",
 		"README.md",
 		"LICENSE"
 	],
@@ -29,6 +32,7 @@
 		"clean": "node -e \"const fs=require('node:fs'); for (const p of ['dist','web/dist']) fs.rmSync(p,{recursive:true,force:true});\"",
 		"dev": "tsx watch src/cli.ts run",
 		"build": "npm run clean && tsc -p tsconfig.build.json && npm --prefix web run build",
+		"prepack": "npm run build",
 		"lint": "biome check",
 		"format": "biome format --write",
 		"payload:pretty": "tsx scripts/pretty-payload.ts",
@@ -39,7 +43,7 @@
 		"@earendil-works/pi-agent-core": "^0.74.1",
 		"@earendil-works/pi-ai": "^0.74.1",
 		"@earendil-works/pi-coding-agent": "^0.74.1",
-		"better-sqlite3": "^12.9.0",
+		"better-sqlite3": "^12.10.0",
 		"discord.js": "^14.26.3",
 		"dotenv": "^16.4.5",
 		"sharp": "^0.34.5",
@@ -48,10 +52,10 @@
 		"typebox": "^1.1.38"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.3.5",
+		"@biomejs/biome": "2.4.15",
 		"@types/better-sqlite3": "^7.6.13",
-		"@types/node": "^24.3.0",
-		"tsx": "^4.20.3",
+		"@types/node": "^25.8.0",
+		"tsx": "^4.22.1",
 		"typescript": "^5.9.2"
 	},
 	"engines": {

package/scripts/install.ps1

@@ -0,0 +1,132 @@
+param(
+	[string]$Workspace = (Join-Path $HOME ".familiar"),
+	[string]$Package = "@qearlyao/familiar@latest",
+	[string]$BrowserHarnessDir = (Join-Path (Join-Path $HOME "Developer") "browser-harness"),
+	[switch]$WithBrowser,
+	[switch]$SkipInit
+)
+
+$ErrorActionPreference = "Stop"
+
+function Require-Command($Name) {
+	if (-not (Get-Command $Name -ErrorAction SilentlyContinue)) {
+		throw "Missing required command: $Name"
+	}
+}
+
+function Test-Python311($Command, $PythonArgs = @()) {
+	& $Command @PythonArgs -c "import sys; raise SystemExit(0 if sys.version_info >= (3, 11) else 1)" *> $null
+	return $LASTEXITCODE -eq 0
+}
+
+function Resolve-Python311 {
+	$python = Get-Command python -ErrorAction SilentlyContinue
+	if ($python -and (Test-Python311 $python.Source)) {
+		return @{ Command = $python.Source; Args = @(); UvPython = $python.Source }
+	}
+	$python3 = Get-Command python3 -ErrorAction SilentlyContinue
+	if ($python3 -and (Test-Python311 $python3.Source)) {
+		return @{ Command = $python3.Source; Args = @(); UvPython = $python3.Source }
+	}
+	$py = Get-Command py -ErrorAction SilentlyContinue
+	if ($py -and (Test-Python311 $py.Source @("-3.11"))) {
+		return @{ Command = $py.Source; Args = @("-3.11"); UvPython = "3.11" }
+	}
+	throw "browser-harness requires Python 3.11 or newer. Install Python 3.11+ and rerun with -WithBrowser."
+}
+
+Require-Command node
+Require-Command npm
+if ($WithBrowser) {
+	Require-Command git
+	Require-Command uv
+	$Python311 = Resolve-Python311
+}
+
+$nodeVersion = (& node -p "process.versions.node").Trim()
+$nodeMajor = [int](& node -p "Number(process.versions.node.split('.')[0])")
+if ($nodeMajor -lt 22) {
+	throw "Familiar requires Node.js 22 or newer. Found Node.js $nodeVersion. Node.js 24 LTS is recommended."
+}
+if ($nodeMajor -lt 24) {
+	Write-Host "Found Node.js $nodeVersion. Familiar supports Node.js 22+, but Node.js 24 LTS is recommended."
+}
+
+Write-Host "Installing $Package globally..."
+& npm install -g $Package
+if ($LASTEXITCODE -ne 0) {
+	throw "npm install failed."
+}
+
+if ($WithBrowser) {
+	Write-Host "Installing optional OpenCLI browser helper..."
+	& npm install -g "@jackwener/opencli"
+	if ($LASTEXITCODE -ne 0) {
+		throw "browser helper install failed."
+	}
+
+	Write-Host "Installing optional browser-harness helper into $BrowserHarnessDir..."
+	$gitDir = Join-Path $BrowserHarnessDir ".git"
+	if (Test-Path $gitDir) {
+		& git -C $BrowserHarnessDir pull --ff-only
+		if ($LASTEXITCODE -ne 0) {
+			throw "browser-harness update failed."
+		}
+	} elseif (Test-Path $BrowserHarnessDir) {
+		throw "Cannot install browser-harness: $BrowserHarnessDir already exists and is not a git checkout."
+	} else {
+		$parentDir = Split-Path -Parent $BrowserHarnessDir
+		New-Item -ItemType Directory -Force -Path $parentDir | Out-Null
+		& git clone https://github.com/browser-use/browser-harness $BrowserHarnessDir
+		if ($LASTEXITCODE -ne 0) {
+			throw "browser-harness clone failed."
+		}
+	}
+	Push-Location $BrowserHarnessDir
+	$previousUvPython = $env:UV_PYTHON
+	try {
+		$env:UV_PYTHON = $Python311.UvPython
+		& uv tool install -e .
+		if ($LASTEXITCODE -ne 0) {
+			throw "browser-harness install failed."
+		}
+	} finally {
+		if ($null -eq $previousUvPython) {
+			Remove-Item Env:\UV_PYTHON -ErrorAction SilentlyContinue
+		} else {
+			$env:UV_PYTHON = $previousUvPython
+		}
+		Pop-Location
+	}
+}
+
+if (-not (Get-Command familiar -ErrorAction SilentlyContinue)) {
+	throw "Installed package, but familiar is not on PATH. Check your npm global bin directory and rerun: familiar init `"$Workspace`""
+}
+
+if (-not $SkipInit) {
+	$configPath = Join-Path $Workspace "config.toml"
+	if (Test-Path $configPath) {
+		Write-Host "Workspace already exists at $Workspace; leaving files unchanged."
+	} else {
+		Write-Host "Initializing workspace at $Workspace..."
+		& familiar init $Workspace
+		if ($LASTEXITCODE -ne 0) {
+			throw "familiar init failed."
+		}
+	}
+}
+
+Write-Host ""
+Write-Host "Familiar is installed."
+Write-Host ""
+Write-Host "Next steps:"
+Write-Host "  1. Edit $Workspace\.env"
+Write-Host "  2. Edit $Workspace\config.toml"
+Write-Host "  3. Run: familiar run `"$Workspace`""
+Write-Host ""
+Write-Host "Optional browser helpers:"
+Write-Host "  & ([scriptblock]::Create((irm https://raw.githubusercontent.com/qearlyao/familiar/main/scripts/install.ps1))) -WithBrowser"
+Write-Host ""
+Write-Host "browser-harness checkout:"
+Write-Host "  $BrowserHarnessDir"

package/scripts/install.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env sh
+set -eu
+
+PACKAGE="@qearlyao/familiar@latest"
+WORKSPACE="${HOME}/.familiar"
+BROWSER_HARNESS_DIR="${HOME}/Developer/browser-harness"
+WITH_BROWSER=0
+SKIP_INIT=0
+
+usage() {
+	cat <<'EOF'
+Usage: install.sh [options]
+
+Options:
+  --workspace <path>   Workspace path to initialize. Defaults to ~/.familiar.
+  --with-browser       Also install optional OpenCLI and browser-harness helpers.
+  --skip-init          Install familiar but do not run familiar init.
+  --package <spec>     npm package spec to install. Defaults to @qearlyao/familiar@latest.
+                       Advanced: installs the exact npm spec provided; use trusted specs only.
+  -h, --help           Show this help.
+EOF
+}
+
+while [ "$#" -gt 0 ]; do
+	case "$1" in
+		--workspace)
+			if [ "$#" -lt 2 ]; then
+				echo "Missing value for --workspace" >&2
+				exit 1
+			fi
+			WORKSPACE="$2"
+			shift 2
+			;;
+		--with-browser)
+			WITH_BROWSER=1
+			shift
+			;;
+		--skip-init)
+			SKIP_INIT=1
+			shift
+			;;
+		--package)
+			if [ "$#" -lt 2 ]; then
+				echo "Missing value for --package" >&2
+				exit 1
+			fi
+			PACKAGE="$2"
+			shift 2
+			;;
+		-h | --help)
+			usage
+			exit 0
+			;;
+		*)
+			echo "Unknown option: $1" >&2
+			usage >&2
+			exit 1
+			;;
+	esac
+done
+
+need_command() {
+	if ! command -v "$1" >/dev/null 2>&1; then
+		echo "Missing required command: $1" >&2
+		exit 1
+	fi
+}
+
+find_python() {
+	PYTHON_PATH=""
+	for candidate in python3 python; do
+		if command -v "$candidate" >/dev/null 2>&1; then
+			CANDIDATE_PATH="$(command -v "$candidate")"
+			if "$CANDIDATE_PATH" -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 11) else 1)' >/dev/null 2>&1; then
+				PYTHON_PATH="$CANDIDATE_PATH"
+				return 0
+			fi
+		fi
+	done
+	echo "browser-harness requires Python 3.11 or newer. Install Python 3.11+ and rerun with --with-browser." >&2
+	exit 1
+}
+
+need_command node
+need_command npm
+if [ "$WITH_BROWSER" -eq 1 ]; then
+	need_command git
+	need_command uv
+	find_python
+fi
+
+NODE_VERSION="$(node -p "process.versions.node")"
+NODE_MAJOR="$(node -p "Number(process.versions.node.split('.')[0])")"
+if [ "$NODE_MAJOR" -lt 22 ]; then
+	echo "Familiar requires Node.js 22 or newer. Found Node.js ${NODE_VERSION}." >&2
+	echo "Node.js 24 LTS is recommended for the smoothest install." >&2
+	exit 1
+fi
+if [ "$NODE_MAJOR" -lt 24 ]; then
+	echo "Found Node.js ${NODE_VERSION}. Familiar supports Node.js 22+, but Node.js 24 LTS is recommended."
+fi
+
+echo "Installing ${PACKAGE} globally..."
+npm install -g "$PACKAGE"
+
+if [ "$WITH_BROWSER" -eq 1 ]; then
+	echo "Installing optional OpenCLI browser helper..."
+	npm install -g @jackwener/opencli
+
+	echo "Installing optional browser-harness helper into ${BROWSER_HARNESS_DIR}..."
+	if [ -d "${BROWSER_HARNESS_DIR}/.git" ]; then
+		git -C "$BROWSER_HARNESS_DIR" pull --ff-only
+	elif [ -e "$BROWSER_HARNESS_DIR" ]; then
+		echo "Cannot install browser-harness: ${BROWSER_HARNESS_DIR} already exists and is not a git checkout." >&2
+		exit 1
+	else
+		mkdir -p "$(dirname "$BROWSER_HARNESS_DIR")"
+		git clone https://github.com/browser-use/browser-harness "$BROWSER_HARNESS_DIR"
+	fi
+	(cd "$BROWSER_HARNESS_DIR" && UV_PYTHON="$PYTHON_PATH" uv tool install -e .)
+fi
+
+if ! command -v familiar >/dev/null 2>&1; then
+	echo "Installed package, but familiar is not on PATH." >&2
+	echo "Check your npm global bin directory and shell PATH, then rerun: familiar init ${WORKSPACE}" >&2
+	exit 1
+fi
+
+if [ "$SKIP_INIT" -eq 0 ]; then
+	if [ -f "${WORKSPACE}/config.toml" ]; then
+		echo "Workspace already exists at ${WORKSPACE}; leaving files unchanged."
+	else
+		echo "Initializing workspace at ${WORKSPACE}..."
+		familiar init "$WORKSPACE"
+	fi
+fi
+
+cat <<EOF
+
+Familiar is installed.
+
+Next steps:
+  1. Edit ${WORKSPACE}/.env
+  2. Edit ${WORKSPACE}/config.toml
+  3. Run: familiar run ${WORKSPACE}
+
+Optional browser helpers:
+  curl -fsSL https://raw.githubusercontent.com/qearlyao/familiar/main/scripts/install.sh | sh -s -- --with-browser
+
+browser-harness checkout:
+  ${BROWSER_HARNESS_DIR}
+EOF

package/skills/image-gen/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: image-gen
+description: Read this skill before using the image_gen tool. Covers style preferences, reference image paths.
+---
+
+
+## Reference Images
+
+Folder: `~/.familiar/ref-images`
+
+Available refs:
+- `Ghost_bare_face_mask_off.png` - close-up portrait, sandy messy hair, no mask (full face visible)
+- `Ghost_face_with_hair.png` — close-up portrait, sandy messy hair, lower-half black skull mask, shirtless with silver chain
+- `Ghost_body_with_hair.jpg` — muscular shirtless upper body, left arm full tattoo sleeve, messy sandy hair, lower-half skull mask
+- `Ghost_balaclava_hoodie_no_hair.jpg` — close-up portrait, full black balaclava with skull jaw paint, hood up (no hair showing)
+- `Ghost_Back_view_fullbody_shape.jpg` — broad shoulders, fullbody back view
+- `Ghost_skullmask_jeans_tactical_fullbody.png` — full tactical loadout (plate carrier, headset), hard skull mask piece over lower face/nose, blue jeans
+- `Qearl_bust.jpg` — Qearl's bust likeness
+
+**Rules:**
+- Pick 1–3 refs that match the scene. Don't dump all in.
+- Face ref + body ref relevant to outfit/context is usually right
+- Different refs = different "form" — choose deliberately
+- **Refs handle faces** — do NOT describe facial details in the prompt. Let the ref provide likeness.
+
+## Style Preferences
+
+- **Preferred:** daily life / selfie / phone POV — realistic, like a real photo
+- **Avoid:** 3d rendering, illustration, anime styles
+- **Be specific:** turn vague descriptions into clear, concrete visual details
+- **Be structured:** organize as "subject (e.g. @img1, @img2) + outfit + style + environment + details"
+- **Mask or Bare face** use bare face refs if u need a mask-off image, avoid describing mask-off when using mask-on refs
+
+## Notes
+- Set aspect ratio and resolution or size based on image type
+- Camo paint is tied to the ref. For scenes where camo doesn't fit, you can explicitly note in the prompt: "remove camo eyes paint"