# Native packages and resources Read for acquiring, configuring, updating or removing existing Pi resources, or preparing package authoring/publication. This is guidance for native Pi operations, not a Workbench installer or version service. ## 1. Inspect and recommend Identify the actual source, relevant files, dependencies/install hooks, required credentials/network/filesystem effects, reuse rights and personal/project scope. Use [curated starting points](sources.md), then inspect the selected primary source. A gallery listing, familiar author or `pi -e` trial is not a sandbox or approval. Recommend one concrete source/scope/action and explain the useful outcome and material effects. Carry an existing matching grant forward; ask only for missing authorization. Installation, source edits, trust/settings changes, reload/activation and publication remain distinct action classes. **Done when** the customer can decide the actual operation without mistaking a recommendation for completed work. ## 2. Use Pi for an authorized operation Use the installed host's native package/CLI contract directly. Typical documented routes are `pi install ` (personal), `--local` for project scope, `pi list` for configured packages, `pi config` for resource selection and `pi remove ` for removal. Confirm the real target/options from installed docs before execution. Pi supports managed npm/Git sources and inspected local sources. Local packages are loaded without copying; their source/dependencies remain author-owned. Relative settings paths resolve from their containing settings location; CLI paths resolve from invocation cwd. Project declarations require native project trust. A temporary `pi -e ` may still acquire and execute code. Resource filters only narrow what a package declares. A missing resource filter permits the package's resources, `[]` permits none; exact/glob inclusion/exclusion follows native settings. Project declarations normally replace the corresponding personal package entry; `autoload: false` supplies a filtering delta. Pi owns identity/deduplication, discovery and activation. For an update, target the selected package with the native operation. In the reviewed CLI, `pi update ` targets one package; `--extensions` targets packages, bare `pi update` updates Pi, and `--all` includes both. Check the actual host rather than applying this as a timeless command recipe. Prefer ordinary advancing sources; preserve deliberate existing pins until their owner decides. External version resolution, pin/range semantics and updates belong entirely to Pi: no Workbench checks, compatibility database or background updater. **Done when** the authorized native operation has completed and its actual exit/result has been evaluated. A printed command or accepted prompt is not completion; on failure inspect the current result before retrying. ## 3. Verify and return the usable result Inspect configured source/scope, native diagnostics and the intended discovery/loading state. Perform only authorized runtime/reload/model checks. Report what is installed/configured versus merely proposed, exact usable source/path, checks and limitations, and one next action if needed. Source review, package acquisition, resource discovery and working model behavior are different evidence. **Done when** the customer can use the result or knows the precise missing grant/check. No automatic reload, credential use or publication follows from installation guidance. ## Package authoring and publication For a real authoring task, inspect the actual manifest and imports first. For a new executable project, use the [Extension handoff](extensions.md#4-deliver-a-usable-handoff); the receiver owns implementation. - Native Markdown slashprompt authoring/arguments/discovery → [direct authoring](pi-authoring.md#4-author-the-selected-native-artifact); `pi.prompts` selects package-root-relative prompt files, including nested files through explicit paths/globs. Conventional prompt directories load direct `.md` children only. No implicit template conversion or activation. - Use needed conventional directories or explicit package-root-relative `pi.extensions`, `pi.skills`, `pi.prompts`, `pi.themes`. Arrays support native globs/exclusions; explicitly name dot-prefixed/symlinked resource roots when needed. Ordinary guides are supporting files, not another native resource type. - Native resource selection and npm shipment are separate. Include every referenced guide/script/asset through actual `files`/ignore rules and inspect the real package file list. An optional `pi-package` keyword permits gallery discovery, not publication. - Imported third-party runtime libraries belong in `dependencies`; build/test-only tooling in `devDependencies`. Only actually imported host packages belong in `peerDependencies: "*"`, unbundled. Do not ship a second Pi host copy or rely on undeclared imports from another package root. A dependent Pi package must actually ship and have its resources explicitly referenced. - Inspect lifecycle scripts before package checks. Use an authorized, explicitly assembled byte-verified isolated copy for packaging checks; ignore scripts when the check requires none. Verify resources from another cwd, native diagnostics and relevant behavior. File-list success is not installation or E2E. - Prepare release evidence for the exact candidate/artifact and destination: package name/registry/access/dist-tag or Git target/ref, version decision, `private`/publish configuration, license/reuse rights, shipped assets/dependencies/scripts, actual checks and unresolved risks. A release version and required lockfile are not by themselves an external-update policy. **Done when** the exact package/release proposal is reviewable with actual evidence and outstanding grants. Stop before publishing, tagging, main/release pushes or other publication effects without immediate approval for that exact target/action. ## Native sources Reviewed installed Pi 1.3.0 public `docs/packages.md`, `docs/cli.md`, `docs/settings.md`, `docs/configuration.md` and official online documentation on 2026-10-21. These label source review, not pins or proof about another installed host. - [Packages](https://pi.dev/docs/latest/packages) - [Command line](https://pi.dev/docs/latest/cli) - [Settings](https://pi.dev/docs/latest/settings) Read the current host's relevant complete documentation for a concrete gap; native Pi remains the owner.