# Setup

[Documentation index](README.md) · [Next: tools and loading](2026-10-06-tools-and-loading.md)

## Requirements

| Component | Requirement |
|---|---|
| Node.js | 22.19.0 or newer |
| Pi | Latest stable release; older versions are not the supported baseline |
| Plastic CLI | Authenticated `cm` on PATH, or `PI_PLASTIC_CM_EXECUTABLE` set to its full executable path |
| Workspace | Configured Plastic workspace for workspace-scoped tools; server merge has a separate workspace-free contract |
| Text comparison | A compatible non-GUI GNU/POSIX `diff` |
| Patch generation | CM 11.0.16.10616 native git-diff generation; no external backend |

The package does not install or authenticate Plastic for you. Authenticate using your own authorized account, and inspect the workspace you intend to operate on.

## Choose an installation source

### Published npm release

```bash
pi install npm:@aefree/pi-plastic
```

This is the published package, which can lag Git main. Install at user scope when sessions and child processes in arbitrary workspaces need the Bash guards.

### Git main or a pinned release

```bash
# Track the moving default branch, including unreleased work:
pi install https://github.com/aefreedman/pi-plastic

# Pin an existing release tag:
pi install git:github.com/aefreedman/pi-plastic@v0.8.0

# Equivalent SSH source:
pi install git:git@github.com/aefreedman/pi-plastic@v0.8.0
```

A pinned Git tag/commit does not move to main when updated. Review third-party source before installing: extensions execute with host permissions.

### Local checkout or project settings

```bash
pi install ./path-to-pi-plastic
pi install -l ./path-to-pi-plastic
```

Local sources load from their path without copying. Install checkout dependencies yourself; see [development](2026-10-06-development.md#checkout-setup). Relative local paths resolve from the settings file containing them.

`-l` writes project settings. Project packages are subject to Pi's project-trust rules. A project-local install protects only processes loading that project's settings, not children launched into other workspaces.

## Update and reload

Use `pi list` to inspect configured sources. `pi update --extensions` reconciles installed packages; `pi update <source>` updates one source. Plain `pi update` updates Pi itself, not just this package.

Restart existing Pi processes after installation or source changes. For resource edits during development, Pi provides `/reload`; source files are not automatically watched. See [loading modes](2026-10-06-tools-and-loading.md#loading-modes) when an installed tool is inactive rather than missing.

## Executable configuration

Set environment variables before starting Pi. Full executable paths may contain spaces; the package invokes the resolved executable as-is and does not discover Git Bash paths automatically.

| Variable | Purpose |
|---|---|
| `PI_PLASTIC_CM_EXECUTABLE` | Override `cm` |
| `PI_PLASTIC_DIFF_EXECUTABLE` | Backend for text-only comparisons |
| `PI_PLASTIC_TOOL_LOADING_MODE` | `balanced`, `loader-only`, or `all-active` |
| `TEMP` / `TMP` | Writable ASCII-safe temporary location when the diff backend cannot accept Unicode paths |

For example, in PowerShell, using a **verified local executable**:

```powershell
$env:PI_PLASTIC_CM_EXECUTABLE = "C:/Tools/Plastic/cm.exe"
$env:PI_PLASTIC_DIFF_EXECUTABLE = "C:/Tools/Diff/diff.exe"
pi
```

These are fictional paths, not executable-discovery recommendations.

## Diff and patch backends

Text comparison still uses a compatible external text `diff` (PATH `diff` or `PI_PLASTIC_DIFF_EXECUTABLE`). Windows may require explicit configuration; macOS Apple BSD `/usr/bin/diff` has text-only evidence.

Patch generation uses CM 11.0.16.10616 native git-diff output on all platforms. It requires no external diff executable, patch environment variable, per-call `toolPath`, or startup capability probe. CM `--tool` configures patch application only; application is not exposed by this package. `includeBinaries=true` requests raw byte hunks; by default changed binaries are listed only. Older clients are not a supported fallback.

See [diffs and patches](2026-10-06-diffs-and-patches.md) for comparison scopes, publication, cleanup, and bounds.

## Optional file discovery

`@aefree/pi-file-discovery` is an independently loaded optional integration, not a bundled runtime requirement. Without it, Plastic tools and the skill still work; no discovery filter registry is created. See [integration behavior](2026-10-06-integrations.md#file-discovery-filter).