@aliou/pi-dev-kit 0.6.4 → 0.7.0

package/src/skills/pi-extension/references/structure.md

@@ -1,54 +1,59 @@
 # Extension Structure
 
-This covers the standalone repository structure for a Pi extension. This is the recommended layout for new extensions.
+This is the recommended standalone repository layout for Pi extension packages.
 
 ## Directory Layout
 
 ```
 my-extension/
   src/
-    index.ts              # Entry point (default export)
-    config.ts             # Config schema (types) + loader + defaults
-    client.ts             # API client (if wrapping a third-party API)
+    config.ts
+    client.ts              # API/domain client, no Pi imports when possible
+    manager.ts             # Core/domain logic, no Pi imports when possible
     tools/
-      my-tool.ts          # One file per tool (simple tool)
-      my-multi-tool/      # Multi-action tool
-        index.ts           # Tool registration + renderCall/renderResult
-        actions/           # One file per action
-          create.ts
-          list.ts
-          show.ts
-        render.ts          # Separate render module (when rendering is complex)
-        types.ts           # Serialized types for tool details
+      index.ts             # Tool entry point, default export registers tools
+      actions/             # Optional action modules for multi-action tools
+      render.ts            # Optional complex rendering
+      types.ts             # Optional tool params/details types
     commands/
-      my-command.ts        # One file per command
-    components/
-      my-renderer.ts       # Shared TUI components
+      index.ts             # Command entry point
+      components/          # Command-specific TUI components
+    hooks/
+      index.ts             # Event hook entry point
     providers/
-      index.ts             # Provider registration
-      models.ts            # Model definitions
-    utils/                 # Internal helpers (matching, parsing, etc.)
-      my-helper.ts
+      index.ts             # Provider entry point
+      models.ts
+    components/            # Shared TUI components only when genuinely shared
+    utils/                 # Parsing, matching, migrations, small helpers
   package.json
   tsconfig.json
-  biome.json               # Linting/formatting
-  shell.nix                # Nix dev environment
-  .changeset/
-    config.json            # Changeset config for versioning
+  biome.json
+  shell.nix
+  .changeset/config.json
   README.md
 ```
 
-Not every extension needs every directory. A simple extension with one tool might only have `src/index.ts` and `src/tools/my-tool.ts`.
+Not every extension needs every directory. A one-tool extension can be `src/tools/index.ts` plus `src/config.ts`.
+
+## Organization Rules
+
+- Each feature directory is its own Pi entry point: `tools/index.ts`, `commands/index.ts`, `hooks/index.ts`, `providers/index.ts`.
+- List those entry points directly in `package.json` `pi.extensions`.
+- Avoid a root `src/index.ts` that imports and registers everything in new code.
+- Keep `config.ts` at the root and shared by entry points.
+- Keep config types in `config.ts`, not `types.ts`.
+- Put domain logic in Pi-free modules such as `client.ts` and `manager.ts`; tools and commands should be thin wrappers.
+- Components are support modules, not Pi entry points.
+- Multi-action tools get a directory under `tools/`.
+- Use `utils/` for generic helpers that are not tools, commands, hooks, providers, or components.
+
+## Package Namespace
 
-### Organization principles
+Pi core packages are migrating from `@mariozechner/*` to `@earendil-works/*`.
 
-- **`index.ts` and `config.ts`** stay at root. These are the two core files every non-trivial extension has.
-- **Tools, commands, components, providers, hooks** each get their own directory. One file per tool/command/component.
-- **Config types live in `config.ts`**, not a separate `types.ts` or `config-schema.ts`. The config file exports both the types (raw and resolved) and the config loader instance.
-- **Utility/helper files** go in `utils/`. This includes pattern matching, shell parsing, event helpers, migrations, etc. Anything that is not a tool, command, component, provider, or hook.
-- **No separate `types.ts`** unless the extension has shared types unrelated to config (rare). Config types are the most common shared types, and they belong in `config.ts`.
-- **Multi-action tools** get their own directory under `tools/`. The tool registration + rendering lives in `index.ts`, each action gets its own file in `actions/`, and complex rendering logic goes in `render.ts`. Serialized types for tool details go in `types.ts`.
-- **Core/domain logic** lives in dedicated modules at the `src/` root (`client.ts`, `manager.ts`). These contain the business logic, are testable without the Pi framework, and don't import from `@mariozechner/pi-coding-agent`. Tools are thin wrappers that call these modules and format results.
+- Use `@earendil-works/*` once the target packages are published.
+- Keep `@mariozechner/*` for projects that still target a legacy Pi package namespace.
+- Do not mix namespaces unless you are intentionally doing a staged migration.
 
 ## package.json
 
