@openengio/cli 0.36.0 → 0.37.0

package/package.json

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

package/skill/build-ui/SKILL.md

@@ -5,9 +5,9 @@ description: Use when a person wants an object type's drawer (its object view) o
 
 # Build an object view or an App view
 
-A type carries up to two views in `presentationBindings.views`: an **object view**, which lays out the drawer of
-one object, and an **App view**, which lays out the type's page. Both are display only: they show data and take
-page controls, and they never act. A view is built only from the platform's view catalogue. Read the catalogue
+A type can carry three views in `presentationBindings.views`: an **object view**, which lays out the details panel
+for one engineering record, an **App view**, which lays out the type's collection page, and a **card view**, a compact record summary. They show data. Object, App and page
+views take page controls, and a **Button** in them can run a verb or set properties; a card view takes neither. A view is built only from the platform's view catalogue. Read the catalogue
 reference before step 3: the platform's agent loads it as the skill `author-views`, generated from the
 catalogue the platform validates against. The CLI does not yet ship that generated reference. With `openeng`,
 use this guide's examples and `openeng help types draft revise` for the wire shape, then validate the change
@@ -47,7 +47,7 @@ For each question, choose the components that answer it. Use the reference for w
 | group or hide detail | `Section`, `Tabs` and `TabPanel`, `Disclosure`, `Card`, `Grid`, `Stack` | the same |
 | link to an object | `Link` | `Link` |
 
-The root is `ObjectBody` for an object view and `AppBody` for an App view, and appears nowhere else.
+The root is `ObjectBody` (the object-view container) for an object view and `AppBody` (the collection-page container) for an App view, and appears nowhere else.
 
 ## 4. Bind the data
 

package/skill/conventions/SKILL.md

@@ -79,7 +79,7 @@ Check: the model's convention is written down, and every edge follows it.
   `build-ui` skill).
 - A **named view** (`structureDeclaration.views`, each `{ key, label, steps }`) is a saved tree: one or
   two edge steps. A two-step view passes through an intermediate object, which is left out of the tree
-  and may lend properties to the row (`decoration`); a part under its assembly through a BOM line, with
+  and may lend properties to the row (`decoration`, displayed properties from that intermediate record); a part under its assembly through a BOM line, with
   the line's quantity on the row.
 - **Declaring any named view replaces the web's relationship picker with a picker of those views alone.**
   When you add a view, declare the tree people use most as a view too, first, because the first view is
@@ -115,7 +115,7 @@ then appears once at each placement, and its ancestry depends on the selected tr
   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** is an organisation-owned application definition 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`.
 
@@ -228,6 +228,9 @@ An instant, under schema language version `2`.
 
 ### attachment
 
+Create the object first, then stage and save its attachment. Creation with a file is refused
+as `invalid-properties` with `attachment-requires-object` at each offending property.
+
 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.
@@ -289,7 +292,7 @@ These are small type documents to adapt and validate in a change set before acce
 ### 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"}}}]}}
+{"typeCategory":"verb","typeKey":"create-task","version":1,"displayName":"Create task","description":null,"allowedSubjectTypes":{"kind":"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:

package/skill/demo/SKILL.md

@@ -107,8 +107,7 @@ cares about; do not explain a primitive in isolation.
 - 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: 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
+  Run `openeng link organisation-page agent-model` and open or share the returned link. Run `openeng admin-sdk readModelConfigurationStatus` to read the selected model; this read needs `administer agents` on the organisation. 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
@@ -128,7 +127,7 @@ Invite an action that matters, then check its result with a read. Keep accepted,
 published and seen in the app distinct. Drive through the CLI; the person operates the app.
 
 The person enters Onshape keys themselves at `openeng connector set-credential`'s prompt;
-never ask for keys in conversation or type them. Mirrored objects are owned by the connector.
+never ask for keys in conversation or type them. Mirrored objects can be changed only by the connector that imports them.
 For OAuth, read the published client contract and `openeng help admin-sdk registerClient`.
 Register a public client with a `http://127.0.0.1:<port>/callback` redirect; use authorization code
 with PKCE. Keep the local app read-only unless asked for more; it never sees their password.

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

@@ -5,7 +5,7 @@ description: Use when a person wants types for a use case their organisation's c
 
 # Design the types for a new use case
 
