@unbrained/pm-cli 2026.5.11 → 2026.5.14

package/dist/sdk/index.d.ts

@@ -1,5 +1,7 @@
 import { EXTENSION_CAPABILITY_CONTRACT, EXTENSION_CAPABILITY_CONTRACT_VERSION, EXTENSION_CAPABILITY_LEGACY_ALIASES, type ExtensionApi, type ExtensionManifest } from "../core/extensions/loader.js";
+export { PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS, PM_PACKAGE_RESOURCE_KINDS, collectPackageExtensionDirectories, readPmPackageManifest, type PmPackageCatalogLinkMap, type PmPackageCatalogMediaMap, type PmPackageCatalogMetadata, type PmPackageManifest, type PmPackageResourceKind, type PmPackageResourceMap, } from "../core/packages/manifest.js";
 export * from "./cli-contracts.js";
+export * from "./runtime.js";
 /**
  * Canonical extension capability names accepted by pm.
  *

package/dist/sdk/index.js

@@ -1,5 +1,7 @@
 import { EXTENSION_CAPABILITY_CONTRACT, EXTENSION_CAPABILITY_CONTRACT_VERSION, EXTENSION_CAPABILITY_LEGACY_ALIASES, KNOWN_EXTENSION_CAPABILITIES, KNOWN_EXTENSION_POLICY_MODES, KNOWN_EXTENSION_POLICY_SURFACES, KNOWN_EXTENSION_SANDBOX_PROFILES, KNOWN_EXTENSION_TRUST_MODES, } from "../core/extensions/loader.js";
+export { PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS, PM_PACKAGE_RESOURCE_KINDS, collectPackageExtensionDirectories, readPmPackageManifest, } from "../core/packages/manifest.js";
 export * from "./cli-contracts.js";
+export * from "./runtime.js";
 /**
  * Canonical extension capability names accepted by pm.
  *

package/dist/sdk/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"/","sources":["sdk/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,qCAAqC,EACrC,mCAAmC,EACnC,4BAA4B,EAC5B,4BAA4B,EAC5B,+BAA+B,EAC/B,gCAAgC,EAChC,2BAA2B,GAG5B,MAAM,8BAA8B,CAAC;AACtC,cAAc,oBAAoB,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,4BAA4B,CAAC;AAGnE;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,4BAA4B,CAAC;AACnE,MAAM,CAAC,MAAM,yBAAyB,GAAG,+BAA+B,CAAC;AACzE,MAAM,CAAC,MAAM,qBAAqB,GAAG,2BAA2B,CAAC;AACjE,MAAM,CAAC,MAAM,0BAA0B,GAAG,gCAAgC,CAAC;AAM3E;;GAEG;AACH,OAAO,EAAE,6BAA6B,EAAE,qCAAqC,EAAE,mCAAmC,EAAE,CAAC;AAarH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAkC,MAAe;IAC9E,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import {\n  EXTENSION_CAPABILITY_CONTRACT,\n  EXTENSION_CAPABILITY_CONTRACT_VERSION,\n  EXTENSION_CAPABILITY_LEGACY_ALIASES,\n  KNOWN_EXTENSION_CAPABILITIES,\n  KNOWN_EXTENSION_POLICY_MODES,\n  KNOWN_EXTENSION_POLICY_SURFACES,\n  KNOWN_EXTENSION_SANDBOX_PROFILES,\n  KNOWN_EXTENSION_TRUST_MODES,\n  type ExtensionApi,\n  type ExtensionManifest,\n} from \"../core/extensions/loader.js\";\nexport * from \"./cli-contracts.js\";\n\n/**\n * Canonical extension capability names accepted by pm.\n *\n * Extension manifests should declare one or more of these values in\n * `capabilities`.\n */\nexport const EXTENSION_CAPABILITIES = KNOWN_EXTENSION_CAPABILITIES;\nexport type ExtensionCapability = (typeof EXTENSION_CAPABILITIES)[number];\n\n/**\n * Canonical extension governance policy modes and registration surfaces.\n */\nexport const EXTENSION_POLICY_MODES = KNOWN_EXTENSION_POLICY_MODES;\nexport const EXTENSION_POLICY_SURFACES = KNOWN_EXTENSION_POLICY_SURFACES;\nexport const EXTENSION_TRUST_MODES = KNOWN_EXTENSION_TRUST_MODES;\nexport const EXTENSION_SANDBOX_PROFILES = KNOWN_EXTENSION_SANDBOX_PROFILES;\nexport type ExtensionPolicyMode = (typeof EXTENSION_POLICY_MODES)[number];\nexport type ExtensionPolicySurface = (typeof EXTENSION_POLICY_SURFACES)[number];\nexport type ExtensionTrustMode = (typeof EXTENSION_TRUST_MODES)[number];\nexport type ExtensionSandboxProfile = (typeof EXTENSION_SANDBOX_PROFILES)[number];\n\n/**\n * Versioned capability contract metadata emitted by runtime diagnostics.\n */\nexport { EXTENSION_CAPABILITY_CONTRACT, EXTENSION_CAPABILITY_CONTRACT_VERSION, EXTENSION_CAPABILITY_LEGACY_ALIASES };\n\nexport interface ExtensionModule {\n  /**\n   * Optional in-module metadata mirror.\n   *\n   * The authoritative manifest remains on-disk `manifest.json`; this field is\n   * useful when authors want colocated metadata for tooling/tests.\n   */\n  manifest?: ExtensionManifest;\n  activate(api: ExtensionApi): void | Promise<void>;\n}\n\n/**\n * Typed identity helper for extension module exports.\n *\n * Use as:\n * `export default defineExtension({ activate(api) { ... } })`\n */\nexport function defineExtension<TModule extends ExtensionModule>(module: TModule): TModule {\n  return module;\n}\n\nexport type {\n  AfterCommandHook,\n  AfterCommandHookContext,\n  BeforeCommandHook,\n  BeforeCommandHookContext,\n  CommandDefinition,\n  ExtensionCommandArgumentDefinition,\n  CommandHandler,\n  CommandHandlerContext,\n  CommandOverride,\n  CommandOverrideContext,\n  ExtensionServiceName,\n  Exporter,\n  ExtensionActivationResult,\n  ExtensionApi,\n  ExtensionCommandRegistry,\n  ExtensionDiagnostic,\n  ExtensionDiscoveryResult,\n  ExtensionLoadResult,\n  ExtensionManifest,\n  ExtensionGovernancePolicy,\n  ExtensionPolicyOverride,\n  ExtensionProvenanceMetadata,\n  ExtensionRuntimePermissionDeclaration,\n  ExtensionSearchMode,\n  ExtensionParserRegistry,\n  ExtensionPreflightRegistry,\n  ExtensionRegistrationRegistry,\n  ExtensionRendererRegistry,\n  ExtensionServiceRegistry,\n  FlagValueType,\n  FlagDefinition,\n  ImportExportContext,\n  Importer,\n  OnIndexHook,\n  OnIndexHookContext,\n  OnReadHook,\n  OnReadHookContext,\n  OnWriteHook,\n  OnWriteHookContext,\n  OutputRendererFormat,\n  ParserOverride,\n  ParserOverrideContext,\n  ParserOverrideDelta,\n  PreflightOverride,\n  PreflightOverrideContext,\n  PreflightOverrideDelta,\n  PreflightRuntimeDecision,\n  RendererOverride,\n  RendererOverrideContext,\n  SchemaFieldDefinition,\n  SchemaItemTypeCommandOptionPolicyDefinition,\n  SchemaItemTypeOptionDefinition,\n  SchemaItemTypeDefinition,\n  SchemaMigrationDefinition,\n  SchemaMigrationRunContext,\n  SchemaMigrationRunner,\n  SearchProviderEmbedBatchContext,\n  SearchProviderEmbedContext,\n  SearchProviderDefinition,\n  SearchProviderHit,\n  SearchProviderQueryContext,\n  SearchProviderQueryResult,\n  ServiceOverride,\n  ServiceOverrideContext,\n  VectorStoreAdapterDefinition,\n  VectorStoreDeleteContext,\n  VectorStoreQueryContext,\n  VectorStoreQueryHit,\n  VectorStoreUpsertContext,\n  VectorStoreUpsertPoint,\n} from \"../core/extensions/loader.js\";\n\nexport type { GlobalOptions } from \"../core/shared/command-types.js\";\nexport type { ItemDocument, ItemFrontMatter, ItemStatus, ItemType, PmSettings } from \"../types/index.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"/","sources":["sdk/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,qCAAqC,EACrC,mCAAmC,EACnC,4BAA4B,EAC5B,4BAA4B,EAC5B,+BAA+B,EAC/B,gCAAgC,EAChC,2BAA2B,GAG5B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,sCAAsC,EACtC,yBAAyB,EACzB,kCAAkC,EAClC,qBAAqB,GAOtB,MAAM,8BAA8B,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAE7B;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,4BAA4B,CAAC;AAGnE;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,4BAA4B,CAAC;AACnE,MAAM,CAAC,MAAM,yBAAyB,GAAG,+BAA+B,CAAC;AACzE,MAAM,CAAC,MAAM,qBAAqB,GAAG,2BAA2B,CAAC;AACjE,MAAM,CAAC,MAAM,0BAA0B,GAAG,gCAAgC,CAAC;AAM3E;;GAEG;AACH,OAAO,EAAE,6BAA6B,EAAE,qCAAqC,EAAE,mCAAmC,EAAE,CAAC;AAarH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAkC,MAAe;IAC9E,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import {\n  EXTENSION_CAPABILITY_CONTRACT,\n  EXTENSION_CAPABILITY_CONTRACT_VERSION,\n  EXTENSION_CAPABILITY_LEGACY_ALIASES,\n  KNOWN_EXTENSION_CAPABILITIES,\n  KNOWN_EXTENSION_POLICY_MODES,\n  KNOWN_EXTENSION_POLICY_SURFACES,\n  KNOWN_EXTENSION_SANDBOX_PROFILES,\n  KNOWN_EXTENSION_TRUST_MODES,\n  type ExtensionApi,\n  type ExtensionManifest,\n} from \"../core/extensions/loader.js\";\nexport {\n  PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS,\n  PM_PACKAGE_RESOURCE_KINDS,\n  collectPackageExtensionDirectories,\n  readPmPackageManifest,\n  type PmPackageCatalogLinkMap,\n  type PmPackageCatalogMediaMap,\n  type PmPackageCatalogMetadata,\n  type PmPackageManifest,\n  type PmPackageResourceKind,\n  type PmPackageResourceMap,\n} from \"../core/packages/manifest.js\";\nexport * from \"./cli-contracts.js\";\nexport * from \"./runtime.js\";\n\n/**\n * Canonical extension capability names accepted by pm.\n *\n * Extension manifests should declare one or more of these values in\n * `capabilities`.\n */\nexport const EXTENSION_CAPABILITIES = KNOWN_EXTENSION_CAPABILITIES;\nexport type ExtensionCapability = (typeof EXTENSION_CAPABILITIES)[number];\n\n/**\n * Canonical extension governance policy modes and registration surfaces.\n */\nexport const EXTENSION_POLICY_MODES = KNOWN_EXTENSION_POLICY_MODES;\nexport const EXTENSION_POLICY_SURFACES = KNOWN_EXTENSION_POLICY_SURFACES;\nexport const EXTENSION_TRUST_MODES = KNOWN_EXTENSION_TRUST_MODES;\nexport const EXTENSION_SANDBOX_PROFILES = KNOWN_EXTENSION_SANDBOX_PROFILES;\nexport type ExtensionPolicyMode = (typeof EXTENSION_POLICY_MODES)[number];\nexport type ExtensionPolicySurface = (typeof EXTENSION_POLICY_SURFACES)[number];\nexport type ExtensionTrustMode = (typeof EXTENSION_TRUST_MODES)[number];\nexport type ExtensionSandboxProfile = (typeof EXTENSION_SANDBOX_PROFILES)[number];\n\n/**\n * Versioned capability contract metadata emitted by runtime diagnostics.\n */\nexport { EXTENSION_CAPABILITY_CONTRACT, EXTENSION_CAPABILITY_CONTRACT_VERSION, EXTENSION_CAPABILITY_LEGACY_ALIASES };\n\nexport interface ExtensionModule {\n  /**\n   * Optional in-module metadata mirror.\n   *\n   * The authoritative manifest remains on-disk `manifest.json`; this field is\n   * useful when authors want colocated metadata for tooling/tests.\n   */\n  manifest?: ExtensionManifest;\n  activate(api: ExtensionApi): void | Promise<void>;\n}\n\n/**\n * Typed identity helper for extension module exports.\n *\n * Use as:\n * `export default defineExtension({ activate(api) { ... } })`\n */\nexport function defineExtension<TModule extends ExtensionModule>(module: TModule): TModule {\n  return module;\n}\n\nexport type {\n  AfterCommandHook,\n  AfterCommandHookContext,\n  BeforeCommandHook,\n  BeforeCommandHookContext,\n  CommandDefinition,\n  ExtensionCommandArgumentDefinition,\n  CommandHandler,\n  CommandHandlerContext,\n  CommandOverride,\n  CommandOverrideContext,\n  ExtensionServiceName,\n  Exporter,\n  ExtensionActivationResult,\n  ExtensionApi,\n  ExtensionCommandRegistry,\n  ExtensionDiagnostic,\n  ExtensionDiscoveryResult,\n  ExtensionLoadResult,\n  ExtensionManifest,\n  ExtensionGovernancePolicy,\n  ExtensionPolicyOverride,\n  ExtensionProvenanceMetadata,\n  ExtensionRuntimePermissionDeclaration,\n  ExtensionSearchMode,\n  ExtensionParserRegistry,\n  ExtensionPreflightRegistry,\n  ExtensionRegistrationRegistry,\n  ExtensionRendererRegistry,\n  ExtensionServiceRegistry,\n  FlagValueType,\n  FlagDefinition,\n  ImportExportContext,\n  Importer,\n  OnIndexHook,\n  OnIndexHookContext,\n  OnReadHook,\n  OnReadHookContext,\n  OnWriteHook,\n  OnWriteHookContext,\n  OutputRendererFormat,\n  ParserOverride,\n  ParserOverrideContext,\n  ParserOverrideDelta,\n  PreflightOverride,\n  PreflightOverrideContext,\n  PreflightOverrideDelta,\n  PreflightRuntimeDecision,\n  RendererOverride,\n  RendererOverrideContext,\n  SchemaFieldDefinition,\n  SchemaItemTypeCommandOptionPolicyDefinition,\n  SchemaItemTypeOptionDefinition,\n  SchemaItemTypeDefinition,\n  SchemaMigrationDefinition,\n  SchemaMigrationRunContext,\n  SchemaMigrationRunner,\n  SearchProviderEmbedBatchContext,\n  SearchProviderEmbedContext,\n  SearchProviderDefinition,\n  SearchProviderHit,\n  SearchProviderQueryContext,\n  SearchProviderQueryResult,\n  ServiceOverride,\n  ServiceOverrideContext,\n  VectorStoreAdapterDefinition,\n  VectorStoreDeleteContext,\n  VectorStoreQueryContext,\n  VectorStoreQueryHit,\n  VectorStoreUpsertContext,\n  VectorStoreUpsertPoint,\n} from \"../core/extensions/loader.js\";\n\nexport type { GlobalOptions } from \"../core/shared/command-types.js\";\nexport type { ItemDocument, ItemFrontMatter, ItemStatus, ItemType, PmSettings } from \"../types/index.js\";\n"]}

package/dist/sdk/runtime.d.ts

@@ -0,0 +1,29 @@
+export { getActiveExtensionRegistrations, runActiveOnReadHooks, runActiveOnWriteHooks, } from "../core/extensions/index.js";
+export { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic } from "../core/fs/fs-utils.js";
+export { appendHistoryEntry, createHistoryEntry } from "../core/history/history.js";
+export { generateItemId, normalizeItemId, normalizeRawItemId } from "../core/item/id.js";
+export { canonicalDocument, normalizeFrontMatter, serializeItemDocument, splitFrontMatter, } from "../core/item/item-format.js";
+export { parseTags } from "../core/item/parse.js";
+export { normalizeStatusInput } from "../core/item/status.js";
+export { resolveItemTypeRegistry } from "../core/item/type-registry.js";
+export { acquireLock } from "../core/lock/lock.js";
+export { resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry } from "../core/schema/runtime-schema.js";
+export { EXIT_CODE } from "../core/shared/constants.js";
+export { PmCliError } from "../core/shared/errors.js";
+export { isTimestampLiteral, nowIso } from "../core/shared/time.js";
+export { listAllFrontMatter, locateItem, readLocatedItem } from "../core/store/item-store.js";
+export { getHistoryPath, getItemPath, getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
+export { readSettings } from "../core/store/settings.js";
+export { renderCalendarMarkdown, resolveCalendarOutputFormat, runCalendar, type CalendarOptions, type CalendarResult, } from "../cli/commands/calendar.js";
+export { renderGuideMarkdown, resolveGuideOutputFormat, runGuide, type GuideDepth, type GuideOptions, type GuideOutputFormat, type GuideResult, } from "../cli/commands/guide.js";
+export { runCompletion, type CompletionResult, type CompletionShell } from "../cli/commands/completion.js";
+export { runCommentsAudit, type CommentsAuditEntry, type CommentsAuditHistoryRow, type CommentsAuditOptions, type CommentsAuditResult, type CommentsAuditSummary, type CommentsAuditTypeSummary, } from "../cli/commands/comments-audit.js";
+export { runDedupeAudit, type DedupeAuditCandidate, type DedupeAuditCluster, type DedupeAuditOptions, type DedupeAuditResult, } from "../cli/commands/dedupe-audit.js";
+export { runNormalize, type NormalizeCommandOptions, type NormalizeResult } from "../cli/commands/normalize.js";
+export { runReindex, type ReindexOptions, type ReindexResult } from "../cli/commands/reindex.js";
+export { runSearch, type SearchOptions, type SearchResult } from "../cli/commands/search.js";
+export { loadCreateTemplateOptions, runTemplatesList, runTemplatesSave, runTemplatesShow, type CreateTemplateOptions, type TemplatesListResult, type TemplatesSaveResult, type TemplatesShowResult, } from "../cli/commands/templates.js";
+export { runTestRunsList, runTestRunsLogs, runTestRunsResume, runTestRunsStatus, runTestRunsStop, type TestRunsListCommandOptions, type TestRunsLogsCommandOptions, type TestRunsResumeCommandOptions, type TestRunsStopCommandOptions, } from "../cli/commands/test-runs.js";
+export { CONFIDENCE_TEXT_VALUES, DEPENDENCY_KIND_VALUES, ISSUE_SEVERITY_VALUES, RISK_VALUES, } from "../types/index.js";
+export type { GlobalOptions } from "../core/shared/command-types.js";
+export type { Dependency, ItemDocument, ItemMetadata, ItemStatus, ItemType, LinkedDoc, LinkedFile, LinkedTest, LogNote, PmSettings, } from "../types/index.js";

package/dist/sdk/runtime.js

@@ -0,0 +1,28 @@
+export { getActiveExtensionRegistrations, runActiveOnReadHooks, runActiveOnWriteHooks, } from "../core/extensions/index.js";
+export { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic } from "../core/fs/fs-utils.js";
+export { appendHistoryEntry, createHistoryEntry } from "../core/history/history.js";
+export { generateItemId, normalizeItemId, normalizeRawItemId } from "../core/item/id.js";
+export { canonicalDocument, normalizeFrontMatter, serializeItemDocument, splitFrontMatter, } from "../core/item/item-format.js";
+export { parseTags } from "../core/item/parse.js";
+export { normalizeStatusInput } from "../core/item/status.js";
+export { resolveItemTypeRegistry } from "../core/item/type-registry.js";
+export { acquireLock } from "../core/lock/lock.js";
+export { resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry } from "../core/schema/runtime-schema.js";
+export { EXIT_CODE } from "../core/shared/constants.js";
+export { PmCliError } from "../core/shared/errors.js";
+export { isTimestampLiteral, nowIso } from "../core/shared/time.js";
+export { listAllFrontMatter, locateItem, readLocatedItem } from "../core/store/item-store.js";
+export { getHistoryPath, getItemPath, getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
+export { readSettings } from "../core/store/settings.js";
+export { renderCalendarMarkdown, resolveCalendarOutputFormat, runCalendar, } from "../cli/commands/calendar.js";
+export { renderGuideMarkdown, resolveGuideOutputFormat, runGuide, } from "../cli/commands/guide.js";
+export { runCompletion } from "../cli/commands/completion.js";
+export { runCommentsAudit, } from "../cli/commands/comments-audit.js";
+export { runDedupeAudit, } from "../cli/commands/dedupe-audit.js";
+export { runNormalize } from "../cli/commands/normalize.js";
+export { runReindex } from "../cli/commands/reindex.js";
+export { runSearch } from "../cli/commands/search.js";
+export { loadCreateTemplateOptions, runTemplatesList, runTemplatesSave, runTemplatesShow, } from "../cli/commands/templates.js";
+export { runTestRunsList, runTestRunsLogs, runTestRunsResume, runTestRunsStatus, runTestRunsStop, } from "../cli/commands/test-runs.js";
+export { CONFIDENCE_TEXT_VALUES, DEPENDENCY_KIND_VALUES, ISSUE_SEVERITY_VALUES, RISK_VALUES, } from "../types/index.js";
+//# sourceMappingURL=runtime.js.map

package/dist/sdk/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"/","sources":["sdk/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,+BAA+B,EAC/B,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC3G,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACzF,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,2BAA2B,EAAE,4BAA4B,EAAE,MAAM,kCAAkC,CAAC;AAC7G,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9F,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACrG,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,WAAW,GAGZ,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,QAAQ,GAKT,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,aAAa,EAA+C,MAAM,+BAA+B,CAAC;AAC3G,OAAO,EACL,gBAAgB,GAOjB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EACL,cAAc,GAKf,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,YAAY,EAAsD,MAAM,8BAA8B,CAAC;AAChH,OAAO,EAAE,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AACjG,OAAO,EAAE,SAAS,EAAyC,MAAM,2BAA2B,CAAC;AAC7F,OAAO,EACL,yBAAyB,EACzB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GAKjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GAKhB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,EACrB,WAAW,GACZ,MAAM,mBAAmB,CAAC","sourcesContent":["export {\n  getActiveExtensionRegistrations,\n  runActiveOnReadHooks,\n  runActiveOnWriteHooks,\n} from \"../core/extensions/index.js\";\nexport { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic } from \"../core/fs/fs-utils.js\";\nexport { appendHistoryEntry, createHistoryEntry } from \"../core/history/history.js\";\nexport { generateItemId, normalizeItemId, normalizeRawItemId } from \"../core/item/id.js\";\nexport {\n  canonicalDocument,\n  normalizeFrontMatter,\n  serializeItemDocument,\n  splitFrontMatter,\n} from \"../core/item/item-format.js\";\nexport { parseTags } from \"../core/item/parse.js\";\nexport { normalizeStatusInput } from \"../core/item/status.js\";\nexport { resolveItemTypeRegistry } from \"../core/item/type-registry.js\";\nexport { acquireLock } from \"../core/lock/lock.js\";\nexport { resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry } from \"../core/schema/runtime-schema.js\";\nexport { EXIT_CODE } from \"../core/shared/constants.js\";\nexport { PmCliError } from \"../core/shared/errors.js\";\nexport { isTimestampLiteral, nowIso } from \"../core/shared/time.js\";\nexport { listAllFrontMatter, locateItem, readLocatedItem } from \"../core/store/item-store.js\";\nexport { getHistoryPath, getItemPath, getSettingsPath, resolvePmRoot } from \"../core/store/paths.js\";\nexport { readSettings } from \"../core/store/settings.js\";\nexport {\n  renderCalendarMarkdown,\n  resolveCalendarOutputFormat,\n  runCalendar,\n  type CalendarOptions,\n  type CalendarResult,\n} from \"../cli/commands/calendar.js\";\nexport {\n  renderGuideMarkdown,\n  resolveGuideOutputFormat,\n  runGuide,\n  type GuideDepth,\n  type GuideOptions,\n  type GuideOutputFormat,\n  type GuideResult,\n} from \"../cli/commands/guide.js\";\nexport { runCompletion, type CompletionResult, type CompletionShell } from \"../cli/commands/completion.js\";\nexport {\n  runCommentsAudit,\n  type CommentsAuditEntry,\n  type CommentsAuditHistoryRow,\n  type CommentsAuditOptions,\n  type CommentsAuditResult,\n  type CommentsAuditSummary,\n  type CommentsAuditTypeSummary,\n} from \"../cli/commands/comments-audit.js\";\nexport {\n  runDedupeAudit,\n  type DedupeAuditCandidate,\n  type DedupeAuditCluster,\n  type DedupeAuditOptions,\n  type DedupeAuditResult,\n} from \"../cli/commands/dedupe-audit.js\";\nexport { runNormalize, type NormalizeCommandOptions, type NormalizeResult } from \"../cli/commands/normalize.js\";\nexport { runReindex, type ReindexOptions, type ReindexResult } from \"../cli/commands/reindex.js\";\nexport { runSearch, type SearchOptions, type SearchResult } from \"../cli/commands/search.js\";\nexport {\n  loadCreateTemplateOptions,\n  runTemplatesList,\n  runTemplatesSave,\n  runTemplatesShow,\n  type CreateTemplateOptions,\n  type TemplatesListResult,\n  type TemplatesSaveResult,\n  type TemplatesShowResult,\n} from \"../cli/commands/templates.js\";\nexport {\n  runTestRunsList,\n  runTestRunsLogs,\n  runTestRunsResume,\n  runTestRunsStatus,\n  runTestRunsStop,\n  type TestRunsListCommandOptions,\n  type TestRunsLogsCommandOptions,\n  type TestRunsResumeCommandOptions,\n  type TestRunsStopCommandOptions,\n} from \"../cli/commands/test-runs.js\";\nexport {\n  CONFIDENCE_TEXT_VALUES,\n  DEPENDENCY_KIND_VALUES,\n  ISSUE_SEVERITY_VALUES,\n  RISK_VALUES,\n} from \"../types/index.js\";\nexport type { GlobalOptions } from \"../core/shared/command-types.js\";\nexport type {\n  Dependency,\n  ItemDocument,\n  ItemMetadata,\n  ItemStatus,\n  ItemType,\n  LinkedDoc,\n  LinkedFile,\n  LinkedTest,\n  LogNote,\n  PmSettings,\n} from \"../types/index.js\";\n"]}

package/docs/ARCHITECTURE.md

@@ -193,7 +193,7 @@ Command/action metadata is centralized in `src/sdk/cli-contracts.ts` and used by
 - CLI option normalization
 - help output
 - completion generation
-- Pi wrapper schema
+- provider-safe tool schemas
 - `pm contracts`
 - extension command/action contract exposure
 

package/docs/COMMANDS.md

@@ -31,7 +31,7 @@ Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 | Verification | `test`, `test-all`, `test-runs`, `validate`, `gc` | run linked tests and repository checks |
 | History | `history`, `activity`, `restore`, `stats` | inspect and recover item state |
 | Calendar | `calendar`, `cal` | project deadlines, reminders, and events |
-| Extensions | `extension`, extension command groups | install, manage, and run extension commands |
+| Packages | `install`, `upgrade`, `package`, `packages`, `extension`, package/extension command groups | install, upgrade, manage, and run package-backed extension commands |
 | Machines | `guide`, `contracts`, `completion`, `help` | local docs routing plus command contracts and shell helpers |
 
 ## Bootstrap
@@ -44,6 +44,21 @@ pm health --check-only
 
 `pm init` creates `.agents/pm`. `pm health --check-only` inspects without refreshing optional search artifacts.
 
+## Packages
+
+```bash
+pm install '*' --project
+pm package catalog --project
+pm install npm:@scope/pm-package --project
+pm package doctor --project --detail summary
+pm upgrade --dry-run
+pm upgrade --packages-only
+pm upgrade --cli-only --repair
+```
+
+`pm install` and `pm package` are the preferred package-first workflow. `pm install '*'`, shell-expanded `pm install *`, and `pm install all` install bundled first-party packages. `pm extension` remains as a compatibility command for direct extension lifecycle operations.
+When package-owned commands are unavailable, usage guidance includes an install-ready retry (for example `pm install calendar`, `pm install search-advanced`, `pm install governance-audit`, or `pm install guide-shell`).
+
 ## Triage
 
 ```bash
@@ -168,6 +183,7 @@ pm context --from today --to +7d --limit 10
 ```
 
 `calendar` defaults to markdown for human and agent readability. Other commands default to TOON unless configured otherwise.
+For `--include events` without explicit `--to`, `--recurrence-lookahead-days`, or `--occurrence-limit`, recurring expansion is intentionally capped to a bounded default window and emits a warning with retry hints for broader windows.
 
 ## Validation and Maintenance
 

package/docs/EXTENSIONS.md

@@ -1,25 +1,60 @@
-# Extensions
+# Packages and Extensions
 
-Extensions let you add or override `pm` runtime behavior without modifying core `pm-cli` sources.
+Packages let you add or override `pm` runtime behavior without modifying core `pm-cli` sources. A package can currently contain one or more runtime extensions, and the package-first command surface is the preferred user-facing workflow.
 
-This document is the canonical extension reference for manifest contracts, governance policy, trust and sandbox controls, reload workflows, and diagnostics.
+`pm extension ...` remains supported for compatibility. New scripts and docs should prefer `pm install ...` and `pm package ...`.
+
+This document is the canonical package/extension reference for manifest contracts, governance policy, trust and sandbox controls, reload workflows, and diagnostics.
 
 ## Quick Start
 
 ```bash
-# 1) Scaffold an extension
-pm extension --init ./my-extension
+# 1) Scaffold a package extension
+pm package init ./my-package-extension
 
 # 2) Install in project scope
-pm extension --install --project ./my-extension
+pm install ./my-package --project
+
+# Or install all bundled first-party packages
+pm install '*' --project
 
 # 3) Run diagnostics
-pm extension --doctor --project --detail summary
+pm package doctor --project --detail summary
 
-# 4) Reload runtime modules after local edits
-pm extension --reload --project
+# 4) Plan CLI/SDK and package upgrades
+pm upgrade --dry-run
+
+# 5) Reload runtime modules after local edits
+pm package reload --project
 ```
 
+Compatibility equivalents:
+
+```bash
+pm extension init ./my-package        # prefer: pm package init ./my-package
+pm extension install ./my-package --project
+pm extension doctor --project --detail summary
+pm extension reload --project
+```
+
+Use compatibility equivalents only for existing automation or for debugging extension-runtime behavior directly.
+
+## Upgrade Workflow
+
+`pm upgrade` is the package-first update entrypoint:
+
+```bash
+pm upgrade --dry-run              # plan CLI/SDK and project package updates
+pm upgrade                        # update the global pm CLI/SDK, then refresh project packages
+pm upgrade --packages-only        # refresh managed packages without changing the CLI
+pm upgrade todos --dry-run        # plan one managed package refresh
+pm upgrade --cli-only --repair    # force a global CLI/SDK reinstall through npm
+```
+
+CLI/SDK upgrades use `npm install -g @unbrained/pm-cli@<tag>`.
+Managed package upgrades reuse the source recorded at install time, including `npm:`, GitHub, local, and first-party package paths.
+Use `--tag <version-or-dist-tag>` to target a registry tag such as `latest` or `next`.
+
 ## Extension Locations
 
 - project scope: `.agents/pm/extensions/<name>/`
@@ -31,6 +66,84 @@ Runtime path overrides:
 - `PM_PATH`: project tracker root override
 - `PM_GLOBAL_PATH`: global profile root override
 
+## Package Sources
+
+`pm install` accepts these package sources:
+
+```bash
+pm install ./local-package
+pm install /absolute/path/to/package
+pm install npm:@scope/package
+pm install npm:package@1.2.3
+pm install https://github.com/org/repo
+pm install --github org/repo/path --ref main
+```
+
+Package roots can expose resources with a `pm` manifest in `package.json`:
+
+```json
+{
+  "name": "my-pm-package",
+  "keywords": ["pm-package"],
+  "pm": {
+    "aliases": ["my-workflow"],
+    "extensions": ["extensions/my-extension"],
+    "docs": ["README.md"],
+    "examples": ["README.md"],
+    "catalog": {
+      "display_name": "My pm Package",
+      "category": "workflow",
+      "summary": "Adds a custom workflow to pm.",
+      "tags": ["workflow"],
+      "links": {
+        "docs": "https://example.com/docs",
+        "repository": "https://github.com/org/my-pm-package",
+        "report": "https://github.com/org/my-pm-package/issues"
+      },
+      "media": {
+        "image": "https://example.com/preview.png"
+      }
+    }
+  }
+}
+```
+
+`pm.aliases` declares short install targets for bundled first-party packages. If aliases are omitted, `pm` derives a default alias from the `packages/pm-*` directory name. The SDK exposes this project-management package model through `PM_PACKAGE_RESOURCE_KINDS`, `PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS`, and `readPmPackageManifest`. Package installation currently activates only `pm.extensions`; `pm.docs` and `pm.examples` are metadata-first catalog resources. Agent-specific bundles such as prompts, skills, and MCP servers should live in separate agent adapter packages rather than the core `pm` package contract.
+
+When no manifest is present, `pm` discovers conventional extension directories:
+
+- `.agents/pm/extensions/`
+- `extensions/`
+- `.custom/pm-extensions/`
+- `.custom/pm-extension/`
+
+If a package contains multiple extension manifests, install the exact extension path so the managed state has one deterministic package target.
+
+First-party optional packages are shipped as package roots under `packages/`:
+
+```bash
+pm package catalog --project
+pm install '*' --project
+pm install all --project
+pm install packages/pm-calendar --project
+pm install packages/pm-beads --project
+pm install packages/pm-todos --project
+```
+
+`pm install '*'` and `pm install all` install every bundled first-party package in deterministic alias order. If your shell expands `pm install *`, pm recognizes that expansion and treats it as the same bundled-package install-all request.
+
+Compatibility aliases remain available:
+
+```bash
+pm install beads --project
+pm install calendar --project
+pm install todos --project
+```
+
+Those aliases install package-shipped extension sources. They are then tracked in managed package state and can be refreshed with `pm upgrade --packages-only`.
+
+If a package-owned command is invoked before installation (for example `pm calendar --help`, `pm reindex --help`, or `pm normalize --help` in bare core mode), runtime usage guidance now includes a direct recovery command such as `pm install calendar`, `pm install search-advanced`, or `pm install governance-audit`.
+
 ## Manifest Contract
 
 ### Manifest v1 (supported)
@@ -184,13 +297,14 @@ pm extension --doctor --project --detail deep --trace
 Management commands:
 
 ```bash
-pm extension --explore
-pm extension --manage --project
-pm extension --manage --project --probe-runtime
-pm extension --manage --project --adopt-unmanaged
-pm extension --activate my-extension --project
-pm extension --deactivate my-extension --project
-pm extension --uninstall my-extension --project
+pm package catalog --project
+pm package explore
+pm package manage --project
+pm package manage --project --runtime-probe
+pm package manage --project --fix-managed-state
+pm package activate my-extension --project
+pm package deactivate my-extension --project
+pm package uninstall my-extension --project
 ```
 
 Common warning prefixes:
@@ -214,7 +328,7 @@ Common warning prefixes:
 
 ```bash
 pm contracts --json
-pm extension --doctor --project --detail summary --strict-exit
+pm package doctor --project --detail summary --strict-exit
 ```
 
 6. Resolve warnings before enforcing `mode=enforce` and `trust_mode=enforce`.
@@ -228,7 +342,7 @@ pm extension --doctor --project --detail summary --strict-exit
 - `docs/examples/ci/github-actions-pm-extension-gate.yml`
 - `docs/examples/ci/gitlab-ci-pm-extension-gate.yml`
 - `docs/examples/ci/jenkins-pm-extension-gate.Jenkinsfile`
-# Extensions
+# Extension Runtime Details
 
 Extensions let you add or override `pm` runtime behavior without modifying core `pm-cli`.
 
@@ -243,17 +357,17 @@ This guide is the authoritative reference for:
 ## Quick Start
 
 ```bash
-# 1) Scaffold an extension
-pm extension --init ./my-extension
+# 1) Scaffold a package-backed extension
+pm package init ./my-package
 
 # 2) Install in project scope
-pm extension --install --project ./my-extension
+pm install ./my-package --project
 
 # 3) Run diagnostics
-pm extension --doctor --project --detail summary
+pm package doctor --project --detail summary
 
 # 4) Reload runtime modules after local edits
-pm extension --reload --project
+pm package reload --project
 ```
 
 ## Delta From Previous Scope
@@ -263,7 +377,7 @@ Compared to the previous policy-only extension surface, this release adds:
 - **Manifest v2 metadata** for trust, provenance, sandbox profile, and runtime permission declarations.
 - **Policy v2 controls** for trust mode, provenance requirement, sandbox defaults, and command/action/service allow/block maps.
 - **Registration enforcement upgrades** so command/action/service restrictions are evaluated at registration boundaries.
-- **Hot reload controls** via cache-busted extension reload (`pm extension --reload`) with watch-mode semantics (`--watch`).
+- **Hot reload controls** via cache-busted package reload (`pm package reload`) with watch-mode semantics (`--watch`).
 - **Contracts metadata upgrades** for trust/sandbox compatibility information in `pm contracts`.
 
 ## Extension Locations
@@ -473,27 +587,27 @@ pm extension --doctor --project --detail summary --strict-exit
 - `docs/examples/ci/github-actions-pm-extension-gate.yml`
 - `docs/examples/ci/gitlab-ci-pm-extension-gate.yml`
 - `docs/examples/ci/jenkins-pm-extension-gate.Jenkinsfile`
-# Extensions
+# Extension Runtime Governance
 
 Extensions let you add or override `pm` runtime behavior without editing core `pm-cli` sources. They are loaded at runtime, gated by manifest capabilities, and now support granular governance policies for capability/surface allow/block controls.
 
 ## Quick Start
 
 ```bash
-# 1) Scaffold a new extension
-pm extension --init ./my-extension
+# 1) Scaffold a new package
+pm package init ./my-package
 
 # 2) Install into project scope
-pm extension --install --project ./my-extension
+pm install ./my-package --project
 
-# 3) Run extension diagnostics
-pm extension --doctor --project --detail summary
+# 3) Run package diagnostics
+pm package doctor --project --detail summary
 
 # 4) Deep diagnostics with traces
-pm extension --doctor --project --detail deep --trace
+pm package doctor --project --detail deep --trace
 ```
 
-Expected summary signals from `extension --doctor`:
+Expected summary signals from `pm package doctor`:
 
 - `details.summary.status`: `ok` or `warn`
 - `details.summary.warning_codes`: deterministic warning code list
@@ -674,27 +788,27 @@ For CI/CD and agents:
 
 ## Troubleshooting
 
-- Manifest/entry failures: run `pm extension --explore --project`
-- Activation failures: run `pm extension --doctor --detail deep --trace`
+- Manifest/entry failures: run `pm package explore --project`
+- Activation failures: run `pm package doctor --detail deep --trace`
 - Policy blocks: review `settings.extensions.policy` and `details.summary.policy`
 - Runtime drift suspicion: compare with `pm --no-extensions <command>`
-- Managed-state update-check gaps: run `pm extension --manage --fix-managed-state`
+- Managed-state update-check gaps: run `pm package manage --fix-managed-state`
 
 ## Related Docs
 
 - `docs/SDK.md`
 - `docs/examples/starter-extension/README.md`
 - `docs/CLAUDE_CODE_PLUGIN.md`
-# Extensions
+# Extension Runtime Reference
 
 Extensions add commands, schema, renderers, importers/exporters, search adapters, lifecycle hooks, and selected runtime overrides without modifying core `pm-cli`.
 
 ## Agent Quick Context
 
-- Use `pm extension init ./my-extension` for a starter scaffold.
+- Use `pm package init ./my-package` for a starter scaffold.
 - Use `@unbrained/pm-cli/sdk` for public extension APIs.
 - Declare only the capabilities your extension uses.
-- Run `pm extension doctor --detail deep --trace` for activation failures.
+- Run `pm package doctor --detail deep --trace` for activation failures.
 - Use `--no-extensions` to isolate core behavior during incident triage.
 - Use `pm guide extensions --depth standard` for local docs routing.
 
@@ -719,44 +833,44 @@ Load order is global, then project. Project extensions take precedence when keys
 Scaffold:
 
 ```bash
-pm extension init ./my-extension
-pm extension scaffold ./my-extension
+pm package init ./my-package
+pm package scaffold ./my-package
 ```
 
 Install:
 
 ```bash
-pm extension install ./my-extension --project
-pm extension install github.com/unbraind/pm-cli/.agents/pm/extensions/todos --project
-pm extension --install --project todos
+pm package install ./my-package --project
+pm package install github.com/unbraind/pm-cli/packages/pm-todos --project
+pm install todos --project
 ```
 
 Inspect and manage:
 
 ```bash
-pm extension explore --project
-pm extension manage --project
-pm extension doctor --detail summary
-pm extension doctor --detail deep --trace
+pm package explore --project
+pm package manage --project
+pm package doctor --detail summary
+pm package doctor --detail deep --trace
 ```
 
 Activate and deactivate:
 
 ```bash
-pm extension activate my-extension --project
-pm extension deactivate my-extension --project
+pm package activate my-extension --project
+pm package deactivate my-extension --project
 ```
 
 Adopt unmanaged extensions:
 
 ```bash
-pm extension adopt my-extension --project
-pm extension adopt-all --project
+pm package adopt my-extension --project
+pm package adopt-all --project
 ```
 
 ## Install Sources
 
-`pm extension install` accepts:
+`pm install` and `pm package install` accept:
 
 - local directories
 - GitHub HTTPS URLs
@@ -898,7 +1012,7 @@ pm health --check-only
 
 ## Bundled Managed Extensions
 
-`pm-cli` ships bundled extension sources that are not auto-installed:
+`pm-cli` ships optional first-party package roots that are not auto-installed:
 
 | Alias | Commands after install | Purpose |
 |-------|------------------------|---------|
@@ -908,16 +1022,10 @@ pm health --check-only
 Install:
 
 ```bash
-pm extension --install --project beads
-pm extension --install --project todos
+pm install beads --project
+pm install todos --project
 ```
 
 ## Starter Extension
 
 See [examples/starter-extension](examples/starter-extension/README.md) for a compact extension that demonstrates all capability categories through the public SDK.
-
-## Pi Wrapper
-
-The Pi wrapper source is `.pi/extensions/pm-cli/index.ts`. It is an agent wrapper, not a runtime extension managed by `pm extension`.
-
-Use [AGENTS.md](../AGENTS.md) for repository-specific Pi wrapper operating rules.

package/docs/QUICKSTART.md

@@ -23,10 +23,10 @@ pm --version
 For updates, use the registry package again:
 
 ```bash
-npm install -g @unbrained/pm-cli@latest
+pm upgrade --cli-only
 ```
 
-Do not use the GitHub git URL as the normal global update path. If a previous git-sourced install left a stale `pm` shim, run `bash scripts/install.sh --repair` from a checkout or uninstall the package before reinstalling from npm.
+`pm upgrade` uses `npm install -g @unbrained/pm-cli@latest` for the CLI/SDK and can also refresh installed pm packages. Do not use the GitHub git URL as the normal global update path. If a previous git-sourced install left a stale `pm` shim, run `pm upgrade --cli-only --repair`, run `bash scripts/install.sh --repair` from a checkout, or uninstall the package before reinstalling from npm.
 
 For one-off use:
 
@@ -34,6 +34,15 @@ For one-off use:
 npx @unbrained/pm-cli --help
 ```
 
+Optional first-party packages are installable on demand:
+
+```bash
+pm package catalog --project
+pm install '*' --project
+pm install all --project
+pm package doctor --project --detail summary
+```
+
 ## Initialize a Repository
 
 ```bash

package/docs/README.md

@@ -21,8 +21,7 @@ pm guide release --json
 | New user | [Quickstart](QUICKSTART.md) | [Command Reference](COMMANDS.md) |
 | Coding agent | [Agent Guide](AGENT_GUIDE.md) | [Configuration](CONFIGURATION.md), then command help |
 | Maintainer | [Contributing](../CONTRIBUTING.md) | [Testing](TESTING.md), [Releasing](RELEASING.md), [Architecture](ARCHITECTURE.md) |
-| Extension author | [Extensions](EXTENSIONS.md) | [SDK](SDK.md), [starter extension](examples/starter-extension/README.md) |
-| Pi user | [Pi Package](PI_PACKAGE.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md) |
+| Package author | [Packages and Extensions](EXTENSIONS.md) | [SDK](SDK.md), [starter extension](examples/starter-extension/README.md) |
 | Codex user | [Codex Plugin](CODEX_PLUGIN.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md) |
 | Machine client | `pm guide commands` | [Command Reference](COMMANDS.md#machine-contracts), then `pm contracts --json` |
 
@@ -34,9 +33,8 @@ pm guide release --json
 - [Configuration](CONFIGURATION.md) - settings, storage formats, output, search, validation, and environment variables.
 - [Testing](TESTING.md) - sandbox-safe local tests and linked-test orchestration.
 - [Architecture](ARCHITECTURE.md) - contributor internals: storage, mutation flow, search, extensions, and command contracts.
-- [Extensions](EXTENSIONS.md) - runtime extension lifecycle and API reference.
+- [Packages and Extensions](EXTENSIONS.md) - package install workflows, runtime extension lifecycle, and API reference.
 - [SDK](SDK.md) - public import surfaces and typed authoring examples.
-- [Pi Package](PI_PACKAGE.md) - official Pi package install, native tool, skills, prompts, and workflows.
 - [Codex Plugin](CODEX_PLUGIN.md) - native MCP plugin install, tools, skills, and safety notes.
 - [Releasing](RELEASING.md) - maintainer release checklist and failure handling.
 - [starter extension](examples/starter-extension/README.md) - compact extension scaffold reference.
@@ -49,7 +47,7 @@ pm guide release --json
 | `commands` | [Command Reference](COMMANDS.md), [Configuration](CONFIGURATION.md) |
 | `workflows` | [Agent Guide](AGENT_GUIDE.md), [Testing](TESTING.md) |
 | `sdk` | [SDK](SDK.md), [Architecture](ARCHITECTURE.md) |
-| `extensions` | [Extensions](EXTENSIONS.md), [starter extension](examples/starter-extension/README.md) |
+| `extensions`, `packages` | [Packages and Extensions](EXTENSIONS.md), [starter extension](examples/starter-extension/README.md) |
 | `skills` | [Agent Guide](AGENT_GUIDE.md) plus `.agents/skills/*` |
 | `harnesses` | [Agent Guide](AGENT_GUIDE.md) plus `.agents/skills/HARNESS_COMPATIBILITY.md` |
 | `release` | [Releasing](RELEASING.md), [CHANGELOG](../CHANGELOG.md) |
@@ -68,7 +66,7 @@ Community files:
 2. Use [Command Reference](COMMANDS.md) for command families, not exhaustive flag memory.
 3. Use `pm <command> --help --json` or `pm contracts --command <name> --flags-only --json` for exact flags.
 4. Use [Architecture](ARCHITECTURE.md) only when changing internals or debugging behavior.
-5. Use [SDK](SDK.md) and [Extensions](EXTENSIONS.md) only when authoring or troubleshooting extensions.
+5. Use [SDK](SDK.md) and [Packages and Extensions](EXTENSIONS.md) only when authoring or troubleshooting packages/extensions.
 
 ## Tracker References