@openengio/cli 0.23.3 → 0.24.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openengio/cli",
-  "version": "0.23.3",
+  "version": "0.24.3",
   "license": "Apache-2.0",
   "type": "module",
   "engines": {

package/skill/build-ui/SKILL.md

@@ -13,6 +13,10 @@ catalogue the platform validates against. The CLI does not yet ship that generat
 use this guide's examples and `openeng help types draft revise` for the wire shape, then validate the change
 set; the host decides which components, props, bounds and bindings your version admits.
 
+An **App** is an organisation entity with its own pages and drafts, linked by `openeng link app`.
+An **App view** is a type's collection content in `presentationBindings.views.app`, root `AppBody`,
+and cannot be linked by `link app`.
+
 Work through the steps in order, and stop where a step says so.
 
 ## 1. Know what the view must answer

package/skill/conventions/SKILL.md

@@ -101,6 +101,10 @@ the first view.
   drawer; an **App view** (`.app`, root `AppBody`) lays out the type's page. Only components the view
   catalogue admits may appear, each with the props it takes.
 
+An **App** is an organisation entity with its own pages and drafts, linked by `openeng link app`.
+An **App view** is a type's collection content in `presentationBindings.views.app`, root `AppBody`,
+and cannot be linked by `link app`.
+
 ## 6. Versions
 
 - A new type key starts at version 1. A changed type is sent at its published version plus one;
@@ -132,6 +136,64 @@ for a lifecycle state. A wrong edge is replaced by a new edge type key and a rec
   {"value": <the new value>}}}`; `{"absent": true}` stands for no value on either side. A `from` that no
   longer matches is refused, so read the object first.
 
+## Property kinds
+
+An enum's `members` is a list of strings or finite numbers. A published member cannot be removed.
+
+### enum
+
+```json
+{"kind": "enum", "members": ["open", "closed"]}
+```
+
+### null
+
+```json
+{"kind": "null"}
+```
+
+### boolean
+
+```json
+{"kind": "boolean"}
+```
+
+### string
+
+```json
+{"kind": "string"}
+```
+
+### number
+
+```json
+{"kind": "number"}
+```
+
+### integer
+
+```json
+{"kind": "integer"}
+```
+
+### person
+
+```json
+{"kind": "person"}
+```
+
+### array
+
+```json
+{"kind": "array", "items": {"kind": "string"}, "maxItems": 10}
+```
+
+### object
+
+```json
+{"kind": "object", "properties": {"name": {"kind": "string"}}, "required": ["name"]}
+```
+
 ## 9. Examples
 
 A minimal object type and a structural edge, every key at version 1:

package/skill/new-use-case/SKILL.md

@@ -105,6 +105,10 @@ Stop: the person agrees the properties and the rail.
 
 ## 6. Decide views, if any
 
+An **App** is an organisation entity with its own pages and drafts, linked by `openeng link app`.
+An **App view** is a type's collection content in `presentationBindings.views.app`, root `AppBody`,
+and cannot be linked by `link app`.
+
 An object view shapes the object's drawer; an App view shapes the type's page. Propose one only when the
 default layout does not answer step 1's questions. Use only the components the view catalogue admits.
 

package/skill/openeng/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: openeng
-description: Use when you need to work with an OpenEngineering platform through its command line, `openeng`. Signing in, listing projects and types, editing object types, writing objects on a branch and submitting them for review.
+description: >-
+  Use when you need to work with an OpenEngineering platform through its command line, `openeng`.
+  Signing in, listing projects and types, editing object types, writing objects on an agreed ref
+  and submitting branches for review.
 ---
 
 # Working with the platform through `openeng`
@@ -11,12 +14,6 @@ description: Use when you need to work with an OpenEngineering platform through
 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`.
-
 This skill gives the commands and their order. It gives no input shapes, because the commands print
 their own. Before you send a generated command (`objects-sdk`, `branches-sdk` and the other
 `<module> <method>` commands), run `openeng help <module> <method>`. It prints the fields, the kinds a
