@inventarch/cli 3.0.0 → 3.1.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 (102) hide show
  1. package/README.md +221 -23
  2. package/SPEC.md +39 -18
  3. package/assets/base/df626d1dc4949649ba7203842b29b4f064e0552e8db8c2c41ff74b6462b81b75.ia.tgz +0 -0
  4. package/assets/base.json +3 -3
  5. package/assets/host/f91ffe4c2071b196e925e93507bd661b3e09f5dc75392f7d6453fdbec5e28d62.tgz +0 -0
  6. package/assets/host.json +4 -4
  7. package/assets/vocabulary.json +152 -1
  8. package/dist/author.d.ts.map +1 -1
  9. package/dist/author.js +6 -7
  10. package/dist/author.js.map +1 -1
  11. package/dist/briefing.d.ts +2 -2
  12. package/dist/briefing.d.ts.map +1 -1
  13. package/dist/capture.d.ts +2 -2
  14. package/dist/capture.js +7 -7
  15. package/dist/commands.d.ts +7 -7
  16. package/dist/commands.d.ts.map +1 -1
  17. package/dist/commands.js +69 -30
  18. package/dist/commands.js.map +1 -1
  19. package/dist/consumer.d.ts +29 -25
  20. package/dist/consumer.d.ts.map +1 -1
  21. package/dist/consumer.js +40 -35
  22. package/dist/consumer.js.map +1 -1
  23. package/dist/decline.js +1 -1
  24. package/dist/distribute.d.ts +13 -14
  25. package/dist/distribute.d.ts.map +1 -1
  26. package/dist/distribute.js +17 -17
  27. package/dist/distribute.js.map +1 -1
  28. package/dist/doctor-user.d.ts +1 -1
  29. package/dist/doctor-user.d.ts.map +1 -1
  30. package/dist/doctor-user.js +2 -2
  31. package/dist/doctor-user.js.map +1 -1
  32. package/dist/doctor.d.ts +1 -1
  33. package/dist/doctor.d.ts.map +1 -1
  34. package/dist/doctor.js +53 -54
  35. package/dist/doctor.js.map +1 -1
  36. package/dist/format.js +3 -3
  37. package/dist/format.js.map +1 -1
  38. package/dist/home-remedy.d.ts +1 -1
  39. package/dist/home-remedy.js +1 -1
  40. package/dist/host-projection.d.ts +41 -38
  41. package/dist/host-projection.d.ts.map +1 -1
  42. package/dist/host-projection.js +84 -71
  43. package/dist/host-projection.js.map +1 -1
  44. package/dist/host.d.ts +37 -38
  45. package/dist/host.d.ts.map +1 -1
  46. package/dist/host.js +54 -57
  47. package/dist/host.js.map +1 -1
  48. package/dist/init.d.ts +69 -58
  49. package/dist/init.d.ts.map +1 -1
  50. package/dist/init.js +166 -107
  51. package/dist/init.js.map +1 -1
  52. package/dist/main.js +4 -4
  53. package/dist/main.js.map +1 -1
  54. package/dist/next.js +15 -15
  55. package/dist/next.js.map +1 -1
  56. package/dist/operation-help.d.ts +3 -3
  57. package/dist/operation-help.d.ts.map +1 -1
  58. package/dist/operation-help.js +9 -9
  59. package/dist/operation-help.js.map +1 -1
  60. package/dist/pack.js +6 -6
  61. package/dist/plugin-product.d.ts +3 -0
  62. package/dist/plugin-product.d.ts.map +1 -0
  63. package/dist/plugin-product.js +154 -0
  64. package/dist/plugin-product.js.map +1 -0
  65. package/dist/plugin-sources.d.ts +16 -0
  66. package/dist/plugin-sources.d.ts.map +1 -0
  67. package/dist/plugin-sources.js +120 -0
  68. package/dist/plugin-sources.js.map +1 -0
  69. package/dist/position.d.ts.map +1 -1
  70. package/dist/position.js +10 -11
  71. package/dist/position.js.map +1 -1
  72. package/dist/preview.d.ts +4 -4
  73. package/dist/preview.d.ts.map +1 -1
  74. package/dist/preview.js +27 -28
  75. package/dist/preview.js.map +1 -1
  76. package/dist/profile.d.ts +23 -23
  77. package/dist/profile.d.ts.map +1 -1
  78. package/dist/profile.js +53 -54
  79. package/dist/profile.js.map +1 -1
  80. package/dist/project.d.ts +7 -8
  81. package/dist/project.d.ts.map +1 -1
  82. package/dist/project.js +38 -28
  83. package/dist/project.js.map +1 -1
  84. package/dist/read.d.ts +1 -1
  85. package/dist/read.d.ts.map +1 -1
  86. package/dist/read.js +4 -4
  87. package/dist/read.js.map +1 -1
  88. package/dist/render.d.ts +3 -3
  89. package/dist/render.js +3 -3
  90. package/dist/session.d.ts +9 -9
  91. package/dist/session.d.ts.map +1 -1
  92. package/dist/session.js +10 -10
  93. package/dist/session.js.map +1 -1
  94. package/dist/validate.d.ts +8 -8
  95. package/dist/validate.d.ts.map +1 -1
  96. package/dist/validate.js +34 -37
  97. package/dist/validate.js.map +1 -1
  98. package/dist/vocabulary.js +2 -2
  99. package/dist/vocabulary.js.map +1 -1
  100. package/package.json +6 -6
  101. package/assets/base/08eaab3e1a6215d78283b82a94a0228367ac7bd78d0a746c56db79c8d7546c3a.ia.tgz +0 -0
  102. package/assets/host/d7722e32fd0511df2a6dfdf2353e621fdff1cf559d5c8b7ac256c7eceac0452f.tgz +0 -0
