@unbrained/pm-cli 2026.5.6 → 2026.5.10

package/dist/types.d.ts

@@ -145,6 +145,10 @@ export interface RuntimeStatusDefinition {
 }
 export interface RuntimeFieldDefinition {
     key: string;
+    metadata_key?: string;
+    /**
+     * @deprecated Use metadata_key.
+     */
     front_matter_key?: string;
     cli_flag?: string;
     cli_aliases?: string[];
@@ -195,7 +199,7 @@ export interface ItemTestRunSummary {
     linked_tests?: number;
     fail_on_skipped_triggered?: boolean;
 }
-export interface ItemFrontMatter {
+export interface ItemMetadata {
     id: string;
     title: string;
     description: string;
@@ -258,8 +262,12 @@ export interface ItemFrontMatter {
     close_reason?: string;
     [key: string]: unknown;
 }
+/**
+ * @deprecated Use ItemMetadata.
+ */
+export type ItemFrontMatter = ItemMetadata;
 export interface ItemDocument {
-    front_matter: ItemFrontMatter;
+    metadata: ItemMetadata;
     body: string;
 }
 export interface HistoryPatchOp {

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"/","sources":["types.ts"],"names":[],"mappings":"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","sourcesContent":["export const BUILTIN_ITEM_TYPE_VALUES = [\n  \"Epic\",\n  \"Feature\",\n  \"Task\",\n  \"Chore\",\n  \"Issue\",\n  \"Decision\",\n  \"Event\",\n  \"Reminder\",\n  \"Milestone\",\n  \"Meeting\",\n] as const;\nexport const ITEM_TYPE_VALUES = BUILTIN_ITEM_TYPE_VALUES;\nexport type BuiltinItemType = (typeof BUILTIN_ITEM_TYPE_VALUES)[number];\nexport type ItemType = string;\n\nexport const STATUS_VALUES = [\n  \"draft\",\n  \"open\",\n  \"in_progress\",\n  \"blocked\",\n  \"closed\",\n  \"canceled\",\n] as const;\nexport type ItemStatus = string;\n\nexport const RUNTIME_STATUS_ROLE_VALUES = [\n  \"draft\",\n  \"active\",\n  \"blocked\",\n  \"terminal\",\n  \"terminal_done\",\n  \"terminal_canceled\",\n  \"default_open\",\n  \"default_close\",\n  \"default_cancel\",\n] as const;\nexport type RuntimeStatusRole = (typeof RUNTIME_STATUS_ROLE_VALUES)[number];\n\nexport const RUNTIME_FIELD_TYPE_VALUES = [\"string\", \"number\", \"boolean\", \"string_array\"] as const;\nexport type RuntimeFieldType = (typeof RUNTIME_FIELD_TYPE_VALUES)[number];\n\nexport const RUNTIME_FIELD_COMMAND_VALUES = [\"create\", \"update\", \"update_many\", \"list\", \"search\", \"calendar\", \"context\"] as const;\nexport type RuntimeFieldCommand = (typeof RUNTIME_FIELD_COMMAND_VALUES)[number];\n\nexport const RUNTIME_UNKNOWN_FIELD_POLICY_VALUES = [\"allow\", \"warn\", \"reject\"] as const;\nexport type RuntimeUnknownFieldPolicy = (typeof RUNTIME_UNKNOWN_FIELD_POLICY_VALUES)[number];\n\nexport const DEPENDENCY_KIND_VALUES = [\n  \"blocks\",\n  \"parent\",\n  \"child\",\n  \"parent_child\",\n  \"child_of\",\n  \"related\",\n  \"related_to\",\n  \"discovered_from\",\n  \"blocked_by\",\n  \"incident_from\",\n  \"epic\",\n  \"supersedes\",\n  \"task\",\n] as const;\nexport type DependencyKind = (typeof DEPENDENCY_KIND_VALUES)[number];\n\nexport const SCOPE_VALUES = [\"project\", \"global\"] as const;\nexport type LinkScope = (typeof SCOPE_VALUES)[number];\n\nexport const RISK_VALUES = [\"low\", \"medium\", \"high\", \"critical\"] as const;\nexport type RiskLevel = (typeof RISK_VALUES)[number];\n\nexport const ISSUE_SEVERITY_VALUES = [\"low\", \"medium\", \"high\", \"critical\"] as const;\nexport type IssueSeverity = (typeof ISSUE_SEVERITY_VALUES)[number];\n\nexport const CONFIDENCE_TEXT_VALUES = [\"low\", \"medium\", \"high\"] as const;\nexport type ConfidenceTextLevel = (typeof CONFIDENCE_TEXT_VALUES)[number];\nexport type ConfidenceValue = number | ConfidenceTextLevel;\n\nexport const ITEM_FORMAT_VALUES = [\"toon\", \"json_markdown\"] as const;\nexport type ItemFormat = (typeof ITEM_FORMAT_VALUES)[number];\n\nexport const SPRINT_RELEASE_FORMAT_POLICY_VALUES = [\"warn\", \"strict_error\"] as const;\nexport type SprintReleaseFormatPolicy = (typeof SPRINT_RELEASE_FORMAT_POLICY_VALUES)[number];\nexport const PARENT_REFERENCE_POLICY_VALUES = [\"warn\", \"strict_error\"] as const;\nexport type ParentReferencePolicy = (typeof PARENT_REFERENCE_POLICY_VALUES)[number];\nexport const VALIDATE_METADATA_PROFILE_VALUES = [\"core\", \"strict\", \"custom\"] as const;\nexport type ValidateMetadataProfile = (typeof VALIDATE_METADATA_PROFILE_VALUES)[number];\nexport const GOVERNANCE_PRESET_VALUES = [\"minimal\", \"default\", \"strict\", \"custom\"] as const;\nexport type GovernancePreset = (typeof GOVERNANCE_PRESET_VALUES)[number];\nexport const GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES = [\"none\", \"warn\", \"strict\"] as const;\nexport type GovernanceOwnershipEnforcement = (typeof GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES)[number];\nexport const GOVERNANCE_CREATE_MODE_DEFAULT_VALUES = [\"progressive\", \"strict\"] as const;\nexport type GovernanceCreateModeDefault = (typeof GOVERNANCE_CREATE_MODE_DEFAULT_VALUES)[number];\nexport const GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES = [\"off\", \"warn\", \"strict\"] as const;\nexport type GovernanceCloseValidationDefault = (typeof GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES)[number];\nexport const VALIDATE_METADATA_REQUIRED_FIELD_VALUES = [\n  \"author\",\n  \"acceptance_criteria\",\n  \"estimated_minutes\",\n  \"close_reason\",\n  \"reviewer\",\n  \"risk\",\n  \"confidence\",\n  \"sprint\",\n  \"release\",\n] as const;\nexport type ValidateMetadataRequiredField = (typeof VALIDATE_METADATA_REQUIRED_FIELD_VALUES)[number];\n\nexport const RECURRENCE_FREQUENCY_VALUES = [\"daily\", \"weekly\", \"monthly\", \"yearly\"] as const;\nexport type RecurrenceFrequency = (typeof RECURRENCE_FREQUENCY_VALUES)[number];\n\nexport const RECURRENCE_WEEKDAY_VALUES = [\"mon\", \"tue\", \"wed\", \"thu\", \"fri\", \"sat\", \"sun\"] as const;\nexport type RecurrenceWeekday = (typeof RECURRENCE_WEEKDAY_VALUES)[number];\n\nexport interface Dependency {\n  id: string;\n  kind: DependencyKind;\n  created_at: string;\n  author?: string;\n  source_kind?: string;\n}\n\nexport interface Comment {\n  created_at: string;\n  author: string;\n  text: string;\n}\n\nexport interface LogNote {\n  created_at: string;\n  author: string;\n  text: string;\n}\n\nexport interface LinkedFile {\n  path: string;\n  scope: LinkScope;\n  note?: string;\n}\n\nexport interface LinkedTest {\n  command?: string;\n  path?: string;\n  scope: LinkScope;\n  timeout_seconds?: number;\n  pm_context_mode?: \"schema\" | \"tracker\" | \"auto\";\n  env_set?: Record<string, string>;\n  env_clear?: string[];\n  shared_host_safe?: boolean;\n  assert_stdout_contains?: string[];\n  assert_stdout_regex?: string[];\n  assert_stderr_contains?: string[];\n  assert_stderr_regex?: string[];\n  assert_stdout_min_lines?: number;\n  assert_json_field_equals?: Record<string, string>;\n  assert_json_field_gte?: Record<string, number>;\n  note?: string;\n}\n\nexport interface LinkedDoc {\n  path: string;\n  scope: LinkScope;\n  note?: string;\n}\n\nexport interface Reminder {\n  at: string;\n  text: string;\n}\n\nexport interface RecurrenceRule {\n  freq: RecurrenceFrequency;\n  interval?: number;\n  count?: number;\n  until?: string;\n  by_weekday?: RecurrenceWeekday[];\n  by_month_day?: number[];\n  exdates?: string[];\n}\n\nexport interface CalendarEvent {\n  start_at: string;\n  end_at?: string;\n  title?: string;\n  description?: string;\n  location?: string;\n  all_day?: boolean;\n  timezone?: string;\n  recurrence?: RecurrenceRule;\n}\n\nexport interface ItemTypeOptionDefinition {\n  key: string;\n  values: string[];\n  required?: boolean;\n  aliases?: string[];\n  description?: string;\n}\n\nexport interface ItemTypeCommandOptionPolicy {\n  command: \"create\" | \"update\";\n  option: string;\n  required?: boolean;\n  visible?: boolean;\n  enabled?: boolean;\n}\n\nexport interface ItemTypeDefinition {\n  name: string;\n  folder?: string;\n  aliases?: string[];\n  required_create_fields?: string[];\n  required_create_repeatables?: string[];\n  options?: ItemTypeOptionDefinition[];\n  command_option_policies?: ItemTypeCommandOptionPolicy[];\n}\n\nexport interface RuntimeStatusDefinition {\n  id: string;\n  aliases?: string[];\n  roles?: RuntimeStatusRole[];\n  description?: string;\n  order?: number;\n}\n\nexport interface RuntimeFieldDefinition {\n  key: string;\n  front_matter_key?: string;\n  cli_flag?: string;\n  cli_aliases?: string[];\n  description?: string;\n  type?: RuntimeFieldType;\n  commands?: RuntimeFieldCommand[];\n  repeatable?: boolean;\n  required?: boolean;\n  required_on_create?: boolean;\n  required_types?: string[];\n  allow_unset?: boolean;\n}\n\nexport interface RuntimeWorkflowDefinition {\n  draft_status?: string;\n  open_status?: string;\n  in_progress_status?: string;\n  blocked_status?: string;\n  close_status?: string;\n  canceled_status?: string;\n}\n\nexport interface RuntimeSchemaFileConfig {\n  types?: string;\n  statuses?: string;\n  fields?: string;\n  workflows?: string;\n}\n\nexport interface RuntimeSchemaSettings {\n  version: number;\n  files: RuntimeSchemaFileConfig;\n  statuses: RuntimeStatusDefinition[];\n  fields: RuntimeFieldDefinition[];\n  workflow: RuntimeWorkflowDefinition;\n  unknown_field_policy: RuntimeUnknownFieldPolicy;\n}\n\nexport interface ItemTestRunSummary {\n  run_id: string;\n  kind: \"test\" | \"test-all\";\n  status: \"passed\" | \"failed\" | \"stopped\" | \"canceled\";\n  started_at: string;\n  finished_at: string;\n  recorded_at: string;\n  attempt?: number;\n  resumed_from?: string;\n  passed: number;\n  failed: number;\n  skipped: number;\n  items?: number;\n  linked_tests?: number;\n  fail_on_skipped_triggered?: boolean;\n}\n\nexport interface ItemFrontMatter {\n  id: string;\n  title: string;\n  description: string;\n  type: ItemType;\n  source_type?: string;\n  type_options?: Record<string, string>;\n  status: ItemStatus;\n  priority: 0 | 1 | 2 | 3 | 4;\n  tags: string[];\n  created_at: string;\n  updated_at: string;\n  deadline?: string;\n  reminders?: Reminder[];\n  events?: CalendarEvent[];\n  closed_at?: string;\n  assignee?: string;\n  source_owner?: string;\n  author?: string;\n  estimated_minutes?: number;\n  acceptance_criteria?: string;\n  design?: string;\n  external_ref?: string;\n  definition_of_ready?: string;\n  order?: number;\n  goal?: string;\n  objective?: string;\n  value?: string;\n  impact?: string;\n  outcome?: string;\n  why_now?: string;\n  parent?: string;\n  reviewer?: string;\n  risk?: \"low\" | \"medium\" | \"high\" | \"critical\";\n  confidence?: ConfidenceValue;\n  sprint?: string;\n  release?: string;\n  blocked_by?: string;\n  blocked_reason?: string;\n  unblock_note?: string;\n  reporter?: string;\n  severity?: IssueSeverity;\n  environment?: string;\n  repro_steps?: string;\n  resolution?: string;\n  expected_result?: string;\n  actual_result?: string;\n  affected_version?: string;\n  fixed_version?: string;\n  component?: string;\n  regression?: boolean;\n  customer_impact?: string;\n  dependencies?: Dependency[];\n  comments?: Comment[];\n  notes?: LogNote[];\n  learnings?: LogNote[];\n  files?: LinkedFile[];\n  tests?: LinkedTest[];\n  test_runs?: ItemTestRunSummary[];\n  docs?: LinkedDoc[];\n  close_reason?: string;\n  [key: string]: unknown;\n}\n\nexport interface ItemDocument {\n  front_matter: ItemFrontMatter;\n  body: string;\n}\n\nexport interface HistoryPatchOp {\n  op: \"add\" | \"remove\" | \"replace\" | \"move\" | \"copy\" | \"test\";\n  path: string;\n  from?: string;\n  value?: unknown;\n}\n\nexport interface HistoryEntry {\n  ts: string;\n  author: string;\n  op: string;\n  patch: HistoryPatchOp[];\n  before_hash: string;\n  after_hash: string;\n  message?: string;\n}\n\nexport const CONTEXT_DEPTH_VALUES = [\"brief\", \"standard\", \"deep\"] as const;\nexport type ContextDepth = (typeof CONTEXT_DEPTH_VALUES)[number];\n\nexport const CONTEXT_SECTION_VALUES = [\n  \"hierarchy\",\n  \"activity\",\n  \"progress\",\n  \"blockers\",\n  \"files\",\n  \"workload\",\n  \"staleness\",\n  \"tests\",\n] as const;\nexport type ContextSectionName = (typeof CONTEXT_SECTION_VALUES)[number];\n\nexport interface ContextSectionSettings {\n  hierarchy: boolean;\n  activity: boolean;\n  progress: boolean;\n  blockers: boolean;\n  files: boolean;\n  workload: boolean;\n  staleness: boolean;\n  tests: boolean;\n}\n\nexport interface ContextSettings {\n  default_depth: ContextDepth;\n  activity_limit: number;\n  stale_threshold_days: number;\n  sections: ContextSectionSettings;\n}\n\nexport interface GovernanceSettings {\n  preset: GovernancePreset;\n  ownership_enforcement: GovernanceOwnershipEnforcement;\n  create_mode_default: GovernanceCreateModeDefault;\n  close_validation_default: GovernanceCloseValidationDefault;\n  parent_reference: ParentReferencePolicy;\n  metadata_profile: ValidateMetadataProfile;\n  force_required_for_stale_lock: boolean;\n}\n\nexport interface PmSettings {\n  version: number;\n  id_prefix: string;\n  author_default: string;\n  item_format: ItemFormat;\n  locks: {\n    ttl_seconds: number;\n  };\n  output: {\n    default_format: \"toon\" | \"json\";\n  };\n  history: {\n    missing_stream: \"auto_create\" | \"strict_error\";\n  };\n  validation: {\n    sprint_release_format: SprintReleaseFormatPolicy;\n    parent_reference: ParentReferencePolicy;\n    metadata_profile: ValidateMetadataProfile;\n    metadata_required_fields: ValidateMetadataRequiredField[];\n    lifecycle_stale_blocker_reason_patterns: string[];\n    lifecycle_closure_like_blocked_reason_patterns: string[];\n    lifecycle_closure_like_resolution_patterns: string[];\n    lifecycle_closure_like_actual_result_patterns: string[];\n  };\n  governance: GovernanceSettings;\n  workflow: {\n    definition_of_done: string[];\n  };\n  testing: {\n    record_results_to_items: boolean;\n  };\n  telemetry: {\n    enabled: boolean;\n    first_run_prompt_completed: boolean;\n    capture_level: \"minimal\" | \"redacted\" | \"max\";\n    endpoint: string;\n    installation_id: string;\n    retention_days: number;\n  };\n  item_types: {\n    definitions: ItemTypeDefinition[];\n  };\n  schema: RuntimeSchemaSettings;\n  extensions: {\n    enabled: string[];\n    disabled: string[];\n  };\n  search: {\n    score_threshold: number;\n    hybrid_semantic_weight: number;\n    max_results: number;\n    embedding_model: string;\n    embedding_batch_size: number;\n    scanner_max_batch_retries: number;\n    provider?: string;\n    tuning?: {\n      title_exact_bonus?: number;\n      title_weight?: number;\n      description_weight?: number;\n      tags_weight?: number;\n      status_weight?: number;\n      body_weight?: number;\n      comments_weight?: number;\n      notes_weight?: number;\n      learnings_weight?: number;\n      dependencies_weight?: number;\n      linked_content_weight?: number;\n    };\n  };\n  providers: {\n    openai: {\n      base_url: string;\n      api_key: string;\n      model: string;\n    };\n    ollama: {\n      base_url: string;\n      model: string;\n    };\n  };\n  context: ContextSettings;\n  vector_store: {\n    adapter?: string;\n    qdrant: {\n      url: string;\n      api_key: string;\n    };\n    lancedb: {\n      path: string;\n    };\n  };\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"/","sources":["types.ts"],"names":[],"mappings":"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","sourcesContent":["export const BUILTIN_ITEM_TYPE_VALUES = [\n  \"Epic\",\n  \"Feature\",\n  \"Task\",\n  \"Chore\",\n  \"Issue\",\n  \"Decision\",\n  \"Event\",\n  \"Reminder\",\n  \"Milestone\",\n  \"Meeting\",\n] as const;\nexport const ITEM_TYPE_VALUES = BUILTIN_ITEM_TYPE_VALUES;\nexport type BuiltinItemType = (typeof BUILTIN_ITEM_TYPE_VALUES)[number];\nexport type ItemType = string;\n\nexport const STATUS_VALUES = [\n  \"draft\",\n  \"open\",\n  \"in_progress\",\n  \"blocked\",\n  \"closed\",\n  \"canceled\",\n] as const;\nexport type ItemStatus = string;\n\nexport const RUNTIME_STATUS_ROLE_VALUES = [\n  \"draft\",\n  \"active\",\n  \"blocked\",\n  \"terminal\",\n  \"terminal_done\",\n  \"terminal_canceled\",\n  \"default_open\",\n  \"default_close\",\n  \"default_cancel\",\n] as const;\nexport type RuntimeStatusRole = (typeof RUNTIME_STATUS_ROLE_VALUES)[number];\n\nexport const RUNTIME_FIELD_TYPE_VALUES = [\"string\", \"number\", \"boolean\", \"string_array\"] as const;\nexport type RuntimeFieldType = (typeof RUNTIME_FIELD_TYPE_VALUES)[number];\n\nexport const RUNTIME_FIELD_COMMAND_VALUES = [\"create\", \"update\", \"update_many\", \"list\", \"search\", \"calendar\", \"context\"] as const;\nexport type RuntimeFieldCommand = (typeof RUNTIME_FIELD_COMMAND_VALUES)[number];\n\nexport const RUNTIME_UNKNOWN_FIELD_POLICY_VALUES = [\"allow\", \"warn\", \"reject\"] as const;\nexport type RuntimeUnknownFieldPolicy = (typeof RUNTIME_UNKNOWN_FIELD_POLICY_VALUES)[number];\n\nexport const DEPENDENCY_KIND_VALUES = [\n  \"blocks\",\n  \"parent\",\n  \"child\",\n  \"parent_child\",\n  \"child_of\",\n  \"related\",\n  \"related_to\",\n  \"discovered_from\",\n  \"blocked_by\",\n  \"incident_from\",\n  \"epic\",\n  \"supersedes\",\n  \"task\",\n] as const;\nexport type DependencyKind = (typeof DEPENDENCY_KIND_VALUES)[number];\n\nexport const SCOPE_VALUES = [\"project\", \"global\"] as const;\nexport type LinkScope = (typeof SCOPE_VALUES)[number];\n\nexport const RISK_VALUES = [\"low\", \"medium\", \"high\", \"critical\"] as const;\nexport type RiskLevel = (typeof RISK_VALUES)[number];\n\nexport const ISSUE_SEVERITY_VALUES = [\"low\", \"medium\", \"high\", \"critical\"] as const;\nexport type IssueSeverity = (typeof ISSUE_SEVERITY_VALUES)[number];\n\nexport const CONFIDENCE_TEXT_VALUES = [\"low\", \"medium\", \"high\"] as const;\nexport type ConfidenceTextLevel = (typeof CONFIDENCE_TEXT_VALUES)[number];\nexport type ConfidenceValue = number | ConfidenceTextLevel;\n\nexport const ITEM_FORMAT_VALUES = [\"toon\", \"json_markdown\"] as const;\nexport type ItemFormat = (typeof ITEM_FORMAT_VALUES)[number];\n\nexport const SPRINT_RELEASE_FORMAT_POLICY_VALUES = [\"warn\", \"strict_error\"] as const;\nexport type SprintReleaseFormatPolicy = (typeof SPRINT_RELEASE_FORMAT_POLICY_VALUES)[number];\nexport const PARENT_REFERENCE_POLICY_VALUES = [\"warn\", \"strict_error\"] as const;\nexport type ParentReferencePolicy = (typeof PARENT_REFERENCE_POLICY_VALUES)[number];\nexport const VALIDATE_METADATA_PROFILE_VALUES = [\"core\", \"strict\", \"custom\"] as const;\nexport type ValidateMetadataProfile = (typeof VALIDATE_METADATA_PROFILE_VALUES)[number];\nexport const GOVERNANCE_PRESET_VALUES = [\"minimal\", \"default\", \"strict\", \"custom\"] as const;\nexport type GovernancePreset = (typeof GOVERNANCE_PRESET_VALUES)[number];\nexport const GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES = [\"none\", \"warn\", \"strict\"] as const;\nexport type GovernanceOwnershipEnforcement = (typeof GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES)[number];\nexport const GOVERNANCE_CREATE_MODE_DEFAULT_VALUES = [\"progressive\", \"strict\"] as const;\nexport type GovernanceCreateModeDefault = (typeof GOVERNANCE_CREATE_MODE_DEFAULT_VALUES)[number];\nexport const GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES = [\"off\", \"warn\", \"strict\"] as const;\nexport type GovernanceCloseValidationDefault = (typeof GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES)[number];\nexport const VALIDATE_METADATA_REQUIRED_FIELD_VALUES = [\n  \"author\",\n  \"acceptance_criteria\",\n  \"estimated_minutes\",\n  \"close_reason\",\n  \"reviewer\",\n  \"risk\",\n  \"confidence\",\n  \"sprint\",\n  \"release\",\n] as const;\nexport type ValidateMetadataRequiredField = (typeof VALIDATE_METADATA_REQUIRED_FIELD_VALUES)[number];\n\nexport const RECURRENCE_FREQUENCY_VALUES = [\"daily\", \"weekly\", \"monthly\", \"yearly\"] as const;\nexport type RecurrenceFrequency = (typeof RECURRENCE_FREQUENCY_VALUES)[number];\n\nexport const RECURRENCE_WEEKDAY_VALUES = [\"mon\", \"tue\", \"wed\", \"thu\", \"fri\", \"sat\", \"sun\"] as const;\nexport type RecurrenceWeekday = (typeof RECURRENCE_WEEKDAY_VALUES)[number];\n\nexport interface Dependency {\n  id: string;\n  kind: DependencyKind;\n  created_at: string;\n  author?: string;\n  source_kind?: string;\n}\n\nexport interface Comment {\n  created_at: string;\n  author: string;\n  text: string;\n}\n\nexport interface LogNote {\n  created_at: string;\n  author: string;\n  text: string;\n}\n\nexport interface LinkedFile {\n  path: string;\n  scope: LinkScope;\n  note?: string;\n}\n\nexport interface LinkedTest {\n  command?: string;\n  path?: string;\n  scope: LinkScope;\n  timeout_seconds?: number;\n  pm_context_mode?: \"schema\" | \"tracker\" | \"auto\";\n  env_set?: Record<string, string>;\n  env_clear?: string[];\n  shared_host_safe?: boolean;\n  assert_stdout_contains?: string[];\n  assert_stdout_regex?: string[];\n  assert_stderr_contains?: string[];\n  assert_stderr_regex?: string[];\n  assert_stdout_min_lines?: number;\n  assert_json_field_equals?: Record<string, string>;\n  assert_json_field_gte?: Record<string, number>;\n  note?: string;\n}\n\nexport interface LinkedDoc {\n  path: string;\n  scope: LinkScope;\n  note?: string;\n}\n\nexport interface Reminder {\n  at: string;\n  text: string;\n}\n\nexport interface RecurrenceRule {\n  freq: RecurrenceFrequency;\n  interval?: number;\n  count?: number;\n  until?: string;\n  by_weekday?: RecurrenceWeekday[];\n  by_month_day?: number[];\n  exdates?: string[];\n}\n\nexport interface CalendarEvent {\n  start_at: string;\n  end_at?: string;\n  title?: string;\n  description?: string;\n  location?: string;\n  all_day?: boolean;\n  timezone?: string;\n  recurrence?: RecurrenceRule;\n}\n\nexport interface ItemTypeOptionDefinition {\n  key: string;\n  values: string[];\n  required?: boolean;\n  aliases?: string[];\n  description?: string;\n}\n\nexport interface ItemTypeCommandOptionPolicy {\n  command: \"create\" | \"update\";\n  option: string;\n  required?: boolean;\n  visible?: boolean;\n  enabled?: boolean;\n}\n\nexport interface ItemTypeDefinition {\n  name: string;\n  folder?: string;\n  aliases?: string[];\n  required_create_fields?: string[];\n  required_create_repeatables?: string[];\n  options?: ItemTypeOptionDefinition[];\n  command_option_policies?: ItemTypeCommandOptionPolicy[];\n}\n\nexport interface RuntimeStatusDefinition {\n  id: string;\n  aliases?: string[];\n  roles?: RuntimeStatusRole[];\n  description?: string;\n  order?: number;\n}\n\nexport interface RuntimeFieldDefinition {\n  key: string;\n  metadata_key?: string;\n  /**\n   * @deprecated Use metadata_key.\n   */\n  front_matter_key?: string;\n  cli_flag?: string;\n  cli_aliases?: string[];\n  description?: string;\n  type?: RuntimeFieldType;\n  commands?: RuntimeFieldCommand[];\n  repeatable?: boolean;\n  required?: boolean;\n  required_on_create?: boolean;\n  required_types?: string[];\n  allow_unset?: boolean;\n}\n\nexport interface RuntimeWorkflowDefinition {\n  draft_status?: string;\n  open_status?: string;\n  in_progress_status?: string;\n  blocked_status?: string;\n  close_status?: string;\n  canceled_status?: string;\n}\n\nexport interface RuntimeSchemaFileConfig {\n  types?: string;\n  statuses?: string;\n  fields?: string;\n  workflows?: string;\n}\n\nexport interface RuntimeSchemaSettings {\n  version: number;\n  files: RuntimeSchemaFileConfig;\n  statuses: RuntimeStatusDefinition[];\n  fields: RuntimeFieldDefinition[];\n  workflow: RuntimeWorkflowDefinition;\n  unknown_field_policy: RuntimeUnknownFieldPolicy;\n}\n\nexport interface ItemTestRunSummary {\n  run_id: string;\n  kind: \"test\" | \"test-all\";\n  status: \"passed\" | \"failed\" | \"stopped\" | \"canceled\";\n  started_at: string;\n  finished_at: string;\n  recorded_at: string;\n  attempt?: number;\n  resumed_from?: string;\n  passed: number;\n  failed: number;\n  skipped: number;\n  items?: number;\n  linked_tests?: number;\n  fail_on_skipped_triggered?: boolean;\n}\n\nexport interface ItemMetadata {\n  id: string;\n  title: string;\n  description: string;\n  type: ItemType;\n  source_type?: string;\n  type_options?: Record<string, string>;\n  status: ItemStatus;\n  priority: 0 | 1 | 2 | 3 | 4;\n  tags: string[];\n  created_at: string;\n  updated_at: string;\n  deadline?: string;\n  reminders?: Reminder[];\n  events?: CalendarEvent[];\n  closed_at?: string;\n  assignee?: string;\n  source_owner?: string;\n  author?: string;\n  estimated_minutes?: number;\n  acceptance_criteria?: string;\n  design?: string;\n  external_ref?: string;\n  definition_of_ready?: string;\n  order?: number;\n  goal?: string;\n  objective?: string;\n  value?: string;\n  impact?: string;\n  outcome?: string;\n  why_now?: string;\n  parent?: string;\n  reviewer?: string;\n  risk?: \"low\" | \"medium\" | \"high\" | \"critical\";\n  confidence?: ConfidenceValue;\n  sprint?: string;\n  release?: string;\n  blocked_by?: string;\n  blocked_reason?: string;\n  unblock_note?: string;\n  reporter?: string;\n  severity?: IssueSeverity;\n  environment?: string;\n  repro_steps?: string;\n  resolution?: string;\n  expected_result?: string;\n  actual_result?: string;\n  affected_version?: string;\n  fixed_version?: string;\n  component?: string;\n  regression?: boolean;\n  customer_impact?: string;\n  dependencies?: Dependency[];\n  comments?: Comment[];\n  notes?: LogNote[];\n  learnings?: LogNote[];\n  files?: LinkedFile[];\n  tests?: LinkedTest[];\n  test_runs?: ItemTestRunSummary[];\n  docs?: LinkedDoc[];\n  close_reason?: string;\n  [key: string]: unknown;\n}\n\n/**\n * @deprecated Use ItemMetadata.\n */\nexport type ItemFrontMatter = ItemMetadata;\n\nexport interface ItemDocument {\n  metadata: ItemMetadata;\n  body: string;\n}\n\nexport interface HistoryPatchOp {\n  op: \"add\" | \"remove\" | \"replace\" | \"move\" | \"copy\" | \"test\";\n  path: string;\n  from?: string;\n  value?: unknown;\n}\n\nexport interface HistoryEntry {\n  ts: string;\n  author: string;\n  op: string;\n  patch: HistoryPatchOp[];\n  before_hash: string;\n  after_hash: string;\n  message?: string;\n}\n\nexport const CONTEXT_DEPTH_VALUES = [\"brief\", \"standard\", \"deep\"] as const;\nexport type ContextDepth = (typeof CONTEXT_DEPTH_VALUES)[number];\n\nexport const CONTEXT_SECTION_VALUES = [\n  \"hierarchy\",\n  \"activity\",\n  \"progress\",\n  \"blockers\",\n  \"files\",\n  \"workload\",\n  \"staleness\",\n  \"tests\",\n] as const;\nexport type ContextSectionName = (typeof CONTEXT_SECTION_VALUES)[number];\n\nexport interface ContextSectionSettings {\n  hierarchy: boolean;\n  activity: boolean;\n  progress: boolean;\n  blockers: boolean;\n  files: boolean;\n  workload: boolean;\n  staleness: boolean;\n  tests: boolean;\n}\n\nexport interface ContextSettings {\n  default_depth: ContextDepth;\n  activity_limit: number;\n  stale_threshold_days: number;\n  sections: ContextSectionSettings;\n}\n\nexport interface GovernanceSettings {\n  preset: GovernancePreset;\n  ownership_enforcement: GovernanceOwnershipEnforcement;\n  create_mode_default: GovernanceCreateModeDefault;\n  close_validation_default: GovernanceCloseValidationDefault;\n  parent_reference: ParentReferencePolicy;\n  metadata_profile: ValidateMetadataProfile;\n  force_required_for_stale_lock: boolean;\n}\n\nexport interface PmSettings {\n  version: number;\n  id_prefix: string;\n  author_default: string;\n  item_format: ItemFormat;\n  locks: {\n    ttl_seconds: number;\n  };\n  output: {\n    default_format: \"toon\" | \"json\";\n  };\n  history: {\n    missing_stream: \"auto_create\" | \"strict_error\";\n  };\n  validation: {\n    sprint_release_format: SprintReleaseFormatPolicy;\n    parent_reference: ParentReferencePolicy;\n    metadata_profile: ValidateMetadataProfile;\n    metadata_required_fields: ValidateMetadataRequiredField[];\n    lifecycle_stale_blocker_reason_patterns: string[];\n    lifecycle_closure_like_blocked_reason_patterns: string[];\n    lifecycle_closure_like_resolution_patterns: string[];\n    lifecycle_closure_like_actual_result_patterns: string[];\n  };\n  governance: GovernanceSettings;\n  workflow: {\n    definition_of_done: string[];\n  };\n  testing: {\n    record_results_to_items: boolean;\n  };\n  telemetry: {\n    enabled: boolean;\n    first_run_prompt_completed: boolean;\n    capture_level: \"minimal\" | \"redacted\" | \"max\";\n    endpoint: string;\n    installation_id: string;\n    retention_days: number;\n  };\n  item_types: {\n    definitions: ItemTypeDefinition[];\n  };\n  schema: RuntimeSchemaSettings;\n  extensions: {\n    enabled: string[];\n    disabled: string[];\n  };\n  search: {\n    score_threshold: number;\n    hybrid_semantic_weight: number;\n    max_results: number;\n    embedding_model: string;\n    embedding_batch_size: number;\n    scanner_max_batch_retries: number;\n    provider?: string;\n    tuning?: {\n      title_exact_bonus?: number;\n      title_weight?: number;\n      description_weight?: number;\n      tags_weight?: number;\n      status_weight?: number;\n      body_weight?: number;\n      comments_weight?: number;\n      notes_weight?: number;\n      learnings_weight?: number;\n      dependencies_weight?: number;\n      linked_content_weight?: number;\n    };\n  };\n  providers: {\n    openai: {\n      base_url: string;\n      api_key: string;\n      model: string;\n    };\n    ollama: {\n      base_url: string;\n      model: string;\n    };\n  };\n  context: ContextSettings;\n  vector_store: {\n    adapter?: string;\n    qdrant: {\n      url: string;\n      api_key: string;\n    };\n    lancedb: {\n      path: string;\n    };\n  };\n}\n"]}

package/docs/AGENT_GUIDE.md

@@ -11,6 +11,7 @@ pm context --limit 10
 pm search "<request keywords>" --limit 10
 pm list-open --limit 20
 pm list-in-progress --limit 20
+pm guide workflows
 ```
 
 If a relevant item exists, reuse it. If not, create a parent lineage, then create and claim the child implementation item.
@@ -94,9 +95,22 @@ pm release <item-id>
 | Low-noise machine contracts | `pm contracts --command <command> --flags-only --json` |
 | Timeline | `pm activity --id <id> --limit 20` |
 | Dependencies | `pm deps <id> --format tree` |
+| Local docs routing | `pm guide <topic>` |
 
 Default TOON output is preferred for model-readable loops. Use `--json` only when strict parsing is needed.
 
+## Guide Routing for Agents
+
+Use `pm guide` as the local progressive-disclosure router before opening large documents:
+
+```bash
+pm guide
+pm guide quickstart
+pm guide commands --depth standard
+pm guide skills --depth deep --format markdown
+pm guide release --json
+```
+
 ## Ownership Rules
 
 - Claim before heavy edits.
@@ -109,6 +123,7 @@ Default TOON output is preferred for model-readable loops. Use `--json` only whe
 
 - Keep [README](../README.md) short.
 - Put details in focused docs under `docs/`.
+- Keep reusable workflow prompts in `.agents/skills/*` and route via `pm guide skills`.
 - Use relative links such as `[Command Reference](COMMANDS.md)`.
 - Add tracker references near the top of new docs when a task created the change.
 - Link docs back to the active item with `pm docs`.

package/docs/ARCHITECTURE.md

@@ -125,7 +125,7 @@ body: |
   Implementation notes.
 ```
 
-Alternative format is JSON-front-matter markdown. `front_matter` is the internal TypeScript model key; TOON stores the same metadata as top-level fields.
+Legacy JSON-front-matter markdown files are read only for one-way migration into TOON. Runtime internals use `metadata` as the item metadata model key.
 
 Built-in item types:
 
@@ -223,7 +223,7 @@ Search supports:
 - semantic mode, when an embedding provider and vector store are available
 - hybrid mode, combining keyword and semantic results
 
-Keyword scoring uses weighted fields such as title, description, tags, status, body, comments, notes, learnings, and dependencies.
+Keyword scoring uses weighted fields such as title, description, tags, status, body, comments, notes, learnings, reminders, events, and dependencies. Semantic indexing uses the same core corpus so calendar-heavy work remains discoverable through normal search and reindex flows.
 
 Runtime semantic components can come from built-ins or extensions:
 

package/docs/CLAUDE_CODE_PLUGIN.md

@@ -0,0 +1,186 @@
+# pm CLI — Claude Code Plugin
+
+Native pm integration for Claude Code via the Model Context Protocol (MCP). Claude can use all pm operations as native tools — no shell invocation, no context switching.
+
+## Architecture
+
+```
+pm-cli/ (repo root)
+├── .claude-plugin/
+│   └── marketplace.json     # Root marketplace catalog — read by /plugin marketplace add
+├── plugins/pm-cli-claude/
+│   ├── .claude-plugin/
+│   │   └── plugin.json      # Claude Code plugin manifest (name: "pm-cli")
+│   ├── .mcp.json            # MCP server config using ${CLAUDE_PLUGIN_ROOT}
+│   ├── skills/
+│   │   ├── pm-workflow/     # Auto-invoked: orient → claim → implement → close
+│   │   ├── pm-developer/    # Developer execution loop with evidence requirements
+│   │   ├── pm-release/      # Release gate sequence and evidence linking
+│   │   ├── pm-audit/        # Comprehensive audit suite
+│   │   └── pm-planner/      # Planning: decompose, prioritize, triage
+│   ├── commands/
+│   │   ├── pm-status.md     # /pm-status
+│   │   ├── pm-start-task.md # /pm-start-task [id|keywords]
+│   │   ├── pm-close-task.md # /pm-close-task [id]
+│   │   ├── pm-triage.md     # /pm-triage <request>
+│   │   ├── pm-audit.md      # /pm-audit
+│   │   ├── pm-search.md     # /pm-search <query>
+│   │   ├── pm-new.md        # /pm-new <title>
+│   │   ├── pm-list.md       # /pm-list [filter]
+│   │   └── pm-calendar.md   # /pm-calendar [view]
+│   ├── hooks/
+│   │   ├── hooks.json       # SessionStart hook definition
+│   │   └── session-start.mjs # Injects pm context at session start
+│   ├── agents/
+│   │   └── pm-coordinator.md # Subagent for multi-item coordination
+│   ├── scripts/
+│   │   └── pm-mcp-server.mjs # MCP server launcher (repo → npx fallback)
+│   └── README.md            # User-facing installation guide
+└── scripts/
+    └── smoke-claude-plugin.mjs  # Full plugin smoke test (run in CI)
+```
+
+The MCP server itself lives at `src/mcp/server.ts` (compiled to `dist/mcp/server.js`) and is bundled with the npm package as the `pm-mcp` binary.
+
+## MCP Server Tools
+
+The server exposes 18 native tools that call pm library functions directly:
+
+| Tool | pm Operation | Key Args |
+|------|-------------|----------|
+| `pm_context` | `pm context` | `options.limit`, `options.depth` |
+| `pm_search` | `pm search` | `query` (required), `options.limit` |
+| `pm_list` | `pm list` | `options.status`, `options.type`, `options.limit` |
+| `pm_get` | `pm get` | `id` (required) |
+| `pm_create` | `pm create` | `options.title`, `options.description`, `options.type` |
+| `pm_update` | `pm update` | `id` (required), `options.*` |
+| `pm_claim` | `pm claim` | `id` (required), `force` |
+| `pm_release` | `pm release` | `id` (required), `force` |
+| `pm_close` | `pm close` | `id` (required), `reason` (required) |
+| `pm_comments` | `pm comments` | `id` (required), `options.add` |
+| `pm_files` | `pm files` | `id` (required), `options.add`, `options.remove` |
+| `pm_docs` | `pm docs` | `id` (required), `options.add`, `options.remove` |
+| `pm_test` | `pm test` | `id` (required), `options.add`, `options.run` |
+| `pm_validate` | `pm validate` | `options.checkResolution`, `options.checkFiles` |
+| `pm_health` | `pm health` | `options.checkOnly` |
+| `pm_contracts` | `pm contracts` | `options.command`, `options.json` |
+| `pm_guide` | `pm guide` | `options.topic`, `options.depth` |
+| `pm_run` | any pm action | `action` (required), `id`, `query`, `reason`, `options.*` |
+
+All tools accept `cwd` (workspace directory), `path` (pm data root override), and `author` (mutation author).
+
+## Installation Methods
+
+### 1. Plugin marketplace (recommended — full feature set)
+
+Add the pm-cli GitHub repo as a marketplace source, then install:
+
+```
+/plugin marketplace add unbraind/pm-cli
+/plugin install pm-cli@pm-cli
+```
+
+This clones the repo, reads `.claude-plugin/marketplace.json` at the root, installs the plugin from `./plugins/pm-cli-claude/`, and configures the MCP server, 5 skills, 9 slash commands, and the session hook automatically.
+
+### 2. Global MCP via Claude Code CLI (MCP tools only)
+
+```bash
+claude mcp add --transport stdio pm-cli-native -- npx -y @unbrained/pm-cli pm-mcp
+```
+
+Gives you the 18 MCP tools without skills or slash commands.
+
+### 3. Direct project `.mcp.json` (project-scoped MCP only)
+
+Add to the project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "pm-cli-native": {
+      "command": "node",
+      "args": ["./plugins/pm-cli-claude/scripts/pm-mcp-server.mjs"],
+      "env": { "PM_AUTHOR": "claude-code-agent" }
+    }
+  }
+}
+```
+
+The repo root `.mcp.json` uses this approach — activates automatically when Claude Code opens this repository.
+
+## MCP Server Launcher
+
+`plugins/pm-cli-claude/scripts/pm-mcp-server.mjs` resolves the server in order:
+
+1. `PM_CLI_MCP_SERVER` env var (explicit override)
+2. `dist/mcp/server.js` walking up from the launcher (repo checkout)
+3. `npx -y @unbrained/pm-cli@latest pm-mcp` (npm-installed fallback)
+
+This means the plugin works both from a repo checkout and from an npm-cached plugin install.
+
+## Session Start Hook
+
+`hooks/session-start.mjs` runs at the start of each Claude Code session. It:
+
+1. Checks for `.agents/pm/settings.json` in the current workspace.
+2. Exits silently if pm is not initialized.
+3. Runs `pm context --limit 5 --json` with a 5-second timeout.
+4. Injects a compact status line into the session context.
+
+Example injection:
+```
+pm tracker: 3 in_progress, 2 open
+  • [pm-xxxx] Fix authentication bug (in_progress)
+  • [pm-yyyy] Add calendar feature (in_progress)
+  • [pm-zzzz] Update docs (open)
+Use pm_context tool or /pm-status for full details.
+```
+
+## Testing the Plugin
+
+### Full Claude Code plugin smoke test (runs in CI)
+
+```bash
+node scripts/smoke-claude-plugin.mjs
+# or:
+pnpm smoke:claude-plugin
+```
+
+Verifies: file structure (23 files), manifest name consistency, MCP initialize, 18 tools present, full workflow (init → create → claim → update → link files/docs/tests → get → context → search → validate → health), and session-start hook.
+
+### MCP server smoke test
+
+```bash
+node scripts/smoke-codex-plugin-mcp.mjs
+# or:
+pnpm smoke:codex-plugin
+```
+
+### Validate manifests
+
+```bash
+claude plugin validate .claude-plugin/marketplace.json
+claude plugin validate plugins/pm-cli-claude/.claude-plugin/plugin.json
+```
+
+### Manual verification
+
+After installing the plugin:
+
+1. Start Claude Code: `claude` (in a pm-initialized directory)
+2. Ask: "What's the current pm project status?"
+   → Verify Claude uses `pm_context` (not Bash)
+3. Try `/pm-status` — active items + calendar
+4. Try `/pm-search authentication` — search results
+5. Try `/pm-new Fix the login timeout bug` — duplicate-checked create
+6. Try `/pm-start-task pm-xxxx` — claim and start
+7. Try `/pm-calendar week` — upcoming deadlines
+8. Try `/pm-close-task pm-xxxx` — verify, evidence, close
+
+## Compatibility
+
+| pm-cli version | Plugin version | Claude Code version |
+|---------------|----------------|---------------------|
+| 2026.5.x+ | 1.0.0 | Any current |
+
+The MCP server uses JSON-RPC 2.0 over stdio with protocol version `2025-06-18`.

package/docs/CODEX_PLUGIN.md

@@ -0,0 +1,33 @@
+# Codex Plugin
+
+pm-cli ships a repo-local Codex plugin at [`plugins/pm-cli-codex`](../plugins/pm-cli-codex/README.md).
+
+## Install From This Repo
+
+```bash
+codex plugin marketplace add .
+```
+
+Restart Codex and install **pm CLI** from the `pm CLI Local` marketplace.
+
+## What It Provides
+
+- `pm-cli-native` MCP server for structured pm operations without invoking the `pm` shell command
+- narrow tools for common loops: context, search, list, get, create, update, claim, release, close, comments, files, docs, tests, validate, health, contracts, and guide
+- `pm_run` for the rest of the pm surface, including calendar, activity, aggregate, dedupe-audit, normalize, reindex, extensions, templates, history, stats, gc, and test-runs controls
+- skills for native tracking, audits, and release workflows
+- command prompts for start, close, and audit flows
+
+## Native MCP Notes
+
+The plugin launcher uses the local repository build when `dist/mcp/server.js` is present. When the plugin is cached outside the repo, it falls back to:
+
+```bash
+npx -y @unbrained/pm-cli@latest pm-mcp
+```
+
+The fallback starts the package MCP server, not the `pm` CLI command. Tool calls import pm command modules and return JSON-compatible structured results.
+
+## Safety
+
+For real repository tracking, leave `path` unset so pm uses the repository `.agents/pm` root. For tests, use a sandbox `cwd` or `path` and isolate `PM_GLOBAL_PATH`.

package/docs/COMMANDS.md

@@ -6,12 +6,14 @@ This is a task-oriented command guide. For exact flags, use runtime help because
 pm <command> --help
 pm <command> --help --json
 pm contracts --command <command> --flags-only --json
+pm guide commands --depth standard
 ```
 
 ## Agent Quick Context
 
 - Prefer `pm context`, `pm search`, and narrow list commands before mutation.
 - Prefer TOON for reading and `--json` for strict parsing.
+- Use `pm guide <topic>` for local docs routing before opening deeper pages.
 - Use `pm contracts` for machine clients.
 - Every mutation writes history.
 
@@ -30,7 +32,7 @@ Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 | 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 |
-| Machines | `contracts`, `completion`, `help` | expose stable command contracts and shell helpers |
+| Machines | `guide`, `contracts`, `completion`, `help` | local docs routing plus command contracts and shell helpers |
 
 ## Bootstrap
 
@@ -118,11 +120,13 @@ pm release <id> --allow-audit-release --author <you>
 
 ```bash
 pm comments <id> "Implemented command parsing fix."
+printf '%s\n' '## Verification summary' '- Linux pass' '- macOS pass' | pm comments <id> --stdin
+pm comments <id> --file docs/release-evidence.md
 pm notes <id> --add "Keep renderer changes isolated to TOON output."
 pm learnings <id> --add "Use runtime contracts instead of duplicating flag lists."
 ```
 
-Use comments for progress and evidence, notes for implementation context, and learnings for durable future guidance.
+Use comments for progress and evidence, notes for implementation context, and learnings for durable future guidance. For comments, choose exactly one input source (`[text]`, `--add`, `--stdin`, or `--file`) per invocation.
 
 ## Linked Artifacts
 

package/docs/CONFIGURATION.md

@@ -40,7 +40,7 @@ Precedence:
 |---------|---------|
 | `id_prefix` | generated item ID prefix, default `pm-` |
 | `author_default` | fallback mutation author |
-| `item_format` | `toon` or `json_markdown` item files |
+| `item_format` | item storage format (`toon` writes; legacy markdown is read/migrate only) |
 | `output.default_format` | default renderer, usually `toon` |
 | `locks.ttl_seconds` | stale lock threshold |
 | `history.missing_stream` | `auto_create` or `strict_error` |
@@ -70,13 +70,7 @@ TOON is the default:
 pm config project set item-format --format toon
 ```
 
-JSON-front-matter markdown is also supported:
-
-```bash
-pm config project set item-format --format json_markdown
-```
-
-Changing item format runs migration on item files. History stays JSONL.
+Markdown item files are treated as legacy migration input only. Mutations always write TOON files, and history stays JSONL.
 
 ## Output Format
 

package/docs/EXTENSIONS.md

@@ -9,6 +9,7 @@ Extensions add commands, schema, renderers, importers/exporters, search adapters
 - Declare only the capabilities your extension uses.
 - Run `pm extension 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.
 
 Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 

package/docs/PI_PACKAGE.md

@@ -0,0 +1,56 @@
+# Pi Native Package
+
+pm-cli ships an official Pi package so Pi can use pm through a native extension instead of shelling out to the `pm` CLI.
+
+## Install
+
+After the package is published:
+
+```bash
+pi install npm:@unbrained/pm-cli
+```
+
+If you install an unscoped npm alias, use the same Pi syntax, for example `pi install npm:pm-cli`. The published package in this repository is `@unbrained/pm-cli`.
+
+From a local checkout:
+
+```bash
+pnpm build
+pi install -l .
+# or try without writing settings
+pi --no-extensions -e .
+```
+
+`pnpm build` is required for local checkouts because the Pi extension imports the compiled native integration from `dist/pi/native.js`.
+
+## Package Resources
+
+The root `package.json` declares the Pi manifest:
+
+- `pi.extensions`: `.pi/extensions/pm-cli/index.js`
+- `pi.skills`: `.pi/skills`
+- `pi.prompts`: `.pi/prompts`
+
+The extension registers:
+
+- native `pm` tool using pm command modules directly, not the `pm` shell command
+- `/pm-context`, `/pm-start`, `/pm-close`, and `/pm-actions` helper commands
+- status footer entry `pm native`
+
+## Native Tool Usage
+
+Use the Pi `pm` tool with an `action` field. Examples:
+
+```json
+{ "action": "context", "limit": 10 }
+{ "action": "search", "query": "pi extension", "limit": 10 }
+{ "action": "start-task", "id": "pm-1234", "author": "pi-agent" }
+{ "action": "files", "id": "pm-1234", "add": ["path=src/file.ts,scope=project,note=implementation"], "author": "pi-agent" }
+{ "action": "close-task", "id": "pm-1234", "text": "Verified and complete", "author": "pi-agent", "validateClose": "warn" }
+```
+
+For real project tracking, leave `path` unset. For tests, set `path` to a sandbox pm root and isolate `PM_GLOBAL_PATH`.
+
+## Supported Surface
+
+The native integration covers the core pm action set exposed by the SDK contracts: init/config/extensions, item creation and lifecycle, list/search/context/calendar/activity, files/docs/deps/tests, validation/health/gc/contracts, templates, test-runs, and guide workflows.

package/docs/QUICKSTART.md

@@ -9,6 +9,7 @@ Use this page to get from a clean repository to a tracked, verified item.
 - Claim before implementation.
 - Link changed files, docs, and tests to the item.
 - Close only after evidence is recorded.
+- Use `pm guide quickstart` or `pm guide workflows` when you need local docs routing.
 
 Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 

package/docs/README.md

@@ -2,6 +2,18 @@
 
 This directory is the public documentation home for `pm-cli`. It is organized for progressive disclosure: read the smallest page that answers the current question, then follow links only when more detail is needed.
 
+## CLI Guide Router
+
+`pm guide` exposes the same documentation routes from inside the CLI:
+
+```bash
+pm guide
+pm guide quickstart
+pm guide commands --depth standard
+pm guide sdk --depth deep --format markdown
+pm guide release --json
+```
+
 ## Read Path
 
 | Reader | First page | Then read |
@@ -10,7 +22,9 @@ This directory is the public documentation home for `pm-cli`. It is organized fo
 | 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) |
-| Machine client | [Command Reference](COMMANDS.md#machine-contracts) | `pm contracts --json` |
+| Pi user | [Pi Package](PI_PACKAGE.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.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` |
 
 ## Documentation Map
 
@@ -22,9 +36,24 @@ This directory is the public documentation home for `pm-cli`. It is organized fo
 - [Architecture](ARCHITECTURE.md) - contributor internals: storage, mutation flow, search, extensions, and command contracts.
 - [Extensions](EXTENSIONS.md) - 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.
 
+## Guide Topic Map
+
+| `pm guide` topic | Primary docs |
+|------------------|--------------|
+| `quickstart` | [Quickstart](QUICKSTART.md), [Command Reference](COMMANDS.md) |
+| `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) |
+| `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) |
+
 Community files:
 
 - [Contributing](../CONTRIBUTING.md)

package/docs/RELEASING.md

@@ -1,6 +1,7 @@
 # Releasing `@unbrained/pm-cli`
 
 This page is for maintainers cutting npm and GitHub releases. It assumes release work is tracked with `pm`.
+For local progressive-disclosure routing, use `pm guide release`.
 
 ## Agent Quick Context
 
@@ -9,6 +10,7 @@ This page is for maintainers cutting npm and GitHub releases. It assumes release
 - Publishing is owned by the tag-driven GitHub Actions release workflow.
 - Do not run manual `npm publish`.
 - Run local parity gates before pushing release tags.
+- Use `pm guide release --json` for machine-readable release docs routing.
 
 Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 
@@ -64,7 +66,7 @@ The pipeline performs:
 
 1. change detection + one-release-per-day guard
 2. version bump + changelog promotion from `[Unreleased]`
-3. strict gates (build, typecheck, coverage, static quality, compatibility, security, smoke checks, reliability gate)
+3. strict gates (build, typecheck, docs/skills freshness, coverage, static quality, compatibility, security, smoke checks, reliability gate)
 4. release note generation from changelog + pm evidence
 5. commit and tag creation (plus optional push)
 
@@ -85,7 +87,7 @@ Minimum coverage:
 - parent and dependency links
 - comments, notes, learnings, body, reminders, events
 - linked files, docs, and tests
-- json_markdown items with external YAML wrappers before JSON front matter
+- legacy markdown item files (including external YAML wrappers before JSON front matter) migrating cleanly to TOON
 - closed issue metadata and history drift checks
 - current-build write mutation and item-count preservation
 

package/docs/SDK.md

@@ -7,6 +7,7 @@ The public SDK is exported from `@unbrained/pm-cli/sdk`. Use it for extension au
 - Primary import: `@unbrained/pm-cli/sdk`.
 - Runtime extension lifecycle is documented in [Extensions](EXTENSIONS.md).
 - Exact command/action contracts are available through `pm contracts`.
+- Local deep-dive routing is available through `pm guide sdk --depth deep`.
 
 Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 
@@ -144,8 +145,8 @@ export default defineExtension({
       name: "example-search",
       async query(context) {
         return context.documents
-          .filter((doc) => doc.front_matter.title?.toLowerCase().includes(context.query.toLowerCase()))
-          .map((doc) => ({ id: doc.front_matter.id, score: 0.5, matched_fields: ["title"] }));
+          .filter((doc) => doc.metadata.title?.toLowerCase().includes(context.query.toLowerCase()))
+          .map((doc) => ({ id: doc.metadata.id, score: 0.5, matched_fields: ["title"] }));
       },
     });
   },