@modootoday/pmcp 0.22.13 → 0.23.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (144) hide show
  1. package/.agents/plugins/marketplace.json +1 -1
  2. package/.claude-plugin/marketplace.json +1 -1
  3. package/.claude-plugin/plugin.json +1 -1
  4. package/.mcp.json +1 -1
  5. package/dist/{affected-ZWO2F5EM.js → affected-D6FRJPPI.js} +2 -2
  6. package/dist/{apply-OIKQ5SIY.js → apply-3PWUO4J5.js} +20 -19
  7. package/dist/{available-Z5MIDFPH.js → available-74CMIBPD.js} +9 -9
  8. package/dist/{broadcast-BF2QL3O7.js → broadcast-VKZY7WSD.js} +3 -3
  9. package/dist/chunk-2GZKA33O.js +173 -0
  10. package/dist/chunk-2HL2MFNI.js +159 -0
  11. package/dist/{chunk-5PNS6V5C.js → chunk-2K4WYN4C.js} +2 -2
  12. package/dist/{chunk-4O4ZOSBQ.js → chunk-2MX5C7B2.js} +3 -3
  13. package/dist/chunk-43MXRTKH.js +134 -0
  14. package/dist/chunk-4VVQLWTS.js +93 -0
  15. package/dist/{chunk-24L4MO7H.js → chunk-5HNLHI5F.js} +2 -2
  16. package/dist/{chunk-JEL35P7S.js → chunk-5NDUWEMW.js} +2 -2
  17. package/dist/{chunk-737BENAU.js → chunk-6NRLBSEG.js} +5 -5
  18. package/dist/chunk-6QJ3F445.js +166 -0
  19. package/dist/{chunk-7ZOQELXR.js → chunk-72V6U7CZ.js} +3 -3
  20. package/dist/{chunk-J3QUG6O5.js → chunk-7CHUMF3E.js} +2 -2
  21. package/dist/{chunk-INT7QLEU.js → chunk-7DJQASH3.js} +25 -6
  22. package/dist/chunk-7IRXUPM2.js +7 -0
  23. package/dist/{chunk-UED3RH53.js → chunk-DNSHJIS4.js} +2 -2
  24. package/dist/{chunk-ISGBOJT7.js → chunk-DZTSCJOZ.js} +3 -3
  25. package/dist/{chunk-KEHB4FZP.js → chunk-E2E4HIEN.js} +49 -3
  26. package/dist/{chunk-VNZTULFD.js → chunk-EQF64INS.js} +3 -3
  27. package/dist/{chunk-G4ATQPQI.js → chunk-F3R5HEUB.js} +5 -1
  28. package/dist/{chunk-JW5NMQTU.js → chunk-HES44LTA.js} +4 -4
  29. package/dist/{chunk-RHJEGLYM.js → chunk-HF5D6B2U.js} +45 -6
  30. package/dist/{chunk-5OFQVW2K.js → chunk-HYXOJYVR.js} +2 -2
  31. package/dist/chunk-JANBBPKP.js +50 -0
  32. package/dist/{chunk-A6DARDQ4.js → chunk-JJFPSFDU.js} +2 -2
  33. package/dist/{chunk-XNML2KIC.js → chunk-JPYQDOEW.js} +3 -3
  34. package/dist/{chunk-733WVP2R.js → chunk-KYGGQPAH.js} +2 -2
  35. package/dist/{chunk-NNGGNXF2.js → chunk-LGRFYN5T.js} +2 -2
  36. package/dist/{chunk-GNVME5AD.js → chunk-LO54UUDE.js} +2 -2
  37. package/dist/{chunk-XSWF7APE.js → chunk-OGCJO6HQ.js} +9 -8
  38. package/dist/{chunk-T4GVN7XO.js → chunk-P25V6NEX.js} +5 -5
  39. package/dist/{chunk-A7XCUR2C.js → chunk-Q6V274OB.js} +8 -6
  40. package/dist/chunk-QR6A3TYP.js +315 -0
  41. package/dist/{chunk-EIDIVIAD.js → chunk-QYLOIM4U.js} +9 -2
  42. package/dist/{chunk-ZKB7ZNKY.js → chunk-RRKA3GF5.js} +4 -4
  43. package/dist/{chunk-P5D6RKMT.js → chunk-RZYZILU4.js} +5 -3
  44. package/dist/{chunk-5IZFEVPW.js → chunk-SDQYZDHS.js} +2 -2
  45. package/dist/chunk-UVTGY2R3.js +78 -0
  46. package/dist/{chunk-LLT5FQBE.js → chunk-VBVNOLRR.js} +7 -3
  47. package/dist/{chunk-ABTJQ4QV.js → chunk-WBPVNCQO.js} +20 -5
  48. package/dist/{chunk-K2VU3B4W.js → chunk-WQBKQTNT.js} +3 -3
  49. package/dist/{chunk-YGOWIJPE.js → chunk-WZYGM3FR.js} +6 -2
  50. package/dist/chunk-Y6NFETNG.js +232 -0
  51. package/dist/{chunk-5KWDQFVY.js → chunk-YRNFMPZB.js} +7 -8
  52. package/dist/{chunk-ZS5IDQFJ.js → chunk-ZXMECZBI.js} +4 -4
  53. package/dist/{cli-IHVNE3WL.js → cli-GFDT4YXM.js} +14 -15
  54. package/dist/{cli-FSSYFCV3.js → cli-YWV7FLYO.js} +18 -12
  55. package/dist/cli.js +307 -47
  56. package/dist/{completion-ZTTJVV4C.js → completion-OKGNN7DE.js} +25 -23
  57. package/dist/{diagnostics-XC5L6Z3E.js → diagnostics-N4XRRCQG.js} +5 -5
  58. package/dist/{doctor-FGDSUBR3.js → doctor-3H6UYNEA.js} +20 -20
  59. package/dist/{entry-NNB2CQLZ.js → entry-KDLLG6ED.js} +9 -9
  60. package/dist/{exec-mcp-ZU3Z3XT6.js → exec-mcp-AENALAHJ.js} +8 -8
  61. package/dist/{harness-B7ANLH5M.js → harness-GRYTNUF2.js} +26 -44
  62. package/dist/harness-launch-gate.js +3 -3
  63. package/dist/harness-worker.js +5 -5
  64. package/dist/{heavy-IIZBO4YM.js → heavy-BGXKJKYB.js} +78 -22
  65. package/dist/hooks-V25ANQ4Q.js +24 -0
  66. package/dist/{host-XXWQ23LD.js → host-4EGPADOJ.js} +6 -6
  67. package/dist/{host-5P4D7GSE.js → host-MLSWY7D7.js} +17 -14
  68. package/dist/{host-run-AEWHFVQL.js → host-run-VI52IUKF.js} +5 -5
  69. package/dist/http.js +1 -1
  70. package/dist/{import-mcp-BQM5DKYH.js → import-mcp-FIXFLUDM.js} +11 -11
  71. package/dist/index.d.ts +1 -1
  72. package/dist/index.js +10 -9
  73. package/dist/init-ALTBFUPP.js +14 -0
  74. package/dist/{install-OFVLR7TI.js → install-5JH4DSFF.js} +10 -10
  75. package/dist/{invoke-3BQ5NG3P.js → invoke-7T7UY57O.js} +7 -7
  76. package/dist/{list-EU4MJOXA.js → list-JFZ7UZLV.js} +11 -11
  77. package/dist/{list-WWYCGD3X.js → list-LV5EKCF6.js} +11 -7
  78. package/dist/{logout-6DFDYJUI.js → logout-7CNBO76Z.js} +8 -8
  79. package/dist/{logs-BRF6DBKG.js → logs-2JEMSNSG.js} +7 -7
  80. package/dist/{mailbox-QYA2LQSE.js → mailbox-5FVFMQ2J.js} +6 -6
  81. package/dist/{mailbox-AQCTXO3H.js → mailbox-ZHZWZMAY.js} +14 -21
  82. package/dist/{mainline-O5AEHG3J.js → mainline-6PBT3VNR.js} +8 -7
  83. package/dist/{marketplace-TI5HFAHB.js → marketplace-2X3OOEPW.js} +10 -9
  84. package/dist/{mcp-HR5JFUW7.js → mcp-MVQVMAKJ.js} +4 -4
  85. package/dist/{mcp-4R53HSGY.js → mcp-PBTQ5SJW.js} +2 -2
  86. package/dist/{models-63NQBSV3.js → models-XSF45MCD.js} +9 -5
  87. package/dist/{pause-UF7FQDJX.js → pause-CMZOIHTJ.js} +3 -3
  88. package/dist/{preview-WSESS2UN.js → preview-465CQJBQ.js} +4 -4
  89. package/dist/{project-JXXL24WN.js → project-FZGJRG2U.js} +14 -12
  90. package/dist/{reindex-3GPKAFBW.js → reindex-D62HQAN2.js} +7 -7
  91. package/dist/{report-JUSKQPAC.js → report-UB7MXAUB.js} +10 -10
  92. package/dist/{resume-3WAROOQ3.js → resume-PAKIT4TT.js} +3 -3
  93. package/dist/{run-XRWU4L73.js → run-TOP37ZQC.js} +7 -7
  94. package/dist/run-VGJDMA2O.js +23 -0
  95. package/dist/{serve-OEX5V5CD.js → serve-LR7SJHNH.js} +13 -13
  96. package/dist/{session-YZVX4NGN.js → session-3YVVO2GR.js} +6 -6
  97. package/dist/{setup-SWNAC2C7.js → setup-6AQUOWOH.js} +3 -2
  98. package/dist/{smoke-5BGJXAHX.js → smoke-6X6IXQIQ.js} +4 -4
  99. package/dist/{start-login-MG26NDE3.js → start-login-X37KGCCB.js} +9 -9
  100. package/dist/{status-GKCIVAAR.js → status-4PYPTYUB.js} +4 -4
  101. package/dist/{status-APADL7O2.js → status-E4AFUOQO.js} +17 -10
  102. package/dist/{status-LH7Q255G.js → status-LBRK37GA.js} +27 -26
  103. package/dist/stdio.js +2 -2
  104. package/dist/{sweep-VTVPDAPY.js → sweep-VURZU6DI.js} +3 -3
  105. package/dist/{test-TK2J3IB7.js → test-D2EEFUN2.js} +11 -11
  106. package/dist/{tui-YTPHHKCW.js → tui-D7E3MD3X.js} +45 -19
  107. package/dist/{unbroadcast-CH7BAQ2G.js → unbroadcast-7AMLURCG.js} +3 -3
  108. package/dist/{validate-5QVZBE6W.js → validate-YXR7FJJX.js} +11 -9
  109. package/dist/{wait-4HYJJAWO.js → wait-HEODT7KV.js} +3 -3
  110. package/dist/{worker-RBXYAMR4.js → worker-WTBC6VYO.js} +7 -7
  111. package/dist/{worktree-create-FEZNQUQ6.js → worktree-create-FTSLMZWS.js} +2 -2
  112. package/docs/commands.md +64 -28
  113. package/docs/hooks.md +3 -3
  114. package/docs/project-configuration.md +33 -33
  115. package/docs/terminal-workspace.md +2 -0
  116. package/docs/upgrading.md +43 -0
  117. package/gemini-extension.json +2 -2
  118. package/mcp.json +1 -1
  119. package/package.json +5 -5
  120. package/plugin.json +1 -1
  121. package/plugins/pmcp/.claude-plugin/plugin.json +1 -1
  122. package/plugins/pmcp/.mcp.json +1 -1
  123. package/plugins/pmcp/gemini-extension.json +2 -2
  124. package/plugins/pmcp/mcp.json +1 -1
  125. package/plugins/pmcp/plugin.json +1 -1
  126. package/plugins/pmcp/skills/headless-agents-ci-scaffold/SKILL.md +1 -1
  127. package/plugins/pmcp/skills/pmcp-project-init/SKILL.md +1 -1
  128. package/plugins/pmcp/skills/pmcp-sessions-and-git/SKILL.md +3 -2
  129. package/skills/headless-agents-ci-scaffold/SKILL.md +1 -1
  130. package/skills/pmcp-project-init/SKILL.md +1 -1
  131. package/skills/pmcp-sessions-and-git/SKILL.md +3 -2
  132. package/dist/chunk-2P4Z2NUX.js +0 -28
  133. package/dist/chunk-3Y3HDMHA.js +0 -108
  134. package/dist/chunk-74O7KZUH.js +0 -45
  135. package/dist/chunk-BN4XAXMQ.js +0 -65
  136. package/dist/chunk-E3DQB5LS.js +0 -48
  137. package/dist/chunk-JWRZDYB5.js +0 -59
  138. package/dist/chunk-LMUBBIE2.js +0 -83
  139. package/dist/chunk-QBSJL3SP.js +0 -162
  140. package/dist/chunk-VSTUKACC.js +0 -7
  141. package/dist/chunk-WFY7ATSZ.js +0 -116
  142. package/dist/hooks-IEJTW7BV.js +0 -24
  143. package/dist/init-L6GUO3PW.js +0 -14
  144. package/dist/run-VUUQS4WY.js +0 -19
