@unbrained/pm-cli 2026.5.14 → 2026.5.24

package/docs/QUICKSTART.md

@@ -9,7 +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.
+- Use `pm install guide-shell --project` before `pm guide quickstart` or `pm guide workflows` when you need local docs routing.
 
 Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 
@@ -34,9 +34,10 @@ For one-off use:
 npx @unbrained/pm-cli --help
 ```
 
-Optional first-party packages are installable on demand:
+Optional first-party packages are installable during init or on demand:
 
 ```bash
+pm init --defaults --with-packages
 pm package catalog --project
 pm install '*' --project
 pm install all --project
@@ -48,9 +49,14 @@ pm package doctor --project --detail summary
 ```bash
 pm init
 pm health --check-only
+pm init --agent-guidance status
+pm init --agent-guidance add
 ```
 
 `pm init` creates `.agents/pm/` with settings, item folders, history, locks, search cache directories, and project extension storage.
+When AGENTS/CLAUDE guidance is missing, default `pm init` uses `--agent-guidance ask`: it prompts only in TTY, never blocks non-interactive runs, and records declined prompts.
+Use `pm init --agent-guidance add` to write the compact workflow block later, or `pm init --agent-guidance status` to inspect guidance state without changing files.
+Use `pm init --defaults --with-packages` when agents should get bundled commands such as calendar, templates, advanced search, and governance helpers in one non-interactive setup step.
 
 ## Create Your First Item
 
@@ -94,9 +100,9 @@ Do not create a duplicate item until `context`, `search`, and list commands show
 ## Link Work Artifacts
 
 ```bash
-pm files <item-id> --add path=src/core/lock/lock.ts,scope=project,note="implementation"
-pm docs <item-id> --add path=docs/ARCHITECTURE.md,scope=project,note="design context"
-pm test <item-id> --add command="node scripts/run-tests.mjs test -- tests/unit/lock.spec.ts",scope=project,timeout_seconds=240
+pm files <item-id> --add path=src/core/lock/lock.ts,note="implementation"
+pm docs <item-id> --add path=docs/ARCHITECTURE.md,note="design context"
+pm test <item-id> --add command="node scripts/run-tests.mjs test -- tests/unit/lock.spec.ts",timeout_seconds=240
 ```
 
 Use `node scripts/run-tests.mjs ...` for linked tests so tracker data is sandboxed.

package/docs/README.md

@@ -2,11 +2,12 @@
 
 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
+## Optional CLI Guide Router
 
-`pm guide` exposes the same documentation routes from inside the CLI:
+`pm guide` is provided by the optional `guide-shell` package. Install it when local in-CLI documentation routing is useful:
 
 ```bash
+pm install guide-shell --project
 pm guide
 pm guide quickstart
 pm guide commands --depth standard
@@ -23,7 +24,7 @@ pm guide release --json
 | Maintainer | [Contributing](../CONTRIBUTING.md) | [Testing](TESTING.md), [Releasing](RELEASING.md), [Architecture](ARCHITECTURE.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` |