@@ -46,7 +43,10 @@ field may take, the selector keys and one example input, and needs no sign-in.
   does, an example and the shape of its output. `openeng help <group>` lists a group's commands.
   `openeng --version` prints the published version.
 - `openeng` has no host built in. The production host is `https://api.openeng.io`: pass
-  `--host https://api.openeng.io`, or set `OPENENG_HOST=https://api.openeng.io` once.
+  `--host https://api.openeng.io` on every command, or prefix it as
+  `OPENENG_HOST=https://api.openeng.io openeng ...`. An export in `~/.zshrc` does not reach
+  an agent's shell or a Claude Code `!` shell. In zsh, persist it in `~/.zshenv`.
+  Fix `no-host` by adding the flag or prefix.
 - `openeng orgs list` and `openeng organisations list` mean `openeng org list`; `openeng project list` means
   `openeng projects list`.
 - A mutation or a branch command that needs a `correlation` mints it for you when your input has
@@ -58,7 +58,10 @@ field may take, the selector keys and one example input, and needs no sign-in.
 ## 1. Sign in and orient
 
 1. `openeng help` to see what exists.
-2. `openeng login`. It opens a browser to sign in; `openeng login --no-open` prints the address instead.
+2. Run `openeng login` yourself with the host flag. It opens the person's browser and waits;
+   tell the person to finish sign-in there. Do not ask the person to run it. If your tool cuts a
+   command off before it returns, run it in the background or use `openeng login --no-open`
+   with the host flag and give the person the printed address.
 3. `openeng whoami` to confirm who you are.
 4. `openeng org list --json` prints the organisations you belong to. `openeng org attach <id>` attaches
    your session to one. If you have no organisation, create one with
