# Kujo Pi onboarding guide

Kujo Pi adds optional Kujo tools to [Pi](https://pi.dev/). It gives Pi a local-first way to inspect repositories, prepare agent context, review changes, run guarded checks, and connect to Kujo services when you choose to configure them.

It does not replace Pi, start background daemons, or contact a service during startup. Runtime installation is an explicit, approved setup action.

## Is it usable today?

Yes. Kujo Pi 1.0 is the stable line within its documented client-integration boundary. Stable releases are published on npm with provenance and matching GitHub release evidence.

Kujo Pi is a thin integration layer. It is not a guarantee that every Kujo component is installed, configured, or compatible with every organization. Use `kujo_doctor` to inspect the current environment.

## What it adds to Pi

| Tool | What it helps with | Default behavior |
|---|---|---|
| `kujo_tools` | Discover and enable Kujo integrations | Active |
| `kujo_doctor` | Check the CLI, optional binaries, entrypoints, versions, and service configuration | Active; read-only |
| `kujo_status` | Confirm that the Kujo CLI is available | Active; read-only |
| `kujo_check` | Validate a Kujo source file | Active; read-only |
| `kujo_scout` | Map a repository's structure, dependencies, routes, and risks | Opt-in |
| `kujo_scent` | Build a scoped, provenance-aware context pack for an agent task | Opt-in; dry-run |
| `kujo_review_changes` | Create a PatchBrief handoff for current changes | Opt-in |
| `kujo_changebucket` | Measure change size, risk, and blast radius | Opt-in |
| `kujo_shipcheck` | Run release-readiness checks | Opt-in; approval required |
| `kujo_mcp_make` | Generate a guarded, repository-specific MCP server | Opt-in; approval required |
| `kujo_dispatch_run` | Run a resumable Dispatch workflow | Opt-in; approval required |
| `kujo_agents_smoke` | Run deterministic Agents SDK examples | Opt-in; approval required |
| `kujo_runledger` | Start or finish a local execution receipt | Opt-in |
| `kujo_watchdog` | Read configured Watchdog telemetry | Opt-in; URL required |
| `kujo_leash_approval` | Send an explicit approval event to Leash | Opt-in; approval and token required |
| `kujo_rag_query` | Query a local Kujo RAG index with citations | Opt-in |
| `kujo_ability_list` | Discover principal-visible Kujo Abilities | Opt-in; URL required |
| `kujo_ability_call` | Run a canonical Ability and retain its receipt | Opt-in; approval required |

Optional tools stay inactive until you enable them. Pi must also report the open project as trusted before Kujo Pi enables or runs repository-scoped tools. This keeps normal sessions quiet and prevents installation alone from creating side effects.

### Use Kujo Ability

Configure the application gateway that owns the Ability handlers and policy:

```bash
export KUJO_ABILITY_GATEWAY_URL=http://127.0.0.1:8080
export KUJO_ABILITY_GATEWAY_TOKEN='use-a-least-privilege-token'
```

Then enable the Extend pack or the two Ability tools directly. Discovery returns only the tools authorized for the token. Execution always passes through Pi approval and then the gateway's independent authorization, approval, idempotency, and audit controls.

```text
/kujo enable kujo_ability_list kujo_ability_call
```

## Install

### Recommended: stable npm release

Install the published release:

```bash
pi install npm:@kujolang/kujo-pi
```

The package currently requires Node.js 22.19 or newer.

### Alternative: pinned project-local Git install

Run this from the repository where you use Pi:

```bash
pi install -l git:github.com/kujolang/kujo-pi@<full-commit-sha>
```

The `-l` flag keeps the package in the project's `.pi/settings.json`, which makes the installation visible and repeatable for a team.

You can install globally instead:

```bash
pi install git:github.com/kujolang/kujo-pi@<full-commit-sha>
```

## Released toolchain setup

No contributor checkout is needed. In a trusted Git repository with a change:

```text
/kujo setup review
/kujo setup plan review
/kujo setup install review
/kujo demo
```

The read-only summary reports available, missing, mismatched and unsupported integrations. The preview includes exact versions, archive/provenance identities, commands, write locations and network destinations. Interactive installation displays that plan for confirmation. Denial makes no changes. The demo measures your real working-tree change using ChangeBucket, without an API key or model call.

Setup installs Kujo runtime 1.8.1, Kennel 1.1.1, and the signed pack versions under `~/.local/share/kujo-pi`. Set an absolute `KUJO_PI_HOME` to choose another dedicated directory; paths with spaces are supported. Avoid symlinks and directories writable by other users. Setup uses the released npm runtime and Kennel tool lifecycle; it does not require the broader contributor installer profile.

| Pack | Released tools installed | Additional configuration |
|---|---|---|
| understand | Scout, Scent | Repository to inspect |
| review | PatchBrief, ChangeBucket | Git repository with changes |
| ship | ShipCheck, RunLedger | Project check configuration |
| orchestrate | Dispatch, Agents SDK | Dispatch provider credentials, or explicit `DISPATCH_OFFLINE_FIXTURE=true`; existing bounded adapters |
| extend | MCP, RAG | RAG index/provider; Ability gateway configured separately |
| observe | None | Explicit Watchdog/Leash URLs and credentials |

Tool installation is separate from activation: `/kujo enable <pack>` enables its Pi tools. Installing Extend does not create a RAG index or authorize a gateway. Installing Observe never starts services.

The Pi extension supports macOS/Linux/Windows. Managed Kennel installation supports macOS/Linux; use WSL on Windows. This platform limit is shown before installation, and does not prevent the core extension from loading. Explicit binary/entrypoint overrides remain available for supported custom installations.

For headless setup, run the packaged executable in the environment inherited by Pi:

```bash
npx --package=@kujolang/kujo-pi kujo-pi-setup plan review
# Review the JSON, then copy its digest into the following command:
npx --package=@kujolang/kujo-pi kujo-pi-setup apply review --approve-plan <digest>
```

The digest binds the pack, versions, destinations and commands. Changes require a fresh preview and approval. Nothing installs at startup or merely by asking for the plan. npm and Kennel use their normal package caches; the private toolchain and setup receipt live under `KUJO_PI_HOME`. Network access is needed for an approved installation, including pinned tool dependencies.

Discovery precedence is explicit `*_BIN`, explicit `*_ENTRY`, private Kennel installation, PATH command, then checksum-verified ecosystem checkout. Runtime precedence is `KUJO_BIN`, the managed runtime, then PATH. Explicit overrides are user trust decisions, not verified release identities. Managed discovery verifies Kennel's recorded archive/provenance identity and the signed entrypoint checksum; it is not a continuous hash audit of every installed dependency.

### Upgrade, rollback and removal

Upgrade Kujo Pi through Pi's package manager, preview the new pack plan, then approve it. Before upgrading a working private toolchain, copy its dedicated `KUJO_PI_HOME` directory as a backup. To roll back, stop Pi and setup processes, restore that backup at its original absolute path, and reinstall the matching Kujo Pi version. Kennel records absolute module paths, so moving a backup alone is insufficient. To remove managed tools, stop their processes and remove only the dedicated toolchain directory after reviewing its path. Pi settings, unrelated commands and shell profiles are unaffected.

Failed setup leaves completed steps available for inspection and retry; it is not an atomic multi-package transaction. A concurrent installer is rejected by `.setup.lock`. After an interrupted process, confirm that its recorded PID is no longer running before removing that lock. Review any `.installer.download` or `.setup-receipt.tmp` file before cleanup. Do not delete another live installer's state.

First useful result within five minutes is a product target, not a measured human-onboarding guarantee. `npm run test:consumer` checks clean installation, normal peer resolution and a real packaged Pi workflow; it explicitly downloads released tools.

## Existing installations

You can continue using a separately installed Kujo CLI:

```bash
kujo --version
```

If the binary is elsewhere, configure it for the Pi process:

```bash
export KUJO_BIN="$HOME/src/kujo/target/release/kujo"
```

If you have a standard Kujo ecosystem checkout, configure its root once. Doctor verifies the packaged registry signature and checksums canonical entrypoints before using them:

```bash
export KUJO_ECOSYSTEM_ROOT="$HOME/src/kujo-repos"
```

Kujo Pi can also call ecosystem entrypoints directly through environment variables. Entrypoints must be absolute existing file paths; the extension does not execute repository-local fallback names. A typical local checkout looks like this:

```bash
export KUJO_SCOUT_ENTRY="$HOME/src/scout/scout.kujo"
export KUJO_SCENT_ENTRY="$HOME/src/scent/scent.kujo"
export KUJO_MCP_ENTRY="$HOME/src/mcp/mcp.kujo"
export KUJO_DISPATCH_ENTRY="$HOME/src/dispatch/dispatch.kujo"
export KUJO_AGENTS_SMOKE_ENTRY="$HOME/src/agents-sdk/examples/examples_smoke_runner.kujo"
export KUJO_RAG_ENTRY="$HOME/src/rag/main.kujo"
```

If you use standalone commands instead, set the relevant `*_BIN` variables listed in the [configuration reference](#configuration).

## First five minutes

1. Start Pi in the repository you want to work on.
2. Confirm that Pi marks the project as trusted.
3. Run the setup summary:

   ```text
   /kujo setup
   ```

   It verifies the signed registry, reports available local integrations, and gives one next action. Use `kujo_doctor` when you need the full diagnostic record and per-dependency remediations:

   ```text
   Use kujo_doctor to check my Kujo Pi setup.
   ```

   Doctor returns one copy-ready remediation for every missing dependency and reports the signed-registry and checksum state.

4. Inspect the task-oriented packs:

   ```text
   /kujo packs
   ```

   Run `/kujo active` at any time to see which optional integrations are active in the current session.

5. Enable only what you need:

   ```text
   Enable the understand pack.
   ```

   You can also use the slash command:

   ```text
   /kujo enable understand
   ```

6. Ask Pi to work with the enabled tools:

   ```text
   Use Kujo Scout to understand this repository, then use Kujo Scent to prepare context for fixing the authentication bug.
   ```

To create a visible project marker for Kujo artifacts, run:

```text
/kujo init
```

This creates only `.kujo/pi/README.md` and does not overwrite an existing file.

## Useful workflows

### Understand an unfamiliar repository

Enable Scout, then ask Pi for an evidence-based map:

```text
/kujo enable kujo_scout
Use Kujo Scout to map this repository. Focus on the runtime entrypoints, external services, and test commands.
```

Scout writes the report according to its own configuration. Review generated files before committing them.

### Prepare focused agent context

Scent is useful when a repository is too large or noisy to place in one prompt:

```text
/kujo enable kujo_scent
Prepare a dry-run Kujo Scent pack for implementing the cache invalidation task.
```

The tool scopes context and reports provenance and redaction metadata. It does not modify the project by default.

### Review a change before asking for implementation

```text
/kujo enable kujo_review_changes kujo_changebucket
Review the current changes with PatchBrief, then report the change footprint and blast radius.
```

This is useful for handoffs, pull-request preparation, and deciding whether a change is small enough to ship safely.

### Run release checks

ShipCheck can execute project checks and therefore requires explicit approval:

```text
/kujo enable kujo_shipcheck
Run Kujo ShipCheck for this repository after I approve the operation.
```

Treat the result as release evidence, not as a replacement for human review or organization-specific controls.

### Generate a repository-specific MCP server

```text
/kujo enable kujo_mcp_make
Generate the guarded MCP server for this repository and show me the files before anything is committed.
```

MCP generation is approval-gated and remains governed by the canonical Kujo MCP repository.

### Run a Dispatch workflow

```text
/kujo enable kujo_dispatch_run
Run the Dispatch workflow for producing a dependency-upgrade report, but wait for my approval before execution.
```

Dispatch writes resumable workflow state and artifacts. Use a project-local output directory and review the resulting files.

### Query a local RAG index

```text
/kujo enable kujo_rag_query
Query the local Kujo RAG index: where is the retry policy defined? Include citations.
```

RAG availability depends on an index and the configured Kujo RAG entrypoint.

## Configuration

Set these variables in the environment inherited by Pi. Do not put secrets in `.pi/settings.json`, project files, or shell history.

| Variable | Purpose |
|---|---|
| `KUJO_BIN` | Explicit Kujo runtime; otherwise private runtime, then PATH |
| `KUJO_PI_HOME` | Absolute dedicated managed toolchain directory |
| `KUJO_ECOSYSTEM_ROOT` | Discover and verify canonical entrypoints through the signed registry |
| `KUJO_SCOUT_BIN` / `KUJO_SCOUT_ENTRY` | Scout executable or `.kujo` entrypoint |
| `KUJO_SCENT_BIN` / `KUJO_SCENT_ENTRY` | Scent executable or `.kujo` entrypoint |
| `KUJO_PATCHBRIEF_BIN` | PatchBrief executable; default `patchbrief` |
| `KUJO_CHANGEBUCKET_BIN` | ChangeBucket executable; default `changebucket` |
| `KUJO_SHIPCHECK_BIN` | ShipCheck executable; default `shipcheck` |
| `KUJO_MCP_ENTRY` | Required absolute MCP entrypoint |
| `KUJO_DISPATCH_ENTRY` | Required absolute Dispatch entrypoint |
| `KUJO_AGENTS_SMOKE_ENTRY` | Required absolute Agents SDK fixture runner |
| `KUJO_RAG_ENTRY` | Required absolute RAG entrypoint |
| `KUJO_RUNLEDGER_BIN` | RunLedger executable; default `runledger` |
| `KUJO_PI_MIN_KUJO_VERSION` | Optional minimum Kujo version checked by Doctor |
| `KUJO_PI_RECEIPTS` | Set to `1` to record redacted session receipts |

### Optional Watchdog and Leash services

The `KUJO_WATCHDOG_URL` setting enables Kujo Pi's read-only Watchdog tool; it
does not reroute Pi's model provider. To capture Pi model traffic in Watchdog,
configure a Watchdog-backed Pi provider as described in
[the Watchdog proxy guide](watchdog-pi-proxy.md).

For local services:

```bash
export KUJO_WATCHDOG_URL=http://127.0.0.1:4318
export KUJO_LEASH_URL=http://127.0.0.1:4319
export KUJO_LEASH_TOKEN='local-token-from-your-secret-manager'
```

For remote services, use HTTPS and configure the service audience:

```bash
export KUJO_WATCHDOG_URL=https://watchdog.example.internal
export KUJO_WATCHDOG_TOKEN='read-from-your-secret-manager'
export KUJO_WATCHDOG_AUDIENCE=kujo-watchdog
export KUJO_LEASH_URL=https://leash.example.internal
export KUJO_LEASH_TOKEN='read-from-your-secret-manager'
export KUJO_LEASH_AUDIENCE=kujo-leash
```

These integrations are disabled until their URLs are configured. The extension rejects remote HTTP, does not follow redirects, bounds response bodies, and never contacts a service during startup.

## Safety and trust model

- Read-only tools can inspect the current workspace, but they do not grant Pi or Kujo permissions.
- Every subprocess, network call, and project write requires a project Pi reports as trusted.
- Side-effecting tools are opt-in. ShipCheck, MCP generation, Dispatch, Agents SDK runs, and Leash delivery also require approval. Interactive sessions always show Pi's approval UI.
- Workflow entrypoints are explicit absolute files; missing or relative entrypoint configuration fails closed.
- Workspace paths are checked for lexical escapes and existing symlink escapes before they are passed to a command.
- Commands use argument arrays with shell execution disabled.
- Subprocess output and service responses are bounded before they reach the model.
- Network attempts retain a per-attempt timeout even when the caller provides a cancellation signal.
- Receipts are off by default and contain operation metadata, not credentials or raw output.
- Pi extensions run with the user's system permissions. Review the source and your project trust settings before installing any extension.

Kujo Pi does not provide tenant isolation, certificate pinning, service authorization, or a second permission system. Keep those controls at the Pi host, Kujo runtime, service, and organization layers.

## Troubleshooting

### `kujo_doctor` reports a missing dependency

Use the `remediations` returned by Doctor. Run `kujo --version`, confirm the binary is on `PATH`, set `KUJO_BIN` to its absolute path, or configure `KUJO_ECOSYSTEM_ROOT`. For an individual integration, set the matching entrypoint or standalone binary variable.

See the [signed registry contract](integration-registry.md), [versioned result and receipt contracts](contracts.md), and [capability examples](capability-examples.md).

### An optional tool is not available to Pi

Enable it for the current session:

```text
/kujo enable kujo_scout
```

Optional tools are inactive in a new session. Once enabled, their activation is stored in that Pi session and restored after reload or session-tree navigation. Use `/kujo disable <tool|pack>` to turn them off persistently for the session.

### A service check fails

Confirm the URL, protocol, token, and audience. Local HTTP is allowed only for loopback addresses. Remote services must use HTTPS. See [service profiles](service-profiles.md).

### You want to test the package itself

From a checkout of Kujo Pi:

```bash
npm install
npm test
npm audit --omit=dev --audit-level=high
```

The opt-in live smoke check requires an installed Kujo CLI:

```bash
KUJO_PI_LIVE=1 npm run test:live
```

To exercise the local ecosystem adapter matrix, also set `KUJO_PI_ECOSYSTEM_ROOT` to the directory containing the Kujo repositories.

## Where to go next

- Read the [Kujo Pi README](../README.md) for the complete capability and environment reference.
- Read the [service profiles](service-profiles.md) before connecting Watchdog or Leash.
- Read the [compatibility policy](compatibility.md), [v1 migration guide](migration-v1.md), and [support policy](support.md) before adopting the stable 1.x line.
- Read the [v1 release standard](v1-roadmap.md) for the stable compatibility and safety guarantees.
- Browse the canonical Kujo repositories linked in the README when you need runtime-specific documentation.