+| Machine client | `pm contracts --json` | [Command Reference](COMMANDS.md#machine-contracts), optionally `pm install guide-shell --project && pm guide commands` |
 
 ## Documentation Map
 
@@ -41,8 +42,8 @@ pm guide release --json
 
 ## Guide Topic Map
 
-| `pm guide` topic | Primary docs |
-|------------------|--------------|
+| Optional `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) |
@@ -79,7 +80,7 @@ This documentation structure is tracked through:
 When changing docs, link files back to the active item:
 
 ```bash
-pm docs <item-id> --add path=docs/README.md,scope=project,note="documentation index"
+pm docs <item-id> --add path=docs/README.md,note="documentation index"
 pm comments <item-id> "Docs updated; links and build verified."
 ```
 

package/docs/RELEASING.md

@@ -1,7 +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`.
+For local progressive-disclosure routing, install `guide-shell` with `pm install guide-shell --project`, then use `pm guide release`.
 
 ## Agent Quick Context
 
@@ -10,7 +10,7 @@ For local progressive-disclosure routing, use `pm guide 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.
+- Use `pm guide release --json` for machine-readable release docs routing after `guide-shell` is installed.
 
 Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 
@@ -35,12 +35,12 @@ pnpm version:check
 
 ## One-Time Setup
 
-- Prefer npm Trusted Publishing for `.github/workflows/release.yml` so GitHub-hosted release jobs can publish with short-lived OIDC credentials. Keep `id-token: write`, `npm publish --access public --provenance`, and the package repository URL aligned with npm's Trusted Publisher configuration. If Trusted Publishing is not configured yet, add `NPM_TOKEN` as a GitHub Environment or repository secret as the fallback publisher credential.
+- Use npm provenance publishing for `.github/workflows/release.yml` so GitHub-hosted release jobs publish signed packages. Keep `id-token: write`, Node 24 or newer, npm 11.5.1 or newer, `NODE_AUTH_TOKEN` from the `release` environment `NPM_TOKEN` secret, and `npm publish --access public --provenance`. The token must authenticate as a maintainer with read-write access to `@unbrained/pm-cli`.
 - Add `SENTRY_AUTH_TOKEN` as an optional GitHub Environment or repository secret when Sentry release creation and sourcemap upload should run. Add `SENTRY_PERSONAL_ADMIN_TOKEN` only when the GitHub-hosted Sentry issue-threshold gate should read unresolved issues; CI-scoped release tokens may not have issue-read scope. The release workflow skips Sentry upload cleanly when `SENTRY_AUTH_TOKEN` is absent and skips the GitHub-hosted issue-threshold gate when `SENTRY_PERSONAL_ADMIN_TOKEN` is absent; local maintainers should still run the token-backed Sentry gate before release.
 - Keep any `release` environment compatible with free GitHub features. This repository is public, so environment secrets and tag/branch deployment rules are compatible with the free GitHub path; do not add paid-only release gates.
 - Ensure `GITHUB_TOKEN` has `contents: write` for GitHub Release creation.
 - Keep `package.json` repository, homepage, and bugs URLs aligned with `https://github.com/unbraind/pm-cli`.
-- Keep npm automation token settings compatible with provenance publishing. The release workflow must keep `id-token: write`, a GitHub-hosted runner, and `npm publish --access public --provenance`. npm Trusted Publishing is preferred because it uses OIDC short-lived credentials; if the npm package is configured for Trusted Publishing, restrict traditional token publishing after verifying the workflow.
+- Keep npm publishing compatible with provenance. The release workflow must keep `id-token: write`, a GitHub-hosted runner, Node 24 or newer, npm 11.5.1 or newer, a valid `NPM_TOKEN`, and `npm publish --access public --provenance`.
 
 ## Automated Daily Driver
 
@@ -53,7 +53,8 @@ Policy:
 - release at most once per UTC day by default
 - same-day follow-up release (`YYYY.M.D-N`) is manual-only via `allow_same_day_release=true`
 - release preparation must pass all quality and compatibility gates before commit+tag push
-- external Sentry checks run when a Sentry token is configured; local maintainers can make Sentry and private telemetry mandatory with `--telemetry-mode required`
+- `CHANGELOG.pm.md` is generated by the latest npm `pm-changelog` package (`pm install npm:pm-changelog --project`, then `pm changelog generate`) from closed tracker items and checked in CI; do not edit it by hand
+- external Sentry checks run when a Sentry token is configured; local maintainers should run private reliability checks separately and keep raw operational details in ignored local notes
 - after creating and pushing a new tag, auto-release dispatches `.github/workflows/release.yml` with that tag and waits for the publish workflow to finish, because GitHub does not start normal push/tag workflows from `GITHUB_TOKEN` pushes
 
 Pipeline entrypoint:
@@ -66,9 +67,12 @@ The pipeline performs:
 
 1. change detection + one-release-per-day guard
 2. version bump + changelog promotion from `[Unreleased]`
-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)
+3. latest `pm-changelog` install and tracker changelog refresh through `pm changelog generate`
+4. strict gates (build, typecheck, docs/skills freshness, coverage, static quality, compatibility, security, smoke checks, reliability gate)
+5. release note generation from changelog + pm evidence
+6. commit and tag creation (plus optional push)
+
+If commits since the last tag touch source, package, script, or workflow files, an empty `[Unreleased]` section is a release blocker. The pipeline exits nonzero and reports `changelog_required_files` plus `release_changelog_required:source_or_package_changes_without_unreleased_entry` so the missing release note is visible in automation instead of becoming a green no-op.
 
 ## Local Release Parity Checklist
 
@@ -104,7 +108,7 @@ If private reliability checks identify repeated user friction, either confirm th
 pnpm release:pipeline:dry-run
 
 # Full local preparation (version/changelog mutation + local commit/tag)
-pnpm release:pipeline -- --telemetry-mode required
+pnpm release:pipeline
 ```
 
 5. Push branch and tag after local green.

package/docs/SDK.md

@@ -110,7 +110,16 @@ pm contracts --action calendar --runtime-only --schema-only --json
 pm contracts --command templates --runtime-only --flags-only --json
 ```
 
-Use static SDK contracts for baseline validation, then use `pm contracts --runtime-only` in the target project before invoking package-provided commands or actions.
+Use static SDK contracts for baseline validation, then use runtime contracts in the target project before invoking package-provided commands or actions. Embedded SDK consumers can avoid subprocesses:
+
+```ts
+import { getContracts } from "@unbrained/pm-cli/sdk";
+
+const contracts = await getContracts("/path/to/project/.agents/pm", {
+  runtimeOnly: true,
+  flagsOnly: true,
+});
+```
 
 When a package-owned command is missing at runtime, CLI usage guidance now includes a deterministic install hint (for example `pm install calendar` or `pm install search-advanced`) so agents can recover in one retry.
 
@@ -223,7 +232,7 @@ Manifest capability: `search`.
 ## Robust Automation Pattern
 
 1. Read `PM_TOOL_ACTIONS` or `PM_TOOL_PARAMETERS_SCHEMA` for baseline static validation.
-2. Run `pm contracts --runtime-only --json` inside the target project.
+2. Load runtime contracts with `getContracts(pmRoot, { runtimeOnly: true })` or run `pm contracts --runtime-only --json` inside the target project.
 3. Verify the action appears in `actions` and has `action_availability[].invocable: true`.
 4. Validate required fields with `PM_TOOL_ACTION_PARAMETER_CONTRACTS` for static actions or the runtime schema for package actions.
 5. Execute only after preflight passes.

package/docs/TESTING.md

@@ -36,7 +36,7 @@ Use focused runs while iterating, then run coverage before closure when risk or
 Add tests to the item that owns the work:
 
 ```bash
-pm test <item-id> --add command="node scripts/run-tests.mjs test -- tests/unit/output.spec.ts",scope=project,timeout_seconds=240
+pm test <item-id> --add command="node scripts/run-tests.mjs test -- tests/unit/output.spec.ts",timeout_seconds=240
 pm test <item-id> --run --progress
 ```
 
@@ -76,7 +76,7 @@ Linked tests can include assertion metadata:
 
 ```bash
 pm test <item-id> --add \
-  command="pm list-open --json",scope=project,timeout_seconds=120,assert_json_field_gte=count:0
+  command="pm list-open --json",timeout_seconds=120,assert_json_field_gte=count:0
 ```
 
 Common assertion keys include:

package/marketplace.json