@@ -85,10 +88,11 @@ For a generic open-cycle gas turbine demonstration project, run `openeng demo se
   `org: <name> (<id>)`, then `· project: <id>` and `· ref: <ref>` when you named them. Read it
   before you trust an answer.
 - With `--json`, the one value on standard output carries the same scope as a `scope` object:
-  `{"organisation": {"id", "name"}, "project"?, "ref"?}`. An object value gains a `scope` key.
+  `{"organisation": {"id", "name"}, "project"?, "ref"?}`. An object value normally gains a `scope` key.
   A value that is an array or null, such as the list from `openeng projects list`, comes wrapped as
-  `{"scope": {...}, "value": <the original value>}`. A command with no scope carries no `scope`
-  field.
+  `{"scope": {...}, "value": <the original value>}`. Rules command successes always use this wrapper
+  to preserve the rule's own `scope` field. Organisation-ref, lock, ceiling and schema-update
+  successes also always use `{ scope, value }`. A command with no scope carries no `scope` field.
 - A `not-found` in an organisation is often a project or a ref that belongs to another one. The
   command prints "not found in organisation <name>: check that you are attached to the correct
   organisation (openeng org current)". Run `openeng org current`; if it names the wrong organisation,
@@ -137,28 +141,117 @@ watchers are admitted; the publication validator decides whether a declaration i
 
 ## 3. Write data
 
-Data is written on a branch and then submitted for review.
+Write on the ref agreed with the person and within their authority. That may be `main` when
+the applicable protections permit the write; an approved agent plan may also name an unprotected
+project's `main`. Use a branch and review when a rule protects the ref or the person asks for it.
 
 1. `openeng help objects-sdk mutate` and `openeng help branches-sdk createBranch` for the fields, the
    selector keys and an example each.
-2. `openeng branches-sdk createBranch` makes a branch in the project. It answers the branch's ref,
-   written `<project id>/<name>`.
+2. When a branch is needed, `openeng branches-sdk createBranch` makes one in the project. It
+   answers the branch's ref, written `<project id>/<name>`.
 3. `openeng objects-sdk mutate` creates, changes or deletes an object or an edge on that ref. A ref in
-   a selector takes one of two forms: the project's trunk is the bare `main`, with no project id;
-   a branch is its whole ref, `<project id>/<name>`, the slash and the project id included. Use
-   `main` to read what is published, and the branch's ref to read or write your own work, here and
-   for `openeng objects-sdk readObject` and `openeng objects-sdk queryObjects`.
+   a selector takes one of three forms: the organisation trunk is the bare `main`; a project
+   branch is its whole ref, `<project id>/<name>`; an organisation ref is its bare name.
+   The server derives the organisation from the token. Use the agreed ref for writes and read
+   back from that same ref with
+   `openeng objects-sdk readObject` and `openeng objects-sdk queryObjects`.
 4. Read back what you wrote: `openeng objects-sdk readObject` for one object, or
    `openeng objects-sdk queryObjects` for a list. Use the type key and version the project's
-   `openeng types list` showed.
+   `openeng types list` showed. For an object's edges use `openeng objects-sdk queryGraph`;
+   for paths use `openeng objects-sdk findPaths`. Confirm relationships through the CLI;
+   do not hand the check to the web app.
 5. `openeng objects-sdk executeVerb` runs a verb a type defines. `openeng objects-sdk discoverVerbs` lists
    the verbs available.
-6. `openeng branches-sdk submitProposal` sends the branch for review. It names the branch by its
-   `name` alone, the part of the ref after the slash.
+6. When using a branch for review, `openeng branches-sdk submitProposal` sends it for review. It
+   names the branch by its `name` alone, the part of the ref after the slash.
 
 If a command is refused, the refusal names the field and its allowed kinds. Run
 `openeng help <module> <method>` again and compare.
 
+### Read relationships back after a write
+
+Run `openeng help objects-sdk queryGraph` first. Take the project and object identifiers from
+the confirmed write and replace the placeholders below. One start address and one hop step
+read that object's connections, including the edges in the answer:
+
+```sh
+openeng objects-sdk queryGraph --host https://api.openeng.io --selector '{"projectId":"<project-id>","ref":"<project-id>/<branch>"}' --input '{"kind":"graph","start":{"kind":"objects","objects":[{"projectId":"<project-id>","objectId":"<object-id>"}]},"steps":[{"depth":1}]}' --json
+```
+
+Check the returned hops against the relationships you wrote. Use `findPaths` for paths across
+several objects; read its help before supplying input.
+
+## Project ref rules
+
+A project rule may protect `main` or refs under that project's identifier. A matching
+`merge-only` rule requires changes through a branch and merge. A `locked-rows-only` rule binds
+merge-only row locks on the matching ref while leaving unlocked rows direct.
+
+Rule management is the person's workflow: they must hold `administer projects` on the project
+and run these commands themselves. Never add or remove rules on their behalf, including to
+get past a refusal.
+
+1. The person runs `openeng rules add --project <id> --pattern main --consequence merge-only`
+   to protect the project's trunk. The answer includes the rule's identifier. Adding the same
+   content again returns the existing rule.
+2. `openeng rules list --project <id>` reads the visible rules, their identifiers, patterns and
+   consequences; it needs `read` on the project.
+3. To lift one rule, the person runs `openeng rules remove --project <id> --rule-id <id>` with
+   the identifier from the list. An absent identifier or one from another project answers
+   `not-found`. Removal is audited, as is addition, and takes effect on the next request.
+   Other matching rules and row locks may still protect the ref's rows.
+
+## Organisation rules, refs, locks and agent ceilings
+
+These protections are managed by the person. Never change rules, refs or locks yourself,
+including to get past a refusal. Read their current state and ask the person to make a change.
+Each command's `--help` names the person's capability. A `not-permitted` refusal carries no
+capability; read the help line before asking the person to seek permission.
+
+- The person uses the rules commands above with `--organisation` instead of `--project <id>`
+  for organisation rules, for example
+  `openeng rules add --organisation --pattern release-v1 --consequence merge-only`.
+  Choose exactly one flag. `--organisation` takes no value and uses the attached organisation.
+  `openeng rules list --organisation` reads the rules;
+  `openeng rules remove --organisation --rule-id <id>` removes one by its identifier.
+  Adding or removing needs `administer projects` in the attached organisation; listing needs `read`.
+- `openeng org-refs list` reads organisation refs and their read-only state. The person creates
+  one with `openeng org-refs create --name <name> [--read-only]`, marks it read-only with
+  `openeng org-refs mark-read-only --name <name>`, or deletes a writable one with
+  `openeng org-refs delete --name <name>`. Names are single segments, such as `release-v1`.
+  Creating, deleting and marking need `administer projects` in the attached organisation;
+  listing needs `read`.
+- The person sets or lifts an object's lock with
+  `openeng locks set --project <id> --ref <ref> --object <objectId> --lock <none|merge-only|frozen>`.
+  `none` lifts it. The lock also applies to its existing structural child edges in the selected
+  project. New children on a live ref are not thereby frozen. Use a read-only organisation ref
+  for a fixed baseline. This needs `lock objects` on the selected project.
+- `openeng ceiling show --project <id>` reads the maximum agent role. The person sets it with
+  `openeng ceiling set --project <id> --ceiling <contributor|maintainer>`.
+  Showing needs `read`; setting needs `administer projects` on the selected project.
+
+## Protection refusals
+
+When a command returns one of these rules, follow its action and do not repeat the same request:
+
+- `immutable`: the type forbids changing or deleting the record on every ref. Leave it unchanged.
+- `owned`: a connected system alone writes the record. Ask that system to make the change.
+- `frozen`: someone with the lock capability must lift the lock. Ask that person; do not try a
+  different ref.
+- `protected`: a rule allows the record to change only through a merge from a branch. Make the
+  change on a branch and merge it.
+- `not-a-ref-head`: the commit is not the head of a ref you can use. Read the usable refs and
+  choose one of their heads; the refusal does not identify which commit or ref was involved.
+- `branch-needs-schema-update`: the ref's schema must be updated before writing. The
+  person can run `openeng schema-update request --ref <ref>` to record a request, then
+  `openeng schema-update show --ref <ref>` to read its state or `no request`. Stop writing while
+  the ref needs an update; recording a request does not execute the update. Requesting needs
+  `write ref` on the branch's home project, or `administer projects` for an organisation ref;
+  showing reads only the requester's records in the token organisation and needs no project read
+  access. A branch whose name contains `/` cannot request or show a schema update today.
+- `organisation-not-ready`: the organisation's trunk is not ready. Try again shortly.
+- `read-only-ref`: nothing can be written or merged into this ref. Choose a writable ref.
+
 ## 4. Link to a page
 
 To give the person a page, run `openeng link` and hand them the address it prints; never write a path
@@ -170,6 +263,15 @@ project. `openeng link ontology --ref <ref>` and `openeng link change-set --ref
 project, and `openeng link organisation-page <page>` takes neither flag. The organisation is the one
 your session is attached to.
 
+Every kind with `--ref`, including `ontology` and `change-set`, takes `main` or
+`<projectId>/<branch>`, the ref the platform returns. A bare branch name or change-set id is
+refused by `openeng link`. Before printing, the command reads the ref and the page's own subject;
+a subject it cannot find is a refusal with a reason and no printed address.
+
+An **App** is an organisation entity with its own pages and drafts, linked by `openeng link app`.
+An **App view** is a type's collection content in `presentationBindings.views.app`, root `AppBody`,
+and cannot be linked by `link app`.
+
 ## 5. Show data to the person
 
 The CLI draws nothing. Read the `--json` output of a query or a read and draw it yourself, as a
@@ -209,10 +311,10 @@ The order, from no connection to a first imported document:
    `succeeded` or `failed`.
 5. `openeng connector revoke <connection>` ends the connection.
 
-Mirrored objects are read-only in practice: 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. Do not write to a mirror project expecting the change to stay.
+The connected system alone writes records of its owned types. A person's write is refused as
+`owned`. People put their own information in separate rows and link those rows to the mirrored
+records. The importer counts updates to mirrored properties as `overwritten`. If a mirrored
+record is absent, the importer creates it with a new identifier and counts it as `created`.
 
 Refusals you will meet, with what each means and what to do: