@agimon-ai/po-help
Activation-gated package guidance and help skills for Po and Pi extensions.
Package details
Install @agimon-ai/po-help from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@agimon-ai/po-help- Package
@agimon-ai/po-help- Version
0.0.0-alpha.183- Published
- Nov 22, 2026
- Downloads
- 31.1K/mo · 5,006/wk
- Author
- agiflow-ai
- License
- BUSL-1.1
- Types
- extension, skill
- Size
- 842.4 KB
- Dependencies
- 6 dependencies · 4 peers
Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
@agimon-ai/po-help
Activation-gated package guidance and read-only diagnostics for Po agent setup and debugging.
Part of the Po distribution.
Alpha: Help contribution contracts may change between releases.
Requirements and installation
Requires Node.js 24 or newer and the Pi version declared in this package's peer dependencies. The distribution selects Help through default.packages in presets.yaml; it remains configurable rather than fixed host infrastructure.
Activate and diagnose
Use the mode menu, /mode help, or /po-help. Help is additive: unrelated tools, skills, and modes retain their existing activation and permission rules.
The mode detail reports applied skills and diagnostics, distinguishing pending discovery and degraded contributors from usable contributions.
| Capability | Owner | Purpose |
|---|---|---|
help_status |
Help | Applied Help skills/tools, owners, availability, and bounded diagnostic codes. |
diagnose_setup |
Distribution | Saved configuration, installed packages, and sync drift for the current workspace. |
diagnose_agent |
Log | Bounded current-session captured failure and token-usage evidence. |
Optional owners contribute only when present in the composition. The entry skill help-how-to-help routes to configuration, profile, mode, domain, skill, and debugging guidance rather than loading every document eagerly. Deactivating Help withdraws it from future discovery.
Diagnostics do not install packages, change configuration, authenticate servers, clear logs, or restart processes. Existing approval and permission boundaries apply to repairs. Empty or unavailable telemetry is not proof of health.
Deactivation withdraws Help-only capabilities and rejects stale references. It cancels supported in-flight work, but cannot undo completed effects or remove earlier guidance from conversation history.
Package-owned contributions
Use named routes under src/extensions/workspaces/sessions/(backend)/resource/ and tool/. Root files own shared state and lifecycle. Do not create a second tool registry inside Help or add executable callbacks to the documentation descriptor.
Human starter guides
The session help.guides typed data slot supplies human-readable starter guides on web and native. Help, Artifacts, Calendar, Goal, and Author each own two README-grounded guides. These are independent of Help-only agent skills and diagnostic tools; contributing guidance does not activate a mode or grant permissions.
Contribute a shared plain-data module under the owning fill's _lib/, then thin fill/<Label>.help.guides.web.ts and .native.ts routes using each platform's defineFill. Set slot: 'help.guides', a stable fill id, deterministic order, and data. No dependency on the optional Help package is needed: locally check the structural data with satisfies. Builds regenerate routed entries; never edit generated entries by hand.
The v1 data shape is { version: 1, label, guides }. Each guide has a stable id, question, plain-text answer, and optional keywords and numeric order. Labels and IDs are at most 80 characters, questions 240, answers 4,000, with at most 64 guides and 16 keywords of at most 64 characters each. Keep IDs unique within a set and all text nonempty. Invalid sets are rejected as a whole. Answers do not render Markdown or executable callbacks.
Keep wording grounded in the owning README and preserve approved question, answer, keyword, and ordering changes in contract tests. Runtime modules must never import story fixtures. The approved fixtures are test and story evidence only.
Skills
For the server, declare a normal skill resource with HELP_WHEN, a useful description, and path: packageResourcePath(import.meta.url, 'src/prompts/<name>/SKILL.md'). Its reader returns the same file. Validate required content and report unavailable resources rather than registering empty successful guidance. Keep package documents lazy; eager context is only for small live activation instructions.
Publish llms.txt and src/prompts in the package files allowlist. Relative links must remain inside the published package. Normal runtime skills retain their ordinary activation rules; content-only domain plugin schemas are not changed by this feature.
Tools
import { PO_HELP_WHEN as HELP_WHEN } from '@agimon-ai/po-core/help';
Contributor packages import the shared contract from Core, not the optional Help package, so the distribution does not acquire an unconditional mode dependency.
A server tool uses when: HELP_WHEN, remains owned by its normal server plugin, and checks the active host and Help selection at execution boundaries. Domain conditions can be combined with Help when both are required. Help does not bypass other restrictions.
The Log package's diagnose_agent routes are a first-party example. Provider replacement, late arrival, withdrawal, cancellation, and package shutdown must preserve owner cleanup. Adding Help never grants filesystem, shell, network, or remote MCP access.
Status data
The Help service binds the skill consumer's accepted inventory instead of assuming every resolved descriptor reaches the model. Server status reads the host's applied capability metadata. Neither status API exposes executable declarations, credentials, raw logs, or skill bodies.
Verification
pnpm nx run @agimon-ai/po-help:test
pnpm nx run @agimon-ai/po-help:typecheck
pnpm nx run @agimon-ai/po-help:lint
Tests cover contribution withdrawal and rollback, the real headless prompt and tool surface, explicit skill reading, deactivation, and remote MCP exclusion. Packed-install checks must also verify resource paths outside the checkout before release.
License
Business Source License 1.1: free for personal use, organisations under USD 1M revenue, non-profits and education. See LICENSE and https://agimon.ai/licensing.