package/docs/commands.md CHANGED
@@ -3,7 +3,9 @@
3
3
  [Back to the overview](../README.md)
4
4
 
5
5
  Every pmcp command with its flags, behaviour and exit codes. `pmcp <command> --help` prints
6
- the same usage from the command itself.
6
+ the same usage from the command itself, with its subcommands and examples, and
7
+ `pmcp <command> <subcommand> --help` prints the usage, options and examples of one
8
+ subcommand, such as `pmcp harness group create --help` or `pmcp mailbox export --help`.
7
9
 
8
10
  ## The invocation a host uses
9
11
 
@@ -12,7 +14,7 @@ the same usage from the command itself.
12
14
  - `pmcp --root ./node_modules`: a leading option with no command is still a server, because
13
15
  hosts pass options without one.
14
16
 
15
- An unrecognised command does not fall through to a server the caller did not ask for. Only an empty argument list, or one that begins with an option, takes that path.
17
+ An unrecognised command does not fall through to a server the caller did not ask for. Only an empty argument list, or one that begins with an option `serve` accepts, takes that path. `-v`, `-V`, `--version` and `version` print the version; any other leading option, such as `-x` or a misspelled `--verison`, is an unknown option and exits 2 without reading standard input.
16
18
 
17
19
  ## status
18
20
 
@@ -20,7 +22,7 @@ An unrecognised command does not fall through to a server the caller did not ask
20
22
  pmcp status [--config <file>] [--json]
