# Package structure and compatibility

## Identity

- npm name: `@prjct.app/pi-activity`.
- Initial version: `0.1.0`.
- Source repository: [prjct-app/pi-activity](https://github.com/prjct-app/pi-activity).
- Tested host: Pi `0.85.1`; Node.js `22.19+`.

The npm name and repository name may differ. Repository URLs remain unchanged. Existing runtime command names, event names, persisted entry types, and settings keys are unchanged by the package rename.

## Resource manifest

```json
{
  "name": "@prjct.app/pi-activity",
  "keywords": [
    "pi-package"
  ],
  "pi": {
    "extensions": [
      "./index.ts"
    ]
  }
}
```

The `pi-package` keyword makes the package discoverable. Manifest paths are relative to the package root. The extension entry point is shipped as TypeScript because Pi loads it directly. There is no CLI binary or JavaScript build artifact to install separately.

## Dependencies

Pi-provided libraries imported by this package are declared in `peerDependencies` with `*`, as required by Pi's package guide. They are not bundled. Exact Pi 0.85.1 development dependencies establish the tested baseline; the peer wildcard is not a claim that every Pi release is supported.

Third-party runtime dependencies belong in `dependencies`. Companion extensions are installed separately only when communication uses Pi's event bus; this package does not import code from a separately installed companion. A package that directly imports another Pi package's resources must instead bundle it following the official guide.

## Public interfaces

Uses documented `registerTool()` overrides and render contexts, `registerEntryRenderer()`, `registerCommand()`, lifecycle and tool-execution events, keybinding hints, syntax highlighting, diff rendering, working messages, composable status text, temporary widgets, `ctx.ui.custom()`, and `SettingsList`. The extension deliberately leaves Pi's default working indicator unchanged.

Activity summaries and density preferences use custom session entries. They do not enter model context and are reconstructed from the active session branch after resume or tree navigation. Terminal-only calls are guarded by `ctx.mode === "tui"`.

## Published contents

The `files` allowlist includes the TypeScript entry point, its `src/` runtime modules, user documentation, and license files. Development tests, dependency folders, repository settings, and Git history are excluded. npm also includes `package.json` automatically. The npm lockfile remains in the repository for repeatable development installs.

Run `npm run check:package` to inspect the exact prospective tarball before release. Check that each manifest entry and each referenced local document exists in the packed file list. Only claim npm availability after verifying a successful registry publication.

## Official references

These links are pinned to the tested Pi version rather than the moving main branch:

- [Packages: manifest, sources, dependencies, filtering, and deduplication](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/packages.md).
- [Extensions: lifecycle, commands, tools, messages, and UI APIs](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/extensions.md).
- [TUI: components, rendering, terminal widths, and image support](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/tui.md).

The installed `@earendil-works/pi-coding-agent@0.85.1` package ships the same guides under `docs/`. The [current official guide](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md) may describe changes beyond this tested baseline.

## Discovery metadata

The `pi-package` keyword identifies this package for the official Pi gallery. Focused keywords describe its actual features. The `pi.image` field points to its public cover, following the [official gallery metadata format](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/packages.md#gallery-metadata).