@openengio/cli 0.23.3 → 0.24.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openengio/cli",
-  "version": "0.23.3",
+  "version": "0.24.4",
   "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/demo/SKILL.md

@@ -1,112 +1,139 @@
 ---
 name: demo
-description: Use when a person new to OpenEngineering wants a hands-on tour, or has just signed in and has no task of their own yet. Builds a small example with them on a familiar workflow (requirements, product lifecycle, project tracking) or their own, optionally connects Onshape or a small local OAuth app, alternating your configuration with links and actions they take in the app.
+description: Use when a person new to OpenEngineering wants a hands-on tour, or has just signed in and has no task of their own yet. Offers the example plant seed, a free-form capability tour around their workflow, or a task they name.
 ---
 
 # Give a person a tour of OpenEngineering
 
-The aim is one outcome the person cares about, experienced in the app with their own hands. Covering
-features is not the aim: a tour is done when they have seen that outcome and know how to carry on.
-Ask at most two questions at a time. Do not turn routine commands into permission questions.
-
-## 1. Offer the tour once
-
-After sign-in, when the person has no task of their own, offer once: "I can set up a small example
-around your work, then we can explore it together in the app." They may accept, decline, or go to
-their own task. An accepted tour covers work inside a demo organisation. It does not cover inviting
-anyone, connecting an external account (Onshape), registering an app, or touching an existing
-organisation's data: ask before each of those.
-
-## 2. Learn what matters to them
-
-Ask about their work first: "What do you design or manage, and where does the work get hard today?"
-
-Then anchor the tour on a workflow they will recognise, and offer two or three that fit what they said,
-each with one line on why:
-- a requirements platform in the style of Jama or DOORS: requirements, their decomposition, and the
-  verification that proves them (`openeng skill playbook engineering-requirements`);
-- a product lifecycle platform in the style of Arena or Windchill: parts, revisions, the bill of
-  materials, and changes that are requested, approved and released (`openeng skill playbook
-  product-lifecycle`);
-- a project and work tracker (`openeng skill playbook project-management`).
-
-Say plainly that they can go smaller, or ask for something entirely their own, and follow that when
-they do. Then refine the chosen one in their terms: who is involved, what starts the work, what they
-need to see, and what a good result looks like. Use their names for things inside the familiar shape.
-If they would rather look around a fuller example before building their own, build a slightly larger
-one from the chosen playbook first, and say which data is invented.
-
-## 3. Agree a small story
-
-Propose a short flow with a visible result, for example: "We make the controller and its thermal
-requirement, record a failed test, then propose a fix on a branch for review." Keep it to two or three
-types, a handful of objects, one relationship that shows structure, and one change that shows a
-branch and a review. Create a new organisation for the tour (`openeng org create`) unless they ask to
-use an existing one. Say which data is invented.
-
-Design the types with `openeng skill new-use-case`, and keep its stop points. Read `openeng skill
-conventions` before you choose relationships: structure (one parent) is not navigation (declared
-relationships), and the difference shows in their tree.
-
-## 4. Build in small steps, each with something to see
-
-For each step:
-1. Say in their words what you will do next and why.
-2. Make the smallest useful change with `openeng`. Use one atomic batch for related writes.
-3. Read the result back in the organisation, project and ref you meant. Validate before you publish.
-   Keep apart: accepted, validated, published, and seen rendered in the app.
-4. Give a link from `openeng link` at once. Say what they should see there, and any limit of that page.
-5. Invite one action that matters: edit a value, comment, subscribe, compare a branch with main, or
-   accept a proposal if their role allows it. Say what to do and what you will check afterwards.
-6. Check the result with a read, not with their click. Then use their reaction to choose the next step.
-
-Leave a state on screen until they have had a chance to see it. If they say a step is dull or already
-clear, move on.
-
-## 5. Make it usable in the app
-
-Choose readable names and a distinct icon per type from the supported set. Build object views and
-apps with `openeng skill build-ui` and the component catalogue it names; do not guess components or
-bindings. A view is worth building when it serves the story; most tours need none.
-
-## 6. Connect their tools, when it serves the story
-
-Two extensions show that the platform is open. Offer each one when it fits; ask before starting either.
-
-**Onshape, if they use it.** Ask whether they have an Onshape account and which document, team or
-company they would like to mirror. Create a connector with `openeng connector create`. The person enters
-their Onshape key pair themselves at the prompt of `openeng connector set-credential`: never ask for a key
-in the conversation, never accept one pasted there, and never type one. Agree the import scope before
-`openeng connector run`, then read `openeng connector runs` and show what arrived. Mirrored objects are owned by
-the connector and are not edited here; trace them into the story with links. If a run imports nothing,
-say what was looked for and ask them to check the scope.
-
-**A small app of their own, using OAuth.** Offer to build a tiny local web app that signs in to
-OpenEngineering and reads their data, for example a dashboard of failed tests. Register it as a public
-client of their organisation with `openeng admin-sdk registerClient` (read `openeng help admin-sdk
-registerClient` first), using a `http://127.0.0.1:<port>/callback` redirect. The app uses the
-authorization-code flow with PKCE against the issuer the help names, so the person signs in and
-consents on OpenEngineering's own page; the app never sees their password. Keep it read-only unless
-they ask for more, run it on their machine, and give them the local link. Read the platform's published
-client contract before you write the app; do not guess the request shape.
-
-## 7. When something goes wrong
-
-Read the refusal and fix the input. When the help does not say enough, make a minimal example, record
-the exact command and answer, and ask the person; do not guess in a loop. When an outcome is unknown,
-read the state before you write again. Never claim to have contacted the OpenEngineering team.
-
-## 8. End on the outcome
-
-Recap what they saw, with the links to come back to, and one or two next steps for their own work. Say
-what remains in the demo organisation: types, objects, branches, proposals and drafts, and any
-connector or registered client, which they can revoke (`openeng connector revoke`). Agree before
-deleting anything. Do not imply that a short tour proves every feature or permission.
+## 1. Offer three paths
+
+After sign-in, when the person has no task of their own, offer once:
+
+- **Seed demo**: create a project, run `openeng demo seed --project <id>`, then follow the
+  [Quickstart](https://docs.openeng.io/get-started/quickstart/) together.
+- **Free-form tour** (the main path): build a small example around their work and explore its
+  capabilities together in the app.
+- **Something else**: follow the task the person names. They may decline the tour.
+
+Before the tour starts, load every capability below into your own native task or plan tool,
+whatever your harness provides: one item per capability, its Checklist line as the title and its
+Features shown line as the detail. Show the person the list and say they may skip any item.
+Run one item at a time. Tick it only when the person has seen its result in the app and you have
+checked that result with a read. Drop a declined item from the remaining work and mark it skipped,
+never done. If you have no task or plan tool, write the same checklist in the conversation and
+show each item's state again whenever it changes.
+
+Offer C1, C3 and C5 first, then the others by the person's interest. Use the chosen playbook or
+the example plant for the stories. All capabilities below are shipped. Leave per-field conflicts
+out of every story.
+
+- [ ] C1. Describe your workflow, and use the tool five minutes later
+  Checklist: Build a working tool from a description of the person's workflow.
+  Features shown: Organisations and projects; Familiar workflow playbooks; Types and the ontology;
+  Ontology agent; Rail groups and type icons; Objects; Table of one type; The object card.
+
+- [ ] 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.
+
+- [ ] C3. Follow one question across every tool
+  Checklist: Answer one question that crosses requirements, parts and tests.
+  Features shown: Relationships; Structure tree; Graph and Explore; Paths between two objects;
+  Counts and rollups; The object card.
+
+- [ ] C4. Every record carries its own story
+  Checklist: Show who changed a record, why, and what a delete would take with it.
+  Features shown: The object card; Object history with per-field attribution; Comments and
+  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.
+  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
+  locks; Type rules.
+
+- [ ] C7. Your CAD system stays the source of truth
+  Checklist: Mirror Onshape parts and link a requirement to one of them.
+  Features shown: Types and the ontology; Relationships; Service identities; Onshape mirror; Type
+  rules.
+
+- [ ] C8. Build on it: a screen for each team, and your own app
+  Checklist: Build a team page from configuration, then a small OAuth app on the same data.
+  Features shown: Counts and rollups; Object views and App views; Apps with several pages; Roles
+  and membership; OAuth apps.
+
+## 2. Agree the workflow and keep its stop points
+
+Ask what the person designs or manages and where the work gets hard. Offer a fitting playbook:
+`openeng skill playbook engineering-requirements`, `product-lifecycle` or `project-management`,
+or use their own vocabulary. Agree a small story with a visible result. Create a demo organisation
+with `openeng org create` unless asked to use an existing one; say which data is invented.
+Ask before touching existing data, inviting anyone, connecting Onshape or registering an app.
+Ask at most two questions at a time; do not turn routine commands into permission questions.
+
+Whenever the tour designs types, read `openeng skill new-use-case` and follow every stop point
+in order: show the person the work and wait for agreement at each one. Do not skip a stop point
+to speed up the tour. Read `openeng skill conventions` before choosing relationships, properties,
+icons and rail groups. Draft nothing before new-use-case's drafting step; accept a change set
+only on the person's word naming it.
+
+## 3. Show one story at a time
+
+Use `openeng help <module> <route>` for request shapes. Each story answers a question the person
+cares about; do not explain a primitive in isolation.
+
+- C1: agree and publish types from the chosen playbook, write believable data with
+  `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
+  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
+  "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
+  and relationship, and keep a baseline with `org-refs create --read-only`. Show an immutable
+  test result refusing changes on a branch too.
+- C7: for an Onshape user, agree the import scope; use `connector create`, `set-credential`,
+  `draft-types`, publish agreed types, `run` and `runs`. Link a requirement to a mirrored part,
+  show it cannot be edited here, and show a repeat import preserves the requirement.
+- C8: read `openeng skill build-ui` and its component catalogue, publish a team page through
+  the App draft workflow, and show `link app`. Offer a small local OAuth app reading the same
+  data; show consent and how to disconnect it.
+
+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.
+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.
+
+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.
+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.
+
+## 4. Handle refusals and finish
+
+Read a refusal and fix the input. If help is insufficient, record one minimal command and answer
+and ask the person; do not guess in a loop. For an unknown outcome, read state before writing again.
+Never claim to have contacted the OpenEngineering team.
+
+Recap completed and skipped tasks, return links and next steps. Say what remains: types, objects,
+branches, proposals, drafts and any connector or registered client, and how to revoke the connector
+(`openeng connector revoke`) or disconnect the app. Agree before deleting anything.
+Do not imply a short tour proves every feature or permission.
 
 ## Dogfood mode (only when the person asks for feedback capture)
 
-The OpenEngineering team uses this mode to test the product. Record each friction as it happens, with
-the command, the answer and your confidence, classed as: your own omission, a help gap, an observed
-defect, a user-reported issue, a feature request, or an open question. Merge later corrections into
-earlier entries. At the end, hand over one file: the findings grouped, with evidence, a proposed
-priority and the open questions, kept apart from the recap. Never send feedback anywhere yourself.
+Record friction as it happens: command, answer, confidence, and whether it is your omission, a help
+gap, an observed defect, a user-reported issue, a feature request or an open question. Merge later
+corrections into earlier entries. Hand over one file with evidence, proposed priorities and open
+questions, separate from the recap. Never send feedback anywhere yourself.

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: