@unbrained/pm-cli 2026.7.8 → 2026.7.9

package/docs/AGENT_GUIDE.md

@@ -116,9 +116,12 @@ pm release <item-id>
 | Open work only | `pm search "<keywords>" --status open` (drops closed-history noise; did-you-mean on typos) |
 | Scope search like list | `pm search "<keywords>" --type Task --assignee <name> --parent <id>` (full `pm list` filter parity) |
 | Items changed since last window | `pm list-all --updated-after <prev-run-ISO> --brief` (relative `-2h`/`-7d` also work) |
+| Open items changed today | `pm list-open --today --brief` (local-midnight shorthand; mutually exclusive with `--updated-after`) |
+| Items changed recently | `pm list-all --recent --brief` (last seven days; mutually exclusive with `--updated-after`) |
 | Single item | `pm get <id>` |
 | Full machine payload | `pm get <id> --full --json` |
 | Command flags | `pm <command> --help --json` |
+| Command intent map | `pm contracts --summary --json` (one command plus terse intent per row; use before command-scoped contracts) |
 | Low-noise machine contracts | `pm contracts --command <command> --flags-only --json` |
 | Semantic index refresh | `pm reindex --mode semantic --progress` (stale-first by default; add `--full` to force full rebuild; requires the `search-advanced` package) |
 | Timeline | `pm activity --id <id> --limit 20` |

package/docs/COMMANDS.md

@@ -7,6 +7,7 @@ Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon),
 ```bash
 pm <command> --help
 pm <command> --help --json
+pm contracts --summary --json
 pm contracts --command <command> --flags-only --json
 ```
 
