npm package: @peteturnbull/pi-extensions
Description: A pi extension pack with a local task board TUI and a deterministic docs-store with qmd-powered search.
Latest version: 1.0.6

# @peteturnbull/pi-extensions

A `pi` extension pack that includes:

- A **TUI task board** backed by `.pi/task-board/tasks.json`
- A **deterministic docs-store** backed by `.pi/docs-store/` with qmd-powered search

## Features

### Task board

- Ticket tools: `create_ticket`, `update_ticket`, `list_tickets`, `list_ready_tickets`, `get_ticket`
- `/task-board` command launches the terminal UI
- Ready/active/blocked/all workflow views
- Keyboard-first ticket inspect + status transitions + progress + notes
- Feature tags (`feature:<slug>`) for feature-isolated planning/filtering
- JSON persistence with dependency-aware readiness and blocked-state reasoning

### Docs-store

**Why this exists**

When agents only use ad-hoc files, knowledge gets fragmented and hard to recover.
Docs-store gives agents a single, structured memory surface with two goals:

1. **Deterministic writes**
   - Agents write via typed tools, not arbitrary file paths.
   - This reduces random file dumping and keeps stored knowledge consistent.

2. **High-quality retrieval**
   - Stored docs are indexed for qmd search (`query`/`search`/`vsearch`).
   - Agents can reliably find prior decisions, notes, and context by meaning or keywords.

In short: docs-store is for durable project memory that stays organized and searchable as runs accumulate.

- Deterministic write/read tools (no arbitrary write paths in tool inputs)
- Tools: `docs_store_put`, `docs_store_get`, `docs_store_list`, `docs_store_search`, `docs_store_delete`, `docs_store_status`, `docs_store_set_base_dir`, `docs_store_refresh`
- `/docs-store` helper command (`help`, `status`, `where`, `set-dir`, `use-default`, `refresh`, `refresh-embed`)
- Configurable base directory (default: `<project>/.pi/docs-store`)
- Markdown documents persisted under `<base-dir>/docs/*.md`
- qmd integration (`query`/`search`/`vsearch`) on a project-scoped qmd index

## Install

```bash
# global
pi install npm:@peteturnbull/pi-extensions

# project-local
pi install -l npm:@peteturnbull/pi-extensions
```

## Usage

### Task board

```bash
/task-board
/task-board <feature>
/task-board help
```

- `/task-board` opens the board with tickets from all features.
- `/task-board <feature>` opens a feature-scoped board (tickets where `ticket.feature === <feature>`).

#### TUI keys

- List: `↑/↓`, `Enter`, `1..4`, `/`, `Esc`
- Detail: `s` (start), `b` (block), `c` (complete), `p` (progress), `n` (note), `Esc`

### Docs-store

```bash
/docs-store
/docs-store status
/docs-store where
/docs-store set-dir ../shared/docs-store
/docs-store use-default
/docs-store refresh
/docs-store refresh-embed
```

Docs-store data location defaults to:

```text
<project>/.pi/docs-store/
  docs/      # managed markdown docs
  index.json # metadata index
```

Override options (highest precedence first):

1. Environment variable: `PI_DOCS_STORE_DIR`
2. Config file: `<project>/.pi/docs-store.config.json` (set by `/docs-store set-dir` or `docs_store_set_base_dir`)
3. Default: `<project>/.pi/docs-store`

### qmd requirement

Docs-store search uses the `qmd` CLI. Install globally:

```bash
npm install -g @tobilu/qmd
```

### Docs-store smoke test

Run the integration smoke flow (`set-base-dir -> put -> list -> get -> search -> delete -> use-default`):

```bash
# Runs search only if qmd is available
npm run smoke:docs-store

# Enforce qmd availability (fails if qmd is missing)
npm run smoke:docs-store:qmd
```

## Task board data file

```text
<project>/.pi/task-board/tasks.json
```

## Seed task board demo data

```bash
node .pi/scripts/seed-task-board.mjs --force
```

---

## Publishing to npm

### One-time setup

1. Ensure you have an npm account and are logged in:
   ```bash
   npm login
   npm whoami
   ```

2. Confirm package name availability (first publish only):
   ```bash
   npm view @peteturnbull/pi-extensions name
   ```
   - If this returns `E404`, the name is available.
   - If it exists and you do not own it, choose a new package name in `package.json`.

3. Confirm access rights if package already exists:
   ```bash
   npm access ls-packages $(npm whoami)
   ```

### Preflight checks

```bash
npm run preflight
npm run pack:dry
```

### Release script workflow (recommended)

This repo includes `scripts/release.sh`, which handles:
- clean working tree check
- preflight + `npm pack --dry-run`
- version bump
- changelog section rollover
- release commit + git tag
- optional push + npm publish

#### Prepare release only (no publish)

```bash
npm run release
# or: npm run release:patch | release:minor | release:major
```

#### Release + publish in one command

```bash
npm run release:publish:patch
# or: release:publish:minor | release:publish:major
```

#### Dry-run publish (safe test)

```bash
npm run release:publish:dry-run
```

### Manual fallback

```bash
# after release commit + tag exists
git push && git push --tags
npm publish --access public
```

---

## Package layout

```text
extensions/
  task-board.ts
  docs-store.ts
  docs-store-paths.ts
test/
  docs-store-paths.test.ts
  smoke/
    mock-loader.mjs
    register-loader.mjs
    shims/
      pi-ai.mjs
      typebox.mjs
      pi-coding-agent.mjs
CHANGELOG.md
README.md
package.json
scripts/
  preflight.mjs
  release.sh
  smoke-docs-store.mjs
```