-Work through the steps in order. Do not skip a stop point: at each one, show the person what you
+Work through the steps in order. A catalogue is the organisation's shared set of object and relationship definitions. A change set is the saved draft of proposed definition changes. Do not skip a stop point: at each one, show the person what you
 have and wait for their agreement. Ask at most three questions at a time, each with lettered options
 and your recommendation. Draft nothing in a change set before step 7. Read `openeng skill conventions` before
 step 3; it holds the rules every step below relies on.
@@ -21,7 +21,7 @@ step 3; it holds the rules every step below relies on.
 | open a change set | `open_change_set` | `openeng types draft open` |
 | save the changed types | `revise_change_set` | `openeng types draft revise --change-set <id> --revision <token> --from <file> [--rail-groups <json>]` |
 | validate | `validate_change_set` | `openeng types draft validate --change-set <id> --revision <token>` (exit 4 with violations) |
-| try a sample against a draft type | `try_instance` | none yet; validate, and after acceptance write one object on a throwaway branch |
+| try a sample against a draft type | `try_instance` | `openeng types draft try`; checks a sample without an engineering write |
 | publish | never: the person publishes | `openeng types draft accept` only after the person says so, for that change set |
 | search the web | `web_search`, `web_fetch` | your own tools, under the same rule: never put anything read from the platform into a query or an address |
 

package/skill/openeng/SKILL.md

@@ -21,6 +21,22 @@ their own. Before you send a generated command (`objects-sdk`, `branches-sdk` an
 `<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.
 
+## Read a route's policy
+
+Generated route help prints `actors` (the caller categories allowed) and `step-up` (whether user confirmation is required) from the route table's current `policy` (access rules).
+The policy is `{ none: true }` for no access-token requirement, or an `actors` map whose keys name
+admitted classes and whose values state each class's step-up. `person` is the person's authority;
+in-app agent names are `agent:explore`, `agent:apply` and `agent:types`. Application actors use
+`app:client` or `app:hosted`, and service authority uses `service`. These are actor labels;
+a CLI session in agent mode still acts as `person`.
+
+A step-up value is `none`, `person-present` (requires the signed-in user's confirmation), or `{ personPresentWhen: <predicateName> }` (requires confirmation when a condition is met). Help
+names the predicate and its condition, including `unlocks` (the condition for removing a lock) when a lock is set to `"none"`.
+Read the generated lines for the route you need; this skill keeps no separate admission list.
+A person's own live web session is never challenged. An agent-mode CLI call (a session configured to require confirmation for sensitive actions) on an action requiring confirmation
+meets the challenge and waits for its person, as described below. In-app agent classes are omitted
+from every marked policy in this release; confirmation cannot grant them admission.
+
 ## Explain each step
 
 When guiding a person, say what you intend to learn or change, give the command, then report what it
@@ -47,6 +63,9 @@ that step; do not construct a page address yourself. For example:
 
 ## Attachments
 
+Create the object first, then stage and save its attachment. Creation with a file is refused
+as `invalid-properties` with `attachment-requires-object` at each offending property.
+
 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
@@ -68,8 +87,8 @@ After reviewing the upstream, run `openeng links clear <link> --version <upstrea
 list up to 100 link ids and repeat `--version` once per link in the same order. On
 `upstream-changed`, read status and review before sending its new version; do not replace the
 precondition blindly. `upstream-not-readable` requires upstream read access. There is no
-organisation clearing setting: the edge's write rule decides who may clear. User, run-apply,
-client and service tokens are admitted; run-explore and run-types are refused at admission.
+organisation clearing setting: the edge's write rule decides who may clear. Read the generated route
+help for the actor classes admitted to clearing.
 The object agent has no clearing tool; clear through this CLI or the SDK. Recover an unknown
 outcome by correlation before retrying.
 
@@ -86,7 +105,7 @@ Export a component that takes `{ client }` and start it by calling the runtime's
 package that wraps this call is not published yet). Publish the built bundle with
 `openeng hosted-app publish <bundle> --project <id> --key <app key>`; it creates the app when the
 project has none under that key, and prints the version and its SHA-256. If the app holds the
-one-wall permission, the output also carries a warning: read it to the person and do not hide it.
+reduced isolation permission, output carries a warning when its grants can be read: read it to the person and do not hide it. If grants cannot be read, output says the permission is unknown.
 `openeng hosted-app list --project <id>` lists the apps, `openeng hosted-app versions <app key>
 --project <id>` lists an app's versions, and `openeng hosted-app revoke <app key | app id | version id>
 --project <id>` revokes a version (an id starting `hav_`) or the whole app by its key or `app_` id. Revoke only when the
@@ -95,15 +114,36 @@ person asks. Hosted apps run only in Google Chrome.
 ## Rules that hold for every command
 
 - Add `--json` when you read the answer yourself. It prints one JSON value on standard output.
-- Exit code 0 is success. Any other exit code is a refusal or a failure, and its message says what
+- Exit code 0 is success. Any other exit code is a refusal (a rejected operation with a reason) or a failure, and its message says what
   to do. Read it; do not retry the same command unchanged.
 - When you report a refusal to the person, quote its `reference:` line (the `reference` field under
   `--json`) exactly. The line is how the platform's operators find the request. A refusal with no
   such line was built by `openeng` itself, or the host sent no id with it.
 - A refusal of a field names the field, such as `input.correlation`, and the kinds it may take.
   Fix that field and send the command again.
+- A command that the platform holds to the person's own confirmation prints an address, then waits.
+  Tell the person to open that address in their browser and confirm; the command carries on by itself
+  once they do, and prints nothing from the confirmation. A timeout reports that the action was refused
+  because nobody confirmed in time and exits non-zero, with no write. Other poll refusals retain their
+  actual meaning. Read the refusal before deciding whether to ask the person to try again. A refusal
+  `step-up-required` (confirmation needed) or `step-up-mismatch` (confirmation did not match this action) that still reaches you
+  means that CLI session still needs confirmation for that call. A different CLI session of the
+  same person cannot collect or use its proof. In-app agent tokens are refused on every marked action,
+  even with a proof, so do not retry the command or look for another way to make the
+  change. Tell the person which action was refused and ask them to make it themselves. A refusal
+  `step-up-capacity` means the person already has the most confirmations waiting; ask them to
+  clear those first.
+- CLI sessions start in agent mode. The server stores channel and mode; local `whoami` output is
+  identity information, not evidence of human mode. Use `openeng session status` for the server's
+  channel, mode and sign-in time. A person working at the terminal can deliberately run
+  `openeng session human`, confirm once in their browser, and stop further prompts for the life of
+  that CLI session. The command prints the stored mode; repeating it is a no-op. A fresh CLI login
+  starts in agent mode. Only request human mode when the person explicitly asks for it. An unknown
+  session becomes CLI/agent on confirmation and challenges again
+  on its next marked action. A browser's own unknown session must sign in again, without a confirm
+  link or automatic replay.
 - `openeng help` lists every command. `openeng help <command words>` prints one command's help: what it
-  does, an example and the shape of its output. `openeng help <group>` lists a group's commands.
+  does and an example. `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` on every command, or prefix it as
@@ -132,7 +172,7 @@ person asks. Hosted apps run only in Google Chrome.
 5. Until you attach, these commands run without an organisation: `openeng login`, `openeng logout`,
    `openeng whoami`, `openeng help`, `openeng skill`, `openeng org list`, `openeng org attach <id>`,
    `openeng org create --name <name>`, and `openeng org current`. The generated command
-   `openeng admin-sdk createOrganisation` also runs unattached. Other commands refuse with "not attached
+   `openeng admin-sdk createOrganisation`, `openeng session status`, and `openeng session human` also run unattached. Commands that need an organisation refuse with "not attached
    to an organisation" before they send anything.
 6. `openeng projects list --json`. Note each project's id and its namespace; later steps need both.
 7. `openeng types list --project <project id>` to see the project's published types, each with its
@@ -143,12 +183,12 @@ For a generic open-cycle gas turbine demonstration project, run `openeng demo se
 ### Which organisation you are in
 
 - `openeng org current` prints the organisation your session is attached to, or none.
-  `openeng org detach` removes the attachment, and the commands refuse again until you attach.
+  `openeng org detach` removes the attachment; commands that need an organisation refuse until you attach again.
 - The CLI passes no scope for `openeng login`, `openeng logout`, `openeng whoami`, `openeng help`, `openeng skill`,
   `openeng org list`, `openeng org attach <id>`, `openeng org create --name <name>`, `openeng org current`,
-  `openeng org detach`, and `openeng admin-sdk createOrganisation`. Other commands print their scope on
+  `openeng org detach`, `openeng admin-sdk createOrganisation`, `openeng session status`, and `openeng session human`. Other commands that need an organisation print their scope on
   standard error when the platform answers them, as