@@ -70,35 +75,40 @@ Not every extension needs every directory. A simple extension with one tool migh
   },
   "files": ["src", "README.md"],
   "pi": {
-    "extensions": ["./src/index.ts"],
+    "extensions": [
+      "./src/tools/index.ts",
+      "./src/commands/index.ts",
+      "./src/hooks/index.ts",
+      "./src/providers/index.ts"
+    ],
     "skills": ["./skills"],
     "themes": ["./themes"],
     "prompts": ["./prompts"],
     "video": "https://example.com/demo.mp4"
   },
+  "dependencies": {},
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": ">=CURRENT_VERSION",
-    "@mariozechner/pi-ai": ">=CURRENT_VERSION",
-    "@mariozechner/pi-tui": ">=CURRENT_VERSION",
-    "@sinclair/typebox": ">=0.34.0"
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
   },
   "peerDependenciesMeta": {
-    "@mariozechner/pi-coding-agent": { "optional": true },
-    "@mariozechner/pi-ai": { "optional": true },
-    "@mariozechner/pi-tui": { "optional": true },
-    "@sinclair/typebox": { "optional": true }
+    "@earendil-works/pi-coding-agent": { "optional": true },
+    "@earendil-works/pi-ai": { "optional": true },
+    "@earendil-works/pi-tui": { "optional": true },
+    "typebox": { "optional": true }
   },
   "devDependencies": {
-    "@aliou/biome-plugins": "^0.3.0",
-    "@biomejs/biome": "^2.0.0",
+    "@biomejs/biome": "^2.3.0",
     "@changesets/cli": "^2.27.0",
-    "@mariozechner/pi-ai": "CURRENT_VERSION",
-    "@mariozechner/pi-coding-agent": "CURRENT_VERSION",
-    "@mariozechner/pi-tui": "CURRENT_VERSION",
-    "@sinclair/typebox": "0.34.41",
+    "@earendil-works/pi-ai": "CURRENT_VERSION",
+    "@earendil-works/pi-coding-agent": "CURRENT_VERSION",
+    "@earendil-works/pi-tui": "CURRENT_VERSION",
+    "typebox": "1.1.24",
     "@types/node": "^25.0.0",
     "husky": "^9.0.0",
-    "typescript": "^5.8.0"
+    "typescript": "^5.9.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
@@ -112,48 +122,36 @@ Not every extension needs every directory. A simple extension with one tool migh
   },
   "pnpm": {
     "overrides": {
-      "@mariozechner/pi-ai": "$@mariozechner/pi-coding-agent",
-      "@mariozechner/pi-tui": "$@mariozechner/pi-coding-agent"
+      "@earendil-works/pi-ai": "$@earendil-works/pi-coding-agent",
+      "@earendil-works/pi-tui": "$@earendil-works/pi-coding-agent"
     }
   },
   "packageManager": "pnpm@10.26.1"
 }
 ```
 
-Replace `CURRENT_VERSION` with the actual installed version of pi (e.g., `0.52.7`).
-
-Only include `pi` sub-fields that are actually used. `skills`, `themes`, `prompts`, and `video` are optional.
-
-### Fields
-
-**`pi` key**: Declares extension resources. All paths are relative to the package root.
-
-| Field | Description |
-|---|---|
-| `extensions` | Array of entry point paths. Each is a TypeScript file with a default export function. |
-| `skills` | Array of directories containing skill definitions. Optional. |
-| `themes` | Array of directories containing theme files. Optional. |
-| `prompts` | Array of directories containing prompt files. Optional. |
-| `video` | URL to an `.mp4` demo video. Displayed on the pi website package listing. Not used by pi itself. Optional. |
+Replace `CURRENT_VERSION` with the exact target Pi version for local type checking. If the target version is only available under the legacy namespace, use the matching `@mariozechner/*` package names consistently.
 
-**`peerDependencies`**: Declares the minimum pi version required. Pi ships these packages and injects them via jiti at runtime, so extensions never need to install them:
+Only include `pi` sub-fields you actually use. `skills`, `themes`, `prompts`, `video`, and `image` are optional.
 
-- `@mariozechner/pi-coding-agent` — core types, utilities, and extension APIs
-- `@mariozechner/pi-tui` — TUI components
-- `@mariozechner/pi-ai` — AI utilities (`StringEnum`, etc.)
-- `@sinclair/typebox` — schema definitions for tool parameters and related types
+### Dependency Rules
 
-List any of these you import at runtime in `peerDependencies` as optional peers. This prevents npm from installing duplicate copies when a user installs your extension. Use `>=` with the current version when creating.
+Pi provides these runtime packages to extensions:
 
-**`peerDependenciesMeta`**: Marks peer dependencies as optional. Without `optional: true`, npm 7+ auto-installs peers that are not already present, which defeats the purpose — Pi already provides them.
+- `@earendil-works/pi-coding-agent` / legacy `@mariozechner/pi-coding-agent`
+- `@earendil-works/pi-agent-core` / legacy `@mariozechner/pi-agent-core`
+- `@earendil-works/pi-ai` / legacy `@mariozechner/pi-ai`
+- `@earendil-works/pi-tui` / legacy `@mariozechner/pi-tui`
+- `typebox`
 
-**`devDependencies`**: Same packages at exact pinned versions for local type checking. `pnpm install` in your repo installs peerDependencies automatically, so local development is unaffected.
+For any of these that you import:
 
-**`scripts.prepare`**: The `[ -d .git ] && husky || true` guard prevents husky from running in consumer environments (including when Pi installs your package). Without this, `husky` runs on every `npm install` and fails with a non-zero exit code in environments without a `.git` directory.
+- Put them in `peerDependencies` with `"*"`.
+- Mark them `optional: true` in `peerDependenciesMeta`.
+- Put exact target versions in `devDependencies` for type checking.
+- Do not bundle them.
 
-**`scripts.check:lockfile`**: Verifies the lockfile is in sync with `package.json`. Run in CI to catch accidental lockfile drift.
-
-**`pnpm.overrides`**: Ensures pi sub-packages resolve to the version bundled with pi-coding-agent, avoiding duplicate installations.
+Third-party runtime packages that Pi does not provide belong in `dependencies`. If bundling another Pi package's resources into your tarball, add it to `dependencies` and `bundledDependencies`, then reference resources through `node_modules/...` paths.
 
 ## tsconfig.json
 
@@ -175,13 +173,11 @@ List any of these you import at runtime in `peerDependencies` as optional peers.
 }
 ```
 
-Extensions are loaded directly by pi (no build step). `noEmit: true` means TypeScript is only used for type checking.
-
-**Do not add `jsx` or `jsxImportSource` settings.** Although `src/components/` exists, pi-tui components are not React components. They implement the `Component` interface from `@mariozechner/pi-tui` and render to plain strings. No JSX transpilation is involved.
+Pi loads TypeScript directly through jiti. No build step is needed. Do not add JSX settings; Pi TUI components are not React components.
 
 ## biome.json
 
-All extensions use Biome for linting and formatting. Canonical config:
+Use Biome 2.x. If the project uses `@aliou/biome-plugins`, enable the Pi-relevant plugins.
 
 ```json
 {
@@ -221,34 +217,18 @@ All extensions use Biome for linting and formatting. Canonical config:
 }
 ```
 
-The `plugins` field requires Biome 2.x for GritQL plugin support. The `@aliou/biome-plugins` package has five plugins; three apply to pi extensions:
-
-- `no-inline-imports`: Disallows `await import()` and `require()` inside functions. All imports must be static.
-- `no-js-import-extension`: Disallows `.js` extensions in import paths (enforces the rule in Critical Rules).
-- `no-emojis`: Disallows emoji characters in code and strings.
-
-The other two (`no-interpolated-classname`, `phosphor-icon-suffix`) are specific to React and Phosphor icons and are not applicable.
+## Config Pattern
 
-## config.ts
-
-Non-trivial extensions have a `config.ts` that defines the config schema, types, and loader instance. Use plain TypeScript interfaces with a raw/resolved two-type pattern. The raw type has all fields optional — only overrides are stored to disk. The resolved type has all fields required — defaults are merged in at load time.
+Use plain TypeScript interfaces with raw/resolved types. Do not use TypeBox for config types.
 
 ```typescript
 import { ConfigLoader } from "@aliou/pi-utils-settings";
 
-/**
- * Raw config shape (what gets saved to disk).
- * All fields optional -- only overrides are stored.
- */
 export interface MyExtensionConfig {
   enabled?: boolean;
   myOption?: string;
 }
 
