### Install and Basic Commands

Source: https://github.com/alvinunreal/openpets/blob/main/skills/openpets/references/commands.md

Installs the OpenPets CLI globally and demonstrates basic commands for checking status, listing pets, installing a specific pet, and configuring agents.

```bash
npm install -g @open-pets/cli
openpets status
openpets pets
openpets install <pet-id>
openpets configure --agent claude --pet <pet-id> --cwd <project-path> --yes
openpets configure --agent opencode --pet <pet-id> --cwd <project-path> --yes
openpets configure --agent cursor --pet <pet-id> --cwd <project-path> --yes
openpets mcp --pet <pet-id>
```

--------------------------------

### Package Desktop Application (Installer)

Source: https://github.com/alvinunreal/openpets/blob/main/README.md

Builds and packages the desktop application into final installer or setup archives.

```bash
# Build & package into final installer / setup archives
pnpm package:desktop
```

--------------------------------

### Install Plugin SDK

Source: https://github.com/alvinunreal/openpets/blob/main/packages/sdk/README.md

Install the OpenPets plugin SDK as a development dependency.

```bash
npm i -D @open-pets/plugin-sdk
```

--------------------------------

### Pet Installation Flow

Source: https://github.com/alvinunreal/openpets/blob/main/apps/desktop/src/codemap.md

Details the steps involved in installing a pet, from downloading to state management.

```typescript
pet-installation.ts
├── installPet()
│   ├── getCatalogPet() → catalog.ts
│   ├── downloadPetZip() → validate ZIP magic
│   ├── extractPetZip() → yauzl with entry validation
│   └── installPetState() → app-state.ts
└── importCodexPet() → codex-pets.ts
```

--------------------------------

### Install and Run OpenPets MCP Server (Global CLI)

Source: https://github.com/alvinunreal/openpets/blob/main/skills/openpets/references/integrations.md

Installs and runs an OpenPets MCP server using the global CLI for a specific pet. Use this if the CLI is not installed globally.

```bash
npx -y @open-pets/cli@latest --pet <pet-id>
```

--------------------------------

### Install Pet CLI Usage

Source: https://github.com/alvinunreal/openpets/blob/main/packages/install-pet/codemap.md

Demonstrates how to use the install-pet CLI tool to install a pet from the OpenPets gallery catalog. Can be run directly or via npx.

```bash
install-pet <pet-id>
npx -y install-pet <pet-id>
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/alvinunreal/openpets/blob/main/README.md

Installs all necessary dependencies for the project workspace using pnpm.

```bash
pnpm install
```

--------------------------------

### Agent Setup Flow

Source: https://github.com/alvinunreal/openpets/blob/main/apps/desktop/src/codemap.md

Outlines the process for setting up agents, including detecting Claude status and running setup actions.

```typescript
windows.ts (IPC handlers)
└── agent-setup.ts
    ├── detectClaudeCodeStatus() (claude --version, claude mcp list)
    ├── runAgentSetupAction()
    │   ├── configure/replace/remove (MCP commands)
    │   ├── install-memory (claude-memory.ts)
    │   └── install-hooks/uninstall-hooks/doctor-hooks (@open-pets/claude)
    ├── OpenCode global config management (@open-pets/opencode)
    └── Cursor global MCP config management (@open-pets/cursor)
```

--------------------------------

### Cursor Project Setup Configuration

Source: https://github.com/alvinunreal/openpets/blob/main/packages/codemap.md

Describes the Cursor project setup process, including writing MCP configuration and rules via the client package.

```text
Cursor Setup (packages/cursor/src/cursor-project-setup.ts)
    └── Writes MCP config + rules → @open-pets/client
