docs: document pi-assistant prompt file management

Add a Pi Assistant section to both AGENTS.md and CONTRIBUTING.md
explaining:
- the prompt lives in .github/prompts/pi-assistant.md, not in the YAML
- the {{dot.notation.path}} placeholder syntax (context.* and env.*)
- when an explicit env: entry is needed vs available automatically
- how to add new placeholders if required

Author: mcowger

AGENTS.md

@@ -145,6 +145,36 @@ Several services are singletons (e.g., `OAuthAuthManager`, `CooldownManager`, `D
 
 ---
 
+## Pi Assistant (AI Agent Workflow)
+
+The `/pi` trigger in issue and PR comments is handled by `.github/workflows/pi-assistant.yml`,
+which invokes `mcowger/pi-coding-agent-action`.
+
+### Prompt file
+
+The agent's system prompt lives at **`.github/prompts/pi-assistant.md`** — edit that file
+to change what the agent is instructed to do. Do not put prompt text inside the workflow YAML.
+
+The prompt file supports `{{dot.notation.path}}` placeholders resolved at runtime against
+two namespaces:
+
+| Namespace | Contents | Example |
+|-----------|----------|---------|
+| `context.*` | The full `@actions/github` context — event payload, actor, SHA, ref, repo, etc. | `{{context.payload.comment.body}}` |
+| `env.*` | All environment variables, including `GITHUB_*` / `RUNNER_*` runner vars and any values passed via the step's `env:` block | `{{env.INITIAL_COMMENT_ID}}` |
+
+Most GitHub context data is available automatically via `context.*`. The only value
+currently passed explicitly via `env:` is `INITIAL_COMMENT_ID`, because it is derived
+from a previous workflow step output and is not part of the event payload.
+
+### Workflow env: block
+
+If a new placeholder is needed that cannot be sourced from `context.*`, add it to the
+`env:` block on the **Run Pi agent** step in `pi-assistant.yml` and reference it as
+`{{env.YOUR_VAR_NAME}}` in the prompt file. Do not add it to any other step.
+
+---
+
 ## Frontend
 
 ### Tailwind CSS v4

CONTRIBUTING.md

@@ -49,6 +49,24 @@ The project uses separate Drizzle ORM config files for each database dialect:
 
 When running Drizzle Kit commands, specify the appropriate config file with `--config`.
 
+## Pi Assistant Prompt
+
+The system prompt for the `/pi` AI agent lives at **`.github/prompts/pi-assistant.md`**.
+Edit that file directly — do not put prompt text inside the workflow YAML.
+
+The file supports `{{dot.notation.path}}` placeholders that are substituted at runtime:
+
+- `{{context.payload.comment.body}}` — the triggering comment's text
+- `{{context.payload.issue.number}}` — issue/PR number
+- `{{context.actor}}` — the GitHub actor who triggered the run
+- `{{env.GITHUB_SHA}}` — any `GITHUB_*` / `RUNNER_*` runner environment variable
+- `{{env.INITIAL_COMMENT_ID}}` — a value passed explicitly via the step's `env:` block
+
+Anything reachable from the [`@actions/github` context object](https://github.com/actions/toolkit/tree/main/packages/github)
+is available under `context.*` without any extra wiring. Values that come from
+previous step outputs (like `INITIAL_COMMENT_ID`) must be added to the `env:` block
+on the **Run Pi agent** step in `.github/workflows/pi-assistant.yml`.
+
 ## Code Style
 
 All code must be formatted with Biome before committing: