@openengio/cli 0.27.1 → 0.33.0

package/package.json

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

package/skill/build-ui/SKILL.md

@@ -79,7 +79,7 @@ differences:
 
 | json-render teaches | here | why |
 |---|---|---|
-| props naming a project, ref, organisation, namespace, object, type version, URL or path | refused, always | a view never chooses its own scope: the host derives the page's project and ref from its address, so a view cannot read or link outside it |
+| props naming a project, branch or baseline, organisation, namespace, object, type version, URL or path | refused, always | a view never chooses its own scope: the host derives the page's project and branch or baseline from its address, so a view cannot read or link outside it |
 | `className`, `style`, `html`, `color` | refused, always | a visual choice is a design-token name, such as a Badge's `tone`, so every view keeps the platform's look and carries no raw HTML |
 | defining your own catalog and components | not possible | a view is display data, not a capability: the web renders only the catalogue's components |
 | fetching data from json-render | not possible | data enters only through a `Query` element, which the host scopes |

package/skill/conventions/SKILL.md

@@ -88,6 +88,14 @@ Check: the model's convention is written down, and every edge follows it.
 Check: each type's default tree is the one the person expects; a type with views has its main tree as
 the first view.
 
+The `relationships` array is the ordered list of natural parent edge types: the first declared edge
+that supplies a parent places an object in the default tree. Climbing farther uses each ancestor
+type's own declaration. A `structureDeclaration.views` entry is a navigation tree; declaring views
+replaces the relationship picker with those views, so include the usual tree first. A two-step view
+can pass through a shared intermediate object, omit it from the tree, and show its properties as
+decoration. A traceability edge with a `parentEnd` can give one object several parents; the object
+then appears once at each placement, and its ancestry depends on the selected tree.
+
 ## 5. The rail and the page
 
 - The organisation holds one list of rail groups, in the order the rail draws them; it is sent whole
@@ -96,7 +104,13 @@ the first view.
   `rail` is listed under "More types": leave it off for a type that is the detail of another, not a
   destination.
 - `presentationBindings.title` names the property that titles the object in tables, trees and the graph view.
-  `presentationBindings.typeIcon` is a Material Symbols glyph name.
+  `presentationBindings.typeIcon` is a Material Symbols glyph name. A new object type needs one, and so does
+  every later version of a type whose current version has one; publication refuses it otherwise
+  (`missing-type-icon`). Before choosing, read the organisation's existing type icons (`openeng types export`)
+  and pick a glyph that is relevant to the type and distinct from theirs.
+  `presentationBindings.propertyLabels` maps a property key to a display label of at most 80 characters,
+  and `presentationBindings.propertyOrder` lists property keys in display order, each once. Both name
+  only properties the version defines.
 - An **object view** (`presentationBindings.views.object`, root `ObjectBody`) lays out the object's
   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.
@@ -135,6 +149,12 @@ for a lifecycle state. A wrong edge is replaced by a new edge type key and a rec
 - An update is a compare-and-set per property: `{"<property>": {"from": {"value": <what it holds now>}, "to":
   {"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.
+- A `datetime` property takes an RFC 3339 date-time with an explicit offset and zero to three fraction digits
+  (`2026-10-19T22:30:00+01:00`); a value with no offset, an impossible date or time, or four or more
+  fraction digits is refused, never truncated. It is stored as `YYYY-MM-DDTHH:MM:SS.sssZ`, the same
+  instant in UTC, and a `from` naming the stored instant in another offset still matches. A calendar
+  date is its midnight in UTC; there is no date kind. A type that declares `datetime` is schema
+  language version `2` or later, and a type's version never decreases.
 
 ## Property kinds
 
@@ -194,8 +214,65 @@ An enum's `members` is a list of strings or finite numbers. A published member c
 {"kind": "object", "properties": {"name": {"kind": "string"}}, "required": ["name"]}
 ```
 