-  `org: <name> (<id>)`, then `· project: <id>` and `· ref: <ref>` when you named them. Read it
+  `org: <name> (<id>)`, then `· project: <id>` and `· ref: <ref>` when named in `--selector`. 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 normally gains a `scope` key.
@@ -166,14 +206,16 @@ For a generic open-cycle gas turbine demonstration project, run `openeng demo se
 Edit a file, not the published types directly. The change is a draft that is checked, reviewed and
 then accepted.
 
-If `openeng types list` says `no published types`, start the type file from the `changes` map in the
-example input printed by `openeng help ontology-sdk reviseChangeSet`. Read `openeng help types draft revise`
-to understand each part, then design the model with the person before you draft it.
+If `openeng types list` says `no published types`, use the example type documents in
+`openeng skill conventions` to start the type file. Put each type document under its type key, because
+`draft.json` is a map keyed by type key and a bare document is refused. Read `openeng help types draft revise` to
+understand each part, then design the model with the person before you draft it.
 
 1. If the project has published types, run `openeng types export --project <project id> > draft.json`;
    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`.
+   with revise. If it has no published types, create `draft.json` from an example type document in
+   `openeng skill conventions`, putting the type document under its type key: the headed examples there
+   are bare documents, and one pasted as it stands is refused.
    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
@@ -250,12 +292,52 @@ project's `main`. Use a branch and review when a rule protects the branch or the
 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 full branch name after the slash.
+   names the branch by its `name` alone, the part of the full branch name after the slash. The input
+   takes an optional `target`: `main`, a writable organisation ref or a project branch; omission
+   targets `main`. An apply run submits only its approved plan's ref.
+7. A person approves with `openeng branches-sdk approveProposal`, sending `proposalId` and, as
+   `headHash`, the `atHash` of the `readBranchDiff` they read. An approval from a CLI session in agent mode is confirmed
+   on the web. A moved head requires reading and reviewing again. An agent proposes and never approves.
+
+### Draft and comment routes
+
+The Objects SDK transport also exposes `acquireDraft`, `saveDraft`, `promoteDraft`, `releaseDraft`,
+`discardDraft`, `readDraftLock` and `breakDraftLock`. Read each request with
+`openeng help objects-sdk <method>`. Draft methods take the selected project and ref plus an
+`objectId`; `saveDraft` also takes the `draftHash` last read, `blocks` keyed by identifiers the
+draft already holds, and `added`, a list of new blocks without identifiers; it answers the
+identifiers the server minted for them in `minted`.
+`openeng objects-sdk acquireDraft` starts a draft of the object's body and answers its blocks and
+`draftHash`; `openeng objects-sdk promoteDraft` publishes the draft as the body with the
+`draftHash` last read. If the body already equals the draft, promotion makes no commit; `body-changed` means it moved since the draft was acquired. Each takes `--selector` and `--input` as JSON, as the other routes here do. A save renews
+the five-minute lock. Release only releases an
+unchanged draft; discard removes the holder's draft, while breaking a lock leaves its draft text
+in place and is a project-administrator action. `readDraftLock` reports the holder and expiry or
+that no lock is live, never the draft contents.
+
+A draft write blocked by a rule answers `protected`, with the same optional
+`protection: { ref, patterns }` as a property save. Only readable patterns appear. Make the change
+on another branch and merge it; a caller without write access receives the ordinary denial.
+
+Object history (`openeng objects-sdk readHistory`) and a branch comparison
+(`openeng branches-sdk readBranchDiff`) carry a `bodyChanges` list on each version or changed object:
+one entry per body block that differs, `{ blockId, kind, before, after }`, with `kind` one of `added`,
+`removed`, `changed` or `moved`, and only the block text. Read it to describe a body change; the
+property fields do not show one.
+
+`breakDraftLock` and `restoreDraft` require a person token and use `objects.draftAdmin`. No client
+scope or run client holds this capability. `restoreDraft` takes `trashId` and `newRefName` and
+restores a draft from the trash of a disposed branch onto a new ref.
+
+`setCommentResolved` takes `commentId` and `resolved` and is for resolving or reopening a comment.
+`addComment` takes the ordinary comment fields and an optional anchor naming the quoted block and
+span. It admits people and hosted apps. Resolving a comment is a person action. The route's refusal is authoritative for required capability
+and admitted caller kinds.
 
 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
+A refusal may name the field it concerns, and `invalid-request` lists the kinds where the request schema allows it. Run
 `openeng help <module> <method>` again and compare.
 
 ### Read relationships back after a write
@@ -274,17 +356,29 @@ several objects; read its help before supplying input.
 ### 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.
+`openeng help branches-sdk readBranchDiff` for a proposal's comparison, at the branch's current head
+while the proposal is pending, with `atHash` naming that head.
 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,