@@ -15,7 +16,7 @@ pm contracts --command <command> --flags-only --json
 - Prefer `pm context`, `pm search`, and narrow list commands before mutation.
 - Prefer TOON for reading and `--json` for strict parsing.
 - Use the [guide topic map](README.md#guide-topic-map) when optional `pm guide` local docs routing is needed.
-- Use `pm contracts` for machine clients.
+- Use `pm contracts --summary --json` for the cheapest command map, then narrow with command-scoped contracts.
 - Every mutation writes history.
 
 Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
@@ -129,6 +130,10 @@ pm list-all --updated-after 2026-06-04T15:18:32Z --brief
 pm list-open --updated-after=-2h --brief
 pm list-all --created-after=-7d --status open
 
+# Common list windows avoid date math (`list-open` keeps the view open-only).
+pm list-open --today --brief
+pm list-all --recent --brief
+
 # Search scoped to open work only (drops closed-history noise); statuses accept
 # all (no lifecycle restriction), open/closed/canceled aliases, or configured
 # ids, comma-separated, with a did-you-mean hint on typos.
@@ -141,6 +146,8 @@ pm search "reminder validation" --status all --limit 10
 pm search "calendar" --type Task --assignee alice --updated-after=-7d --parent pm-abcd
 ```
 
+Use only one updated-at window per list call: `--today`, `--recent`, and `--updated-after` are mutually exclusive. `--today` starts at local midnight; `--recent` is the same as `--updated-after=-7d`.
+
 `pm get`, `pm history`, and `pm search` also accept command-local `--format json|toon`. `--format json` is equivalent to the global `--json` flag for that command, while `--format toon` keeps the default agent-readable output. Do not combine global `--json` with `--format toon`.
 
 `list`/`search` full and fields projections echo full filter metadata. Compact mode emits only active filters (plus runtime schema filters when present) and omits the default projection/sorting/now trailer keys for lower token cost.
@@ -858,12 +865,14 @@ Invariants:
 
 ```bash
 pm contracts --json
+pm contracts --summary --json
 pm contracts --command create --flags-only --json
 pm contracts --action create --schema-only --json
 pm help create --json
 ```
 
 Agents should use runtime contracts instead of hard-coding flag lists. Contract output includes extension-provided command surfaces when active.
+Use `pm contracts --summary --json` first when bootstrapping in a tight context window; it emits one command and terse intent per row before the agent requests heavier command-specific flags or schemas.
 
 ## Completion
 

package/docs/SDK.md

@@ -106,6 +106,12 @@ Command/action contract exports:
 - `PmClient` / `runAction` (high-level in-process action execution for custom tools, bots, CI, and embedded runtimes)
 - Typed read primitives on `PmClient`: `get`, `list`, `search`, `context`, `next`, `aggregate`, and `stats`
 - Read primitive option/result contracts: `GetOptions` / `GetResult`, `ListOptions` / `ListResult`, `SearchOptions` / `SearchResult`, `ContextOptions` / `ContextResult`, `NextOptions` / `NextResult`, `AggregateOptions` / `AggregateResult`, `StatsCommandOptions` / `StatsResult`
+- Typed annotation and relationship primitives on `PmClient`: `comments`, `notes`, `learnings`, `files`, `filesDiscover`, `docs`, `deps`, and `append`
+- Annotation and relationship option/result contracts: `CommentsCommandOptions` / `CommentsResult`, `NotesCommandOptions` / `NotesResult`, `LearningsCommandOptions` / `LearningsResult`, `FilesCommandOptions` / `FilesResult`, `FilesDiscoverOptions` / `FilesDiscoverResult`, `DocsCommandOptions` / `DocsResult`, `DepsCommandOptions` / `DepsResult`, `AppendCommandOptions` / `AppendResult`
+- Typed customization primitives on `PmClient`: `init`, `config`, `schema`, `schemaList`, `schemaShow`, `schemaAddType`, `schemaRemoveType`, `schemaAddStatus`, `schemaRemoveStatus`, `schemaAddField`, `schemaRemoveField`, `schemaListFields`, `schemaShowField`, `schemaApplyPreset`, `schemaInferTypes`, `schemaShowStatus`, `profile`, `profileList`, `profileShow`, `profileApply`, and `profileLint`
+- Customization primitive option/result contracts: `InitCommandOptions` / `InitResult`, `ConfigCommandOptions` / `ConfigResult`, `SchemaSubcommand` / `SchemaResult` / `SchemaInspectResult`, `SchemaListResult`, `SchemaShowResult`, `SchemaAddTypeResult`, `SchemaRemoveTypeResult`, `SchemaAddStatusResult`, `SchemaRemoveStatusResult`, `SchemaAddFieldResult`, `SchemaRemoveFieldResult`, `SchemaListFieldsResult`, `SchemaShowFieldResult`, `SchemaApplyPresetResult`, `SchemaAddTypeInferResult`, `SchemaShowStatusResult`, `ProfileSubcommand` / `ProfileResult`, `ProfileListResult`, `ProfileShowResult`, `ProfileApplyResult`, `ProfileLintResult`
+- Typed governance and maintenance primitives on `PmClient`: `validate`, `health`, and `gc`
+- Governance and maintenance option/result contracts: `ValidateCommandOptions` / `ValidateResult`, `RunHealthOptions` / `HealthResult`, `GcCommandOptions` / `GcResult`
 - Typed package and extension lifecycle primitives on `PmClient`: `extension`, `extensionList`, `extensionActivate`, `extensionDeactivate`, `package`, `packageList`, `packageInstall`, `packageUninstall`, `packageDoctor`, `packageManage`, `packageDescribe`, `packageReload`, `packageCatalog`, `packageActivate`, `packageDeactivate`, and `upgrade`
 - Lifecycle primitive option/result contracts: `ExtensionCommandOptions` / `ExtensionCommandResult`, `PackageCommandOptions` / `PackageCommandResult`, `UpgradeCommandOptions` / `UpgradeResult`
 - `PM_CORE_COMMAND_NAMES`
@@ -450,6 +456,14 @@ const open = await pm.list({ status: "open", limit: "20" });
 const recommendation = await pm.next({ readyOnly: true });
 const grouped = await pm.aggregate({ groupBy: "status", count: true });
 const stats = await pm.stats({ metadataCoverage: true });
+await pm.comments(created.item.id, { add: "Investigation context captured." });
+await pm.files(created.item.id, { add: ["src/index.ts"], note: "entrypoint" });
+await pm.docs(created.item.id, { add: ["docs/SDK.md"], note: "authoring reference" });
+const graph = await pm.deps(created.item.id, { format: "graph" });
+const types = await pm.schemaList();
+const profiles = await pm.profileList();
+const validation = await pm.validate({ checkResolution: true });
+const health = await pm.health({ checkOnly: true, summary: true });
 const packages = await pm.packageList({ project: true });
 const doctor = await pm.packageDoctor({ project: true, isolated: true });
 const plannedUpgrade = await pm.upgrade(undefined, { dryRun: true, cliOnly: true });
@@ -501,6 +515,29 @@ payload shape with vocabulary-appropriate SDK signatures. `UpgradeResult` is the
 same structured payload rendered by the CLI, so embedded tools can own their
 presentation layer while sharing pm's package/install/doctor semantics.
 
+Annotation and relationship convenience methods turn "project management =
+context management" into a typed SDK surface. Use `pm.comments`, `pm.notes`,
+`pm.learnings`, `pm.files`, `pm.docs`, `pm.deps`, and `pm.append` when an
+embedded agent, package, or custom UI needs to add durable rationale, link
+changed files/docs/tests, or inspect the item graph. `pm.filesDiscover` exposes
+the same file-candidate discovery used by the CLI, so a custom tool can present
+reviewable link suggestions instead of scraping git output itself.
+
+Customization convenience methods are the SDK baseline for project-specific pm
+tools. `pm.init` stages a tracker, `pm.config` reads/writes settings,
+`pm.schema*` methods manage types/statuses/fields/presets, and `pm.profile*`
+methods list, inspect, apply, and lint project archetypes. These helpers let a
+package or app construct an opinionated project-management experience while
+staying on the same schema/profile primitives the CLI and MCP use.
+
+Governance and maintenance convenience methods expose the operational floor a
+custom PM host should run before it trusts or publishes tracker state.
+`pm.validate` checks resolution/history invariants, `pm.health` performs
+read-only diagnostics, and `pm.gc` runs dry-run or explicit cleanup paths through
+the same bounded maintenance engine as the CLI. Prefer these typed calls over
+shelling out when building CI, editor integrations, or long-running agent
+runtimes.
+
 `PmClient` and `runAction` share the same process-wide extension activation
 queue as MCP. Calls from one process are serialized across extension load,
 activation, dispatch, cleanup, and deactivate so active extension registries stay

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.7.8",
+  "version": "2026.7.9",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",