21
23
  ```
22
24
 
23
- Show enabled features and their TOML or auto source, projection drift, live sessions, pause, leases, unseen broadcasts, worktree ahead/behind counts, shared MCP credential presence, logged errors from the last hour, and, with a [`[budget]`](project-configuration.md#budget) table, each limit beside what it measured. Reads do not acknowledge broadcasts, refresh credentials, prune logs, fetch or move git refs. Projection uses the same check as `project --check`. Exit 0, or 2 when projection or worktree ahead/behind drift exists or a budget limit is exceeded. Missing or invalid input follows the normal usage/failure exit contract. Human output is a compact summary on stderr; JSON retains the full details.
25
+ Show enabled features and their TOML or auto source, projection drift, live sessions, pause, leases, unseen broadcasts, worktree ahead/behind counts, shared MCP credential presence, logged errors from the last hour, and, with a [`[budget]`](project-configuration.md#budget) table, each limit beside what it measured. Reads do not acknowledge broadcasts, refresh credentials, prune logs, fetch or move git refs. Projection uses the same check as `project --check`. Exit 0, or 4 when projection or worktree ahead/behind drift exists or a budget limit is exceeded; 2 when there is no `pmcp.toml`. Missing or invalid input follows the normal usage/failure exit contract. Human output is a compact summary on stdout; JSON retains the full details.
24
26
 
25
27
  ## init
26
28
 
@@ -51,9 +53,27 @@ pmcp hooks report --switch-check shell.heredoc [--since 2d] [--json]
51
53
 
52
54
  `report` summarises the guard lines the hook bundle writes to the project log at debug level (`[logging] level = "debug"`, or `PMCP_LOG=debug`). For each guard and runtime it counts the runs, what the guard found before its mode (`raw`: allow, deny, ask) and what the call got, the modes seen, the sessions, and the p50, p95 and longest durations. Sessions matching a `[hooks.report] exclude_sessions` regex (replays, smoke runs) are left out and counted. `--since` takes a duration such as `10m`, `2h` or `3d`, or an ISO time. `--switch-check <guard>` lists instead the calls that guard found something in and let through, because it was in `observe` or `warn`: what `deny` would have refused. The log holds no command, prompt or transcript text, so neither does the report. `--json` prints `{version, since?, lines, sessions, excluded, guards}`, or `{version, guard, refused}` with `--switch-check`.
53
55
 
54
- ## Read command JSON schemas
56
+ ## JSON output
55
57
 
56
- These opt-in snapshots write one JSON object and a newline to stdout, with `version: 1`. No color or human summary is mixed into stdout. Errors remain on stderr. Without the flag, existing human output is retained, including MCP status's original unversioned object and logs' JSONL stream. Schemas are named in [schemas.json](https://pmcp.build/commands/schemas.json); each entry under `schemas` uses the shared root `$defs`. Consumers must allow unknown fields inside session, decision and log records. Tokens are never part of an auth status object.
58
+ Every command that prints a result takes `--json` and then writes exactly one line to standard output, a JSON envelope, whether it succeeded or failed:
59
+
60
+ ```json
61
+ {
62
+ "schema": "pmcp.hooks.list.v1",
63
+ "ok": true,
64
+ "data": { "version": 1, "policies": [] },
65
+ "errors": []
66
+ }
67
+ ```
68
+
69
+ - `schema` is `pmcp.<command>[.<subcommand>].v1`, such as `pmcp.status.v1`, `pmcp.git.worktree.list.v1` or `pmcp.models.v1`. A change that removes or retypes a field gets a new version.
70
+ - `ok` is true exactly when the exit code is 0 (see [Exit codes](#exit-codes)); `status` with drift prints its report with `ok: false` and exit 4.
71
+ - `data` is the command's result: the object the tables below describe, the array `models` lists, or `null` when the command failed before it had one.
72
+ - `errors` lists `{code, message}` for each error the command reported; `code` names the exit code (`failure`, `usage`, `missing_optional`, `differences`, `busy`). A usage error such as an unknown option still prints an envelope, with `data: null`.
73
+
74
+ No colour or human text is mixed into standard output; the same errors also go to standard error. Without `--json` every command prints human output (`mcp status` and the `tui` receipts included). `mailbox` and `harness` are machine protocols: they always print their own JSON receipts (`{ok, data}` and `{schemaVersion, ok, ...}`), take no `--json`, and are unchanged. `logs` without `--json` keeps its JSONL stream.
75
+
76
+ The `data` of these commands has a published schema in [schemas.json](https://pmcp.build/commands/schemas.json), with `version: 1` inside `data`; each entry under `schemas` uses the shared root `$defs`, and `envelope` describes the wrapper. Consumers must allow unknown fields inside session, decision and log records. Tokens are never part of an auth status object.
57
77
 
58
78
  | Command | Schema | Fields after version |
59
79
  | -------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -143,9 +163,12 @@ Credentials and attachment files contain secrets and must stay outside source co
143
163
  pmcp project
144
164
  pmcp project --check [--smoke]
145
165
  pmcp project import-mcp --source codex:/path/to/config.toml
166
+ pmcp project exec-mcp remote
146
167
  ```
147
168
 
148
- Generate selected runtimes' native files from `pmcp.toml`. Unmanaged entries and credential references are preserved; conflicts stop the write. `--check` reports drift without writes, and MCP import previews changes by default; `--write` applies them. `--check --smoke` then runs the `[hooks.test] fixtures` file as `pmcp hooks test --fixtures` does, and exits 2 on any finding. [Configuration and guard examples](project-configuration.md).
169
+ `exec-mcp <alias>` is what a projected native entry runs to start a declared MCP server with its resolved environment, or, for `auth = "pmcp"`, the shared-auth proxy; you rarely run it by hand. See [shared remote MCP authentication](project-configuration.md#shared-remote-mcp-authentication).
170
+
171
+ Generate selected runtimes' native files from `pmcp.toml`. Unmanaged entries and credential references are preserved; conflicts stop the write. `--check` reports drift without writes (exit 4), and MCP import previews changes by default; `--write` applies them. `--check --smoke` then runs the `[hooks.test] fixtures` file as `pmcp hooks test --fixtures` does, and exits 4 on any finding. [Configuration and guard examples](project-configuration.md).
149
172
 
150
173
  Configuration files and the ownership lock are replaced atomically one file at a time. If projection is interrupted, inspect with `pmcp project --check`, then run `pmcp project` explicitly to repair drift. Projection does not start a runtime or replay terminal input. The complete set of files is not a single transaction.
151
174
 
@@ -186,14 +209,14 @@ pmcp git sync
186
209
  pmcp git affected --base <ref> [--head <ref>] [--tests-only] [--json]
187
210
  ```
188
211
 
189
- The git workflow configured by [`[git]`](git-workflow.md). Each subcommand needs its table; without it the command exits 1 and names the missing table.
212
+ The git workflow configured by [`[git]`](git-workflow.md). Each subcommand needs its table; without it, or without a `pmcp.toml`, the command exits 2 and names what is missing.
190
213
 
191
214
  - `worktree create <alias>` makes a linked worktree under `[git.worktrees] root` on a new branch from the upstream (or `--base`), links the configured files from the main checkout, runs `bootstrap`, and prints the path.
192
215
  - `worktree list` prints alias, branch, behind/ahead and path for the main checkout and each linked worktree.
193
216
  - `worktree sync` moves the current worktree onto the mainline when that loses nothing; exit 1 when it is held back.
194
- - `deliver` fetches, replays the named commits (default: the ones the upstream lacks) onto the mainline, runs the gate in its own tree under a lock, and pushes; it replays again if the mainline moved. A delivery that touches a leased path holds that lease until it has pushed and installed, and it refuses during a pause unless `--during-pause` or `during_pause = "allow"`. `--no-push` replays and runs the gate command, then stops: it takes no lease and pushes, syncs and notifies nothing, and it refuses `gate = "pre-push"`, where the push is the gate. Deliver never takes the [host lease](project-configuration.md#host-lease): replay, gate tree, hooks and push run without it, and the gate wraps only its test stages in `pmcp heavy --profile gate`. Exit 0 delivered, gated with `--no-push`, or nothing to deliver; 1 refused, gate failed or attempts exhausted; 2 fetch failed or `--no-push` with the pre-push gate; 75 the gate command exited 75 because a test stage never got the host lease ("gate not run: host busy"), so nothing was pushed.
195
- - `sync` moves the main checkout to the mainline, installs when a listed file changed, and follows clean submodule pins. Exit 0 moved or already equal, 1 when local work would be lost, 2 when blocked (undelivered edits) or the fetch failed. Run in a desk (a linked worktree matching `[git.worktrees] desks`), it brings the desk up to date the same way without rebasing: exit 0 moved or current, 1 held (an unlanded commit, uncommitted tracked edits, a pause, another session's lease, a git operation in progress), with the reason. In any other linked worktree it exits 2.
196
- - `affected --base <ref>` prints the workspace members the delta from `<ref>` to `--head` (default `HEAD`) touches, with their consumers when [`[git.affected]`](git-workflow.md#affected-members) `consumers` is on (`--tests-only` leaves them out), or `ALL`; unmapped files are named on stderr. It needs only `[git.affected]`, not an enabled workflow. Exit 0 with an answer, `ALL` included when the base does not resolve, equals the head or a manifest does not parse; 2 for a missing `--base` or an invalid table. `--json` prints `pmcp.git.affected.v1`: `all`, `reason`, `base`, `head`, `changed`, `members`, `unmapped` and `selected` (the printed list, or `"ALL"`).
217
+ - `deliver` fetches, replays the named commits (default: the ones the upstream lacks) onto the mainline, runs the gate in its own tree under a lock, and pushes; it replays again if the mainline moved. A delivery that touches a leased path holds that lease until it has pushed and installed, and it refuses during a pause unless `--during-pause` or `during_pause = "allow"`. `--no-push` replays and runs the gate command, then stops: it takes no lease and pushes, syncs and notifies nothing, and it refuses `gate = "pre-push"`, where the push is the gate. Deliver never takes the [host lease](project-configuration.md#host-lease): replay, gate tree, hooks and push run without it, and the gate wraps only its test stages in `pmcp heavy --profile gate`. Exit 0 delivered, gated with `--no-push`, or nothing to deliver; 1 refused, fetch failed, gate failed or attempts exhausted; 2 `--no-push` with the pre-push gate; 75 the gate command exited 75 because a test stage never got the host lease ("gate not run: host busy"), so nothing was pushed.
218
+ - `sync` moves the main checkout to the mainline, installs when a listed file changed, and follows clean submodule pins. Exit 0 moved or already equal, 1 when local work would be lost or the fetch failed, 2 when blocked (undelivered edits, another branch, a git operation in progress). Run in a desk (a linked worktree matching `[git.worktrees] desks`), it brings the desk up to date the same way without rebasing: exit 0 moved or current, 1 held (an unlanded commit, uncommitted tracked edits, a pause, another session's lease, a git operation in progress), with the reason. In any other linked worktree it exits 2.
219
+ - `affected --base <ref>` prints the workspace members the delta from `<ref>` to `--head` (default `HEAD`) touches, with their consumers when [`[git.affected]`](git-workflow.md#affected-members) `consumers` is on (`--tests-only` leaves them out), or `ALL`; unmapped files are named on stderr. It needs only `[git.affected]`, not an enabled workflow. Exit 0 with an answer, `ALL` included when the base does not resolve, equals the head or a manifest does not parse; 2 for a missing `--base` or an invalid table. `--json` prints the [envelope](#json-output) `pmcp.git.affected.v1`, whose `data` has `all`, `reason`, `base`, `head`, `changed`, `members`, `unmapped` and `selected` (the printed list, or `"ALL"`).
197
220
 
198
221
  ## heavy
199
222
 
@@ -332,34 +355,47 @@ pmcp sync [--project <dir>] [--dry-run | --yes]
332
355
 
333
356
  `install` adds skill packages as dev dependencies with your own package manager, and what gets installed is checked against the digest the catalogue published — not its name and version, which any registry can claim. `sync` updates the ones already declared and removes nothing else. pmcp uses the free bundled public catalog by default and verifies immutable archives and installed resources without login. Explicit `--provider hosted` or `--api` selects a separate service's credentialed distribution, such as skills.modoo.today (see [login](#login--logout--whoami)).
334
357
 
335
- Both show the project and lockfile changes and stop: `--yes` approves them, `--dry-run` prints the plan and changes nothing.
358
+ Both show the project and lockfile changes and stop: `--yes` (`-y`) approves them, `--dry-run` prints the plan and changes nothing.
336
359
 
337
360
  ## Options
338
361
 
339
- | Option | Where | Effect |
340
- | ------------------ | ------------------------- | --------------------------------------------------------------------------------------------- |
341
- | `--root <dir>` | `serve`, `list`, `index` | a `node_modules` directory to walk; repeatable, and the first one wins on a duplicate package |
342
- | `--scope <prefix>` | `serve`, `list`, `index` | only packages whose names start with this; repeatable, matched with a plain prefix test |
343
- | `--model <id>` | `index`, `serve` | the encoder to use; rows from another model are never scored |
344
- | `--json` | `list`, `index`, `models` | emit JSON on standard output rather than a table or a summary |
345
- | `--help`, `-h` | anywhere | the help for that command, generated from the command itself |
346
- | `--version` | on its own | the version, on standard output |
362
+ | Option | Where | Effect |
363
+ | ---------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
364
+ | `--root <dir>` | `serve`, `list`, `index`, `validate`, `project` | a `node_modules` directory to walk; repeatable, and the first one wins on a duplicate package |
365
+ | `--scope <prefix>` | `serve`, `list`, `index`, `validate`, `project` | only packages whose names start with this; repeatable, matched with a plain prefix test |
366
+ | `--config <file>` | every command that reads `pmcp.toml` | a `pmcp.toml` to read instead of the nearest one at or above the working directory |
367
+ | `--model <id>` | `index`, `serve` | the encoder to use; rows from another model are never scored |
368
+ | `--json` | every command that prints a result; `pmcp <command> --help` lists it | emit JSON on standard output rather than a table or a summary |
369
+ | `-y`, `--yes` | `install`, `sync`, `tui` | approve the displayed changes, or the first runtime start, without a prompt |
370
+ | `-q`, `--quiet` | anywhere | silence diagnostics and progress on standard error, except errors; results on standard output still print |
371
+ | `--color`, `--no-color` | anywhere | always or never colour; without either, `FORCE_COLOR` (`0` off, anything else on) wins over `NO_COLOR`, `TERM=dumb` and the terminal test |
372
+ | `--help`, `-h` | anywhere | the help for that command or subcommand, generated from the command itself: usage, subcommands, the options that apply and examples |
373
+ | `-v`, `-V`, `--version`, `version` | on its own | the version, on standard output |
374
+
375
+ With `TERM=dumb`, or a locale that is not UTF-8, the few typographic characters in messages (an em dash, a middle dot) print as ASCII. Long operations such as `index` report progress on standard error: one rewritten line on a terminal, a plain `k/N` line every tenth of the work otherwise.
376
+
377
+ Help and tables fit the terminal: `COLUMNS` when set, else the terminal width, kept between 40 and 120 columns; long descriptions wrap under their column, and a name too wide for its column puts its description on the next lines. Off a terminal, help wraps at 80 columns and a table prints one plain record per line (`name description`, no padding), so `grep` and `cut` see whole records.
347
378
 
348
379
  Options are parsed against the command's own list, so an unknown flag is an error rather than a silently ignored typo. Giving a non-repeatable option twice, or leaving off a value it needs, is the same error.
349
380
 
381
+ An unknown command, subcommand or option exits 2 with one line naming it, the closest valid name when one is near (`unknown command "stauts"; did you mean "status"?`), and where to look next (`Run pmcp status --help for its usage.`), rather than the whole help. An unknown subcommand also lists every valid one. `pmcp help <command>` for a command that does not exist is the same error. Every command that needs a `pmcp.toml` and finds none says so the same way and suggests `pmcp init`.
382
+
350
383
  ## Exit codes
351
384
 
352
- | Code | Means | For example |
353
- | ---- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
354
- | `0` | it did what you asked | skills listed, or the whole catalog indexed |
355
- | `1` | it ran and found a problem | no skills under those roots, a partial index, no SQLite in this runtime to store vectors in, a refused or failed `git deliver` |
356
- | `2` | the arguments were unusable, or a check found drift | an unknown command, an unknown option, a missing value; `project --check` drift, stale or undeclared outputs; a `git` fetch that failed or a sync blocked by undelivered edits |
357
- | `3` | an optional dependency is missing | `index` without `@huggingface/transformers` |
358
- | `75` | the host stayed busy, so nothing ran; retry later | `heavy` past `max_wait`, a `git deliver` gate whose test stage never got the host lease, `wait` past `--timeout` |
385
+ Every command uses one table, so a script can branch on the code alone:
386
+
387
+ | Code | Means | For example |
388
+ | ---- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
389
+ | `0` | it did what you asked | skills listed, the whole catalog indexed, nothing to deliver |
390
+ | `1` | it ran and failed, or found a problem | no skills under those roots, a partial index, no SQLite to store vectors in, `validate` errors, a `doctor` FAIL, a declined or failed install, a refused delivery, a failed gate or fetch |
391
+ | `2` | usage error: it could not run as asked | an unknown command, subcommand or option, a missing value, no `pmcp.toml` or a missing `[git]` table, `git sync` in the wrong checkout |
392
+ | `3` | an optional dependency is missing | `index` without `@huggingface/transformers` |
393
+ | `4` | a check ran and found differences | `status` drift or an exceeded budget, `project --check` drift, stale or undeclared outputs, a `hooks test --fixtures` or `--smoke` finding |
394
+ | `75` | the host stayed busy, so nothing ran; retry later | `heavy` past `max_wait`, a `git deliver` gate whose test stage never got the host lease, `wait` past `--timeout` |
359
395
 
360
- The distinction between 1 and 3 is worth wiring into a script: 1 says the project is not what you expected, and 3 says the machine is missing something optional and the server still works without it.
396
+ 1 says the project is not what you expected; 2 says the command line or the setup is wrong, so retrying the same command will not help; 3 says the machine is missing something optional and the server still works without it; 4 says a check did its job and found something to fix, usually with `pmcp project`. A command that runs another command, such as `heavy`, exits with that command's code. Before 0.23.0, drift exited 2 like a usage error; see [Upgrading](upgrading.md).
361
397
 
362
- **Data on stdout, everything else on stderr.** The JSON from `--json` and the string from `--version` go to standard output so they can be piped. Tables, help and messages go to standard error, which is what keeps a pipeline's input clean.
398
+ **Results on stdout, diagnostics on stderr.** What you asked for goes to standard output: the JSON from `--json`, the version, requested help, and the human result of a read (the `list`, `models`, `marketplace list` and `doctor` tables, `validate` findings, the `status` summary, `hooks` and `sessions` listings, an `install` or `sync` plan). So `pmcp list | grep react` and `pmcp list > skills.txt` work, and `-q` never erases a result. Progress, summaries such as "144 skills", warnings, hints and errors go to standard error. Before 0.23.0, human tables and help went to standard error; see [Upgrading](upgrading.md).
363
399
 
364
400
  ## Runtime
365
401
 
package/docs/hooks.md CHANGED
@@ -247,8 +247,8 @@ hook does not look at the repository being committed. Findings:
247
247
  - `[hooks.failure]` differing from the fixtures' `failure`;
248
248
  - a target whose native hook entry is missing, and a run in which no case ran.
249
249
 
250
- `hooks test --fixtures` exits 0 with no finding and 1 otherwise; `project --check
251
- --smoke` exits 2 on a finding, as for drift.
250
+ `hooks test --fixtures` and `project --check --smoke` exit 0 with no finding and 4
251
+ otherwise, as for drift.
252
252
 
253
253
  ## `[hooks.failure]`
254
254
 
@@ -302,7 +302,7 @@ as `projector.json`), and only at the version `pmcp.lock` records. A pmcp on
302
302
  ## Native hook entries pmcp does not own
303
303
 
304
304
  Hook entries a project or a tool wrote itself run beside pmcp's, and a broken one
305
- fails every call it matches. `pmcp project --check` (exit 2) and `pmcp doctor`
305
+ fails every call it matches. `pmcp project --check` (exit 4) and `pmcp doctor`
306
306
  check each such entry in `.claude/settings.json`, `.claude/settings.local.json`,
307
307
  `.codex/hooks.json`, and the `hooks/hooks.json` (or the manifest's `hooks` path)
308
308
  of each plugin whose `.claude-plugin/plugin.json` is tracked by git. Entries that
@@ -130,7 +130,7 @@ args = ["${PROJECT_ROOT}/node_modules/@modootoday/pmcp/dist/cli.js", "serve"]
130
130
 
131
131
  ```sh
132
132
  pmcp project # write
133
- pmcp project --check # exit 2 on drift, stale or undeclared outputs
133
+ pmcp project --check # exit 4 on drift, stale or undeclared outputs
134
134
  pmcp project add <name> # copy a catalog skill or agent into .agents/
135
135
  pmcp project remove <name>
136
136
  pmcp doctor # ask each installed tool what it loads
@@ -292,37 +292,37 @@ max_wait = 2700
292
292
  load_grace = 600
293
293
  ```
294
294
 
295
- | Key | Type | Default | Meaning |
296
- | ------------------- | ------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
297
- | `enabled` | boolean | `true` | `false` runs every `pmcp heavy` command at once, gates without the lease and turns the guard off. |
298
- | `dir` | path | `~/.cache/pmcp/host` | Where the lock file (`heavy.lock`), the admission lock, the `running/` and `waiters/` records, the holder record and `heavy.log` live. Every tool sharing the lease names the same directory. |
299
- | `budget` | integer | `4` | The most weight that runs at once. `1` is one job at a time. |
300
- | `lanes.<lane>` | integer | gate 1, hook 1, interactive 2, bulk 1 | How many jobs of a lane run at once; `0` closes the lane. |
301
- | `weights.<lane>` | integer | gate 1, hook 1, interactive 2, bulk 3 | A job's weight when neither `--weight` nor a `commands` entry names one. A weight above the budget counts as the budget. |
302
- | `commands` | tables | none | `argv` prefix, `lane` and `weight` for commands run without `--lane` or `--weight`; the first match wins. |
303
- | `tiny` | argv lists | none | Commands so short (a few seconds) that they take no slot and no budget (weight 0, also `--weight 0`); only the hard ceiling holds them back, and the log still records them. |
304
- | `per_session` | integer | `1` | How many jobs one agent session may have queued in the interactive lane, and in the bulk lane; the next one waits outside the queue holding no place. `0` is no cap. Gate and hook are exempt. |
305
- | `marker_env` | name | `PMCP_HEAVY_LEASE` | Set to the job's pid for the leased command; a nested `pmcp heavy` whose marker names a running job runs at once. |
306
- | `legacy_marker_env` | name | none | A second marker, set and honoured like `marker_env`, for a shell wrapper that shares `dir`. |
307
- | `legacy_skip_env` | name | none | A second skip variable, honoured like `PMCP_HEAVY_DISABLE`, and set for the leased command so a nested shell wrapper runs at once. |
308
- | `max_load` | number | the CPU count | A job starts only while the 1-minute load average is below this. |
309
- | `max_io` | number | `8` | And while IO pressure (`some`, the `io_window` average) is below this. A host without pressure files checks load only; one without a load average checks neither. |
310
- | `io_window` | string | `avg60` | Which pressure average the check reads: `avg10` follows spikes, `avg60` and `avg300` smooth them so the queue does not stall on a burst. |
311
- | `max_wait` | seconds | `3600` | How long the `default` profile waits; then nothing runs and the exit is 75. |
312
- | `load_grace` | seconds | `900` | After this long waiting on the host, a job may start into moderate overload, but only while no leased job runs, so a grace never starts two jobs together. `0` is no grace. |
313
- | `hard_factor` | number | `2` | Never start, grace or not, while load or IO is at this many times its limit; such a job waits until `max_wait`, then exits 75. |
314
- | `hold_warn` | seconds | `1800` | A job running past this prints one warning, and `pmcp heavy status` marks it. |
315
- | `hold_max` | seconds | none | `pmcp heavy status` flags a job past this as over the limit. Nothing is killed. |
316
- | `memory_max` | size | none | Runs each command in `systemd-run --user --scope -p MemoryMax=<size> -p MemorySwapMax=0` where that is available, so a runaway job is killed alone. |
317
- | `heartbeat`, `poll` | seconds | `60`, `15` | How often a waiter prints that it is still waiting, and how often the host is reread. |
318
- | `profiles.<name>` | table | gate 2700/600, hook 900/30 | `max_wait`, `load_grace` and `memory_max` for `pmcp heavy --profile <name>`. The `gate` and `hook` profiles also choose their lane. Any other profile starts from the top-level values. |
319
- | `heavy` | argv lists | none | The commands the `host.lease` guard expects under the lease, as argv prefixes. Empty, the guard is off. pmcp lists none of its own. |
320
- | `guard` | string | `observe` | The `host.lease` guard's mode: `observe` logs only, `warn` tells the agent, `deny` refuses with the command to run instead (`pmcp heavy -- <command>`), `off`. A command already wrapped passes. |
321
- | `io.enabled` | `"auto"` or boolean | `"auto"` | Each leased job runs in its own `systemd-run --user` scope and gets its lane's `io.weight` where the cgroup v2 io controller reaches the user manager; elsewhere nothing changes. `true` also says when it could not; `false` never. |
322
- | `io.weights.<lane>` | integer | gate 500, hook 300, interactive 100, bulk 25 | The scope's `io.weight` per lane (1 to 10000). |
323
- | `io.max.<lane>` | string | none | An `io.max` line for the lane's scopes, such as `"259:0 wbps=50000000"`; the device is this host's to name. |
324
- | `settle_window` | seconds | `60` | After a leased job ends, its own leftover IO may hold the queue only this long: then a waiter starts on a moderately busy host (below `hard_factor`). `0` turns it off. |
325
- | `usage_cap` | bytes | `5000000` | `usage.jsonl` (one record per run) moves to `usage.jsonl.1` past this size. |
295
+ | Key | Type | Default | Meaning |
296
+ | ------------------- | ------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
297
+ | `enabled` | boolean | `true` | `false` runs every `pmcp heavy` command at once, gates without the lease and turns the guard off. |
298
+ | `dir` | path | `~/.cache/pmcp/host` | Where the lock file (`heavy.lock`), the admission lock, the `running/` and `waiters/` records, the holder record and `heavy.log` live. Every tool sharing the lease names the same directory. |
299
+ | `budget` | integer | `4` | The most weight that runs at once. `1` is one job at a time. |
300
+ | `lanes.<lane>` | integer | gate 1, hook 1, interactive 2, bulk 1 | How many jobs of a lane run at once; `0` closes the lane. |
301
+ | `weights.<lane>` | integer | gate 1, hook 1, interactive 2, bulk 3 | A job's weight when neither `--weight` nor a `commands` entry names one. A weight above the budget counts as the budget. |
302
+ | `commands` | tables | none | `argv` prefix, `lane` and `weight` for commands run without `--lane` or `--weight`; the first match wins. |
303
+ | `tiny` | argv lists | none | Commands so short (a few seconds) that they take no slot and no budget (weight 0, also `--weight 0`); only the hard ceiling holds them back, and the log still records them. |
304
+ | `per_session` | integer | `1` | How many jobs one agent session may have queued in the interactive lane, and in the bulk lane; the next one waits outside the queue holding no place. `0` is no cap. Gate and hook are exempt. |
305
+ | `marker_env` | name | `PMCP_HEAVY_LEASE` | Set to the job's pid for the leased command; a nested `pmcp heavy` whose marker names a running job runs at once. |
306
+ | `legacy_marker_env` | name | none | A second marker, set and honoured like `marker_env`, for a shell wrapper that shares `dir`. |
307
+ | `legacy_skip_env` | name | none | A second skip variable, honoured like `PMCP_HEAVY_DISABLE`, and set for the leased command so a nested shell wrapper runs at once. |
308
+ | `max_load` | number | the CPU count | A job starts only while the 1-minute load average is below this. |
309
+ | `max_io` | number | `8` | And while IO pressure (`some`, the `io_window` average) is below this. A host without pressure files checks load only; one without a load average checks neither. |
310
+ | `io_window` | string | `avg60` | Which pressure average the check reads: `avg10` follows spikes, `avg60` and `avg300` smooth them so the queue does not stall on a burst. |
311
+ | `max_wait` | seconds | `3600` | How long the `default` profile waits; then nothing runs and the exit is 75. |
312
+ | `load_grace` | seconds | `900` | After this long waiting on the host, a job may start into moderate overload, but only while no leased job runs, so a grace never starts two jobs together. `0` is no grace. |
313
+ | `hard_factor` | number | `2` | Never start, grace or not, while load or IO is at this many times its limit; such a job waits until `max_wait`, then exits 75. |
314
+ | `hold_warn` | seconds | `1800` | A job running past this prints one warning, and `pmcp heavy status` marks it. |
315
+ | `hold_max` | seconds | none | `pmcp heavy status` flags a job past this as over the limit. Nothing is killed. |
316
+ | `memory_max` | size | none | Runs each command in `systemd-run --user --scope -p MemoryMax=<size> -p MemorySwapMax=0` where that is available, so a runaway job is killed alone. Without a reachable user manager (no `XDG_RUNTIME_DIR`, or no manager socket in it, as under `env -i` or cron) the command runs without the scope and one line on stderr says why; if `systemd-run` still cannot reach the bus, the command runs once more without it. A missing scope never fails the command. |
317
+ | `heartbeat`, `poll` | seconds | `60`, `15` | How often a waiter prints that it is still waiting, and how often the host is reread. |
318
+ | `profiles.<name>` | table | gate 2700/600, hook 900/30 | `max_wait`, `load_grace` and `memory_max` for `pmcp heavy --profile <name>`. The `gate` and `hook` profiles also choose their lane. Any other profile starts from the top-level values. |
319
+ | `heavy` | argv lists | none | The commands the `host.lease` guard expects under the lease, as argv prefixes. Empty, the guard is off. pmcp lists none of its own. |
320
+ | `guard` | string | `observe` | The `host.lease` guard's mode: `observe` logs only, `warn` tells the agent, `deny` refuses with the command to run instead (`pmcp heavy -- <command>`), `off`. A command already wrapped passes. |
321
+ | `io.enabled` | `"auto"` or boolean | `"auto"` | Each leased job runs in its own `systemd-run --user` scope and gets its lane's `io.weight` where the cgroup v2 io controller reaches the user manager; elsewhere nothing changes. `true` also says when it could not; `false` never. |
322
+ | `io.weights.<lane>` | integer | gate 500, hook 300, interactive 100, bulk 25 | The scope's `io.weight` per lane (1 to 10000). |
323
+ | `io.max.<lane>` | string | none | An `io.max` line for the lane's scopes, such as `"259:0 wbps=50000000"`; the device is this host's to name. |
324
+ | `settle_window` | seconds | `60` | After a leased job ends, its own leftover IO may hold the queue only this long: then a waiter starts on a moderately busy host (below `hard_factor`). `0` turns it off. |
325
+ | `usage_cap` | bytes | `5000000` | `usage.jsonl` (one record per run) moves to `usage.jsonl.1` past this size. |
326
326
 
327
327
  Lanes, in the order a short budget goes to them: `gate` (a land's gate),
328
328
  `hook` (commit-hook work, a short slot that skips the host wait unless the host
@@ -722,7 +722,7 @@ Worktrees, delivery to the mainline and main checkout sync: [Git workflow](git-w
722
722
  ## Budget
723
723
 
724
724
  `[budget]` sets limits on what every agent session loads and on paths the
725
- project keeps out of its tree. `pmcp project --check` exits 2 when one is
725
+ project keeps out of its tree. `pmcp project --check` exits 4 when one is
726
726
  exceeded, naming each, and `pmcp status` shows the measurements beside the
727
727
  limits (its JSON gains `budget: {rows, problems}`, and an exceeded limit counts
728
728
  as drift). Every key is optional; nothing is checked without the table.
@@ -73,6 +73,8 @@ Config budget changes apply to a new group; existing groups keep their grants.
73
73
  `pmcp tui launch --yes` explicitly confirms the first start without the prompt.
74
74
  Launch still requires a supported interactive terminal. `pmcp tui plan` reports
75
75
  resolved settings and saved paths without writing or invoking a provider.
76
+ `plan`, `doctor`, `recovery` and `start-worker` print their receipt as text; add
77
+ `--json` for the [JSON envelope](commands.md#json-output).
76
78
  The launcher checkpoint lives under XDG_STATE_HOME/pmcp/launcher, or
77
79
  ~/.local/state/pmcp/launcher, with private file permissions.
78
80
 
package/docs/upgrading.md CHANGED
@@ -5,6 +5,49 @@
5
5
  What to do when a release changes something you rely on. Each release's notes on GitHub
6
6
  Releases list its breaking changes and link here.
7
7
 
8
+ ## From 0.22 to 0.23
9
+
10
+ 0.23.0 makes the command line behave like other command-line tools; several changes break
11
+ scripts that relied on the old behaviour.
12
+
13
+ **Results go to standard output.** The human result of a command (the `list`, `models`,
14
+ `marketplace list` and `doctor` tables, `validate` findings, the `status` summary, `hooks`
15
+ and `sessions` listings, an `install` or `sync` plan, and help you asked for with `--help`)
16
+ now goes to standard output; before, it went to standard error. Progress, summaries,
17
+ warnings and errors stay on standard error. `-q` silences only standard error (errors still
18
+ print), so `pmcp -q list` prints the table. A script that captured a table with `2>&1` or
19
+ `2>file` should read standard output instead; one that discarded standard output to keep a
20
+ terminal quiet should redirect it too. Off a terminal a table is now one unpadded record per line
21
+ (`name description`), and on a terminal it wraps to the width.
22
+
23
+ **A leading option `serve` does not accept no longer starts the server.** `pmcp -v`,
24
+ `pmcp -V` and `pmcp version` print the version, like `--version`. Any other leading option,
25
+ such as `-x` or `--verison`, exits 2. A host that starts the server with leading options
26
+ (`pmcp --root ./node_modules`) is unaffected; one that passed an option `serve` rejects was
27
+ already failing. A short flag a command does not declare (`pmcp list -j`) exits 2 instead of
28
+ being ignored; use `--` before a positional that starts with a dash. A word after
29
+ `pmcp list` or `pmcp models`, which take none, exits 2 instead of being ignored.
30
+
31
+ **Drift has its own exit code, 4.** `pmcp status` with drift or an exceeded budget,
32
+ `pmcp project --check` with drifted, stale or undeclared outputs, `project --check --smoke`
33
+ and `hooks test --fixtures` with a finding now exit 4; before, the first three exited 2,
34
+ the same code as a mistyped flag, and `hooks test --fixtures` exited 1. Exit 2 now means
35
+ only that the command could not run as asked (bad arguments, no `pmcp.toml`). A failed
36
+ fetch in `pmcp git deliver` or `pmcp git sync` now exits 1, like the other failures, rather
37
+ than 2. A CI step that treated any non-zero code as failure needs no change; one that tested
38
+ for `2` to detect drift should test for `4`. See
39
+ [Exit codes](commands.md#exit-codes).
40
+
41
+ **`--json` prints one envelope.** Every `--json` output is now one line,
42
+ `{"schema":"pmcp.<command>[.<subcommand>].v1","ok":…,"data":…,"errors":[…]}`, and it is
43
+ printed on failure too (before, a failure printed nothing on standard output). What a
44
+ command printed before is `data`, unchanged, `version: 1` included: read `.data.policies`
45
+ where you read `.policies`, `.data` where `models --json` gave a bare array. `ok` mirrors
46
+ exit code 0, and `errors` carries the messages that went to standard error. `mcp status`
47
+ and the `tui plan`, `tui doctor`, `tui recovery` and `tui start-worker` receipts are human
48
+ text unless `--json` is given; before, they always printed JSON. `mailbox` and `harness`
49
+ keep their JSON receipts unchanged. See [JSON output](commands.md#json-output).
50
+
8
51
  ## From 0.22.12 to 0.22.13
9
52
 
10
53
  **A gate command that exits 75 makes `pmcp git deliver` exit 75.** 75 now means a test stage
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "pmcp",
3
- "version": "0.22.13",
3
+ "version": "0.23.1",
4
4
  "mcpServers": {
5
5
  "pmcp": {
6
6
  "type": "stdio",
7
7
  "command": "npx",
8
- "args": ["-y", "@modootoday/pmcp@0.22.13", "serve"]
8
+ "args": ["-y", "@modootoday/pmcp@0.23.1", "serve"]
9
9
  }
10
10
  }
11
11
  }
package/mcp.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "pmcp": {
5
5
  "type": "stdio",
6
6
  "command": "npx",
7
- "args": ["-y", "@modootoday/pmcp@0.22.13", "serve"]
7
+ "args": ["-y", "@modootoday/pmcp@0.23.1", "serve"]
8
8
  }
9
9
  }
10
10
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@modootoday/pmcp",
3
- "version": "0.22.13",
3
+ "version": "0.23.1",
4
4
  "license": "Elastic-2.0",
5
5
  "author": "modootoday",
6
6
  "description": "Use the skills your packages already ship, and keep your AI tools' project configuration in one place.",
@@ -136,9 +136,9 @@
136
136
  "bun": ">=1.3.0"
137
137
  },
138
138
  "optionalDependencies": {
139
- "@modootoday/pmcp-linux-x64": "0.22.13",
140
- "@modootoday/pmcp-linux-arm64": "0.22.13",
141
- "@modootoday/pmcp-darwin-x64": "0.22.13",
142
- "@modootoday/pmcp-darwin-arm64": "0.22.13"
139
+ "@modootoday/pmcp-linux-x64": "0.23.1",
140
+ "@modootoday/pmcp-linux-arm64": "0.23.1",
141
+ "@modootoday/pmcp-darwin-x64": "0.23.1",
142
+ "@modootoday/pmcp-darwin-arm64": "0.23.1"
143
143
  }
144
144
  }
package/plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3
3
  "name": "pmcp",
4
- "version": "0.22.13",
4
+ "version": "0.23.1",
5
5
  "description": "Find package skills and use native runtime project configuration.",
6
6
  "author": { "name": "modootoday" },
7
7
  "license": "Elastic-2.0",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pmcp",
3
- "version": "0.22.13",
3
+ "version": "0.23.1",
4
4
  "description": "Find package skills and use native runtime project configuration.",
5
5
  "author": { "name": "modootoday" },
6
6
  "license": "Elastic-2.0",
@@ -3,7 +3,7 @@
3
3
  "pmcp": {
4
4
  "type": "stdio",
5
5
  "command": "npx",
6
- "args": ["-y", "@modootoday/pmcp@0.22.13", "serve"]
6
+ "args": ["-y", "@modootoday/pmcp@0.23.1", "serve"]
7
7
  }
8
8
  }
9
9
  }
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "pmcp",
3
- "version": "0.22.13",
3
+ "version": "0.23.1",
4
4
  "mcpServers": {
5
5
  "pmcp": {
6
6
  "type": "stdio",
7
7
  "command": "npx",
8
- "args": ["-y", "@modootoday/pmcp@0.22.13", "serve"]
8
+ "args": ["-y", "@modootoday/pmcp@0.23.1", "serve"]
9
9
  }
10
10
  }
11
11
  }
@@ -4,7 +4,7 @@
4
4
  "pmcp": {
5
5
  "type": "stdio",
6
6
  "command": "npx",
7
- "args": ["-y", "@modootoday/pmcp@0.22.13", "serve"]
7
+ "args": ["-y", "@modootoday/pmcp@0.23.1", "serve"]
8
8
  }
9
9
  }
10
10
  }
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3
3
  "name": "pmcp",
4
- "version": "0.22.13",
4
+ "version": "0.23.1",
5
5
  "description": "Find package skills and use native runtime project configuration.",
6
6
  "author": { "name": "modootoday" },
7
7
  "license": "Elastic-2.0",
@@ -73,7 +73,7 @@ tool can supply and grep for it.
73
73
  ## Projection gate
74
74
 
75
75
  ```sh
76
- pmcp project --check # exit 2: generated files drifted, went stale or are undeclared
76
+ pmcp project --check # exit 4: generated files drifted, went stale or are undeclared
77
77
  pmcp doctor # exit 1 on any failed check
78
78
  ```
79
79
 
@@ -123,7 +123,7 @@ next prompt; SessionEnd hooks get at most 3 seconds.
123
123
 
124
124
  ```sh
125
125
  pmcp project # write; exits 1 if it would overwrite a file it did not write
126
- pmcp project --check # write nothing; exit 2 on drift, stale, undeclared or dead-glob outputs
126
+ pmcp project --check # write nothing; exit 4 on drift, stale, undeclared or dead-glob outputs
127
127
  pmcp doctor # exit 1 on any failed check; prints the feature x runtime table
128
128
  ```
129
129
 
@@ -65,8 +65,9 @@ pmcp git deliver <commit>... # only these
65
65
 
66
66
  It fetches, replays the commits onto the mainline, runs the gate in its own tree under a
67
67
  lock, and pushes, replaying again if the mainline moved. Exit 0 delivered or nothing to
68
- deliver; 1 refused (pause, lease, gate failure, attempts exhausted) with the reason on
69
- stderr; 2 the fetch failed. Fix what the gate reports; never bypass it with
68
+ deliver; 1 refused (pause, lease, gate failure, attempts exhausted, failed fetch) with the
69
+ reason on stderr; 75 the gate never got the host lease, so retry later. Fix what the gate
70
+ reports; never bypass it with
70
71
  `--no-verify` or a gate-bypass variable, which the guards refuse.
71
72
 
72
73
  `pmcp git sync` moves the main checkout to the mainline afterwards; it refuses (exit 2)
@@ -73,7 +73,7 @@ tool can supply and grep for it.
73
73
  ## Projection gate
74
74
 
75
75
  ```sh
76
- pmcp project --check # exit 2: generated files drifted, went stale or are undeclared
76
+ pmcp project --check # exit 4: generated files drifted, went stale or are undeclared
77
77
  pmcp doctor # exit 1 on any failed check
78
78
  ```
79
79
 
@@ -123,7 +123,7 @@ next prompt; SessionEnd hooks get at most 3 seconds.
123
123
 
124
124
  ```sh
125
125
  pmcp project # write; exits 1 if it would overwrite a file it did not write
126
- pmcp project --check # write nothing; exit 2 on drift, stale, undeclared or dead-glob outputs
126
+ pmcp project --check # write nothing; exit 4 on drift, stale, undeclared or dead-glob outputs
127
127
  pmcp doctor # exit 1 on any failed check; prints the feature x runtime table
128
128
  ```
129
129
 
@@ -65,8 +65,9 @@ pmcp git deliver <commit>... # only these
65
65
 
66
66
  It fetches, replays the commits onto the mainline, runs the gate in its own tree under a
67
67
  lock, and pushes, replaying again if the mainline moved. Exit 0 delivered or nothing to
68
- deliver; 1 refused (pause, lease, gate failure, attempts exhausted) with the reason on
69
- stderr; 2 the fetch failed. Fix what the gate reports; never bypass it with
68
+ deliver; 1 refused (pause, lease, gate failure, attempts exhausted, failed fetch) with the
69
+ reason on stderr; 75 the gate never got the host lease, so retry later. Fix what the gate
70
+ reports; never bypass it with
70
71
  `--no-verify` or a gate-bypass variable, which the guards refuse.
71
72
 
72
73
  `pmcp git sync` moves the main checkout to the mainline afterwards; it refuses (exit 2)