Glossary

This page defines the terms PiG documentation uses. Each term has its definition, where you meet it, and the page that explains it. The definitions come from docs/project/CONTEXT.md. Edit that file, then run make generate.

Pi

Pi is the upstream TypeScript project at https://github.com/earendil-works/pi. Pi is the reference implementation for parity-bound behavior.

Where you meet it: The upstream project. Docs for Pi behavior that PiG keeps cite it.

PiG

PiG is the Go implementation in this repository. The executable is pig. PiG follows the exact Pi build pinned in .upstream/pin (a release tag, or a pinned commit).

Where you meet it: The pig executable and every page of this documentation.

Stock PiG

Stock PiG is the product-neutral binary built from this repository. It contains Pi-compatible behavior, generic extension and Piglet infrastructure, and the reference documentation required to use those APIs. It activates no optional product Resource and no implicit Piglet composition.

Where you meet it: The plain pig binary you install. It activates no Piglet by itself.

Resource

A Resource contributes one extension, skill, prompt, hook, MCP definition, theme, compatible agent declaration, context input, or agent environment.

Where you meet it: pig piglet show lists the Resources a Piglet selects. Packages carry them.

Package

A Package distributes a versioned collection of Resources. Installing a Package makes its Resources available through normal discovery. A Package does not own or activate a Piglet.

Where you meet it: pig install and pig list.

Plugin

A Plugin packages capabilities for more than one compatible agent harness through an Agent Plugin or another supported vendor format.

Where you meet it: A package for other agent harnesses that PiG can read.

Piglet

A Piglet defines one named agent. It selects and scopes Resources and declares defaults and environment requirements.

Where you meet it: pig piglet commands and the --piglet flag.

Piglet release

A Piglet release pins the exact Resource closure and executable component plan for a Piglet.

Where you meet it: The record a Piglet build writes. pig piglet verify checks it.

Piglet Binary

A Piglet Binary is a target-native PiG executable built for one immutable Piglet composition. It can contain fused Go extensions and prebuilt Go or Rust extension cells. External services, configuration, secrets, and interpreted runtimes remain external requirements unless the release states otherwise.

Where you meet it: pig piglet build --format binary writes one.

Piglet Image

A Piglet Image is the planned OCI materialization of a Piglet and its runtime environment. It is not in this release. No PiG command produces one, and pig piglet build --format image fails.

Where you meet it: Planned. pig piglet build --format image fails today.

PiG Standard

PiG Standard is the optional curated Piglet at piglets/standard/pig-standard.yaml. It is not Stock PiG. A user must select or build it explicitly. A Package can distribute its Resources but cannot own or activate the Piglet.

Where you meet it: The curated Piglet that ships in piglets/standard/. You select it.

Pig Porter

Pig Porter is the local interactive and headless workbench for upstream-first parity work. It is a Piglet Resource in this repository. It does not define PiG product behavior.

Where you meet it: A maintainer workbench in piglets/porter/. You do not need it to use PiG.

Divergence

A divergence is an intentional user-visible or interoperability difference from the pinned Pi behavior. docs/parity/DIVERGENCES.md records each approved divergence. Language mechanics and implementation details that do not change observable behavior are not divergences.

Where you meet it: The "Differs from Pi" boxes and the numbered D entries.

Evidence

Evidence is a reproducible artifact that supports a project claim. Scanner output is evidence input. It is not a validated inventory, license conclusion, vulnerability disposition, or compliance approval by itself.

Where you meet it: The quality and release records of the repository. A user does not need it.

Transcript

A Transcript is normalized, ordered model context. It carries typed system, user, assistant, and tool-result entries in their original order.

Where you meet it: The context PiG sends to a model, in the Session file and in the Go SDK.

Provider

A Provider consumes a normalized Transcript and produces one Event Stream.

Where you meet it: The model service behind a model name.

Event Stream

An Event Stream yields ordered model events and one terminal assistant result. The caller context owns cancellation.

Where you meet it: The ordered events a Provider returns. This is not the JSON mode event stream, which is the CLI output.

Model Runtime

A Model Runtime owns mode-independent model lookup, authentication, completion, and streaming. TUI, print, JSON, and RPC use the same Model Runtime.

Where you meet it: The one model path that the TUI, print, JSON and RPC modes share.

Main Screen

The Main Screen renders transcript and active input into the visible terminal region. Ordinary input changes update only the required visible rows and preserve terminal scrollback unless Pi requires a recovery redraw.

Where you meet it: The terminal area that shows the conversation. Scrollback stays intact.

Extension Host

The Extension Host realizes extension Resources as isolated, packed, or fused components. External components retain their own declared protocol and lifecycle.

Where you meet it: The process model behind extensions: isolated, packed, or fused.

PiG Documentation