@@ -7,10 +7,10 @@
   },
   "plugins": [
     {
-      "name": "pm-cli",
+      "name": "pm-claude",
       "description": "Native pm CLI integration for Claude Code — 18 MCP tools, 5 workflow skills, 14 slash commands, 3 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "1.3.0",
-      "source": "./plugins/pm-cli-claude",
+      "version": "1.4.0",
+      "source": "./plugins/pm-claude",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.5.14",
+  "version": "2026.5.24",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",
@@ -49,12 +49,14 @@
     ".claude-plugin/**",
     "plugins/**",
     "packages/pm-*/**",
+    "scripts/finalize-build.mjs",
     "scripts/install.sh",
     "scripts/install.ps1",
+    "scripts/prepare-build-cache.mjs",
     "marketplace.json"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "node scripts/prepare-build-cache.mjs && tsc -p tsconfig.json && node scripts/finalize-build.mjs",
     "typecheck": "tsc --noEmit -p tsconfig.json && tsc -p tsconfig.packages.json",
     "start": "node dist/cli.js",
     "dev": "tsx src/cli.ts",
@@ -67,6 +69,9 @@
     "smoke:claude-plugin": "node scripts/smoke-claude-plugin.mjs",
     "version:check": "node scripts/release-version.mjs check",
     "version:next": "node scripts/release-version.mjs next",
+    "changelog:pm:install": "node dist/cli.js install npm:pm-changelog --project",
+    "changelog:pm": "pnpm changelog:pm:install && node dist/cli.js changelog generate --output CHANGELOG.pm.md --title \"pm Tracker Changelog\" --group-by release --status closed",
+    "changelog:pm:check": "pnpm changelog:pm:install && node dist/cli.js changelog generate --output CHANGELOG.pm.md --title \"pm Tracker Changelog\" --group-by release --status closed --check",
     "release:notes": "node scripts/generate-release-notes.mjs",
     "release:changelog": "node scripts/release/changelog-promote.mjs",
     "release:gates": "node scripts/release/run-gates.mjs --telemetry-mode best-effort",
@@ -107,21 +112,19 @@
   },
   "dependencies": {
     "@sentry/node": "^10.51.0",
-    "@toon-format/toon": "^2.1.0",
+    "@toon-format/toon": "^2.3.0",
     "commander": "^14.0.3",
     "fast-glob": "^3.3.3",
-    "fast-json-patch": "^3.1.1",
-    "undici": "^8.1.0",
-    "zod": "^4.3.6"
+    "fast-json-patch": "^3.1.1"
   },
   "devDependencies": {
-    "@sentry/cli": "^3.4.1",
-    "@types/node": "^25.6.0",
-    "@vitest/coverage-v8": "^4.1.5",
+    "@sentry/cli": "^3.4.3",
+    "@types/node": "^25.9.1",
+    "@vitest/coverage-v8": "^4.1.7",
     "c8": "^11.0.0",
-    "tsx": "^4.21.0",
+    "tsx": "^4.22.3",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.5"
+    "vitest": "^4.1.7"
   },
   "pnpm": {
     "onlyBuiltDependencies": [
@@ -129,7 +132,7 @@
     ],
     "overrides": {
       "rollup": ">=4.59.0",
-      "brace-expansion": ">=5.0.5",
+      "brace-expansion": ">=5.0.6",
       "vite": "7.3.2"
     }
   }

package/packages/pm-beads/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@unbrained/pm-package-beads",
+  "name": "@unbrained/pm-beads",
   "version": "0.1.0",
   "private": true,
   "type": "module",

package/packages/pm-calendar/README.md

@@ -1,9 +1,11 @@
 # pm Calendar Package
 
-`@unbrained/pm-package-calendar` provides agenda and calendar views as an installable pm package.
+`@unbrained/pm-calendar` provides agenda and calendar views as an installable pm package.
 
 ```bash
-pm install calendar
+pm install calendar --project
+# Or bootstrap all bundled package commands in a new project:
+pm init --defaults --with-packages
 pm calendar --view week --full-period
 pm cal --json --view agenda --include reminders,events
 ```

package/packages/pm-calendar/extensions/calendar/index.js

@@ -23,7 +23,7 @@ const calendarFlags = [
   { long: "--assignee-filter", value_name: "value", value_type: "string", description: "Filter assignee presence." },
   { long: "--sprint", value_name: "value", value_type: "string", description: "Filter by sprint." },
   { long: "--release", value_name: "value", value_type: "string", description: "Filter by release." },
-  { long: "--include", value_name: "value", value_type: "string", description: "Include sources: deadlines|reminders|events|all." },
+  { long: "--include", value_name: "value", value_type: "string", description: "Include sources: deadlines|reminders|events|scheduled|all." },
   { long: "--recurrence-lookahead-days", value_name: "n", value_type: "string", description: "Bound open-ended recurrence lookahead days." },
   { long: "--recurrence-lookback-days", value_name: "n", value_type: "string", description: "Bound open-ended recurrence lookback days." },
   { long: "--occurrence-limit", value_name: "n", value_type: "string", description: "Cap generated occurrences per recurring event." },
@@ -36,8 +36,27 @@ function calendarCommand(name) {
     name,
     action: "calendar",
     description: "Show deadline, reminder, and scheduled event calendar views.",
+    arguments: [{ name: "view", required: false, description: "Calendar view: agenda|day|week|month." }],
     flags: [...calendarFlags],
-    run: async (context) => runCalendarPackage(context.options, context.global),
+    run: async (context) => {
+      // Extension flags are parsed loosely, so context.args still contains flag
+      // tokens (e.g. ["day", "--date", "+7d"]). Only the leading non-flag tokens
+      // are true positionals, so a positional view combined with --date/--from/etc.
+      // must not be mistaken for multiple positional views.
+      const firstFlagIndex = context.args.findIndex((arg) => arg.startsWith("-"));
+      const positionalArgs = firstFlagIndex === -1 ? context.args : context.args.slice(0, firstFlagIndex);
+      const positionalView = positionalArgs[0]?.trim();
+      if (positionalArgs.length > 1) {
+        throw new Error("Calendar accepts at most one positional view: agenda|day|week|month.");
+      }
+      return runCalendarPackage(
+        {
+          ...context.options,
+          ...(positionalView && context.options.view === undefined ? { view: positionalView } : {}),
+        },
+        context.global,
+      );
+    },
   };
 }
 
@@ -46,7 +65,7 @@ export function activate(api) {
   api.registerCommand(calendarCommand("cal"));
   api.registerService("output_format", (context) => {
     const rendered = renderCalendarPackageOutput(context);
-    return rendered ?? context.payload;
+    return rendered ?? null;
   });
 }
 

package/packages/pm-calendar/extensions/calendar/index.ts

@@ -29,7 +29,7 @@ const calendarFlags = [
   { long: "--assignee-filter", value_name: "value", value_type: "string", description: "Filter assignee presence." },
   { long: "--sprint", value_name: "value", value_type: "string", description: "Filter by sprint." },
   { long: "--release", value_name: "value", value_type: "string", description: "Filter by release." },
-  { long: "--include", value_name: "value", value_type: "string", description: "Include sources: deadlines|reminders|events|all." },
+  { long: "--include", value_name: "value", value_type: "string", description: "Include sources: deadlines|reminders|events|scheduled|all." },
   { long: "--recurrence-lookahead-days", value_name: "n", value_type: "string", description: "Bound open-ended recurrence lookahead days." },
   { long: "--recurrence-lookback-days", value_name: "n", value_type: "string", description: "Bound open-ended recurrence lookback days." },
   { long: "--occurrence-limit", value_name: "n", value_type: "string", description: "Cap generated occurrences per recurring event." },
@@ -42,8 +42,27 @@ function calendarCommand(name: "calendar" | "cal"): CommandDefinition {
     name,
     action: "calendar",
     description: "Show deadline, reminder, and scheduled event calendar views.",
+    arguments: [{ name: "view", required: false, description: "Calendar view: agenda|day|week|month." }],
     flags: [...calendarFlags],
-    run: async (context) => runCalendarPackage(context.options as CalendarOptions, context.global),
+    run: async (context) => {
+      // Extension flags are parsed loosely, so context.args still contains flag
+      // tokens (e.g. ["day", "--date", "+7d"]). Only the leading non-flag tokens
+      // are true positionals, so a positional view combined with --date/--from/etc.
+      // must not be mistaken for multiple positional views.
+      const firstFlagIndex = context.args.findIndex((arg) => arg.startsWith("-"));
+      const positionalArgs = firstFlagIndex === -1 ? context.args : context.args.slice(0, firstFlagIndex);
+      const positionalView = positionalArgs[0]?.trim();
+      if (positionalArgs.length > 1) {
+        throw new Error("Calendar accepts at most one positional view: agenda|day|week|month.");
+      }
+      return runCalendarPackage(
+        {
+          ...(context.options as CalendarOptions),
+          ...(positionalView && (context.options as CalendarOptions).view === undefined ? { view: positionalView } : {}),
+        },
+        context.global,
+      );
+    },
   };
 }
 
@@ -52,7 +71,7 @@ export function activate(api: ExtensionApi): void {
   api.registerCommand(calendarCommand("cal"));
   api.registerService("output_format", (context) => {
     const rendered = renderCalendarPackageOutput(context as ServiceOverrideContext);
-    return rendered ?? context.payload;
+    return rendered ?? null;
   });
 }
 

package/packages/pm-calendar/extensions/calendar/runtime.js

@@ -51,10 +51,6 @@ function isCalendarResult(value) {
   );
 }
 
