@inventarch/cli 3.1.0 → 3.2.0
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.
- package/LANGUAGE.md +2 -2
- package/README.md +222 -23
- package/SPEC.md +26 -25
- package/assets/base/62ecd5092f364b40e335e9e509ef512ac8030eb5689e72a5d0ff1e073cb13cfb.ia.tgz +0 -0
- package/assets/base.json +3 -3
- package/assets/host/185ebc43ae4798ede53905a6d6ff35fb0cf65e9e1bafa6413fe58e3306cf8af7.tgz +0 -0
- package/assets/host.json +3 -3
- package/assets/vocabulary.json +14 -14
- package/dist/args.d.ts +1 -1
- package/dist/args.d.ts.map +1 -1
- package/dist/author.d.ts.map +1 -1
- package/dist/author.js +6 -7
- package/dist/author.js.map +1 -1
- package/dist/briefing.d.ts +10 -5
- package/dist/briefing.d.ts.map +1 -1
- package/dist/briefing.js +10 -3
- package/dist/briefing.js.map +1 -1
- package/dist/capture.d.ts +6 -4
- package/dist/capture.d.ts.map +1 -1
- package/dist/capture.js +13 -11
- package/dist/capture.js.map +1 -1
- package/dist/channel.d.ts +4 -1
- package/dist/channel.d.ts.map +1 -1
- package/dist/channel.js +4 -1
- package/dist/channel.js.map +1 -1
- package/dist/claude-cli.d.ts +3 -3
- package/dist/claude-cli.js +7 -7
- package/dist/commands.d.ts +9 -9
- package/dist/commands.d.ts.map +1 -1
- package/dist/commands.js +31 -33
- package/dist/commands.js.map +1 -1
- package/dist/compile.d.ts +1 -1
- package/dist/compile.d.ts.map +1 -1
- package/dist/compile.js +1 -1
- package/dist/compile.js.map +1 -1
- package/dist/consumer.d.ts +49 -42
- package/dist/consumer.d.ts.map +1 -1
- package/dist/consumer.js +60 -56
- package/dist/consumer.js.map +1 -1
- package/dist/decline.js +4 -4
- package/dist/decline.js.map +1 -1
- package/dist/distribute.d.ts +31 -29
- package/dist/distribute.d.ts.map +1 -1
- package/dist/distribute.js +40 -37
- package/dist/distribute.js.map +1 -1
- package/dist/doctor-user.d.ts +3 -3
- package/dist/doctor-user.d.ts.map +1 -1
- package/dist/doctor-user.js +8 -8
- package/dist/doctor-user.js.map +1 -1
- package/dist/doctor.d.ts +3 -3
- package/dist/doctor.d.ts.map +1 -1
- package/dist/doctor.js +70 -64
- package/dist/doctor.js.map +1 -1
- package/dist/format.d.ts +2 -2
- package/dist/format.d.ts.map +1 -1
- package/dist/format.js +6 -6
- package/dist/format.js.map +1 -1
- package/dist/home-remedy.d.ts +2 -2
- package/dist/home-remedy.d.ts.map +1 -1
- package/dist/home-remedy.js +3 -3
- package/dist/home-remedy.js.map +1 -1
- package/dist/host-projection.d.ts +39 -39
- package/dist/host-projection.d.ts.map +1 -1
- package/dist/host-projection.js +73 -74
- package/dist/host-projection.js.map +1 -1
- package/dist/host.d.ts +52 -53
- package/dist/host.d.ts.map +1 -1
- package/dist/host.js +92 -95
- package/dist/host.js.map +1 -1
- package/dist/init.d.ts +65 -60
- package/dist/init.d.ts.map +1 -1
- package/dist/init.js +119 -118
- package/dist/init.js.map +1 -1
- package/dist/main.d.ts +1 -1
- package/dist/main.js +8 -8
- package/dist/main.js.map +1 -1
- package/dist/next.d.ts +1 -1
- package/dist/next.js +16 -16
- package/dist/next.js.map +1 -1
- package/dist/operation-help.d.ts +3 -3
- package/dist/operation-help.d.ts.map +1 -1
- package/dist/operation-help.js +9 -9
- package/dist/operation-help.js.map +1 -1
- package/dist/pack.d.ts +1 -1
- package/dist/pack.d.ts.map +1 -1
- package/dist/pack.js +12 -12
- package/dist/pack.js.map +1 -1
- package/dist/position.d.ts +1 -1
- package/dist/position.d.ts.map +1 -1
- package/dist/position.js +11 -12
- package/dist/position.js.map +1 -1
- package/dist/preview.d.ts +4 -4
- package/dist/preview.d.ts.map +1 -1
- package/dist/preview.js +28 -28
- package/dist/preview.js.map +1 -1
- package/dist/profile.d.ts +23 -23
- package/dist/profile.d.ts.map +1 -1
- package/dist/profile.js +50 -51
- package/dist/profile.js.map +1 -1
- package/dist/project.d.ts +10 -11
- package/dist/project.d.ts.map +1 -1
- package/dist/project.js +31 -33
- package/dist/project.js.map +1 -1
- package/dist/read.d.ts +2 -2
- package/dist/read.d.ts.map +1 -1
- package/dist/read.js +5 -5
- package/dist/read.js.map +1 -1
- package/dist/render.d.ts +31 -30
- package/dist/render.d.ts.map +1 -1
- package/dist/render.js +27 -26
- package/dist/render.js.map +1 -1
- package/dist/session.d.ts +9 -9
- package/dist/session.d.ts.map +1 -1
- package/dist/session.js +13 -13
- package/dist/session.js.map +1 -1
- package/dist/user-host.d.ts +1 -1
- package/dist/user-host.js +5 -5
- package/dist/user-host.js.map +1 -1
- package/dist/validate.d.ts +9 -9
- package/dist/validate.d.ts.map +1 -1
- package/dist/validate.js +35 -38
- package/dist/validate.js.map +1 -1
- package/dist/vocabulary.d.ts +1 -1
- package/dist/vocabulary.d.ts.map +1 -1
- package/dist/vocabulary.js +2 -2
- package/dist/vocabulary.js.map +1 -1
- package/package.json +6 -6
- package/assets/base/7db20e0dbbc2b88701ea24991886b4a8e08d419dda469cce5caff66911f81e4c.ia.tgz +0 -0
- package/assets/host/7e80bd7098018c1c13e3fae4cd363acfeffedccd5b6ec06c4952b62f449a4246.tgz +0 -0
package/LANGUAGE.md
CHANGED
|
@@ -22,7 +22,7 @@ Spec source locators do not load documents. Resource capture and disclosure requ
|
|
|
22
22
|
| @convention | governance-system | Declares a convention in the shared governance shape. |
|
|
23
23
|
| @decision | work-system | Represents a choice that is needed or has been made: the question, options and decider, and once made, the choice and rationale. |
|
|
24
24
|
| @dimension | taxonomy | Defines a supported record dimension used by conditions and lookup. |
|
|
25
|
-
| @distribution | workspace-system | Declares root records from which a distributable closure is selected. |
|
|
25
|
+
| @distribution | workspace-system | Declares root records from which a distributable closure is selected, and optionally the host plugin product it describes. |
|
|
26
26
|
| @execution-binding | agent-composition-system | Connects a native target to a host-installed entry or operation descriptor. |
|
|
27
27
|
| @harness | agent-composition-system | Composes profiles and execution bindings in a workspace under a host contract. |
|
|
28
28
|
| @hook | hook-authoring-system | Represents a host event, tool/path selection and guard message. Registration and executing a guard require a host adapter. |
|
|
@@ -40,7 +40,7 @@ Spec source locators do not load documents. Resource capture and disclosure requ
|
|
|
40
40
|
| @placement | taxonomy | Defines source authority and reach metadata. |
|
|
41
41
|
| @plan | work-system | Represents an arrangement of milestones toward an intent; it heads the work hierarchy and has no parent. Plans do not nest. |
|
|
42
42
|
| @playbook | governance-system | Represents a procedure as phase/primitive cells. Cell delivery is generic; the authored method belongs to its author. |
|
|
43
|
-
| @predicate | taxonomy | Defines a directed relationship and its
|
|
43
|
+
| @predicate | taxonomy | Defines a directed relationship, its inverse spelling and its present phrase. |
|
|
44
44
|
| @primitive | taxonomy | Defines a cognitive primitive coordinate; a cell is selected using its phase and primitive. |
|
|
45
45
|
| @principle | governance-system | Declares a governing rationale in the shared governance shape. |
|
|
46
46
|
| @run | session-system | Represents a governed run identity, declared phase, status and owner. Declaration does not start execution. |
|
package/README.md
CHANGED
|
@@ -1,43 +1,242 @@
|
|
|
1
1
|
# @inventarch/cli
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@inventarch/cli) [](https://github.com/inventarch/ia/actions/workflows/platform-quality.yml) [](LICENSE) [](package.json)
|
|
4
4
|
|
|
5
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
+
| `4` | `install`, `update` or `restore` could not reach or read a remote registry or archive |
|
|
58
|
+
| `130` | Interrupted |
|
|
59
|
+
|
|
60
|
+
### ✍️ Authoring and checking
|
|
61
|
+
|
|
62
|
+
| Command | What it does |
|
|
63
|
+
| --- | --- |
|
|
64
|
+
| `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. |
|
|
65
|
+
| `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. |
|
|
66
|
+
| `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. |
|
|
67
|
+
| `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/`. |
|
|
68
|
+
| `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. |
|
|
69
|
+
| `ia format [<path>...]` | Checks formatting, or rewrites files with `--write`. |
|
|
70
|
+
|
|
71
|
+
```sh
|
|
72
|
+
ia preview decision
|
|
73
|
+
ia preview --set @plan public-api work.source=docs/api.md
|
|
74
|
+
ia author --set @plan public-api work.source=docs/api.md --digest <sha256-from-the-preview>
|
|
75
|
+
ia validate
|
|
76
|
+
ia capture --preview
|
|
77
|
+
ia capture
|
|
78
|
+
ia format
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
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.
|
|
82
|
+
|
|
83
|
+
> [!IMPORTANT]
|
|
84
|
+
> **`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.
|
|
85
|
+
|
|
86
|
+
### 🧭 Reading and navigating
|
|
87
|
+
|
|
88
|
+
| Command | What it does |
|
|
89
|
+
| --- | --- |
|
|
90
|
+
| `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. |
|
|
91
|
+
| `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`. |
|
|
92
|
+
| `ia read <locator>` | Prints the body behind a locator with its `sha256` and the line `body not certified by this read`. |
|
|
93
|
+
| `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. |
|
|
94
|
+
| `ia vocabulary [<word>]` | Looks up the catalogue shipped with the package, with `--schema`, `--example`, `--domain`, `--kind` and `--search`. It opens no workspace. |
|
|
95
|
+
|
|
96
|
+
```sh
|
|
97
|
+
ia position
|
|
98
|
+
ia position --seat work-system/definition/task/write-schema --shape sequence
|
|
99
|
+
ia next
|
|
100
|
+
ia read work-system/definition/decision/api-response-format
|
|
101
|
+
ia read .ia/src/work.ia:12
|
|
102
|
+
ia inspect work-system/definition/task/review-schema
|
|
103
|
+
ia vocabulary decision --schema
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
`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}`.
|
|
107
|
+
|
|
108
|
+
`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.
|
|
109
|
+
|
|
110
|
+
`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`:
|
|
111
|
+
|
|
112
|
+
```text
|
|
113
|
+
Read work-system/definition/decision/api-response-format
|
|
114
|
+
|
|
115
|
+
• record
|
|
116
|
+
sha256 dae126797f0f… 44 bytes
|
|
117
|
+
body not certified by this read
|
|
118
|
+
|
|
119
|
+
Choose a response format for the public API.
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### 🔌 Hosts
|
|
123
|
+
|
|
124
|
+
| Command | What it does |
|
|
125
|
+
| --- | --- |
|
|
126
|
+
| `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)). |
|
|
127
|
+
| `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. |
|
|
128
|
+
| `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. |
|
|
129
|
+
|
|
130
|
+
| Host | Position packet | Skill | MCP registration (`ia host` only) |
|
|
131
|
+
| --- | --- | --- | --- |
|
|
132
|
+
| Claude Code | `.claude/rules/ia-workspace.md` | `.claude/skills/ia-authoring/SKILL.md` | `.mcp.json` |
|
|
133
|
+
| Codex | `AGENTS.md` | `.agents/skills/ia-authoring/SKILL.md` | `.codex/config.toml` |
|
|
134
|
+
|
|
135
|
+
```sh
|
|
136
|
+
ia project claude
|
|
137
|
+
ia project claude --apply --yes
|
|
138
|
+
ia host codex
|
|
139
|
+
ia doctor
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
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.
|
|
143
|
+
|
|
144
|
+
### 🧩 Host plugins
|
|
22
145
|
|
|
23
|
-
|
|
146
|
+
A Claude Code, Codex or Grok plugin directory can become a kit workspace, and that workspace renders the plugin back:
|
|
147
|
+
|
|
148
|
+
| Command | What it does |
|
|
149
|
+
| --- | --- |
|
|
150
|
+
| `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. |
|
|
151
|
+
| `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. |
|
|
152
|
+
| `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. |
|
|
153
|
+
|
|
154
|
+
```sh
|
|
155
|
+
ia init my-kit --from my-plugin
|
|
156
|
+
ia init my-kit --from my-plugin --apply --yes
|
|
157
|
+
ia project claude --product plugin --check --compare my-plugin --root my-kit
|
|
158
|
+
ia project claude --product plugin --out rendered --root my-kit --apply --yes
|
|
159
|
+
```
|
|
24
160
|
|
|
25
|
-
|
|
161
|
+
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
162
|
|
|
27
|
-
|
|
163
|
+
### 📦 Distributions
|
|
28
164
|
|
|
29
|
-
|
|
165
|
+
| Command | What it does |
|
|
166
|
+
| --- | --- |
|
|
167
|
+
| `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. |
|
|
168
|
+
| `ia install <id>[@<range>]...` | Plans an installation, kits included, from a registry, a `--catalog` or the `--offline` cache. |
|
|
169
|
+
| `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. |
|
|
170
|
+
| `ia update <id>` | Plans a version change for one direct request, `--to <range>`. |
|
|
171
|
+
| `ia remove <id>` | Plans the removal of one direct request. |
|
|
172
|
+
| `ia restore --apply` | Reinstalls the locked generation from its pinned archives. |
|
|
173
|
+
| `ia recover [installation\|host\|guard\|lifecycle] --root <directory>` | Finishes or rolls back an interrupted installation or host transaction. |
|
|
30
174
|
|
|
31
|
-
|
|
175
|
+
```sh
|
|
176
|
+
ia restore --apply --yes
|
|
177
|
+
ia update inventarch/language --offline
|
|
178
|
+
ia init my-lib --system --host none --apply --yes
|
|
179
|
+
ia pack --root my-lib --descriptor .ia/release.json
|
|
180
|
+
ia recover --root .
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
`.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.
|
|
184
|
+
|
|
185
|
+
### 🤖 Machine protocol
|
|
186
|
+
|
|
187
|
+
`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.
|
|
188
|
+
|
|
189
|
+
```sh
|
|
190
|
+
ia search --params '{"text":"response"}'
|
|
191
|
+
echo '{"identity":"work-system/definition/task/write-schema"}' | ia get --params -
|
|
192
|
+
ia report --params '{}'
|
|
193
|
+
ia get --schema
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
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.
|
|
197
|
+
|
|
198
|
+
## 🪪 Mandates and `--actor`
|
|
199
|
+
|
|
200
|
+
Eight commands are judged against the acting participant's `@mandate` records before they run:
|
|
201
|
+
|
|
202
|
+
| Move the mandate must grant | Commands |
|
|
203
|
+
| --- | --- |
|
|
204
|
+
| Observation | `ia read`, `ia next` |
|
|
205
|
+
| Verification | `ia validate`, `ia preview` |
|
|
206
|
+
| Synthesis | `ia author` |
|
|
207
|
+
| Execution | `ia capture`, `ia project`, and a workspace `ia host <host> --apply` |
|
|
208
|
+
|
|
209
|
+
`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:
|
|
210
|
+
|
|
211
|
+
```text
|
|
212
|
+
✖ (whole workspace)
|
|
213
|
+
agent-system/policy/mandate/my-project-mandate
|
|
214
|
+
IA-RUNTIME-MANDATE-MOVE agent-system/policy/mandate/my-project-mandate
|
|
215
|
+
allows Observation; validate needs Verification
|
|
216
|
+
→ Run
|
|
217
|
+
"ia position --seat agent-system/policy/mandate/my-project-mandate --shape governance"
|
|
218
|
+
for the mandates that govern here and what they allow.
|
|
219
|
+
```
|
|
32
220
|
|
|
33
|
-
|
|
221
|
+
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
222
|
|
|
35
|
-
|
|
223
|
+
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
224
|
|
|
37
|
-
|
|
225
|
+
## ⚖️ What it does not do
|
|
38
226
|
|
|
39
|
-
|
|
227
|
+
- **It does not authenticate or isolate.** A mandate narrows what IA's commands do; it grants no host permission, and `--actor` proves no identity.
|
|
228
|
+
- **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.
|
|
229
|
+
- **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.
|
|
230
|
+
- **It does not repair.** `ia doctor` observes and suggests. It reports a host registration as written, never as a server it saw answering.
|
|
231
|
+
- **It does not edit authority through `ia author`.** An owner changes administrative records in source and validates them.
|
|
232
|
+
- **It needs no account or hosted service.** Initialization and validation run offline; `ia read` never fetches a URL.
|
|
40
233
|
|
|
41
|
-
|
|
234
|
+
## 📚 Learn more
|
|
42
235
|
|
|
43
|
-
|
|
236
|
+
- [Package contract](SPEC.md): every command's behavior, refusals and JSON shapes
|
|
237
|
+
- [Packaged language summary](LANGUAGE.md): the words this package ships
|
|
238
|
+
- [IA README](https://github.com/inventarch/ia/blob/main/README.md): the quick start, concepts and what a result means
|
|
239
|
+
- [Consumer CLI contract](https://github.com/inventarch/ia/blob/main/docs/specs/consumer-cli-contract/README.md): grammar, dispatch and refusal rules
|
|
240
|
+
- [Language guide](https://github.com/inventarch/ia/blob/main/docs/reference/language/README.md): native syntax, relationships and evaluation limits
|
|
241
|
+
- [Architecture reference](https://github.com/inventarch/ia/blob/main/docs/reference/architecture/README.md): which package to use for what
|
|
242
|
+
- [Changelog](https://github.com/inventarch/ia/blob/main/CHANGELOG.md): what changed in each release, including upgrading from 2.x
|