@openengio/cli 0.0.0-stage → 0.23.3

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,327 @@
-# Temporary Holding Version
+# @openengio/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`openeng` is the platform's command-line client. It signs a person in through the browser, stores the
+session, and calls the platform's host. It runs on Node 22 and has no argument-parser dependency
+(`node:util`'s `parseArgs` serves because every command takes the same few flags).
+
+## Install
+
+Install the public npm package:
+
+```
+npm install -g @openengio/cli
+```
+
+Upgrading from `@benjaminfh/oe2`: first run the earlier package's `logout` command, so its stored
+session does not stay on this machine; then uninstall it and install `@openengio/cli`. The command
+is now `openeng`, the environment variables are
+`OPENENG_HOST`, `OPENENG_SIGN_IN_ORIGIN` and `OPENENG_SESSION_STORE`, and you sign in again once
+with `openeng login`.
+
+`openeng` has no host built in. The production host is `https://api.openeng.io`. Pass `--host
+https://api.openeng.io` to a command, or set `OPENENG_HOST=https://api.openeng.io` once to make it the
+default. An agent starts with `openeng skill`, which prints how to work with the platform.
+
+`openeng --version` prints the published version, `0.<protocol>.<patch>`. `openeng organisations` and
+`openeng orgs` run the commands of `openeng org`, and `openeng project` runs the commands of `openeng projects`.
+
+`openeng help <command words>` prints one command's help, with or without the positional arguments the
+command takes: a description (`does:`), an example and the shape of its output. `openeng help <group>`,
+such as `openeng help connector`, lists the group's commands. Words that name no command are refused
+with the nearest commands.
+
+The package version is `0.<protocol>.<patch>`: its middle number is the host protocol it speaks.
+The installed package contains the bundled command and the skill. It carries no runtime dependencies.
+
+## Commands
+
+| command | what it does | host calls |
+|---|---|---|
+| `openeng login [--no-open]` | binds a loopback listener, opens the browser at the sign-in address (or prints it with `--no-open`), redeems the returned code once and stores the session | one (`redeem`) |
+| `openeng logout` | refreshes first when the access token has expired, calls `logout`, deletes the stored session whatever the host answered | one, two with an expired token |
+| `openeng whoami` | prints the principal, host, store and expiry of the stored session, and the client's protocol version (`protocolVersion` under `--json`); never a token | none |
+| `openeng org list` | lists the organisations the signed-in person holds a live grant in; needs no attachment | one |
+| `openeng org attach <id>` | attaches the session to the organisation, and stores the access token the host answers with the organisation's identifier and name, beside the session and under the same host key; needs no attachment | one |
+| `openeng org create --name <name> [--idempotency-key <key>]` | creates an organisation without an attachment; makes one host call, and prints a minted idempotency key on standard error when none is supplied | one |
+| `openeng org detach` | detaches the session, and stores the access token the host answers with a null organisation; refused while the session has none | one |
+| `openeng org current` | prints the organisation the stored session is attached to, or none (`{ "organisation": null }` under `--json`); sends no request | none |
+| `openeng projects list` | lists the projects the signed-in person may list | one |
+| `openeng demo seed --project <id> [--size standard\|full]` | plays a generic open-cycle gas turbine plant into a project the person may list; `standard` is the default size, and a repeat completes what is left | one listing, one catalogue read, four to publish the types when they are not yet published, then one per object and edge |
+| `openeng link <explore\|branch-diff\|project> --project <id> --ref <ref>`, `openeng link <ontology\|change-set> --ref <ref>`, `openeng link <object\|type\|proposal\|app> <identifier> --project <id> --ref <ref>`, `openeng link app-page <appKey> <pageKey> --project <id> --ref <ref>`, `openeng link app-draft <appKey> --ref <ref>`, `openeng link organisation-page <page>` | prints the address of a page of the web application: the host's web origin joined to the page's path, built for the attached organisation; `--json` answers `{ link }`; a flag the page does not read is refused (exit 2) before any call, and so is a host with no web origin configured; `openeng link --help` prints every form | one (`readWebOrigin`) |
+| `openeng types draft open` | opens a change set on the attached organisation's namespace | one |
+| `openeng projects create --name <text>` | creates a project in the organisation the session is attached to, under a minted idempotency key | one |
+| `openeng types list --project <id>` | lists the project's published types | one |
+| `openeng types draft current` | the attached organisation's open change set, or none | one |
+| `openeng types draft show --change-set <id> [--project <id>]` | the change set's revision and each prospective type's full definition; with `--project`, the delta per type and per field instead (added or changed, the version before and after, each changed field's before and after), and `--json` answers `{ revision, changes, delta }` (with `railGroups` where the change set holds a group change); a line `rail groups <json array>` lists the change set's groups where it holds any; a project whose catalogue listing (category, key and version) is not the change set's is refused (exit 2) before any diff | one; two with `--project` |
+| `openeng types export --project <id>` | prints the project's published types as one JSON object keyed by type key, each the first prospective version of an edit (the next version number, none of the host's bookkeeping); redirect it to a file and edit it for `openeng types draft revise --from`; on an empty catalogue it still prints `{}` and exits 0, with the standard-error note `no published types; start from the example in openeng help ontology-sdk reviseChangeSet` | one |
+| `openeng types draft state --change-set <id>` | whether the change set is open, accepted or discarded | one |
+| `openeng types draft revise --change-set <id> --revision <token> --from <file> [--rail-groups <json>]` | replaces the change set's delta with the JSON object in the file, keyed by type key; a type's rail placement is `presentationBindings.rail` inside its document; `--rail-groups` carries the organisation's whole list of rail groups as a JSON array of strings, and without it the change set keeps the groups its last revision held; a file that is unreadable, not JSON or not an object, or a flag that is not a JSON array of strings, is refused (exit 2) before any call; the host validates the delta | one |
+| `openeng types draft validate --change-set <id> --revision <token>` | the host's violations for that revision, printed with their count; exits 4 when there is one or more and 0 when there are none, so a script can gate `accept` on the exit code | one |
+| `openeng types draft discard --change-set <id>` | discards the change set | one |
+| `openeng types draft accept --change-set <id> --revision <token>` | publishes the change set's types at the revision the person reviewed, under a minted idempotency key | one |
+| `openeng skill [<topic> \| playbook <name>]` | prints the main skill and lists topics, or prints one bundled topic; needs no host and no session | none |
+
+An object type's `subscriptionRoles` field declares which roles it admits: owner, approver or watcher.
+Owner is limited to one; approver and watcher may have optional maxima. Without the field, only
+watchers are admitted.
+
+## The connector commands
+
+A connection imports an Onshape account's documents into a mirror project of its own. Every
+connector command acts with the signed-in person's user token, so it can do what that person may,
+and it needs the organisation the session is attached to. Each command's `--help` names the
+capability it needs.
+
+Everyone with access to this project sees every document this Onshape account can see.
+
+`openeng connector create` prints that sentence, on standard error, before it makes any call.
+`openeng connector set-credential` prints it again with the account identity the key resolved to.
+
+| command | what it does | what the caller must hold |
+|---|---|---|
+| `openeng connector create --system onshape --stack <stack> --name <text> [--company <id>] [--team <id> \| --owner <id>] [--label <text>]` | creates the connection, its mirror project and its service identity, then drafts the connector's types as a change set in the same request; `--name` names the mirror project; `--stack` is the Onshape stack label, the host-name label joined to the suffix, as in `cad`; `--team` or `--owner` limits the import to that team's or owner's documents, and with neither the company's documents are imported, and `--company` is then required and must be the company's own identifier, not a user's, or the command is refused (exit 2) before any call; `--team` with `--owner` is refused (exit 2) before any call. The answer says whether the types were drafted, and if not, which rule stopped it; the connection exists either way | `administer projects` and `administer service identities` in the organisation, which the `owner` role holds |
+| `openeng connector set-credential <connection>` | asks for the Onshape access key and secret key at a terminal prompt with nothing echoed, has the host check them against Onshape, and stores them; no flag or environment variable carries a key, and with no terminal it refuses before any call. Backspace deletes a character, a paste of both keys with a line ending between them fills both prompts, and Control-C or Control-D cancels with a refusal that says no keys were set. Setting it again replaces the stored credential. It prints the Onshape account the key belongs to and the time it was set | `administer projects` in the organisation |
+| `openeng connector draft-types <connection>` | drafts the connector's types as a change set for a person to review, or answers that they are already approved or that a change set is open; use it for a connection whose drafting failed at create, and after a connector update | `administer types` in the organisation, and read on the mirror project |
+| `openeng connector run <connection>` | starts an import run and prints its identifier once its row has committed; the run refuses while the connector's types are not approved | `merge` on the mirror project |
+| `openeng connector runs <connection>` | lists the connection's runs, newest first: state, start and finish times, whether it was complete, the counts (created, updated, unchanged, withdrawn, carried, overwritten) and, for a failed run, its failure kind and fixed text | read on the mirror project |
+| `openeng connector revoke <connection>` | revokes the connection: its running runs end as failed and its service identity can no longer act | `administer projects` and `administer service identities` in the organisation |
+
+`<connection>` is the connection identifier that `create` prints.
+
+### From no connection to a first imported document
+
+1. `openeng connector create ...`, by an organisation owner. Note the connection identifier.
+2. `openeng connector set-credential <connection>`, by a person who holds `administer projects`, at a
+   terminal.
+3. A person who holds `administer types` reviews the drafted change set with `openeng types draft show
+   --change-set <id> --project <mirror project id>` and accepts it with `openeng types draft accept
+   --change-set <id> --revision <token>`. The change set identifier is in `create`'s answer, or in
+   `openeng types draft current`. Until it is accepted, a run refuses with `types-not-approved`.
+4. `openeng connector run <connection>`, by a person who holds `merge` on the mirror project.
+5. `openeng connector runs <connection>` until the run's state is `succeeded` or `failed`.
+
+### The known gap
+
+The next import sets back a person's change to a mirrored property and counts it `overwritten`.
+The next import also creates a deleted mirrored object again, with a new identifier, and counts it
+`created`; links people made to the old object are gone. Mirrored objects are therefore read-only in practice until write-back exists.
+
+## The attached organisation
+
+A CLI session begins unattached: `openeng login` never attaches. A person runs `openeng org list`, then
+`openeng org attach <id>`, once. If the list is empty, `openeng org create --name <name>` creates an
+organisation that can then be attached. The organisation is stored with the
+session (`StoredEntry.organisation`, an identifier and a name, or null), a refresh keeps it, and
+`openeng login` and `openeng logout` replace or delete the whole entry. The host decides what a call may
+reach; the stored organisation decides only what the CLI prints and whether it runs a command.
+
+- **The gate.** Whether a command runs without an organisation comes from its `organisation` field:
+  hand-written commands marked `none` run unattached; generated commands run unattached when their
+  route subject is `platform` or `creating`. Other commands refuse with "not attached to an
+  organisation" (exit 2) before they send a request. With no stored session at all, the command
+  answers that it is not signed in.
+- **The scope echo.** The CLI passes no scope when the organisation gate read no organisation
+  (for every command whose `organisation` is `none` and every hostless command), and for `org
+  detach`. Other commands print when the host answers them, `org: <name> (<id>)` first on standard error,
+  then ` · project: <id>` when `--project` or the selector's `projectId` named one, and
+  ` · ref: <ref>` when the selector named one. No host call finds them.
+- **`--json`.** The one value on standard output gains the same fields as `scope`:
+  `{ "organisation": { "id", "name" }, "project"?, "ref"? }`. An object value gains a `scope` key. A
+  value that is an array or null is wrapped as `{ "scope": {...}, "value": <the original> }`. A
+  failure the host did not answer carries no scope. A command with no scope has no `scope` field.
+- **The hint.** Every `not-found` the host answers to a gated command prints, after the refusal,
+  "not found in organisation <name>: check that you are attached to the correct organisation (openeng org
+  current)", and one line more when the command named a ref: `ref forms: the trunk is the bare "main";
+  a branch is "<project id>/<name>"`. The hint goes to standard error with or without `--json`.
+
+A command that reaches the host with a session whose access token has expired sends one `refresh`
+first and then its own call. A command whose call is answered `unauthenticated` refreshes once and
+sends the call once more.
+
+## The agent skill
+
+`skill/openeng/SKILL.md` is a Claude Code skill that tells an agent which commands to run and in what
+order: sign in and orient, define types, write data, and show it. It names commands and never an
+input shape; for a shape it sends the agent to `openeng help <module> <method>`. `openeng skill` prints it
+and ends with the other topics and the command for each. It reads from the package relative to
+the module, so it works from `dist`. Install it with:
+
+```
+mkdir -p ~/.claude/skills/openeng && openeng skill > ~/.claude/skills/openeng/SKILL.md
+```
+
+`openeng skill` is answered before a host is parsed or a session store is chosen, so it runs on a
+machine with no `OPENENG_HOST`. Its command receives only the topic words, which is how it cannot reach a host.
+
+The topic list comes from the files in the bundled `skill/` folder. Print a topic with:
+
+| command | when to read it |
+|---|---|
+| `openeng skill demo` | guiding a new person through a hands-on example in the app |
+| `openeng skill new-use-case` | designing types for a new use case against the existing catalogue |
+| `openeng skill build-ui` | laying out an object drawer or App view |
+| `openeng skill conventions` | field meanings, direction, trees, views, the rail and versions |
+| `openeng skill playbook engineering-requirements` | modelling requirements, verification and risk |
+| `openeng skill playbook product-lifecycle` | modelling parts, revisions, manufacturing BOMs and changes |
+| `openeng skill playbook project-management` | modelling work items, cycles, milestones and engineering links |
+
+`openeng help skill` and `openeng skill --help` list the topics. Unknown topics are refused with that
+list (exit 2). The material requirements planning draft is held back and is not shipped.
+With `--json`, the main command prints `{ "skill": "...", "topics": ["..."] }`; a topic prints
+`{ "skill": "..." }`, and help uses the CLI's usual `{ "usage": ["..."] }` shape.
+The `build-ui` guide ships as prose; the in-app agent's generated `author-views` reference is
+not yet available through the CLI.
+
+## The generated commands
+
+Beside the commands above, `openeng` has one command for each route the SDK modules export an entry
+for, built when the process starts from those entries (`OBJECTS_ROUTE_ENTRIES`,
+`BRANCHES_ROUTE_ENTRIES`, `ADMIN_ROUTE_ENTRIES`, `AGENTS_ROUTE_ENTRIES` and
+`ONTOLOGY_ROUTE_ENTRIES`). No list of commands, help text or flags is kept by hand.
+
+- **Naming.** `openeng <module> <method>`, the module as its package is named (`objects-sdk`) and the
+  method the route's own name (`openeng objects-sdk readObject`).
+- **Which routes.** Every entry whose `carriesCredential` is false and whose `module` is not
+  `sdk-core`. A route whose request or answer holds a `Credential` (`issueServiceCredential`,
+  `setModelConfiguration`, and the core's `redeem`, `refresh`, `serviceCredential` and
+  `signInCallback`) has no generated command, so no generated command takes a secret in its
+  arguments or prints one. The core's own routes (`health`, `signInStart`, `logout` and the
+  credential ones) are not a module's methods and have none either.
+- **Flags.** `--selector <json>` (required where the route takes a selector, refused where it takes
+  none); `--input <json>`, `--input -` (standard input) or `--input-file <path>`, one of them, a JSON
+  object, `{}` when none is given; `--idempotency-key <key>` on an idempotent route, where a key is
+  minted and printed on standard error when none is given, and refused on a route that is not
+  idempotent. A malformed or missing flag is the client's own refusal (exit 2) naming the flag.
+- **Correlation.** A route whose input schema lists `correlation` as required (`mutate`,
+  `mutateBatch`, `executeVerb`, `createBranch`, `merge`, `disposeRef`, `abandonBranch`) gets
+  `correlation: { kind: "mint" }` when the input has no `correlation` key, and the command prints
+  `correlation: minted by the host` on standard error. A `correlation` the person gave is sent as
+  given, whatever it holds, and the host's refusal judges it. The condition is read from the
+  schema, never from the route's idempotency.
+- **Help.** `openeng <module> <method> --help` prints the route, its method and path, the module, the
+  capability, the admitted token kinds, whether it is idempotent, its selector form and what it
+  does, each read from the entry; then `input fields:` and, for a route with a selector,
+  `selector keys:`, read from the route's schemas, and `example input:`, the route's generated
+  example on one line. Map value fields and the members of a top-level `oneOf` are listed. A field
+  is one line, `name: required|optional; <type>`; a `oneOf` whose members each pin the same
+  discriminator property to a distinct value shows those values, then one line per member with its
+  own fields. Nested object, array and map fields are listed to a depth; beyond that, a line says
+  fields are nested deeper.
+  `openeng help` prints the global usage and `openeng help <module> <method>` prints that command's help,
+  as `--help` does; neither needs a host or a session. A hand-written command with no help text
+  prints its own usage line for `--help`.
+- **Streamed routes** (`openeng agents-sdk sendMessageStreamed`, `answerPlanStreamed`) print one JSON line
+  per event on standard output, after the run ends, and need a `unix:` host.
+- **Calls.** One host call; two when the session had expired. A streamed command holds one
+  connection.
+
+## Flags and environment
+
+Every command takes `--json`, which prints one JSON value on standard output in place of text.
+The flags a command reads, named in its usage above, are `--project`, `--name`, `--change-set`,
+  `--revision`, `--from`, `--size`, `--idempotency-key`, `--rail-groups`, and, for
+`openeng connector create`, `--system`, `--stack`, `--company`, `--team`, `--owner` and `--label`; a
+command that needs one it was not given refuses before any call (exit 2).
+
+| setting | flag | what it is |
+|---|---|---|
+| `OPENENG_HOST` | `--host` | `unix:<absolute socket path>` or an `https` origin. Every other form, `http:` included, is refused before any request (exit 2). The flag wins. |
+| `OPENENG_SIGN_IN_ORIGIN` | `--sign-in-origin` | for a `unix:` host, the network host's `http://127.0.0.1:<port>` or `http://[::1]:<port>` origin. Only the browser visits it; no credential is sent to it. Any non-loopback origin is refused. The flag wins. |
+| `OPENENG_SESSION_STORE` | none | `file` selects the file store. Unset selects the platform's credential store where its tool answers, else the file store. Any other value is refused. |
+| `XDG_CONFIG_HOME` | none | the configuration directory when it is an absolute path, else `~/.config`. |
+
+`openeng` reads no other environment variable.
+
+`openeng login` writes one waiting line to standard error while it waits for the browser, so under
+`--json` standard output stays one JSON value. A loopback listener the system refuses to open, and a
+session store that cannot be read, written or deleted, each print one line (exit 2) and no stack: the
+listener line asks you to allow local loopback listeners and run `openeng login` again; the store line
+names the store and the operation and ends with the next step, `openeng login` again, or `openeng org attach
+<id>` again where the host had already switched the session. The line never holds the system's own
+error text.
+
+`openeng login` against an `https` host uses the same loopback sign-in as a socket host, with the host's
+own origin as the sign-in origin. The sign-in uses PKCE: `openeng` mints a verifier, sends its S256
+challenge with the request, and presents the verifier when it redeems the code, so a code redeems only
+for the client that asked for it.
+
+## Output and exit codes
+
+Text goes to standard output on success and to standard error on every failure, with one
+exception: the violations `openeng types draft validate` answers go to standard output with exit 4. A refusal the host
+answered prints its kind or rule and class, then the refusal catalogue's meaning, then each next
+option on its own line, naming the command for an option's read where `openeng` has one. When the text
+is the refusal class's and not the rule's own, the output says so. With `--json` a refusal prints
+its own fields with `explanation` and `explains` as the SDK attached them. The client's own refusals
+(exit 2) and a transport failure with no answer (exit 7) carry no catalogue entry and print their own
+message. An error that is not a transport failure prints as an internal failure with exit 7, and its stack
+follows on standard error, with `--json` too, so standard output stays one JSON value.
+
+A refusal that arrived in an envelope ends with one line `reference: <correlation id>`, the id the
+host stamped on the envelope, and the `--json` form carries it as a `reference` field. A refusal
+the client builds itself, and an envelope that carries no id, print none. A result whose arm is
+`refused` prints the `correlationId` its arm carries on the same line, and the `--json` form adds the
+`reference` field beside the arm's own fields. The id is the envelope's
+and not the `correlationId` that an `unknown-outcome`, `in-flight` or `internal` refusal carries in its
+own fields, which stays in the first line.
+
+An `invalid-request` that names a field prints `invalid-request: field <path>`. For a generated
+command the path is resolved against the route's schemas (through a `oneOf` by the discriminator the
+person sent, through a map by any key, and through an array by its indexed item); where it lands on a
+`oneOf`, the text adds the allowed values of that field's discriminator and the command's `--help` line,
+and `--json` adds those values beside
+the refusal. A path that does not resolve prints the field alone.
+
+An unknown outcome (exit 5) prints its correlation and the read that settles it. `openeng` never
+repeats the operation. For a non-envelope answer with status 500 to 599, exit 5 says the operation
+may or may not have taken effect. It settles with the minted idempotency key for a generated
+command, or with `check what openeng <words> changes before sending it again` for a hand-written
+command. A non-envelope 5xx answer to the session refresh instead exits 7 with
+`refresh-unanswered`: the command was not sent. A retry with the same idempotency key can
+retrieve a recorded outcome or attempt a call that never reached the host; an earlier outcome
+is not guaranteed to exist.
+
+A non-envelope answer with a status from 400 to 499, such as a proxy's or a wrong address's page, prints
+one line naming the status, the reason phrase the host sent with it where there is one, and the
+route, and says the request may not have reached the platform (exit 7), with no stack. Under
+`--json` its `error.kind` is `host-answer-not-envelope`.
+
+A connection failure before the request was written prints the host and system code, says the
+request was not sent and nothing changed, and confirms that sending it again is safe (exit 7).
+
+A refused result arm prints each conflict after the explanation, naming its property and current
+committed envelope as JSON (`absent` when the property is absent), followed by each violation's
+path and rule. Empty conflict and violation lists add no lines. With `--json`, both lists remain
+in the result as the SDK answered them.
+
+A protocol mismatch (exit 7) prints the client's protocol version, the addressed host and its
+protocol version. When the host read this `openeng`'s protocol version, it asks you to install an `openeng`
+built for that host. Otherwise it says the host did not read this `openeng`'s protocol version and names
+the version it read, or `none`. The catalogue explanation also prints. Under `--json`, the refusal
+carries the host's key as `host` and this client's version as `clientVersion`. The host's `versions`
+are unchanged: `versions.client` is the version the host read, or null, and `versions.host` is the
+host's version.
+
+| exit code | meaning |
+|---|---|
+| 0 | success |
+| 2 | the client's own refusal: configuration, host form, store, a missing flag |
+| 3 | `unauthenticated`: not signed in, a sign-in that was cancelled, timed out or whose state differed, or a logout with nothing stored |
+| 4 | a platform refusal (`refused`), a route result whose arm is `refused`, or the violations `openeng types draft validate` answers (printed on standard output) |
+| 5 | `unknown-outcome`, from the host or from a transport that lost the answer; also a non-envelope answer with status 500 to 599 |
+| 6 | `invalid-request`, `not-found` or `bound-exceeded` |
+| 7 | `internal`, `in-flight`, `protocol-mismatch`, a transport failure with no answer, a non-envelope answer with status 400 to 499, or an internal failure of the client |
+
+## Stores
+
+The session of one host is stored under that host's key: `unix:` and the canonical absolute socket
+path for a socket host, the origin for an `https` host. A read never falls back to another host's
+entry. The stores:
+
+- macOS: the keychain, through `security -i` with the command on standard input.
+- Linux: `secret-tool store`, the secret on standard input.
+- Otherwise, or with `OPENENG_SESSION_STORE=file`: one file per host in
+  `$XDG_CONFIG_HOME/openeng/sessions/` (else `~/.config/openeng/sessions/`), mode `0600` in a directory of
+  mode `0700`.
+
+`openeng whoami` names the store in use.