```

--------------------------------

### Verify Available Pets

Source: https://github.com/alvinunreal/openpets/blob/main/skills/openpets/workflows/install-pet.md

After installation, use this command to list all available pets. This helps confirm the successful installation of the new pet.

```bash
openpets pets
```

--------------------------------

### Direct Install Flow - State Update

Source: https://github.com/alvinunreal/openpets/blob/main/packages/install-pet/codemap.md

Shows the step where the installed pet's state is recorded in the `openpets-state.json` file.

```bash
writeInstalledPetState() → Update openpets-state.json
```

--------------------------------

### Direct Install Flow - Catalog Fetching

Source: https://github.com/alvinunreal/openpets/blob/main/packages/install-pet/codemap.md

Shows the step where the catalog JSON is fetched from the OpenPets catalog URL.

```bash
fetchCatalog() → GET https://openpets.dev/pets/catalog.v2.json
```

--------------------------------

### Install Pet Function Signature

Source: https://github.com/alvinunreal/openpets/blob/main/packages/install-pet/codemap.md

The main function for installing pets, supporting direct installation or attempting to use a running application.

```javascript
installPet({ petId, preferRunningApp })
```

--------------------------------

### Direct Install Flow - Lock Acquisition

Source: https://github.com/alvinunreal/openpets/blob/main/packages/install-pet/codemap.md

Illustrates the initial step in the direct installation process, which involves acquiring a lock to prevent concurrent installations.

```bash
acquireDirectInstallLock() → mkdir lock, write owner.json
```

--------------------------------

### Install a Pet

Source: https://github.com/alvinunreal/openpets/blob/main/skills/openpets/workflows/install-pet.md

Use this command to install a specific pet by its ID. Ensure the pet ID is confirmed before execution.

```bash
openpets install <pet-id>
```

--------------------------------

### OpenCode Project Setup Flow

Source: https://github.com/alvinunreal/openpets/blob/main/packages/opencode/codemap.md

Outlines the sequence of operations for preparing and writing OpenCode project setup configurations. It involves reading existing configs, classifying statuses, and planning atomic writes.

```typescript
prepareOpenCodeProjectSetup({ projectDir, petId, cliVersion })
    ↓
readExistingConfigs() → Parse all candidate config files
    ↓
classifyOpenCodeMcpStatus() → Check if installed/needs update/conflict
    ↓
classifyOpenCodeInstructionsStatus() → Check instruction file
    ↓
classifyOpenCodePluginStatus() → Check plugin array
    ↓
buildNextConfig() → Merge mcp/instructions/plugin updates
    ↓
planOpenCodeConfigWrite() → Atomic write plan with backup
    ↓
planInstructionWrite() → Upsert managed instruction block
    ↓
writePreparedOpenCodeProjectSetup() → Execute writes atomically

```

--------------------------------

### MCP Server Setup with Tools

Source: https://github.com/alvinunreal/openpets/blob/main/packages/mcp/codemap.md

Sets up an MCP server with three registered tools: openpets_status, openpets_react, and openpets_say. Includes tool annotations and AI agent instructions.

```typescript
import {
  McpServer,
  StdioServerTransport,
  Tool,
  ToolAnnotation,
  ToolContext,
} from "@modelcontextprotocol/sdk";
import { z } from "zod";

import { acquireStartupLease } from "./lease";
import { openpets_react, openpets_say, openpets_status } from "./tools";

const saySchema = z.object({
  message: z.string(),
  petId: z.string().optional(),
});

const reactSchema = z.object({
  reaction: z.string(),
  petId: z.string().optional(),
});

const PET_ID_REGEX = /^[a-z0-9][a-z0-9_-]{0,63}$/;

export async function createOpenPetsMcpServer(args: {
  petId?: string;
}): Promise<McpServer> {
  const { petId: configuredPetId } = args;

  const lease = await acquireStartupLease();

  const tools: Tool[] = [
    {
      name: "openpets_status",
      description: "Check the status of the OpenPets desktop pet.",
      inputSchema: z.object({ petId: z.string().regex(PET_ID_REGEX).optional() }),
      outputSchema: z.any(), // TODO: Define a proper output schema
      annotations: {
        [ToolAnnotation.ReadOnly]: true,
        [ToolAnnotation.Idempotent]: true,
      },
      handler: async (ctx: ToolContext) => {
        return openpets_status(ctx, configuredPetId ?? ctx.petId);
      },
    },
    {
      name: "openpets_say",
      description: "Display a message on the OpenPets desktop pet.",
      inputSchema: saySchema,
      outputSchema: z.any(), // TODO: Define a proper output schema
      annotations: {
        [ToolAnnotation.ReadOnly]: false,
        [ToolAnnotation.Idempotent]: false,
      },
      handler: async (ctx: ToolContext) => {
        return openpets_say(ctx, saySchema.parse(ctx.input), {
          petId: configuredPetId ?? ctx.petId,
        });
      },
    },
    {
      name: "openpets_react",
      description: "Make the OpenPets desktop pet display a reaction.",
      inputSchema: reactSchema,
      outputSchema: z.any(), // TODO: Define a proper output schema
      annotations: {
        [ToolAnnotation.ReadOnly]: false,
        [ToolAnnotation.Idempotent]: false,
      },
      handler: async (ctx: ToolContext) => {
        return openpets_react(ctx, reactSchema.parse(ctx.input), {
          petId: configuredPetId ?? ctx.petId,
        });
      },
    },
  ];

  const server = new McpServer({
    tools,
    lease,
    // TODO: Add AI agent instructions here
    aiAgentInstructions: "You are a helpful assistant.",
  });

  return server;
}

