# Repository Guidelines

## Project Overview

`wow-pi` is a Bun + TypeScript pi extension package that ports selected `wow-omp` features to original pi. It provides two runtime modules: Markdown context injection and environment variable injection.

## Architecture & Data Flow

- Root `package.json` declares a private workspace and pi extension entry at `packages/wow-pi/src/index.ts`.
- `packages/wow-pi/src/index.ts` imports `wow-contexts` and `wow-inject` for side-effect module registration, then calls each registered module with pi's `ExtensionAPI`.
- `packages/wow-core` owns shared infrastructure: config loading, module registry, logger, UI rendering, path utilities, and `${protocol:value}` reference resolution.
- `packages/wow-contexts` registers `/wow:contexts:list`, `/wow:contexts:reload`, `/wow:init`, then injects configured Markdown files into `before_agent_start` system prompts.
- `packages/wow-inject` loads `.env` files and `inject.env` values during setup and `session_start`, writing resolved values into `process.env`.

## Key Directories

- `packages/wow-pi/`: pi extension entry package and bundled `dist/` output.
- `packages/wow-core/`: shared config, registry, logger, UI, utilities, and ref resolver.
- `packages/wow-contexts/`: context scanning/building, command handlers, and init prompt.
- `packages/wow-inject/`: `.env` parser and environment injection module.
- `scripts/`: build and install/uninstall orchestration scripts.
- `docs/contexts/`: subsystem reference cards loaded by wow contexts.

## Development Commands

- `bun install`: install workspace dependencies.
- `bun run check`: run TypeScript type checking with `tsc --noEmit`.
- `bun run build`: debug bundle for `packages/wow-pi` using Bun with `--target node`.
- `bun run build:release`: minified release bundle.
- `bun run script:install`: debug build and copy `packages/wow-pi/dist` to `~/.pi/agent/extensions/wow-pi`.
- `bun run script:install:release`: release build and install with `WOW_RELEASE=1`.
- `bun run script:uninstall`: remove installed `~/.pi/agent/extensions/wow-pi`.
- `pi -e /path/to/wow-pi`: load this extension once from source for manual testing.

## Code Conventions & Common Patterns

- Use TypeScript ESM with strict type checking and Bun runtime types.
- Keep feature modules self-registering: import side effects call `registerModule({ name, register })`.
- Keep shared behavior in `wow-core`; feature packages should depend on `wow-core`, not each other.
- Use `getWowSettingSync(key, cwd)` for module config and call `resetWowConfigCache()` when config should be re-read.
- Use `registerWowCommand(pi, name, options)` so commands are namespaced as `/wow:<name>`.
- Use `showInfo`, `showWarn`, or `show` for command UI notifications.
- Avoid relying on source changes after install; installed pi code comes from copied `packages/wow-pi/dist`.

## Important Files

- `package.json`: workspace scripts, pi manifest, peer dependencies.
- `packages/wow-pi/src/index.ts`: extension bootstrap and module registration loop.
- `packages/wow-core/src/config.ts`: JSON/YAML config loading and merge rules.
- `packages/wow-core/src/registry.ts`: module registration contract.
- `packages/wow-contexts/src/index.ts`: `before_agent_start` context injection.
- `packages/wow-contexts/src/commands.ts`: `/wow:*` command handlers.
- `packages/wow-contexts/src/init-prompt.ts`: `/wow:init` prompt template.
- `packages/wow-inject/src/env.ts`: environment injection flow.
- `scripts/build.ts`: debug/release build orchestrator.
- `scripts/install.ts`: hard-copy install/uninstall logic.
- `wow.example.yaml`: example global/project wow configuration.

## Runtime/Tooling Preferences

- Use Bun for package management, scripts, and bundling.
- Build bundles with `--target node`; pi loads extensions through Node/Jiti, and `--target bun` can emit `import.meta.require`, which fails under pi.
- Externalize pi host packages in the bundle: `@earendil-works/pi-coding-agent`, `@earendil-works/pi-ai`, `@earendil-works/pi-tui`, and `typebox`.
- Config files are `~/.pi/agent/wow.{json,yaml,yml}` and `<project>/.pi/wow.{json,yaml,yml}`; project config extends global config.
- Logs write to `~/.pi/agent/wow/logs/wow.YYYY-MM-DD.log` with best-effort rotation.
- `pi-subagents` may be installed in the user environment; `/wow:init` explicitly asks for read-only scout/context-builder fanout when available.

## Testing & QA

- There are no unit tests or test framework dependencies currently.
- `bun run check` is the primary validation command and only runs TypeScript.
- Build validation should include `bun run build` and `bun run build:release` when touching bundling or dependencies.
- Install validation should include `bun run script:install` and a pi smoke command such as `PI_CODING_AGENT_DIR="$HOME/.pi/agent" pi --help`.
- For extension behavior, manually verify `/wow:contexts:list`, `/wow:contexts:reload`, and `/wow:init` in pi.

## Module Contexts (`docs/contexts/`)

- `docs/contexts/wow-pi.md`: extension entry and module orchestration.
- `docs/contexts/wow-core.md`: shared config, registry, logger, UI, and utilities.
- `docs/contexts/wow-contexts.md`: Markdown context scanning, injection, and commands.
- `docs/contexts/wow-inject.md`: `.env` loading and ref-based environment injection.
- `docs/contexts/build-and-install.md`: bundle, install, release, and validation flow.