-function isCalendarCommand(command) {
-  return command === "calendar" || command === "cal";
-}
-
 function readPayloadFormat(payload) {
   if (typeof payload === "object" && payload !== null) {
     const format = payload.format;
@@ -72,6 +68,26 @@ function readPayloadResult(payload) {
   return payload;
 }
 
+function readPayloadCommandOptions(payload) {
+  if (typeof payload === "object" && payload !== null) {
+    const commandOptions = payload.command_options;
+    if (typeof commandOptions === "object" && commandOptions !== null) {
+      return commandOptions;
+    }
+  }
+  return {};
+}
+
+function readPayloadGlobalOptions(payload) {
+  if (typeof payload === "object" && payload !== null) {
+    const global = payload.global;
+    if (typeof global === "object" && global !== null) {
+      return global;
+    }
+  }
+  return {};
+}
+
 export async function runCalendarPackage(options, global) {
   const loaded = await ensureCalendarCoreModule();
   return loaded.runCalendar(options, global);
@@ -79,11 +95,14 @@ export async function runCalendarPackage(options, global) {
 
 export function renderCalendarPackageOutput(context) {
   const result = readPayloadResult(context.payload);
-  if (!calendarCore || !isCalendarCommand(context.command) || !isCalendarResult(result)) {
+  if (!calendarCore || !isCalendarResult(result)) {
     return null;
   }
-  const options = context.options ?? {};
-  const global = context.global ?? {};
+  const options =
+    context.options && Object.keys(context.options).length > 0
+      ? context.options
+      : readPayloadCommandOptions(context.payload);
+  const global = context.global ?? readPayloadGlobalOptions(context.payload);
   const outputFormat = calendarCore.resolveCalendarOutputFormat(options, global);
   if (outputFormat === "markdown") {
     return `${calendarCore.renderCalendarMarkdown(result)}\n`;

package/packages/pm-calendar/extensions/calendar/runtime.ts

@@ -60,10 +60,6 @@ function isCalendarResult(value: unknown): value is CalendarResult {
   );
 }
 
-function isCalendarCommand(command: unknown): boolean {
-  return command === "calendar" || command === "cal";
-}
-
 function readPayloadFormat(payload: unknown): "toon" | "json" {
   if (typeof payload === "object" && payload !== null) {
     const format = (payload as { format?: unknown }).format;
@@ -81,6 +77,26 @@ function readPayloadResult(payload: unknown): unknown {
   return payload;
 }
 
+function readPayloadCommandOptions(payload: unknown): CalendarOptions {
+  if (typeof payload === "object" && payload !== null) {
+    const commandOptions = (payload as { command_options?: unknown }).command_options;
+    if (typeof commandOptions === "object" && commandOptions !== null) {
+      return commandOptions as CalendarOptions;
+    }
+  }
+  return {};
+}
+
+function readPayloadGlobalOptions(payload: unknown): GlobalOptions {
+  if (typeof payload === "object" && payload !== null) {
+    const global = (payload as { global?: unknown }).global;
+    if (typeof global === "object" && global !== null) {
+      return global as GlobalOptions;
+    }
+  }
+  return {};
+}
+
 export async function runCalendarPackage(options: CalendarOptions, global: GlobalOptions): Promise<CalendarResult> {
   const loaded = await ensureCalendarCoreModule();
   return loaded.runCalendar(options, global);
@@ -88,11 +104,14 @@ export async function runCalendarPackage(options: CalendarOptions, global: Globa
 
 export function renderCalendarPackageOutput(context: ServiceOverrideContext): string | null {
   const result = readPayloadResult(context.payload);
-  if (!calendarCore || !isCalendarCommand(context.command) || !isCalendarResult(result)) {
+  if (!calendarCore || !isCalendarResult(result)) {
     return null;
   }
-  const options = (context.options ?? {}) as CalendarOptions;
-  const global = (context.global ?? {}) as GlobalOptions;
+  const options =
+    context.options && Object.keys(context.options).length > 0
+      ? (context.options as CalendarOptions)
+      : readPayloadCommandOptions(context.payload);
+  const global = context.global ?? readPayloadGlobalOptions(context.payload);
   const outputFormat = calendarCore.resolveCalendarOutputFormat(options, global);
   if (outputFormat === "markdown") {
     return `${calendarCore.renderCalendarMarkdown(result)}\n`;

package/packages/pm-calendar/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@unbrained/pm-package-calendar",
+  "name": "@unbrained/pm-calendar",
   "version": "0.1.0",
   "private": true,
   "type": "module",

package/packages/pm-governance-audit/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@unbrained/pm-package-governance-audit",
+  "name": "@unbrained/pm-governance-audit",
   "version": "0.1.0",
   "private": true,
   "type": "module",

package/packages/pm-guide-shell/extensions/guide-shell/index.js

@@ -66,7 +66,7 @@ export function activate(api) {
   api.registerCommand(completionTagsCommand());
   api.registerService("output_format", (context) => {
     const rendered = renderGuideShellPackageOutput(context);
-    return rendered ?? context.payload;
+    return rendered ?? null;
   });
 }
 

package/packages/pm-guide-shell/extensions/guide-shell/index.ts

@@ -71,7 +71,7 @@ export function activate(api: ExtensionApi): void {
   api.registerCommand(completionTagsCommand());
   api.registerService("output_format", (context) => {
     const rendered = renderGuideShellPackageOutput(context as ServiceOverrideContext);
-    return rendered ?? context.payload;
+    return rendered ?? null;
   });
 }
 

package/packages/pm-guide-shell/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@unbrained/pm-package-guide-shell",
+  "name": "@unbrained/pm-guide-shell",
   "version": "0.1.0",
   "private": true,
   "type": "module",

package/packages/pm-linked-test-adapters/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@unbrained/pm-package-linked-test-adapters",
+  "name": "@unbrained/pm-linked-test-adapters",
   "version": "0.1.0",
   "private": true,
   "type": "module",

package/packages/pm-search-advanced/README.md

@@ -6,9 +6,13 @@ First-party package that restores optional advanced search surfaces in bare-core
 
 - Adds `pm search-advanced` with:
   - `--mode keyword|semantic|hybrid`
+  - `--semantic`, `--hybrid`
   - `--include-linked`
   - `--title-exact`
   - `--phrase-exact`
+  - `--type`, `--tag`, `--priority`
+  - `--deadline-before`, `--deadline-after`
+  - `--limit`, `--fields`, `--compact`, `--full`
 - Adds `pm reindex` with:
   - `--mode keyword|semantic|hybrid`
   - `--progress`
@@ -23,5 +27,9 @@ pm install search-advanced --project
 
 ```bash
 pm search-advanced "vector cache" --mode hybrid --limit 5 --json
+pm search-advanced --hybrid "vector cache" --limit 5 --json
+pm search-advanced "calendar package" --mode keyword --fields id,title,score --compact --json
 pm reindex --mode hybrid --progress --json
 ```
+
+Without `--mode`, `--semantic`, or `--hybrid`, `search-advanced` stays keyword-first for fast agent reads.