+`edges`. Live diffs return `cursor`; proposal diffs return `continuation`. One page holds at most 200 changes total; follow the returned value 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.
+grant access to its title, type or properties. Any cursor that is not a current page boundary is refused; start the comparison again without it.
 
 ## Project branch rules
 
-`openeng branches-sdk disposeRef` is a writer's cleanup of a branch with no pending proposal.
+`openeng branches-sdk disposeRef` lets a branch writer dispose when no pending proposal exists
+and no matching rule restricts deletions, or when no rule matches even with a pending proposal.
+Otherwise the caller must be on every matching rule's bypass list. A bypass member may dispose
+with or without a proposal, including under restricted deletions, with write access to all affected
+projects. Success discards the pending proposal after the engine disposal succeeds.
+
+Merge and disposal admit people, services and client apps. Agent runs and hosted apps are refused
+`token-kind-not-admitted`. With no rule matching the merge target, a writer of all affected projects
+can merge, including a Contributor. A client of an Owner gets no role bypass from that person's role;
+it needs an explicit client bypass entry.
+
+When drafts block disposal it answers `ref-has-drafts` and lists readable drafts in writable
+projects, by object and holder. Add `"deleteDrafts":true` to the input to consent: the drafts you may write move to the draft
+trash, where a person who saved one can restore it.
 
 ### Resolve a merge conflict
 
@@ -294,26 +388,43 @@ When merge answers `merge-conflict`, read the conflicts with
 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
+whose target was not `main`. A conflicting object also lists `blocks`: the body blocks both sides changed
+differently, each `{ blockId, base, ours, theirs }` with the text of the common version, of `main` and of
+the source branch (null where a side has no such block). 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 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
-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 that branch's rows.
+A rule has extent `ref` for every row on a matching ref or `rows` for its project's rows.
+Project `ref` rules are `<project>/` and a glob; `rows` may also name `main`. In a glob `*` stops at
+`/`, `**` is any characters, `/` included, `?` is one character other than `/`, and `[]` is a set
+with no negation: `^` and `!` are refused. `<project>/**/x` does not match `<project>/x`. A glob is at most 255 characters.
+`merge-only` requires merges, `locked-rows-only` binds merge-only row locks, and `open` allows
+updates. Several matching rules all apply unless their bypass lists admit the caller.
+
+Rule management is the person's workflow. They need `administer projects` on the owner.
+Never add, update or remove rules on their behalf, including to get past a refusal.
+
+1. The person runs `openeng rules add --project <id> --extent rows --pattern main` to protect
+   their project's trunk rows. The answer includes the identifier and full settings.
+2. `openeng rules list --project <id>` reads visible rules and their settings; it needs `read`.
+3. `openeng rules update --project <id> --rule-id <id> [settings]` changes settings atomically.
+   Every update requires confirmation in an agent-mode session, stronger and weaker alike.
+4. `openeng rules remove --project <id> --rule-id <id>` removes that rule. An absent or other
+   owner's identifier answers `not-found`. Each change is audited and affects the next request.
+
+Add and update accept `--consequence <open|merge-only|locked-rows-only>`,
+`--require-proposal <true|false>`, `--required-approvals <0..10>`,
+`--approver-min-role <contributor|maintainer|owner|null>`, `--restrict-deletions <true|false>`,
+`--approvers '<JSON person-id array>'` and `--bypass '<JSON member array>'`.
+Bypass members are `{"kind":"role","roleKey":"owner"}`, `{"kind":"person","personId":"<id>"}`,
+`{"kind":"service","serviceIdentityId":"<id>"}` or `{"kind":"client","clientId":"<id>"}`.
+A supplied array replaces the list; `[]` clears it. Omitted settings on update keep their values.
+On add, defaults are merge-only, a required proposal, one approval, minimum Maintainer,
+no named approvers and Owner/Maintainer bypass. Deletion restriction defaults to true for project
+`ref` rules only; only those rules may enable it. Positive approvals need a proposal and either
+a minimum role or a named approver. The server validates named members without revealing identities
+outside the home. Refusals are `invalid-rule-pattern`, `invalid-rule-setting` and `unknown-rule-member`.
+A repeated rule add returns the existing rule without changing it. Changing a rule’s consequence
+to one another rule on that pattern already has is refused `duplicate-rule`; the rule stays unchanged.
 
 ## Organisation rules, branches and baselines, locks and agent ceilings
 