```

--------------------------------

### Package Windows NSIS Installer (x64)

Source: https://github.com/alvinunreal/openpets/blob/main/docs/release.md

Manually package the Windows NSIS installer for x64 architecture using electron-builder.

```bash
pnpm --dir apps/desktop exec electron-builder --win nsis --x64 --publish never
```

--------------------------------

### Install and Run OpenPets CLI with npx

Source: https://github.com/alvinunreal/openpets/blob/main/skills/openpets/references/config-files.md

If the `openpets` CLI is not installed globally, use `npx` to run the command. This ensures you are using the latest version of the CLI.

```bash
npx -y @open-pets/cli@latest configure --agent opencode --pet <pet-id> --cwd <project-path> --yes
```

--------------------------------

### Direct Install Flow - Atomic Move

Source: https://github.com/alvinunreal/openpets/blob/main/packages/install-pet/codemap.md

Illustrates the atomic move operation to transfer the validated pet files from the temporary directory to the final installation location.

```bash
rename(tempDir, finalDir) → Atomic move
```

--------------------------------

### OpenCode Global Setup Management

Source: https://github.com/alvinunreal/openpets/blob/main/packages/opencode/codemap.md

Describes the process for managing global OpenCode setup, including cleanup operations, support for removal, and doctor command for status checking. It handles config precedence.

```typescript
// Similar to project setup but for ~/.config/opencode/
// Setup cleanup writes: Removes managed duplicate entries from other config files
// Remove support: prepareOpenCodeGlobalRemove() / writePreparedOpenCodeGlobalRemove() remove managed MCP, instruction, and plugin entries plus the managed instruction block
// Doctor command: doctorOpenCodeGlobalSetup() for status checking
// Config precedence handling: chooses the effective config file across config.json, opencode.json, and opencode.jsonc, preserving existing user arrays when safe

```

--------------------------------

### Direct Install Flow - Pet Download

Source: https://github.com/alvinunreal/openpets/blob/main/packages/install-pet/codemap.md

Details the process of downloading the pet's ZIP file from its URL, including initial validation.

```bash
downloadPetZip(zipUrl) → Stream to buffer, validate magic bytes
```

--------------------------------

### Install a Pet using npx

Source: https://github.com/alvinunreal/openpets/blob/main/skills/openpets/workflows/install-pet.md

If the OpenPets CLI is not installed globally, you can use npx to run the command. This ensures you are using the latest version of the CLI.

```bash
npx -y @open-pets/cli@latest install <pet-id>
```

--------------------------------

### Install OpenPets CLI

Source: https://github.com/alvinunreal/openpets/blob/main/skills/openpets/workflows/install-openpets.md

Install the global command-line interface for OpenPets. This command is used to manage and interact with the OpenPets application from your terminal.

```bash
npm install -g @open-pets/cli
```

--------------------------------

### Catalog Plugin Install/Update

Source: https://github.com/alvinunreal/openpets/blob/main/apps/desktop/src/codemap.md

Details the process for installing and updating plugins from the catalog, including validation and extraction.

```typescript
plugin-catalog.ts → plugin-catalog-validation.ts
└── plugin-package.ts downloads HTTPS ZIP, validates SHA-256, extracts root manifest only, and installs to userData/plugins/{id}
```

--------------------------------

### OpenCode Setup and Removal APIs

Source: https://github.com/alvinunreal/openpets/blob/main/packages/opencode/codemap.md

Lists the primary setup and removal API functions exported by the OpenCode package. These functions are used for managing project and global configurations.

```typescript
// Exports:
// plugin.ts - Default plugin export for OpenCode
// prepareOpenCodeProjectSetup(), writePreparedOpenCodeProjectSetup()
// prepareOpenCodeGlobalSetup(), writePreparedOpenCodeGlobalSetup()
// prepareOpenCodeGlobalRemove(), writePreparedOpenCodeGlobalRemove()
// Config management utilities

