# pi-dynamic-help

Dynamic `/help` dashboard for [Pi](https://pi.dev). It summarizes loaded slash commands, tools, MCP servers, and installed Pi packages, then shows them in a concise TUI markdown panel.

## Install

```bash
pi install npm:pi-dynamic-help
```

Local development install:

```bash
pi install /absolute/path/to/pi-dynamic-help
```

Temporary test run without adding it to settings:

```bash
pi -e /absolute/path/to/pi-dynamic-help
```

After installing, run `/reload` or restart Pi if the command is not visible immediately.

## Commands

- `/help` — open the dynamic help dashboard.
- `/help refresh` — refresh the resource index and persist state.
- `/help search <term>` — filter the dashboard by a term.
- `/help pin <term>` — pin the best matching resource.
- `/help unpin <term>` — unpin the best matching resource.

## What it indexes

- Slash commands registered by Pi, packages, prompt templates, and extensions.
- Active tools exposed to the agent.
- MCP gateway and configured MCP servers.
- Packages listed in user and project Pi settings.

The dashboard keeps command/tool/package/MCP sections separate so the resource type is clear.

## Usage counters

Usage counters currently focus on tools and MCP calls, based on Pi session/tool-result data that is available to the extension. Commands are ranked by pinning and known metadata unless Pi exposes reliable command-usage data in the future.

## State and migration

Runtime metadata is stored under the user's Pi agent state directory:

```text
~/.pi/agent/state/pi-dynamic-help/state.json
```

The old local-extension state file, if present, is read as a migration source:

```text
~/.pi/agent/state/dynamic-help.json
```

State uses stable identities for resources. Command identities normalize `/help` and `help` to the same item, and this package's own local/npm/git/node_modules sources normalize to `pkg:pi-dynamic-help`, preserving `/help` pins and usage across install-source changes.

If the current state file is corrupt, it is moved aside as:

```text
~/.pi/agent/state/pi-dynamic-help/state.corrupt-<timestamp>.json
```

Then the extension starts from legacy state or an empty state. State save failures show a warning but should not prevent `/help` from rendering.

Runtime state is not part of the npm package and should not be committed or published.

## Privacy and safety

This extension reads local Pi settings and MCP configuration files to build the dashboard. It does not upload this information. Like all Pi extensions, it runs locally with the permissions of your Pi process, so install only from sources you trust.

## Development

```bash
npm install
npm run check
npm run test
npm run pack:dry
```

Tests are hermetic and use temporary directories for state-store coverage; they should not write to your real `~/.pi/agent/state`.

Useful local smoke test:

```bash
npm pack
TMP_AGENT_DIR=$(mktemp -d /tmp/pi-dynamic-help-agent-XXXXXX)
PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi install ./pi-dynamic-help-0.2.0.tgz
PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi --no-session -p "/help"
PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi --no-session -p "/help refresh"
PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi --no-session -p "/help search mcp"
PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi --no-session -p "/help pin bash"
PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi --no-session -p "/help unpin bash"
```

## Troubleshooting

- `/help` does not appear: run `/reload` or restart Pi.
- State looks stale: run `/help refresh`.
- A pin targets the wrong resource: use a more specific search term with `/help pin <term>` or undo it with `/help unpin <term>`.
- Installed package is not shown: confirm it is listed in `~/.pi/agent/settings.json` or project `.pi/settings.json`, then run `/help refresh`.
- State corruption warning appears: inspect the generated `state.corrupt-*.json` backup and continue using `/help`; the extension will create a fresh state file.