-/**
- * Resolved config (defaults merged in).
- * All fields required.
- */
 export interface ResolvedMyExtensionConfig {
   enabled: boolean;
   myOption: string;
@@ -259,68 +239,22 @@ const DEFAULTS: ResolvedMyExtensionConfig = {
   myOption: "default-value",
 };
 
-/**
- * Config loader instance.
- * Config is stored at ~/.pi/agent/extensions/<name>.json
- */
-export const configLoader = new ConfigLoader<
-  MyExtensionConfig,
-  ResolvedMyExtensionConfig
->("my-extension", DEFAULTS);
-```
-
-`ConfigLoader` comes from `@aliou/pi-utils-settings`, a standalone published package (source: `~/code/src/github.com/aliou/pi-extensions/packages/settings/`). It is listed as a regular dependency in `package.json`, not a peer dependency.
-
-The name passed to `ConfigLoader` determines the filename: `"my-extension"` → `~/.pi/agent/extensions/my-extension.json`.
-
-### Reading config
-
-After calling `load()`, use `getConfig()` for the resolved config (defaults merged in) or `getRawConfig(scope)` for the raw config at a specific scope.
-
-```typescript
-await configLoader.load();
-const config = configLoader.getConfig();        // ResolvedMyExtensionConfig
-const raw = configLoader.getRawConfig("global"); // MyExtensionConfig | null
-```
-
-### Saving config
-
-Use `save(scope, config)` to persist changes. The scope must be one of the enabled scopes (`"global"`, `"local"`, or `"memory"`). After saving, the loader automatically reloads and re-merges.
-
-```typescript
-await configLoader.save("global", { myOption: "new-value" });
-// configLoader.getConfig() now reflects the saved change
-```
-
-Memory scope is ephemeral -- it resets on reload and is not written to disk.
-
-### Scopes and merge order
-
-Default scopes are `["global", "local"]`. Merge priority (lowest to highest): defaults -> global -> local -> memory. Only overrides are stored to disk; missing fields fall back to defaults.
-
-For extensions with migrations or multi-scope config (global + local + in-memory), pass an options object:
-
-```typescript
 export const configLoader = new ConfigLoader<MyExtensionConfig, ResolvedMyExtensionConfig>(
   "my-extension",
   DEFAULTS,
-  {
-    scopes: ["global", "local", "memory"],
-    migrations: [...],
-  },
 );
 ```
 
-### Config Migrations
+After `await configLoader.load()`, use `configLoader.getConfig()` for resolved config and `getRawConfig(scope)` for a scope's raw overrides.
 
-For evolving config shape across versions, pass named migrations to `ConfigLoader`:
+### Scopes and Migrations
 
 ```typescript
 import { ConfigLoader, type Migration, buildSchemaUrl } from "@aliou/pi-utils-settings";
 import pkg from "../package.json" with { type: "json" };
 
-const legacyMigration: Migration<MyExtensionConfig> = {
-  name: "legacy-flat-key-to-nested",
+const migration: Migration<MyConfig> = {
+  name: "legacy-key-to-workspaces",
   shouldRun: (config) => Boolean(config.apiKey && !config.workspaces),
   run: (config) => {
     const migrated = structuredClone(config);
@@ -330,30 +264,22 @@ const legacyMigration: Migration<MyExtensionConfig> = {
   },
 };
 
-const schemaUrl = buildSchemaUrl(pkg.name, pkg.version);
-
 export const configLoader = new ConfigLoader<MyConfig, ResolvedMyConfig>(
   "my-extension",
   DEFAULTS,
   {
-    schemaUrl,
-    migrations: [legacyMigration],
+    scopes: ["global", "local", "memory"],
+    schemaUrl: buildSchemaUrl(pkg.name, pkg.version),
+    migrations: [migration],
   },
 );
 ```
 
-Each migration has:
-- `name`: unique identifier for idempotency
-- `shouldRun(config)`: predicate that returns true if migration is needed
-- `run(config)`: returns the migrated config (must not mutate the input)
-
-### JSON Schema for Config Validation
-
-Use `buildSchemaUrl(pkg.name, pkg.version)` from `@aliou/pi-utils-settings` to generate a schema URL. Config files get a `$schema` field pointing to the published schema, enabling editor validation and autocompletion.
+Migrations must be named, idempotent, and must not mutate their input.
 
 ## Settings Command
 
-Extensions with user-configurable settings use `registerSettingsCommand` from `@aliou/pi-utils-settings` to create a settings UI with Local/Global tabs:
+Use `registerSettingsCommand` from `@aliou/pi-utils-settings` for configurable extensions.
 
 ```typescript
 import { registerSettingsCommand, type SettingsSection } from "@aliou/pi-utils-settings";
@@ -363,7 +289,9 @@ registerSettingsCommand<MyConfig, ResolvedMyConfig>(pi, {
   commandDescription: "Configure my extension",
   title: "My Extension Settings",
   configStore: configLoader,
-  onSave: () => { /* invalidate caches */ },
+  onSave: () => {
+    // Invalidate caches.
+  },
   buildSections: (tabConfig, resolved, ctx): SettingsSection[] => [
     {
       label: "General",
@@ -381,137 +309,109 @@ registerSettingsCommand<MyConfig, ResolvedMyConfig>(pi, {
 });
 ```
 
-For complex nested config (workspaces, profiles), use `submenu` fields with `SettingsDetailEditor` or `FuzzySelector` components. See `pi-linear/src/commands/settings.ts` for a full example.
+For onboarding credentials, use the `Wizard` component from `@aliou/pi-utils-settings`.
 
-### Auth Wizard
+## Entry Point Pattern
 
-For extensions requiring API credentials, use the `Wizard` component from `@aliou/pi-utils-settings` for multi-step onboarding:
+Each feature entry point loads config, checks `enabled`, then registers its feature.
 
 ```typescript
-import { Wizard, FuzzySelector, type WizardStepContext } from "@aliou/pi-utils-settings";
-
-const wizard = new Wizard({
-  title: "My Auth",
-  theme,
-  steps: [
-    { label: "Key", build: (ctx) => new ApiKeyStep(state, ctx) },
-    { label: "Validate", build: (ctx) => new ValidateStep(state, ctx) },
-    { label: "Scope", build: (ctx) => new ScopeStep(state, ctx) },
-  ],
-  onComplete: async () => { /* save config */ },
-  onCancel: () => done(false),
+// src/tools/index.ts
+import type { AgentToolResult, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { configLoader } from "../config";
+
+const parameters = Type.Object({
+  query: Type.String({ description: "Search query" }),
 });
-```
-
-Each step receives a `WizardStepContext` with `markComplete()`/`markIncomplete()` to control navigation gates. See `pi-linear/src/commands/auth-wizard.ts` for a full example with async validation and spinner.
 
-## Entry Point (src/index.ts)
+type MyToolParams = Static<typeof parameters>;
 
-The entry point is a default export function that receives the `ExtensionAPI` object.
-
-### Standard Pattern
+interface MyToolDetails {
+  results: string[];
+}
 
-```typescript
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { configLoader } from "./config";
-import { registerCommands } from "./commands";
-import { registerHooks } from "./hooks";
-import { registerTools } from "./tools";
+const myTool = defineTool({
+  name: "my_tool",
+  label: "My Tool",
+  description: "Search for items",
+  parameters,
+  async execute(_toolCallId, params, signal): Promise<AgentToolResult<MyToolDetails>> {
+    const results = await search(params.query, { signal });
+    return {
+      content: [{ type: "text", text: JSON.stringify(results) }],
+      details: { results },
+    };
+  },
+});
 
-export default async function (pi: ExtensionAPI) {
+export default async function toolsExtension(pi: ExtensionAPI) {
   await configLoader.load();
   const config = configLoader.getConfig();
   if (!config.enabled) return;
 
-  registerTools(pi);
-  registerCommands(pi);
-  registerHooks(pi);
+  pi.registerTool(myTool);
 }
 ```
 
-### Acceptable Exceptions
-
-Not all extensions follow the standard pattern exactly. These deviations are valid:
-
-**No config**: Extensions that use environment variables exclusively and have no user-configurable settings skip config loading entirely. The entry point reads the env var directly and gates registration on its presence.
+### Acceptable Deviations
 
-**API-key-first**: Extensions wrapping a third-party API check for the API key before loading config or registering anything. If the key is missing, notify the user and return early. Config loads after the key check. See the API Key Pattern section.
+Document deviations in `AGENTS.md`.
 
-**No `enabled` check**: Extensions that are always active by design omit the `enabled` field and the early-return check. The entry point still loads config for other settings. Document this decision in `AGENTS.md`.
-
-When deviating from the standard pattern, note the reason in the extension's `AGENTS.md`.
+- **No config**: no user-configurable settings.
+- **API-key-first**: check required API key before loading config or registering API-dependent features.
+- **No enabled toggle**: extension is always active by design.
+- **Shared bootstrap**: multiple entry points call a shared setup helper.
 
 ## API Key Pattern
 
-If your extension wraps a third-party API that requires an API key:
-
 ```typescript
-export default function (pi: ExtensionAPI) {
+export default function toolsExtension(pi: ExtensionAPI) {
   const apiKey = process.env.MY_API_KEY;
 
-  // Register provider unconditionally if it exists
-  // (provider handles missing key internally for model registration)
-  pi.registerProvider(myProvider);
-
-  // Only register tools that need the key
   if (!apiKey) {
-    pi.on("session_start", async (_event, ctx) => {
-      ctx.ui.notify("MY_API_KEY not set. Tools disabled.", "warning");
+    pi.on("session_start", (_event, ctx) => {
+      ctx.ui.notify("MY_API_KEY not set. my-extension tools disabled.", "warning");
     });
     return;
   }
 
   pi.registerTool(createMyTool(apiKey));
-  pi.registerCommand(createMyCommand(apiKey));
 }
 ```
 
-The principle: check for the API key before registering anything that requires it. If the extension also registers a provider, the provider can be registered regardless (it handles key presence internally for model listing).
+Providers are different: register providers even if a key may be absent, because Pi handles auth resolution and login UI.
 
 ## Imports
 
-Do not use `.js` file extensions in imports. Use bare module paths:
+Do not use `.js` file extensions in TypeScript imports.
 
 ```typescript
 // Correct
 import { myTool } from "./tools/my-tool";
-import type { MyType } from "./types";
 
 // Wrong
 import { myTool } from "./tools/my-tool.js";
 ```
 
+Do not use inline dynamic imports unless there is a documented reason.
+
 ## Monorepo Variant
 
-In a monorepo with pnpm workspaces, the structure differs slightly. There is no `src/` directory; the entry point and config live directly in the package root.
+In pnpm workspaces, package roots may not have `src/`.
 
 ```
-extensions/
-  my-extension/
-    index.ts              # Entry point (no src/ directory)
-    config.ts             # Config schema (types) + loader + defaults
-    commands/
-      settings-command.ts
-    hooks/
-      my-hook.ts
-    components/
-      my-editor.ts
-    utils/
-      matching.ts
-      shell-utils.ts
-    package.json
+extensions/my-extension/
+  index.ts
+  config.ts
+  commands/
+  hooks/
+  components/
+  package.json
 ```
 
-Key differences from standalone:
-- Entry point directly in the package root (no `src/` directory).
-- `"pi": { "extensions": ["./index.ts"] }` instead of `["./src/index.ts"]`.
-- Uses `peerDependencies` (resolved by workspace root).
-- Shared `tsconfig` from a workspace package.
-- Same organization principles apply: config types in `config.ts`, helpers in `utils/`, one directory per feature category.
-
-### Workspace dependencies
-
-When an extension depends on another workspace package (e.g., `@aliou/pi-utils-settings`, `@aliou/pi-agent-kit`), use the `workspace:^` protocol instead of a version range:
+Use workspace protocol only for local workspace packages.
 
 ```json
 {
@@ -522,4 +422,15 @@ When an extension depends on another workspace package (e.g., `@aliou/pi-utils-s
 }
 ```
 
-Use `workspace:^` only for packages that live in this monorepo (under `packages/` or `extensions/`). External published packages like `@aliou/sh` keep regular version ranges.
+Do not publish packages that depend on private workspace packages.
+
+## Checklist
+
+- [ ] One entry point per feature directory.
+- [ ] No root fan-out registrar in new code.
+- [ ] Pi core imports are optional peers with `"*"` and exact dev deps.
+- [ ] Third-party runtime packages are in `dependencies`.
+- [ ] Config uses raw/resolved TypeScript interfaces.
+- [ ] Settings use `registerSettingsCommand` when configurable.
+- [ ] API-key-missing path notifies and disables affected features.
+- [ ] No `.js` suffixes in TypeScript imports.

package/src/skills/pi-extension/references/testing.md

@@ -44,7 +44,7 @@ Test event hooks by triggering the relevant actions:
 
 ## Unit Testing Core Logic
 
-The core/lib pattern makes domain logic testable without the Pi framework. Extract business logic into modules that don't import from `@mariozechner/pi-coding-agent` and test them directly.
+The core/lib pattern makes domain logic testable without the Pi framework. Extract business logic into modules that don't import from Pi core packages (`@earendil-works/pi-coding-agent` or legacy `@mariozechner/pi-coding-agent`) and test them directly.
 
 ### Testable core modules