@@ -324,17 +435,17 @@ 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`.
+  `openeng rules add --organisation --extent ref --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`.
+  Adding or removing needs `administer projects` in the attached organisation; listing needs read on a project in the organisation.
 - `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;
-  listing needs `read`.
+  listing needs read on a project in the organisation.
 - 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
@@ -354,9 +465,15 @@ When a command returns one of these rules, follow its action and do not repeat t
   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.
+- `proposal-required`: submit the source branch for review against the merge target.
+- `approvals-required`: read `approvals.counted` and `approvals.required` for the subject project.
+  Ask eligible reviewers to approve the source's current head; stale approvals do not count.
+- `deletion-restricted`: ask a member of every matching rule's bypass list to dispose of the branch.
+- `bypass-required`: a pending proposal and matching rules require bypass to dispose. Ask a member
+  of every matching rule's bypass list, or refuse the proposal first; deletion restrictions still apply.
 - `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.
+  A successful merge closes only the source ref's pending proposal for that target.
 - `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
@@ -367,7 +484,7 @@ When a command returns one of these rules, follow its action and do not repeat t
   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 branch or baseline. Choose a writable branch.
+- `read-only-ref`: this caller cannot write or merge into this ref; it does not mean nobody can. Choose a ref in your writable scope.
 
 ## 4. Link to a page
 
@@ -403,7 +520,8 @@ using the type key from the object read. Explore also reads its selected object
 ### 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
+2. Query the objects you need with `openeng objects-sdk queryObjects --selector <json> --input <json> --json`; read `openeng help objects-sdk queryObjects`
+   for the input. 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.
    To select several object types in one paged query, use `typeKey: null` with a top-level `{ "kind": "type", "op": "in", "values": ["part", "system"] }` filter. The list holds 1 to 100 published type keys; combine it with a text filter to search those types. Follow the returned continuation without changing the selection.
@@ -417,7 +535,7 @@ using the type key from the object read. Explore also reads its selected object
 
 Every kind with `--ref`, including `ontology` and `change-set`, takes `main` or
 `<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;
+refused by `openeng link`. Before printing, the command reads a `--ref` other than `main`, and the page's own subject where the kind has one;
 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`.
@@ -465,7 +583,7 @@ The order, from no connection to a first imported document:
 
 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
+records. The importer counts an object as `overwritten` when a property the import changes was last modified by someone else; other changes count as `updated`. 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:
@@ -483,8 +601,7 @@ Refusals you will meet, with what each means and what to do:
   permission.
 - `credential-not-valid`: Onshape did not accept the credential, and nothing was stored. The person
   checks the keys and runs `set-credential` again.
-- `connection-exists`: the organisation already has a live connection to this account on this
-  stack. List the connections with `openeng admin-sdk listConnections` rather than creating another.
+- `connection-exists`: the organisation already has a live connection for this stack and company. List the connections with `openeng admin-sdk listConnections` rather than creating another.
 - `connector-template-missing`: this deployment holds no type template for the connector's system.
   No remedy is in your reach; tell the person.
 - `change-set-open`: the organisation already has an open change set, so drafting the types
@@ -506,11 +623,10 @@ equal or higher project role, or the inviter lost the required standing. Sign-in
 
 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.
+- `owner`: administer members, projects and service identities; write refs and read.
+- `maintainer`: write refs and read.
+- `contributor`: write refs and read, including direct merges where no rule matches the target.
+  Matching rules and bypass entries decide how each ref may change.
 - `reader`: read.
 
 A membership can be scoped to an organisation or a project. An organisation role supplies its

package/skill/playbooks/engineering-requirements.md

@@ -116,6 +116,4 @@ Choose B for a team whose engineers read SysML or whose model will meet a SysML
 
 ## Not on the platform today
 
-- **Suspect links**: DOORS and Jama mark a link when its upstream end changes. Nothing does this yet; a
-  team can review changes through a proposal's diff and an object's history.
 - **Coverage percentages** across levels: a count per question is a query; a roll-up is not built.

package/skill/playbooks/product-lifecycle.md

@@ -110,6 +110,6 @@ reached through a part or a plant.
 
 - **Effectivity** (a line valid from a date or a serial number): a date property is possible; nothing filters
   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.
+- **Mass change** of many lines is not built. A **cost roll-up** across a structure is an Aggregate part
+  with a weighted sum over a repeat reach, which needs a numeric property on the edge, within its depth and type bounds.
 - **CAD geometry**: an object view can show an STL attachment (`STLViewer`); there is no live CAD link.