```

--------------------------------

### TCP/WSL Cross-Platform Flow Example

Source: https://github.com/alvinunreal/openpets/blob/main/packages/client/codemap.md

Details the communication path for a WSL client connecting to the Windows desktop app via TCP, highlighting discovery and connection steps.

```text
WSL Client → readDiscoveryFile()
    ↓
Endpoint: tcp://192.168.x.x:port (Windows host IP)
    ↓
validateDiscovery() → allowsCrossPlatformDiscovery()
    ↓
net.createConnection({ host, port }) → Windows desktop app
```

--------------------------------

### Write Plan Flow

Source: https://github.com/alvinunreal/openpets/blob/main/packages/cursor/src/codemap.md

Describes the flow for planning the installation of Cursor MCP configurations. It involves reading existing configurations, classifying status, validating installability, and preparing a write plan with backup and temporary paths.

```text
planCursorMcpInstall(path, options, allowReplace)
  → readCursorMcpConfig(path)
  → classifyCursorMcpStatus(result, path, options)
  → validate status allows install
  → build new entry
  → merge with existing config (preserve other servers)
  → buildWritePlan(path, JSON.stringify(newConfig))
    → assertSafeParentDirectory
    → assertSafeExistingConfigFile
    → generate unique backup path (if exists)
    → generate unique temp path
    → return { targetPath, backupPath?, tempPath, content }
