Pi Wizard

Independent Pi package for the backend-backed Wizard catalog.

Relationship to other plugin packages

• plugins/pi-wizard is an independent Pi package with its own runtime implementation.
• It does not declare a runtime dependency on, import from, or delegate to the OpenCode plugin package.
• The packages can be released independently.

Install

npm install @aexol/pi-wizard

For local development from this repository:

npm --prefix plugins/pi-wizard install
npm --prefix plugins/pi-wizard run build

Release

@aexol/pi-wizard is released separately and does not require another Wizard plugin package at runtime.

Run the package release check before tagging:

npm run pi-wizard:release:check

Use tag format pi-wizard-v<version> and the GitLab manual publish pi wizard job for npm publication.

The package metadata declares Pi extension resources through:

{
  "pi": {
    "extensions": ["./dist/extensions"]
  }
}

Tools

The extension registers Pi-native tool names that call backend auth/workspace/catalog/preference APIs directly:

• wizard_status
• wizard_catalog_fetch
• wizard_artifact_fetch
• wizard_artifact_preference_set
• wizard_published_skills_fetch
• wizard_published_skill_preference_set
• wizard_report_issue

Catalog/status metadata is discovery-only; fetch artifact or skill bodies before treating Wizard instructions as authoritative.

Use wizard_report_issue for authenticated Wizard BUG/FEATURE reports. Required args are reportType (BUG or FEATURE), title, and description; optional safe fields include severity/priority, reproduction steps, expected/actual behavior, impact, labels, related tool, directory override, and a repo-relative path. The tool sends source: PI, safe workspace/repository/directory context, and bounded metadata only; it does not capture transcripts, prompts, env, secrets, tokens, raw logs, or unbounded local absolute paths.

Auth and config

The Pi runtime resolves backend settings and auth directly, without importing or delegating to another Wizard package:

• backend origin default https://opencode-wizard.aexol.work
• PI_WIZARD_BACKEND_ORIGIN override
• OPENCODE_WIZARD_BACKEND_ORIGIN override
• GraphQL /graphql endpoint
• optional PI_WIZARD_SESSION_TOKEN
• optional PI_WIZARD_AUTH_STATE_PATH, defaulting to ~/.config/pi-wizard/config.json
• browser OAuth bootstrap through the same backend session endpoint used by the OpenCode package
• workspace resolution from directory/git metadata

Auth behavior mirrors the OpenCode package without importing it: when auth is missing or rejected, wizard_status and catalog startup paths start a localhost browser login on http://localhost:24953/oauth/callback, exchange the OAuth code for a backend plugin session, and store it in ~/.config/pi-wizard/config.json (or PI_WIZARD_AUTH_STATE_PATH) under { "auth": { ... } }. Tools expose login state and browser URL, never tokens.

Stored auth uses this Pi-owned shape:

{
  "auth": {
    "pluginId": "pi-wizard",
    "sessionToken": "<redacted>",
    "expiresAt": "2026-05-20T00:00:00.000Z",
    "authenticatedAt": "2026-05-20T00:00:00.000Z",
    "userId": "user-id",
    "email": "user@example.com",
    "role": "EDITOR"
  }
}

If backend access is missing after auth bootstrap, tools return request_failed or related operational state instead of a fake local catalog.

Prompt context

On Pi before_agent_start, the extension fetches the backend SKILL catalog when auth is available and appends a Pi Wizard system note listing available skills plus Pi-native fetch rules.

If auth is missing, startup context triggers the same Pi-owned browser bootstrap as wizard_status and includes degraded guidance plus the login URL when available; no hardcoded degraded catalog is injected.