# 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 | A separately verified patch-capable diff backend; see below |

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_PATCH_EXECUTABLE` | Separate default backend for `cm patch` |
| `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"
$env:PI_PLASTIC_PATCH_EXECUTABLE = "C:/Tools/Git/usr/bin/diff.exe"
pi
```

These are fictional paths, not executable-discovery recommendations.

## Diff and patch backends

Text comparison and patch generation have different compatibility requirements. The package does not silently switch backends or retry with another executable.

| Environment | Text comparison | Patch generation |
|---|---|---|
| Windows | Configure a compatible text diff explicitly if needed | Set `toolPath` for one call or `PI_PLASTIC_PATCH_EXECUTABLE`, for example a verified Git `diff.exe`; text/GnuWin32 configuration is not reused as the patch default |
| macOS | Apple BSD `/usr/bin/diff` has text-only evidence; PATH may instead resolve GNU diff | Tested Apple BSD diff rejects CM 11's `--binary` argument; configure a verified GNU Diffutils-compatible backend |
| Other non-Windows environments | Resolve PATH `diff` or the explicit text override | The text override/PATH fallback is usable only when that executable accepts the local CM patch arguments |

Patch precedence: one-call `toolPath`, then `PI_PLASTIC_PATCH_EXECUTABLE`, then the allowed non-Windows fallback. Windows requires explicit patch configuration.

Interactive Pi sessions issue one path-redacted capability warning per runtime for missing Windows patch configuration or an invalid configured override. The tool still validates configuration at call time. Fix configuration before a **new deliberate attempt**; after an uncertain applying operation, inspect state first.

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).