+### datetime
+
+An instant, under schema language version `2`.
+
+```json
+{"kind": "datetime"}
+```
+
+### attachment
+
+A file descriptor on a top-level object property, under schema language version `3`. The kind is
+refused inside object or array properties and in edge and verb schemas. `accept` lists admitted
+classes: adding a class is compatible; removing one or changing the property's kind is refused.
+The accepted classes are `image` (`.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`), `pdf` (`.pdf`),
+`step` (`.step`, `.stp`), `mesh` (`.stl`) and `text` (`.txt`, `.md`, `.csv`, `.json`, `.yaml`,
+`.yml`, `.toml`, `.ini`, `.log`, `.xml`, `.ts`, `.tsx`, `.js`, `.py`, `.c`, `.h`, `.cpp`, `.hpp`,
+`.rs`, `.go`, `.java`, `.m`, `.sql`, `.sh`). The maximum file body is 26,214,400 bytes (25 MiB).
+Use `openeng attachment add <object> <property> <file> --project <id> --ref <ref>` to attach a
+file, `openeng attachment list <object> --project <id> --ref <ref>` to list attachment properties,
+and `openeng attachment get <object> <property> [--out <path>] --project <id> --ref <ref>` to save
+one property's bytes.
+
+```json
+{
+  "typeCategory": "object",
+  "typeKey": "drawing_record",
+  "version": 1,
+  "displayName": "Drawing record",
+  "description": null,
+  "schemaLanguageVersion": "3",
+  "propertyDefinitions": {
+    "drawing": {"kind": "attachment", "accept": ["image", "pdf", "step", "mesh", "text"]}
+  },
+  "requiredPropertyKeys": []
+}
+```
+
 ## 9. Examples
 
+These are small type documents to adapt and validate in a change set before accepting it.
+
+### Example: object type
+
+```json
+{"typeCategory":"object","typeKey":"task","version":1,"displayName":"Task","description":null,"schemaLanguageVersion":"1","propertyDefinitions":{"name":{"kind":"string"}},"requiredPropertyKeys":["name"],"presentationBindings":{"title":"name","typeIcon":"task"}}
+```
+
+### Example: edge type
+
+```json
+{"typeCategory":"edge","typeKey":"depends-on","version":1,"displayName":"Depends on","sourceObjectType":"task","targetObjectType":"task","kind":"traceability","subjectEnd":"source","parentEnd":"source","sourceLabel":"depends on","targetLabel":"is depended on by","schemaLanguageVersion":"1","propertyDefinitions":{},"requiredPropertyKeys":[],"readRule":"both-endpoints","writeRule":"both-endpoints"}
+```
+
+### Example: template verb with its result contract
+
+```json
+{"typeCategory":"verb","typeKey":"create-task","version":1,"displayName":"Create task","description":null,"allowedSubjectTypes":"none","inputSchema":{"kind":"object","properties":{"name":{"kind":"string"}},"required":["name"]},"resultSchema":{"kind":"null"},"schemaLanguageVersion":"1","template":{"operations":[{"kind":"create-object","typeKey":"task","properties":{"name":{"slot":"input","key":"name"}}}]}}
+```
+
 A minimal object type and a structural edge, every key at version 1:
 
 ```json

package/skill/demo/SKILL.md

@@ -44,7 +44,7 @@ out of every story.
 - [ ] C2. One data model, two ways of working: a CRUD app or a branch-first engineering workflow
   Checklist: Switch one project between direct edits on `main` and branch-only edits.
   Features shown: Objects; Branches; Branch diff and changed-object accents; Proposals; Roles and
-  membership; Ref rules.
+  membership; Branch rules.
 
 - [ ] C3. Follow one question across every tool
   Checklist: Answer one question that crosses requirements, parts and tests.
@@ -57,13 +57,15 @@ out of every story.
   subscribers; Delete preview; Branch history and the audit trail.
 
 - [ ] C5. An agent does the work, a person makes the call
-  Checklist: Have the in-product agent make a change that a person approves and merges.
+  Checklist: Explain that the organisation's agent model is chosen in the web app under Admin,
+  Agent model; open or link that page. Have the in-product agent make a change that a person
+  approves and merges.
   Features shown: Branches; Branch diff and changed-object accents; Proposals; Branch history and
   the audit trail; Object agent; Agent model per organisation; Agent ceiling.
 
 - [ ] C6. Freeze what shipped, keep building what comes next
   Checklist: Freeze a released part and keep a read-only release baseline.
-  Features shown: Types and the ontology; Objects; Relationships; Organisation refs; Instance
+  Features shown: Types and the ontology; Objects; Relationships; Organisation branches and baselines; Instance
   locks; Type rules.
 
 - [ ] C7. Your CAD system stays the source of truth
@@ -99,11 +101,14 @@ cares about; do not explain a primitive in isolation.
   `objects-sdk mutateBatch`, then show the rail, table and object card with `link type`.
 - C2: edit on main, add a merge-only rule, show the same edit refused `protected`, then branch,
   edit, compare and submit a proposal. The person merges; remove the rule and show direct edits.
-- C3: narrow with `objects-sdk readStructure`, show `link explore`, and answer a question
+- C3: narrow with `objects-sdk readStructure`, show `link explore --object <id>` for the selected
+  object, and answer a question
   across requirements, parts and tests with `queryObjects`, `findPaths` and `aggregateObjects`.
 - C4: open a record's history, comment and subscribe; use `objects-sdk previewDelete` before
   any deletion, and read branch history and `admin-sdk listAudit`.
-- C5: show the organisation's agent model and project's `ceiling show`. The person uses
+- C5: explain that the organisation's agent model is chosen in the web app under **Admin**, **Agent model**.
+  Run `openeng link organisation-page agent-model` and open or share the returned link. The CLI
+  has no read of the selected model; do not claim to have read it. Show the project's `ceiling show`. The person uses
   "Open agent", approves its plan, inspects the branch diff, submits and merges. Read the audit
   naming the person and run; show the agent refused on protected main.
 - C6: use `locks set --lock frozen` on a released part, show an edit refused, create its successor
@@ -118,7 +123,7 @@ cares about; do not explain a primitive in isolation.
 
 At each step, say what comes next and why, make the smallest useful change (one atomic batch
 for related writes), validate before publishing, and read the result in the intended organisation,
-project and ref. Give a link from `openeng link`, say what they should see, and leave time to see it.
+project and branch or baseline. Give a link from `openeng link`, say what they should see, and leave time to see it.
 Invite an action that matters, then check its result with a read. Keep accepted, validated,
 published and seen in the app distinct. Drive through the CLI; the person operates the app.
 

package/skill/openeng/SKILL.md

@@ -2,7 +2,7 @@
 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 an agreed ref
+  Signing in, listing projects and types, editing object types, writing objects on an agreed branch
   and submitting branches for review.
 ---
 
@@ -14,11 +14,27 @@ description: >-
 npm install -g @openengio/cli
 ```
 
+Set `OPENENG_NO_UPDATE_CHECK=1` to disable the daily npm update check and standard-error notice; `CI`, help and `--version` also skip it.
+
 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
 field may take, the selector keys and one example input, and needs no sign-in.
 
+## Explain each step
+
+When guiding a person, say what you intend to learn or change, give the command, then report what it
+answered and what follows. When the step has a GUI page, include the address from `openeng link` at
+that step; do not construct a page address yourself. For example:
+
+1. Intent: identify the project and its namespace. Run `openeng projects list --json`; report the
+   project id and namespace it returned.
+2. Intent: show the project in the web app. Run `openeng link project --project <id> --ref main`
+   and give the returned address with what the page should show.
+3. Intent: inspect one object in the chosen branch. Run the relevant read command and report its
+   result; when the person needs its page, run `openeng link object <object-id> --project <id>
+   --ref <ref>` and give that returned address.
+
 ## Read the topic for your task
 
 - A person new to OpenEngineering who wants a tour, or has just signed in with no task of their own: `openeng skill demo`.