package/README.md CHANGED
@@ -1,43 +1,241 @@
1
1
  # @inventarch/cli
2
2
 
3
- The IA 2.0.0 command-line interface creates workspaces, validates, inspects, reads and captures native records, shows the position body for a scope key and a plan's delivery view, projects the position packet for an IDE host, and manages native distributions and host registrations. It requires Node.js 22.22.0 or later within Node 22.
3
+ [![npm](https://img.shields.io/npm/v/@inventarch/cli?label=npm)](https://www.npmjs.com/package/@inventarch/cli) [![Public quality](https://github.com/inventarch/ia/actions/workflows/platform-quality.yml/badge.svg?branch=main)](https://github.com/inventarch/ia/actions/workflows/platform-quality.yml) [![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE) [![Node](https://img.shields.io/badge/node-22.x-brightgreen)](package.json)
4
4
 
5
- Install the [published package](https://www.npmjs.com/package/@inventarch/cli) globally with `npm install --global @inventarch/cli@2.0.0` to use `ia` across projects. For a project-local installation, run `npm install --save-dev --save-exact @inventarch/cli@2.0.0` in your JavaScript or TypeScript repository and use `npx ia` in place of `ia`. Either way, each initialized project keeps its own records in `.ia/`.
5
+ > `@inventarch/cli` is the `ia` command, the entry point to IA for people and coding agents. It creates workspaces, previews and authors records, validates and captures them, prints the position and delivery view an agent starts from, projects that position for Claude Code and Codex, turns a host plugin into a kit workspace and back, and installs native distributions.
6
+ >
7
+ > It bundles the language base, vocabulary catalogue and host payload its commands need, so `ia init` and `ia validate` run offline. The [MCP server](https://github.com/inventarch/ia/blob/main/apps/mcp-door/README.md) and the [runner](https://github.com/inventarch/ia/blob/main/apps/runner/README.md) are separate packages.
6
8
 
7
- The [main quick start](https://github.com/inventarch/ia#-quick-start) walks through initialization, a first record, validation and VS Code setup. To run from a source checkout, run `pnpm install --frozen-lockfile` and `pnpm build`, then use `node /path/to/ia/apps/cli/dist/main.js` in place of `ia`.
9
+ ## ⚡ Quick start
10
+
11
+ Use **Node.js `>=22.22.0 <23`**. Install the CLI globally to make `ia` available in every project, including projects without a `package.json`:
8
12
 
9
13
  ```sh
14
+ npm install --global @inventarch/cli
10
15
  ia --version
11
- ia init demo --host none
12
- ia init demo --host none --apply --yes
13
- ia validate --root demo
14
- ia capture --root demo
15
- ia inspect --root demo
16
- ia read agent-system/binding/agent/public-agent-system-steward --root demo
17
- ia project claude --root demo
18
- ia vocabulary plan --schema
19
16
  ```
20
17
 
21
- `init` previews changes unless `--apply` is supplied. Its language base, `inventarch/language`, follows the coordinated release artifact version and is bundled with the CLI, so creating a workspace needs no registry connection. IA syntax remains 1.0. It authors three records in `.ia/src/workspace.ia`: the `@workspace demo` record, which composes the eleven public systems and declares `.ia/src` as its authored source, the participant `@agent demo`, the IDE agent working in it, and that agent's `@mandate demo-mandate`. Place authored `.ia` files beside it anywhere under `.ia/src/` except `.ia/src/floor/`, which would replace the embedded language floor, and `.ia/src/systems/`, where every folder must be a system folder with its own `system.ia`; a record's word decides which system owns it. `init` also writes `.ia/.gitignore` (ignoring `work/` and `distributions/`) unless one exists, then captures the workspace, and with `--host` writes that host's projection. `--system` adds a local `@system demo`, its steward and a `@distribution` in `.ia/src/systems/demo/` for a repository that will release vocabulary, and the `@workspace` composes that system too; without it the workspace releases nothing, and `ia pack` refuses. `ia init --migrate` previews, and with `--apply` makes, the move of a workspace an IA 1.0 or 1.1 `ia init` created to this shape: where the workspace has a 1.x language base, whose schemas lack fields the three records use, it first installs the bundled one in its place, then its own record files leave `.ia/src/systems/demo/records/` for `.ia/src/`, keeping their identities, the three records replace the 1.1.0 `@workspace` and `@distribution`, and the local system goes unless `--system` keeps it. It then captures the workspace and re-projects each registered host, which retires the 1.1.0 steward guard and deletes the steward agent files. A workspace of any other shape is refused before anything is written, and so is one with a file in the way or one that already holds an `@agent demo` or `@mandate demo-mandate` of its own, which would tie with the new records.
18
+ <details>
19
+ <summary>Prefer a project-local install for a JavaScript or TypeScript repository?</summary>
20
+
21
+ ```sh
22
+ npm install --save-dev --save-exact @inventarch/cli
23
+ npx ia --version
24
+ ```
25
+
26
+ Use `npx ia` wherever this guide uses `ia`, and commit your `package.json` and lockfile. With pnpm, use `pnpm add --save-dev --save-exact @inventarch/cli` and `pnpm exec ia`.
27
+
28
+ </details>
29
+
30
+ Then, in your project directory:
31
+
32
+ ```sh
33
+ ia init . --host none # the plan; writes nothing
34
+ ia init . --host none --apply --yes # install the bundled base, author the starter, capture
35
+ ia validate
36
+ ia position
37
+ ```
38
+
39
+ Each project keeps its own records in its own `.ia/` directory. The [main quick start](https://github.com/inventarch/ia#-quick-start) continues with a first record, a plan and host setup. To run from a source checkout, build it as the [contributing section](https://github.com/inventarch/ia#-contributing-and-verification) describes and use `node /path/to/ia/apps/cli/dist/main.js` in place of `ia`.
40
+
41
+ ## ⌨️ Commands
42
+
43
+ `ia --help` lists every command and `ia <command> --help` gives its full syntax. These rules hold across them:
44
+
45
+ - **Plan, then apply.** `init`, `install`, `adopt`, `update`, `remove`, `project` and `host` print a plan and act only with `--apply`, which needs `--yes` without a terminal or with `--json`. A plan applies nothing, though acquiring for an install or update plan may fill the archive cache. `restore` has no preview, so it always takes `--apply`.
46
+ - **One next command.** Every consumer-command refusal names the one command to run next, on the `→` line or as `next` in the `--json` object `{version, ok: false, code, message, exit, where, next}`.
47
+ - **One workspace.** `--root <path>` selects the workspace; by default it is the nearest ancestor holding `.ia/src`. `ia init` takes its directory as an argument instead. `--json` prints one JSON value, with no color, progress or prompts.
48
+
49
+ Automation should read the exit value together with the diagnostic code:
50
+
51
+ | Exit | Means |
52
+ | --- | --- |
53
+ | `0` | Success; warnings alone exit 0 |
54
+ | `1` | Validation errors, and refusals such as a mandate refusal or a stale `--digest` |
55
+ | `2` | Usage errors |
56
+ | `3` | Unavailable inputs and local operational refusals |
57
+ | `130` | Interrupted |
58
+
59
+ ### ✍️ Authoring and checking
60
+
61
+ | Command | What it does |
62
+ | --- | --- |
63
+ | `ia init [<directory>]` | Plans a workspace. `--apply` installs the bundled `inventarch/language` base, writes `.ia/src/workspace.ia` with three starter records (a `@workspace`, its participant `@agent` and that agent's `@mandate`), `.ia/.gitignore` and `.ia/release.json`, then captures. `--host claude` or `--host codex` also registers that host, as `ia host --apply` does. `--system` adds a local `@system` and `@distribution` so `ia pack` can release it. `--from <plugin-directory>` lowers a Claude, Codex or Grok plugin into the new workspace as a kit instead (see [host plugins](#-host-plugins)). `--migrate` moves a workspace an IA 1.0 or 1.1 `init` created to this layout. |
64
+ | `ia preview` | Shows what one new record, one field (`--set`) or one relationship (`--relate`) would compile to: the record before and after, the findings it adds and the target file's `sha256`. `ia preview <word>` prints a word's schema, default file and permitted relationships. It writes nothing. |
65
+ | `ia author` | Writes what the same preview showed. It takes the preview's arguments plus `--digest <sha256>`, writes only while the file still has that digest and the candidate is clean, and adds one `# authored-by` line naming the participant and mandate above the record. |
66
+ | `ia validate [<path>...]` | Admits the workspace and reports findings, with `--severity` and `--max-findings`. It can record the checks that passed or failed as evidence under `.ia/work/evidence/`. |
67
+ | `ia capture` | Writes the admitted snapshot to `.ia/work/snapshot/current.json`, moves the prior capture at another revision to `previous.json`, and reports how many records changed, stayed, are new or were removed. `--preview` reports the same and writes nothing. |
68
+ | `ia format [<path>...]` | Checks formatting, or rewrites files with `--write`. |
69
+
70
+ ```sh
71
+ ia preview decision
72
+ ia preview --set @plan public-api work.source=docs/api.md
73
+ ia author --set @plan public-api work.source=docs/api.md --digest <sha256-from-the-preview>
74
+ ia validate
75
+ ia capture --preview
76
+ ia capture
77
+ ia format
78
+ ```
79
+
80
+ If the file changed since the preview, `ia author` refuses with `IA-CLI-EDIT-STALE` and names the preview to run again. `ia author` refuses the administrative words `workspace`, `agent`, `mandate`, `system`, `schema`, `agent-profile` and `hook` for every actor, with `IA-CLI-EDIT-AUTHORITY`: an owner changes those records in source and runs `ia validate`. You can also edit any `.ia` file by hand; `ia validate` checks it the same way. A capture with admission errors still writes its snapshot, records the findings in it and exits 1. A root whose `.ia/src` declares no `@workspace` is refused before anything is written. `.ia/.gitignore` keeps `work/` out of version control, so each clone captures for itself.
81
+
82
+ > [!IMPORTANT]
83
+ > **`ia compile` was removed in 3.0.** Every invocation, `--help` included, exits 2 and names `ia capture --help`. Use `ia capture`, keep `--preview`, `--json`, `--root` and `--actor` where you used them, and drop `--force`, since capture always writes. `--out` and `--stdout` have no equivalent: capture writes the fixed snapshot files above, not the 1.x `ia.compiled.v1` artifact. The `@inventarch/cli/internal/compile` helpers remain for programmatic callers.
84
+
85
+ ### 🧭 Reading and navigating
86
+
87
+ | Command | What it does |
88
+ | --- | --- |
89
+ | `ia position` | Prints the position body for a scope key: `--seat <id\|path>`, `--shape` (`context`, `governance`, `execution`, `sequence` or `learning`), `--phase` (`orient`, `plan`, `act` or `learn`), `--depth` (0 to 2), `--budget` (0 to 64) and `--word`. With no flag it prints the repository's `@workspace` with its pointers only. It needs no capture and writes nothing. |
90
+ | `ia next` | Prints one plan's delivery view: its milestones, then its tasks in prerequisite order, each with a verdict of `exit evidence recorded (…)`, `no declared blocker` or `blocked (…)`. `--seat` names a `@plan`, `@milestone` or `@task`; without it, the workspace's only `@plan`. |
91
+ | `ia read <locator>` | Prints the body behind a locator with its `sha256` and the line `body not certified by this read`. |
92
+ | `ia inspect [<identity>]` | Shows a workspace overview, or one record (by identity or `--path <file>`) with its edges, `--edges in\|out\|both` and `--depth` 0 to 3. |
93
+ | `ia vocabulary [<word>]` | Looks up the catalogue shipped with the package, with `--schema`, `--example`, `--domain`, `--kind` and `--search`. It opens no workspace. |
94
+
95
+ ```sh
96
+ ia position
97
+ ia position --seat work-system/definition/task/write-schema --shape sequence
98
+ ia next
99
+ ia read work-system/definition/decision/api-response-format
100
+ ia read .ia/src/work.ia:12
101
+ ia inspect work-system/definition/task/review-schema
102
+ ia vocabulary decision --schema
103
+ ```
104
+
105
+ `ia position` prints the key it used, whether the capture is current, the body's digest, the loaded records, pointers, rules and playbooks that apply, mandates, frontier and unknowns, and ends with two `ia position` commands that widen the view. `--word` narrows the loaded records and pointers to one word but never hides a blocking rule or a mandate. A shape, phase, depth or budget outside its set or cap exits 2 and names the same call with the set or cap. With `--json` it prints `{version, ok, body, digest, hostNote}`.
106
+
107
+ `ia next` computes each verdict from declared prerequisites and exit evidence: a success `@observation` on the task at its current digest. It prints `work.status` as self-declared and never uses it as the basis. In a workspace with no `@plan`, it names `ia preview plan`. The view ends with the `ia position` command for the next unblocked task.
108
+
109
+ `ia read` accepts four locators: a record identity, `<identity>#<phase>/<Primitive>` for a playbook cell, `<identity>#<REQ-ID>` for one requirement, and `<path>:<line>` for the record whose source spans that line. A record that names a document (`work.source` on a `@spec`, `@plan`, `@milestone`, `@task` or `@decision`, `reference.document` on an `@authoring-guide`, `template.resource` on a `@template`) reads that file, and a markdown anchor such as `docs/api.md#response-format` reads only that section. Any other record reads its `meaning.says`:
110
+
111
+ ```text
112
+ Read work-system/definition/decision/api-response-format
113
+
114
+ • record
115
+ sha256 dae126797f0f… 44 bytes
116
+ body not certified by this read
117
+
118
+ Choose a response format for the public API.
119
+ ```
120
+
121
+ ### 🔌 Hosts
122
+
123
+ | Command | What it does |
124
+ | --- | --- |
125
+ | `ia project <claude\|codex>` | Plans the position packet files for one host. `--apply` writes them and a receipt. It registers no MCP server. With `--product plugin` it renders the host plugin a lowered workspace describes instead (see [host plugins](#-host-plugins)). |
126
+ | `ia host <claude\|codex>` | Plans the host registration: the MCP server, the same projection and the skills generated from your authored `@playbook` records, plus, for Claude, the agents and edit guards generated from `@agent-profile` and `@hook` records. `--apply` writes it; `--remove` plans removing what it owns. `ia host claude --user` registers a user-level plugin that needs no workspace. |
127
+ | `ia doctor` | Reports runtime, workspace, installation and host state, and suggests repairs without making them. `--host claude` or `--host codex` adds that host's session briefing. |
128
+
129
+ | Host | Position packet | Skill | MCP registration (`ia host` only) |
130
+ | --- | --- | --- | --- |
131
+ | Claude Code | `.claude/rules/ia-workspace.md` | `.claude/skills/ia-authoring/SKILL.md` | `.mcp.json` |
132
+ | Codex | `AGENTS.md` | `.agents/skills/ia-authoring/SKILL.md` | `.codex/config.toml` |
133
+
134
+ ```sh
135
+ ia project claude
136
+ ia project claude --apply --yes
137
+ ia host codex
138
+ ia doctor
139
+ ```
140
+
141
+ The receipt is `.ia/distributions/hosts/<host>-receipt.json`. `ia doctor` compares it with the files and with a fresh render, so an edited record shows as an `outdated` projection that names `ia project claude --apply`. A file IA did not write at one of these paths is named in the plan and refused by `--apply`. `ia host` treats what it writes as machine-local; do not commit those files. Codex reports generated agents and hooks as unsupported, and `ia host cursor` refuses with `IA-DIST-HOST-UNSUPPORTED`. The source-protection row of `ia doctor` warns when an authored `@mandate` declares a restriction but no authored `@hook` covers `.ia/src/**` for `Write`, `Edit` and `MultiEdit`. It never widens a hook's paths.
142
+
143
+ ### 🧩 Host plugins
22
144
 
23
- `ia capture` writes the admitted snapshot, with each record's digest and capture membership, to `.ia/work/snapshot/current.json` and keeps the most recent capture at another revision as `previous.json`; it reports how many records changed since the prior capture. `ia capture --preview` reports the same counts and names the changed, new and removed identities without writing anything, so the previous snapshot is not rotated away. It refuses, writing nothing, a directory whose `.ia/src` declares no `@workspace` and a floor, installed or adopted source that fails to parse; any other finding is written into the snapshot. `ia compile` is removed in 3.0. Replace it with `ia capture`, retaining `--preview`, `--json`, `--root` and `--actor` where needed, and omit `--force` because capture always writes. The old `--out` and `--stdout` options have no equivalent: capture writes the fixed snapshot files above, not the 1.x `ia.compiled.v1` artifact. Every `ia compile` invocation, including `--help`, exits 2 with migration guidance before opening a workspace. The published `@inventarch/cli/internal/compile` helpers remain available to programmatic callers.
145
+ A Claude Code, Codex or Grok plugin directory can become a kit workspace, and that workspace renders the plugin back:
146
+
147
+ | Command | What it does |
148
+ | --- | --- |
149
+ | `ia init <directory> --from <plugin-directory>` | Plans a workspace that holds the plugin as a kit: the three starter records, a system named after the workspace, `records/plugin.ia` (the product `@distribution`, a `@capability` for each skill, and an `@agent`, a tools `@capability` and an `@agent-profile` for each agent), each skill body, agent prompt and owned Markdown file as a pinned resource, every other file as an asset, and a lowering map with a generated `MIGRATION.md`. `--apply` writes it. It takes `--id`, but not `--system`, `--migrate`, `--adopt` or the decline options. |
150
+ | `ia project <claude\|codex> --product plugin --out <directory>` | Plans the plugin the workspace's product `@distribution` describes, with a manifest for every host its `product.hosts` lists, into an absent or empty directory outside the workspace. `--apply` writes it, create-only. |
151
+ | `ia project <claude\|codex> --product plugin --check [--compare <plugin-directory>]` | Renders the plugin in memory, lowers it again and requires the result to match the workspace byte for byte. `--compare` also compares each rendered file with the original plugin. It writes nothing. |
152
+
153
+ ```sh
154
+ ia init my-kit --from my-plugin
155
+ ia init my-kit --from my-plugin --apply --yes
156
+ ia project claude --product plugin --check --compare my-plugin --root my-kit
157
+ ia project claude --product plugin --out rendered --root my-kit --apply --yes
158
+ ```
24
159
 
25
- `ia read <locator>` prints the body behind a locator with its SHA-256 and the line `body not certified by this read`: the text of one cell (`<identity>#<phase>/<Primitive>`) or one requirement (`<identity>#<REQ-ID>`); else the document a record's source locator names (`work.source` on a `@spec`, `@plan`, `@milestone`, `@task` or `@decision`, `reference.document`, `template.resource`), only the section under its heading when the locator carries a markdown anchor, and for an adopted record from the directory `.ia/workspace.json` binds its mount to; else the record's own `meaning.says`. `<path>:<line>` reads the record whose source spans that line. It writes nothing, and `ia inspect` keeps the record's structure.
160
+ A successful check prints `Round trip: content-exact and a fixed point.` Lowering accepts only what rendering writes back: hooks, MCP and LSP configuration, `commands/`, and frontmatter or manifest forms the renderer would not reproduce are refused with `IA-LOWER-UNRESOLVED`, which counts and names them, and nothing is written. A drifted round trip fails with `IA-ROUNDTRIP-DRIFT`; `--json` carries the full report in `details`. The kit's release descriptor keeps the `UNLICENSED` license whatever the plugin's manifest states. The rules are in the [package contract](SPEC.md#host-plugins).
26
161
 
27
- `ia position [--seat <id|path>] [--shape <H>] [--phase <P>] [--depth <d>] [--budget <n>] [--word <w>]` prints the position body for a scope key: with no flag K0, the repository's workspace with its pointers and tallies only; otherwise the seat and the records loaded within the budget, the pointers past it (48 listed, the rest tallied), the rules and playbooks that apply by word with their playbook cells, the blocking rules reserved outside the budget, the mandates, the frontier and the unknowns. It prints the key used and the capture's freshness first, and the two widening keys last as `ia position` commands. `--word` restricts what loads, the pointers, their tallies and the frontier to one word, and never the reserved rules, the rules and playbooks that apply by word with their tallies and cells, or the mandates, so a word hides no blocking rule. With `--json` it prints `{version: 1, ok: true, body, digest, hostNote}`, what the runtime Door's `position` operation returns. A shape, phase, depth or budget outside its closed set or cap names the same call with the set or the cap in its place. It needs no capture and writes nothing, and `ia scope` stays the machine route.
162
+ ### 📦 Distributions
28
163
 
29
- `ia next [--seat <plan|milestone|task>]` prints one plan's delivery view, computed per read and never stored: the plan `--seat` belongs to, or without it the only `@plan` the workspace authors; its milestones; its tasks in prerequisite order, each with its verdict (`exit evidence recorded (…)`, `no declared blocker` or `blocked (…)`), a basis line per requirement, its `work.status` marked self-declared, which is never the verdict's basis, and five state lines; the review items; and the command for the next task with no declared blocker. Exit evidence is a success `@observation` on the task at its current digest. With `--json` it prints `{version: 1, ok: true, view}`, the view the runtime Door's `next` operation returns. A workspace `ia init` creates authors no plan, so there `ia next` names `ia preview plan`, which shows what a `@plan` holds and where it goes. It writes nothing.
164
+ | Command | What it does |
165
+ | --- | --- |
166
+ | `ia pack --descriptor <file>` | Builds a digest-named archive, by default under `.ia/work/dist`. A descriptor that names no distribution, as a default `init` writes, is refused; `ia init --system` authors one. |
167
+ | `ia install <id>[@<range>]...` | Plans an installation, kits included, from a registry, a `--catalog` or the `--offline` cache. |
168
+ | `ia adopt <id>[@version]` | Plans a source-only workspace adoption: pinned source mounted at band 50, then a capture and a refresh of registered projections. `ia init --adopt` adopts at initialization. |
169
+ | `ia update <id>` | Plans a version change for one direct request, `--to <range>`. |
170
+ | `ia remove <id>` | Plans the removal of one direct request. |
171
+ | `ia restore --apply` | Reinstalls the locked generation from its pinned archives. |
172
+ | `ia recover [installation\|host\|guard\|lifecycle] --root <directory>` | Finishes or rolls back an interrupted installation or host transaction. |
30
173
 
31
- `ia project <claude|codex>` plans the workspace's position packet for one host and writes nothing: the packet's entry count and digest, each file it would create, update, leave unchanged or delete (a marked agent file a 1.x `ia host` wrote), every other `.claude/agents` file, which it leaves in place, and whether it first retires the steward guard an earlier release registered. `--apply` writes the files, `.claude/rules/ia-workspace.md` and the `ia-authoring` skill for Claude or `AGENTS.md` and its skill for Codex, and the receipt `.ia/distributions/hosts/<host>-receipt.json`, which `ia doctor` compares with the files and with a fresh render, so an edit to a record shows as an outdated projection. A file it did not write at one of those paths is named in the plan and refused by `--apply`. It registers no MCP server; `ia host` registers one and writes the same projection.
174
+ ```sh
175
+ ia restore --apply --yes
176
+ ia update inventarch/language --offline
177
+ ia init my-lib --system --host none --apply --yes
178
+ ia pack --root my-lib --descriptor .ia/release.json
179
+ ia recover --root .
180
+ ```
181
+
182
+ `.ia/.gitignore` keeps `.ia/distributions/` out of version control, so commands in a fresh clone refuse until `ia restore --apply --yes` rebuilds it from `.ia/distributions.lock.json`. `--plan-out <file>` saves an install, update or remove plan under `.ia/work/`. A refusal that needs recovery names `ia recover … --root <directory>`, which runs the distribution recovery directly, so a global install needs no `ia-distribution` binary on `PATH`. Native package ids, such as `inventarch/language`, are separate from npm package names. In 3.x the bundled language base and the public native systems take the coordinated release version, and IA syntax remains 1.0.
183
+
184
+ ### 🤖 Machine protocol
185
+
186
+ `scope`, `context`, `select`, `get`, `records`, `resolve`, `search`, `traverse` and `report` are frozen operations for programs. Each takes JSON through `--params <JSON>`, or `--params -` for stdin, and prints one JSON line with no color. `ia <operation> --help` lists its parameters, refusals and an example, and `ia <operation> --schema` prints its parameter schema.
187
+
188
+ ```sh
189
+ ia search --params '{"text":"response"}'
190
+ echo '{"identity":"work-system/definition/task/write-schema"}' | ia get --params -
191
+ ia report --params '{}'
192
+ ia get --schema
193
+ ```
194
+
195
+ A scope token lasts one invocation, and a failed operation prints its own one-line JSON with no `next`. Only the CLI serves `report`; the [MCP server](https://github.com/inventarch/ia/blob/main/apps/mcp-door/README.md) serves the other read operations as tools.
196
+
197
+ ## 🪪 Mandates and `--actor`
198
+
199
+ Eight commands are judged against the acting participant's `@mandate` records before they run:
200
+
201
+ | Move the mandate must grant | Commands |
202
+ | --- | --- |
203
+ | Observation | `ia read`, `ia next` |
204
+ | Verification | `ia validate`, `ia preview` |
205
+ | Synthesis | `ia author` |
206
+ | Execution | `ia capture`, `ia project`, and a workspace `ia host <host> --apply` |
207
+
208
+ `ia preview` and `ia author` also check the record's word and the target path. Nothing else is judged: `ia position`, `ia inspect`, `ia init`, an `ia host` plan, `ia host --remove`, `ia host claude --user` and the machine protocol run whatever the mandates say, so the position a refusal names always runs. With a mandate that allows only Observation:
209
+
210
+ ```text
211
+ ✖ (whole workspace)
212
+ agent-system/policy/mandate/my-project-mandate
213
+ IA-RUNTIME-MANDATE-MOVE agent-system/policy/mandate/my-project-mandate
214
+ allows Observation; validate needs Verification
215
+ → Run
216
+ "ia position --seat agent-system/policy/mandate/my-project-mandate --shape governance"
217
+ for the mandates that govern here and what they allow.
218
+ ```
32
219
 
33
- `ia preview` shows what one edit of the workspace's own records would compile to, and writes nothing. `ia preview <word> <name> [<field>=<value>...] [--at <path>]` drafts a new record into `--at` or `<first authored root>/<word>.ia`; `ia preview --relate <owned> <spelling> <target>` adds one relationship row and `ia preview --set <owned> <section.key>=<value>` (or `+=` for one list item) sets one field of a record the workspace owns: authored (band 100) and in a file under an authored root its `@workspace` declares inside `.ia/src`, named by identity or `@word name`. It prints the record before and after, the findings the edit adds, the candidate revision and the target file's current SHA-256, and refuses an unknown field, a value of another type or one carrying syntax, a relationship no consent row admits, and a record it does not own. `ia preview <word>` prints the word's lowering, schema, default file and consent. The edit is spliced into the file as it is, so other lines keep their bytes and line endings; another spelling of an existing path (a case variant, an 8.3 short name) is refused, naming the volume's spelling.
220
+ Each judged command takes `--actor <agent>`, as an identity, `@agent <name>` or a bare name. It must name an authored participant of the workspace or its steward; without it the actor is the steward, or the workspace's one participant. That participant's own mandates then apply. A `@mandate` that fails admission, including one stating `authority.moves []`, closes every judged command until it is corrected by hand, and the refusal names `ia report` for the findings.
34
221
 
35
- `ia author` writes ordinary records using the same arguments as `ia preview` plus `--digest <sha256>`, the file digest the preview printed. It writes only when the file is still that one and the candidate is clean, puts one `# authored-by @agent <participant> under @mandate <name> at <authored revision>` comment above the record, and moves no other record's digest. Administrative words (`workspace`, `agent`, `mandate`, `system`, `schema`, `agent-profile` and `hook`) refuse for every actor; an owner makes those changes in source and validates them. This includes the system starter. Previews remain read-only; see the [administrative source boundary](SPEC.md#administrative-source-boundary).
222
+ Mandates are cooperative restrictions, not authentication or a sandbox. Anyone who can edit `.ia/src` can change them, and `--actor` is a local declaration: naming a participant with looser mandates lifts a restriction for that invocation.
36
223
 
37
- `ia doctor` warns when restrictive authored mandates have no supported hook declaration selecting all `.ia/src` sources for every edit tool. It never widens a hook's paths. A declaration is separate from host registration and enforcement, and the file edit guard checks Synthesis rather than word exclusions or execution limits on file bytes.
224
+ ## ⚖️ What it does not do
38
225
 
39
- `ia read`, `ia next`, `ia validate`, `ia preview`, `ia author`, `ia capture`, `ia project` and a workspace `ia host <host> --apply` are judged by the acting participant's mandates first (Observation, Verification, Synthesis or Execution); `ia position` never is, so the position a refusal names always runs. Each takes `--actor <agent>`, a local declaration that names one of the workspace's authored participants, or its authored steward, whether the workspace leaves the choice open or names a steward; the named participant's own mandates then apply. Mandates are cooperative restrictions and `--actor` is not authentication: a mandate that should hold against its own participant also excludes the `workspace`, `agent` and `mandate` words, which holds it against that participant acting as itself, and every participant the actor can name with `--actor` needs the same exclusions on its own mandates, since naming a looser one lifts them for that invocation.
226
+ - **It does not authenticate or isolate.** A mandate narrows what IA's commands do; it grants no host permission, and `--actor` proves no identity.
227
+ - **It does not certify content.** Admission means the records conform and resolve, not that they are true or complete. `ia read` never certifies a body, and a `not-evaluated` check is never a pass.
228
+ - **It does not execute what records name.** `ia validate` reports each `@execution-binding` as bound, unavailable or revoked without running it, and the machine operations invoke no model.
229
+ - **It does not repair.** `ia doctor` observes and suggests. It reports a host registration as written, never as a server it saw answering.
230
+ - **It does not edit authority through `ia author`.** An owner changes administrative records in source and validates them.
231
+ - **It needs no account or hosted service.** Initialization and validation run offline; `ia read` never fetches a URL.
40
232
 
41
- Use `ia --help` or `ia <command> --help` for the complete command syntax. `--json` returns structured output; applying a plan noninteractively requires `--yes`. Every consumer command refusal names the one command to run next, in `next` with `--json` and on the `→` line otherwise; the nine machine operations keep their one-line JSON. A recovery names `ia recover installation|host|guard|lifecycle --root <directory>`, which runs `@inventarch/distribution`'s recovery, so a global install of `@inventarch/cli` needs no `ia-distribution` binary on `PATH`. `ia doctor` reports observed state and suggested repairs. Host registration is explicit through `ia host claude`, `ia host codex` or `ia host cursor` and their `--apply` option. The projection it writes is the workspace's position packet (`.claude/rules/ia-workspace.md` or `AGENTS.md`, beside the `ia-authoring` skill), with a receipt in `.ia/distributions/hosts/<host>-receipt.json` that `ia doctor` checks; no per-system steward agent is written. `ia host` no longer registers the steward guard, and applying a projection, the refresh after `ia install`, `ia update` or `ia remove` included, retires one an earlier release registered and deletes the steward files it projected (each plan says so first), so edits under `.ia/src/systems/` are not blocked until a later release re-keys the guard to `@mandate` scope.
233
+ ## 📚 Learn more
42
234
 
43
- See [the package contract](SPEC.md) for command behavior, [the packaged language summary](LANGUAGE.md) for the words this release ships, and the [language guide](https://github.com/inventarch/ia/blob/main/docs/reference/language/README.md) for native syntax and evaluation limits.
235
+ - [Package contract](SPEC.md): every command's behavior, refusals and JSON shapes
236
+ - [Packaged language summary](LANGUAGE.md): the words this package ships
237
+ - [IA README](https://github.com/inventarch/ia/blob/main/README.md): the quick start, concepts and what a result means
238
+ - [Consumer CLI contract](https://github.com/inventarch/ia/blob/main/docs/specs/consumer-cli-contract/README.md): grammar, dispatch and refusal rules
239
+ - [Language guide](https://github.com/inventarch/ia/blob/main/docs/reference/language/README.md): native syntax, relationships and evaluation limits
240
+ - [Architecture reference](https://github.com/inventarch/ia/blob/main/docs/reference/architecture/README.md): which package to use for what
241
+ - [Changelog](https://github.com/inventarch/ia/blob/main/CHANGELOG.md): what changed in each release, including upgrading from 2.x