```

--------------------------------

### Stage and Commit Release Changes

Source: https://github.com/alvinunreal/openpets/blob/main/docs/release.md

Add all relevant files, including package manifests and the lockfile, to the staging area and commit with a versioned message. This example stages files for a desktop-only release.

```bash
git add package.json apps/desktop/package.json packages/*/package.json pnpm-lock.yaml
git commit -m "release desktop v<version>"
git push
```

--------------------------------

### MCP Entry Format Example

Source: https://github.com/alvinunreal/openpets/blob/main/packages/cursor/codemap.md

Defines the structure for an MCP entry, specifying the command and arguments to execute.

```json
{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@open-pets/mcp@VERSION", "--pet", "PET_ID"]
}
```

--------------------------------

### IPC Protocol Flow Example

Source: https://github.com/alvinunreal/openpets/blob/main/packages/client/codemap.md

Illustrates the sequence of operations from a client method call to receiving a validated response, including discovery and request sending.

```text
Client Method Call
    ↓
readDiscoveryFile() → Parse ipc.json (token, endpoint)
    ↓
sendRequest() → Build request (id, version, token, method, params)
    ↓
net.createConnection(endpoint) → Write JSON + newline
    ↓
Wait for response (buffer until newline)
    ↓
parseIpcResponse() → Validate shape, return result or throw
```

--------------------------------

### Configure OpenPets as an MCP Server

Source: https://github.com/alvinunreal/openpets/blob/main/README.md

Add OpenPets as an MCP server to your agent's configuration to enable desktop companion control. This example uses stdio communication.

```json
{
  "mcpServers": {
    "openpets": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@open-pets/mcp@latest"]
    }
  }
}
```

--------------------------------

### Configure Project for Cursor Agent

Source: https://github.com/alvinunreal/openpets/blob/main/skills/openpets/workflows/configure-project.md

Command to configure the current project for the Cursor agent. Ensure the pet is installed and the project path is correct. The `--yes` flag bypasses confirmation prompts.

```bash
openpets configure --agent cursor --pet <pet-id> --cwd <project-path> --yes
```

--------------------------------

### OpenCode Project Setup Status Classification

Source: https://github.com/alvinunreal/openpets/blob/main/packages/opencode/codemap.md

Defines the possible statuses for OpenCode project setup, including not installed, installed, needs update, custom, conflict, and error. It also covers managed block detection.

```typescript
// Status classification: not_installed, installed, needs_update, custom, conflict, error
// Managed block detection in instruction files (<!-- OPENPETS:START/END -->)
// Config field updates: mcp, instructions, plugin arrays
// Instruction file: .opencode/openpets.md with usage guidelines

```

--------------------------------

### CLI Entry Point and Dependencies

Source: https://github.com/alvinunreal/openpets/blob/main/packages/codemap.md

Illustrates the main entry point for the CLI package and its dependencies on other internal packages.

```text
CLI Entry (packages/cli/src/index.ts)
    ├── Configures Claude → @open-pets/claude
    ├── Configures OpenCode → @open-pets/opencode
    ├── Configures Cursor → @open-pets/cursor
    ├── Spawns MCP server → @open-pets/mcp
    └── Uses IPC client → @open-pets/client
```

--------------------------------

### Launch with Live Plugins

Source: https://github.com/alvinunreal/openpets/blob/main/README.md

Launches the Electron application with live official plugins loaded and monitored.

```bash
pnpm dev:desktop:plugins
```

--------------------------------

### Direct Install Flow - Lock Release

Source: https://github.com/alvinunreal/openpets/blob/main/packages/install-pet/codemap.md

Details the final step of releasing the installation lock by removing the lock directory.

```bash
releaseLock() → rm lock directory
```

--------------------------------

### Upload Appx to R2

Source: https://github.com/alvinunreal/openpets/blob/main/docs/release.md

Use this command to upload your application package to the R2 object storage. Replace `<version>` with your actual application version.

```bash
bunx wrangler r2 object put \
  "openpets/releases/OpenPets-<version>-win-x64.appx" \
  --file "apps/desktop/dist-electron/OpenPets-<version>-win-x64.appx" \
  --remote
```

--------------------------------

### Create a Test Harness for Plugin Logic

Source: https://github.com/alvinunreal/openpets/blob/main/README.md

Utilize the `@open-pets/plugin-sdk/testing` module to create a test harness for deterministic plugin testing. Mock the host environment, manage time, and assert expected behaviors.

```javascript
import { createTestHarness } from "@open-pets/plugin-sdk/testing";
import { register } from "./index.js";

const h = createTestHarness(register, { permissions: ["pet:speak", "schedule"] });
await h.start();
h.expectScheduled("decay");
await h.clock.advance("30m");
h.expectSpoke(/need attention/i);
```

--------------------------------

### Plugin Initialization and Management

Source: https://github.com/alvinunreal/openpets/blob/main/apps/desktop/src/codemap.md

Details the process of initializing and managing plugins, including state, assets, and runtime.

```typescript
main.ts → initializePluginService(userData, defaultPluginPetApi, appVersion, ElectronPluginJsHost).start()
├── plugin-state.ts reads/writes userData/openpets-plugin-state.json
├── plugin-platform-settings.ts gates audio, voice, speech, mic, quiet hours, and AI provider choices
├── plugin-assets.ts validates/resolves declared plugin assets for SDK refs and rendered UI
├── plugin-user-sound-store.ts stores imported user sounds as plugin-scoped opaque refs
├── plugin-diagnostics.ts records plugin errors/quota/settings blocks for inspector/health UI
├── plugin-runtime.ts reloads enabled manifests
│   ├── declarative runtime schedules timer triggers
│   ├── plugin-js-host.ts starts hidden sandboxed BrowserWindow hosts for JavaScript plugins
│   └── plugin-sdk-bridge.ts dispatches namespaced SDK routes
│       ├── plugin-sdk-audio.ts/plugin-voice.ts → renderer/OS playback and speech surfaces
│       ├── plugin-sdk-bus.ts/plugin-sdk-events.ts → curated pub/sub and host event streams
│       ├── plugin-sdk-config.ts/plugin-sdk-storage.ts/plugin-sdk-state.ts → config, persistent plugin data, and subscriptions
│       ├── plugin-sdk-ui.ts/plugin-panels.ts/plugin-toast.ts → bubbles, alerts, commands, panels, and toasts
│       ├── plugin-oauth.ts/plugin-secrets.ts/plugin-ai-gateway.ts → host-mediated auth, encrypted secrets, and AI gateway
│       └── plugin-pet-api.ts/plugin-pet-registry.ts/default-pet-controller → default/spawned pet actions
├── plugin-service.ts orchestrates UI actions, permission confirmation, config validation, install/update/uninstall/load-local, and runtime reloads
└── lifecycle.ts → stopPluginService() on quit
```

--------------------------------

### Build Desktop Package

Source: https://github.com/alvinunreal/openpets/blob/main/docs/release.md

Manually build the desktop package for the specified platform and architecture without creating a GitHub Release.

```bash
pnpm --filter @open-pets/desktop build
```

--------------------------------

### Publish and Deploy Web Plugin Catalog

Source: https://github.com/alvinunreal/openpets/blob/main/docs/release.md

After validating and staging local catalog artifacts, use these commands to publish plugin ZIPs to R2, regenerate catalogs, and deploy the web application. Verify the live endpoints afterward.

```bash
pnpm plugins:publish
pnpm plugins:deploy
```

--------------------------------

### Package Desktop Application (Directory)

Source: https://github.com/alvinunreal/openpets/blob/main/README.md

Builds and packages the desktop application into a target OS directory.

```bash
# Build & package into target OS directory
pnpm package:desktop:dir
```

--------------------------------

### Build Windows x64 AppX Package

Source: https://github.com/alvinunreal/openpets/blob/main/docs/release.md

This command builds a Windows x64 AppX package using Electron Builder. Ensure you have the correct identity, publisher, and display name configured for Partner Center.

```bash
pnpm --filter @open-pets/desktop build
pnpm --filter @open-pets/desktop exec electron-builder --win appx --x64 \
  -c.appx.identityName=AlvinUnreal.OpenPetsDesktopCompanion \
  -c.appx.publisher=CN=5749BA4D-6A45-4111-8CAA-6B151AEDC238 \
  -c.appx.publisherDisplayName=AlvinUnreal \
  -c.appx.displayName="OpenPets: Desktop Companion" \
  -c.appx.applicationId=OpenPetsDesktopCompanion
```

--------------------------------

### Hook Settings Management

Source: https://github.com/alvinunreal/openpets/blob/main/packages/claude/codemap.md

Manages Claude hook settings, including event definitions, command configurations, and installation modes. Implements safety measures like backups and atomic renames, and tracks installation status.

```typescript
hook-settings.ts:
- Settings path: `~/.claude/settings.json`
- Hook events: `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `Notification`, `Stop`, `StopFailure`
- Command entry: `{ type: "command", command, timeout: 3, async: true, asyncRewake: false }`
- Marker: `--openpets-managed` in command for identification
- Install modes: `published` (npx), `local` (node path), `bundled` (asar unpacked)
- Safety: Backup before write, atomic rename, permission checks
- Status: `not_installed`, `installed`, `needs_update`, `error`
```

--------------------------------

### Pet Catalog URL

Source: https://github.com/alvinunreal/openpets/blob/main/skills/openpets/references/commands.md

The URL for the pet catalog, which contains metadata for installing pets.

```text
https://openpets.dev/pets/catalog.v3.json
```

--------------------------------

### Check Claude Version

Source: https://github.com/alvinunreal/openpets/blob/main/skills/openpets/workflows/verify-claude.md

Verify that the Claude CLI is installed and accessible by checking its version.

```bash
claude --version
```

--------------------------------

### Create and Publish GitHub Release

Source: https://github.com/alvinunreal/openpets/blob/main/docs/release.md

Run the release script with the --yes and --include-optional flags to create and publish the GitHub Release with optional artifacts.

```bash
pnpm release:desktop -- --yes --include-optional
```

--------------------------------

### Update Package Versions

Source: https://github.com/alvinunreal/openpets/blob/main/docs/release.md

Example of updating the version field in a package.json file for a full workspace/npm release.

```json
"version": "2.0.1"
```

--------------------------------

### CLI Command Flow: Plugin Scaffolding

Source: https://github.com/alvinunreal/openpets/blob/main/packages/cli/codemap.md

Describes the process for the 'plugin new' command, including template selection and file generation for new SDK v3 plugins.

```text
CLI command plugin new <name> [--template template] [--dir output]
    ↓
Normalizes plugin id/name and selects template
    ↓
Writes manifest, index.js, test.js, README, and optional locales/en.json
    ↓
Generated code targets @open-pets/plugin-sdk/testing for local verification
```

--------------------------------

### Run Build and Check Commands

Source: https://github.com/alvinunreal/openpets/blob/main/docs/release.md

Execute build and specific package checks before committing. Fix any reported failures.

```bash
pnpm build
pnpm --filter @open-pets/desktop check
```

--------------------------------

### List and Get OpenPets MCP Entry

Source: https://github.com/alvinunreal/openpets/blob/main/skills/openpets/workflows/verify-claude.md

Check the status and details of the OpenPets MCP entry to ensure it's registered.

```bash
claude mcp list
claude mcp get openpets
```

--------------------------------

### Verify Pet Status

Source: https://github.com/alvinunreal/openpets/blob/main/skills/openpets/workflows/install-pet.md

Optionally, use this command to check the status of installed pets. This can be useful for troubleshooting or confirming operational readiness.

```bash
openpets status
```

--------------------------------

### Run Desktop Release Script

Source: https://github.com/alvinunreal/openpets/blob/main/docs/release.md

Executes the desktop release script with the --yes flag to bypass interactive prompts. Use --include-optional to include additional artifacts.

```bash
pnpm release:desktop -- --yes
```

```bash
pnpm release:desktop -- --yes --include-optional
```

--------------------------------

### Use OpenPets CLI Command

Source: https://github.com/alvinunreal/openpets/blob/main/skills/openpets/SKILL.md

Execute commands using the globally installed 'openpets' CLI. Replace '<command>' with the desired operation.

```bash
openpets <command>
```

--------------------------------

### One-off Command Execution

Source: https://github.com/alvinunreal/openpets/blob/main/skills/openpets/references/commands.md

Executes OpenPets CLI commands without a global installation using npx for one-off or fallback scenarios.

```bash
npx -y @open-pets/cli@latest status
```

--------------------------------

### Cursor Status APIs

Source: https://github.com/alvinunreal/openpets/blob/main/packages/cursor/codemap.md

APIs for classifying MCP status, reading configuration files, and planning installation, replacement, or removal operations.

```APIDOC
## Cursor Status APIs

### Description
Functions for managing the status and lifecycle of MCP configurations. This includes reading configuration files, classifying their status, planning modifications, and executing writes atomically.

### Functions
- `classifyCursorMcpStatus(result, path, expected)`: Classify config status.
- `readCursorMcpConfig(path)`: Read and validate config file.
- `planCursorMcpInstall(path, options, allowReplace?)`: Plan install operation.
- `planCursorMcpReplace(path, options)`: Plan replace operation.
- `planCursorMcpRemove(path)`: Plan remove operation.
- `executeCursorMcpWrite(plan)`: Execute planned write atomically.
- `isManagedOpenPetsMcpEntry(value)`: Check if entry is OpenPets-managed.

### Constants
- `maxCursorConfigBytes`: 256 KiB limit constant.
```

--------------------------------

### CLI Command Flow: Configuration

Source: https://github.com/alvinunreal/openpets/blob/main/packages/cli/codemap.md

Illustrates the data and control flow for CLI commands related to configuration, emphasizing safe path enforcement and atomic updates.

```text
CLI command input (e.g. openpets configure --agent claude)
    ↓
resolveProjectDir() → Enforce safe paths
    ↓
Check editor tool presence (e.g., claude CLI or Cursor settings)
    ↓
Acquire active pet selection/lease via IPC
    ↓
Perform atomic update of config files & local hooks
```

--------------------------------

### Direct Install Flow - ZIP Extraction

Source: https://github.com/alvinunreal/openpets/blob/main/packages/install-pet/codemap.md

Describes the extraction of the downloaded pet ZIP file into a temporary directory using yauzl.

```bash
extractPetZip(buffer, tempDir) → yauzl streaming extract
```

--------------------------------

### Package Linux AppImage (x64)

Source: https://github.com/alvinunreal/openpets/blob/main/docs/release.md

Manually package the Linux AppImage for x64 architecture using electron-builder.

```bash
pnpm --dir apps/desktop exec electron-builder --linux AppImage --x64 --publish never
```

--------------------------------

### Get Open Pets User Data Path Function

Source: https://github.com/alvinunreal/openpets/blob/main/packages/install-pet/codemap.md

A utility function to resolve the platform-specific user data directory for OpenPets.

```javascript
getOpenPetsUserDataPath()
```