@@ -29,6 +45,15 @@ field may take, the selector keys and one example input, and needs no sign-in.
 - A domain model: `openeng skill playbook engineering-requirements`,
   `openeng skill playbook product-lifecycle`, or `openeng skill playbook project-management`.
 
+## Attachments
+
+For a top-level object property declared with kind `attachment`, use
+`openeng attachment add <object> <property> <file> --project <id> --ref <ref>` to stage a file and
+save its descriptor, `openeng attachment list <object> --project <id> --ref <ref>` to read its
+attachment properties, and `openeng attachment get <object> <property> [--out <path>]` with the
+project and ref flags to download it. The `get` command uses the descriptor's file name when `--out`
+is omitted. The accepted classes and file-size limit are in `openeng skill conventions`.
+
 ## Rules that hold for every command
 
 - Add `--json` when you read the answer yourself. It prints one JSON value on standard output.
@@ -91,9 +116,9 @@ For a generic open-cycle gas turbine demonstration project, run `openeng demo se
   `{"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>}`. Rules command successes always use this wrapper
-  to preserve the rule's own `scope` field. Organisation-ref, lock, ceiling and schema-update
+  to preserve the rule's own `scope` field. Organisation branch or baseline, 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
+- A `not-found` in an organisation is often a project or a branch or baseline 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,
   `openeng org list` and `openeng org attach <id>`.
@@ -111,6 +136,8 @@ to understand each part, then design the model with the person before you draft
    it writes them as one JSON object keyed by type key, each at the next version, ready to send
    with revise. If it has no published types, create `draft.json` from the `changes` map in the
    example input printed by `openeng help ontology-sdk reviseChangeSet`.
+   A new object type needs `presentationBindings.typeIcon`; read the existing types' icons in the
+   export and choose a relevant glyph that no other type uses.
 2. Make `draft.json` hold only the types you change: delete every other key, and keep each type you
    keep whole, as the export wrote it. Accepting a type you did not change publishes an identical
    new version of it.
@@ -121,12 +148,28 @@ to understand each part, then design the model with the person before you draft
 5. `openeng types draft validate --change-set <id> --revision <revision>` must report no violations.
    It exits 0 when there are no violations, and exits 4 with the violations on standard output
    otherwise; then edit the file and revise again.
+   To try a sample instance against a type in the draft before you accept it, write the sample as a
+   JSON object of raw property values and run `openeng types draft try --type <type key> --sample
+   sample.json`. It reads the open change set and writes nothing, and checks the sample the way a
+   write does: it exits 0 when the sample fits and exits 4 with each violation's path and rule
+   otherwise. Add `--change-set <id>` to name the change set instead of using the open one.
 6. `openeng types draft show --change-set <id> --project <project id>` shows what changes against the
    published types, per type and per field. Check that it is exactly the change you meant.
 7. `openeng types draft accept --change-set <id> --revision <revision>` publishes it. The new version
    is now the published one: from here on, take a type's version for data writes from
    `openeng types list`.
 
+Property kinds are `null`, `boolean`, `string`, `number`, `integer`, `person`, `enum`, `array`,
+`object`, `datetime` and `attachment`. Use `datetime` for an instant. A value is an RFC 3339 date-time
+with an explicit offset and zero to three fraction digits, such as `2026-10-19T22:30:00+01:00` or
+`2026-10-19T21:30:00Z`; a value with no offset, an impossible date or time, or four or more fraction
+digits is refused. The platform stores it as `YYYY-MM-DDTHH:MM:SS.sssZ`, the same instant in UTC.
+A calendar date is midnight UTC; there is no date kind. A type declaring `datetime` needs language
+version `2` or later. An `attachment` is a top-level object property under version `3`, with a
+non-empty `accept` listing classes such as `image` and `pdf`; it is refused inside an object or
+array property and in an edge or verb schema. See the named property example in
+`openeng skill conventions`. Never lower a published type's language version when revising it.
+
 To abandon a draft, `openeng types draft discard --change-set <id>`.
 
 `presentationBindings.typeIcon` is a Material Symbols Rounded name from the installed
@@ -141,29 +184,35 @@ watchers are admitted; the publication validator decides whether a declaration i
 
 ## 3. Write data
 
-Write on the ref agreed with the person and within their authority. That may be `main` when
+Write on the branch 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.
+project's `main`. Use a branch and review when a rule protects the branch 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. 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
+   answers the branch's full name, written `<project id>/<name>`.
+3. `openeng objects-sdk mutate` creates, changes or deletes an object or an edge on that branch. The `ref` field in
    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
+   branch is its full name, `<project id>/<name>`; an organisation branch or baseline is its bare name.
+   `--ref` takes a branch (`main` or `<projectId>/<branch>`) or a baseline for commands that admit organisation names.
+   The server derives the organisation from the token. Use the agreed branch for writes and read
+   back from that same branch 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 objects-sdk queryObjects` for a list. Use `openeng objects-sdk queryRows` when you need
+   selected row cells, a count or grouped values; it answers these in one call instead of paging
+   `queryObjects` to count locally. Use the type key and version the project's
    `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. 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.
+   names the branch by its `name` alone, the part of the full branch name after the slash.
+
+If a verb name is unknown, use `openeng objects-sdk discoverVerbs` for the object and choose a
+listed verb; do not guess a verb key.
 
 If a command is refused, the refusal names the field and its allowed kinds. Run
 `openeng help <module> <method>` again and compare.
@@ -181,11 +230,35 @@ openeng objects-sdk queryGraph --host https://api.openeng.io --selector '{"proje
 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
+### Review object and relationship changes
+
+Run `openeng help branches-sdk diffBranches` for a live branch comparison, or
+`openeng help branches-sdk readBranchDiff` for a submitted proposal's reviewed comparison.
+Read both the object collection (`changes` for a live diff, `objects` for a proposal) and
+`edges`. One page holds at most 200 changes total; follow its cursor until it is null before
+describing the whole change. An edge's source and target carry object and project identifiers,
+plus the edge's own properties before and after. An unreadable endpoint's identifiers do not
+grant access to its title, type or properties. A cursor from an older client is refused;
+start the comparison again with no cursor.
+
+## Project branch rules
+
+`openeng branches-sdk disposeRef` is a writer's cleanup of a branch with no pending proposal.
 
-A project rule may protect `main` or refs under that project's identifier. A matching
+### Resolve a merge conflict
+
+When merge answers `merge-conflict`, read the conflicts with
+`openeng branches-sdk readMergeConflicts --selector '{"projectId":"<project-id>"}'
+--input '{"name":"<source-branch-name>"}'`. The `name` is the source branch's name. For each
+field, `base` is its value before either side changed it, `ours` is `main`, and `theirs` is the
+source branch's value. A value may be absent on a side. The read always compares the source with
+`main`, even if the merge targeted another branch, so it does not report conflicts from a merge
+whose target was not `main`. Reconcile the changes on the source branch, then submit a new merge
+with the reviewed head; reading conflicts makes no changes.
+
+A project rule may protect `main` or branches 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.
+merge-only row locks on the matching branch 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
@@ -199,11 +272,11 @@ get past a refusal.
 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.
+   Other matching rules and row locks may still protect that branch's rows.
 
-## Organisation rules, refs, locks and agent ceilings
+## Organisation rules, branches and baselines, locks and agent ceilings
 
-These protections are managed by the person. Never change rules, refs or locks yourself,
+These protections are managed by the person. Never change rules, branches, baselines 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.
@@ -215,8 +288,8 @@ capability; read the help line before asking the person to seek permission.
   `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 list` reads organisation branches and baselines with their read-only state. The person creates
+  a branch with `openeng org-refs create --name <name>` or a baseline by adding `--read-only`. A branch becomes a baseline 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;
@@ -224,8 +297,8 @@ capability; read the help line before asking the person to seek permission.
 - 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.
+  project. New children on a writable branch are not thereby frozen. Use a baseline
+  to preserve a fixed snapshot. 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.
@@ -234,50 +307,75 @@ capability; read the help line before asking the person to seek permission.
 
 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.
+- `immutable`: the type forbids changing or deleting the record on every branch or baseline. 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.
+  different branch or baseline.
 - `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
+- `stale-source`: read a branch you can use and merge its current head. Optional merge `name`
+  requires that bound branch's current head to equal `sourceHash`; it never selects a proposal.
+  A successful merge into main closes every pending proposal in the project at that reviewed hash.
+- `not-a-ref-head`: the branch has new commits since the review began. Reload the proposal to
+  review its latest commit; the refusal does not identify the branch or its newer head.
+- `branch-needs-schema-update`: the branch'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;
+  the branch 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 branch or baseline;
   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.
+- `read-only-ref`: nothing can be written or merged into this branch or baseline. Choose a writable branch.
 
 ## 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
-or an address yourself. `openeng link <kind> --project <id> --ref <ref>` takes `explore`, `branch-diff`
+or an address yourself. `openeng link <kind> --project <id> --ref <ref>` takes `branch-diff`
 or `project`; `openeng link <kind> <identifier> --project <id> --ref <ref>` takes `object`, `type`, `proposal` or
 `app` (the app's first page); `openeng link app-page <appKey> <pageKey> --project <id> --ref <ref>` takes
 one page of an app; `openeng link app-draft <appKey> --ref <ref>` takes the app's draft screen and no
-project. `openeng link ontology --ref <ref>` and `openeng link change-set --ref <ref>` take a ref and no
+project. `openeng link ontology --ref <ref>` and `openeng link change-set --ref <ref>` take a branch and no
 project, and `openeng link organisation-page <page>` takes neither flag. The organisation is the one
 your session is attached to.
 
+| kind | destination |
+|---|---|
+| `object <id>` | The object's type page with the object open; the type comes from its read. |
+| `type <key>` | The type's page. |
+| `explore` | Explore with exactly one `--object <id>` or `--object-set <id>` seed. |
+| `branch-diff` | The branch comparison page. |
+| `project` | The project page. |
+| `proposal <id>` | The proposal review page. |
+| `ontology` | The organisation's Types workspace. |
+| `change-set` | The organisation's Change set workspace. |
+| `app <key>` | The published app's first page. |
+| `app-page <appKey> <pageKey>` | The named page of a published app. |
+| `app-draft <key>` | The app's draft screen in the Types workspace. |
+| `organisation-page <page>` | The named organisation administration page or settings. |
+
+Only `explore` opens Explore. Use `openeng link explore --project <id> --ref <ref>` with exactly
+one of `--object <id>` or `--object-set <id>`; neither or both refuse before a host call.
+The seed flags are only for `explore`. `link object <id>` opens the type page with that object,
+using the type key from the object read. Explore also reads its selected object or saved set first.
+
 ### Save an object set and link to its canvas
 
 1. Run `openeng help objects-sdk createObjectSet` and `openeng help objects-sdk readObjectSet`.
 2. Query the objects you need with `openeng objects-sdk queryObjects --json`. Keep each object's
    project with its identifier; one set may contain objects of several projects in your organisation.
+   To combine two selections on the same ref, send `{ "kind": "set", "op": "difference", "left": { "kind": "objects", "typeKey": "..." }, "right": { "kind": "objects", "typeKey": "..." }, "limit": 100, "continuation": null }`. `op` may be `union`, `intersection` or `difference`. Each operand may have its own `projects`, `filters` and `steps`; operands cannot be nested set operations.
+   `aggregateObjects` also accepts `operation: "average"` with one numeric `property`; the result includes its mean and the count averaged, and omits the mean when that count is zero.
 3. Call `openeng objects-sdk createObjectSet` with a name and the selected addresses, following its
    help. Keep the returned set identifier and revision. Retrying with the same idempotency key
    returns that original answer.
 4. Run `openeng link explore --project <page project> --ref <ref> --object-set <set id>` and give the
    person the address it prints. It reads the set first; a refused read prints no link. The set
-   stores no ref, so the link's ref chooses which version of its objects opens.
+   stores no branch or baseline, so the link's branch chooses which version of its objects opens.
 
 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;
+`<projectId>/<branch>`, the branch name the platform returns. Baseline names are not accepted by `openeng link`. A bare branch name or change-set id is
+refused by `openeng link`. Before printing, the command reads the branch 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`.
@@ -350,3 +448,47 @@ Refusals you will meet, with what each means and what to do:
 - `change-set-open`: the organisation already has an open change set, so drafting the types
   stopped. Read it with `openeng types draft current` and continue with it; the connection exists, and
   `openeng connector draft-types <connection>` drafts once that change set is settled.
+
+## Inviting a person
+
+Run `openeng help admin-sdk createInvitation` before inviting. The request takes `email`, an
+organisation `roleKey`, and optional `projectRoles`: up to 50 `{ projectId, roleKey }` entries,
+one per project in the attached organisation. The inviter must administer members on the
+organisation and each project, and may offer no role above their own there. Send no organisation
+field; the server derives it. Deliver the returned link to the person.
+
+`openeng admin-sdk listInvitations --input '{}' --json` lists pending invitations and their
+project roles. Re-issuing keeps the roles; revoking removes the invitation from that list.
+Acceptance skips and audits a project role when the project ended, the person already holds an
+equal or higher project role, or the inviter lost the required standing. Sign-in continues.
+
+Membership roles are `owner`, `maintainer`, `contributor` and `reader`. They grant, respectively:
+
+- `owner`: administer members, projects and service identities; write trunk, branches and protected
+  rows; merge; and read.
+- `maintainer`: write trunk, branches and protected rows; merge; and read.
+- `contributor`: write branches and read. For example, a project contributor may edit on a branch
+  and read the project, but does not gain merge or trunk-write permission.
+- `reader`: read.
+
+A membership can be scoped to an organisation or a project. An organisation role supplies its
+capabilities in each project of that organisation too; a project role applies to its named project.
+For a project-specific exception, grant the role on that project rather than assuming a membership
+in one project applies to another.
+
+An unknown role on an invitation or membership grant answers `unknown-role` with `roleKeys`, the
+deployment's role keys. Choose one of those keys. A known role above your own answers
+`above-caller-role`.
+
+## Recover an interrupted operation
+
+`openeng objects-sdk recover` checks the record of a mutation or verb whose result was unknown. Give
+the same project and ref, and the original correlation id:
+
+```sh
+openeng objects-sdk recover --selector '{"projectId":"<project-id>","ref":"<project-id>/<branch>"}' --input '{"correlationId":"<correlation-id>"}' --json
+```
+
+Recovery can report a committed change and its hash, and finish the recovery record. It never sends
+the original mutation again. If the saved evidence still cannot establish an outcome, it returns
+`unknown`; it cannot undo a successful write, restore a deleted object, or retry a failed operation.

package/skill/playbooks/product-lifecycle.md

@@ -112,4 +112,4 @@ reached through a part or a plant.
   a structure by it.
 - **Mass change** of many lines, and a **cost roll-up** across a structure: a count per question is a query, a
   roll-up is not built.
-- **CAD geometry**: an object view can show an STL property (`STLViewer`); there is no live CAD link.
+- **CAD geometry**: an object view can show an STL attachment (`STLViewer`); there is no live CAD link.