@openengio/cli 0.0.0-stage → 0.24.3

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

@@ -0,0 +1,136 @@
+---
+name: new-use-case
+description: Use when a person wants types for a use case their organisation's catalogue does not yet model, from the platform's own agent or from your own agent using `openeng`.
+---
+
+# 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
+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.
+
+## The tools, by step
+
+| step | in the platform's agent | with `openeng` |
+|---|---|---|
+| read the catalogue | `read_catalogue` | `openeng types list --project <id>`; `openeng types export --project <id>` for every type's whole document |
+| read one type | `describe_type` | the type's key in `openeng types export --project <id>` |
+| read the change set | `read_change_set` | `openeng types draft current`; `openeng types draft show --change-set <id> --project <id>` |
+| read sample objects | `sample_objects` | `openeng objects-sdk queryObjects` |
+| 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 |
+| 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 |
+
+## 1. Understand the use case
+
+Ask what the team does, who uses the model, and which questions it must answer. Write the questions
+down in the team's own words, for example "which requirements have no verification".
+
+- [ ] The use case in one or two sentences.
+- [ ] Three to seven questions the model must answer.
+
+Stop: the person agrees the use case and the questions.
+
+## 1b. Orient in the existing catalogue
+
+Read the whole published catalogue and every type that might touch the use case. Other use cases built
+it, and this one should join it. An organisation with no published types starts from the examples in
+`openeng skill conventions`; there is nothing to export.
+
+- [ ] Each concept mapped to an existing type, a close type, or nothing yet.
+- [ ] For each close type: reuse with an extension (an optional property in a new version), or a new
+      type, with the cost of each and a recommendation.
+- [ ] The existing types the new ones must connect to, and by which edge.
+- [ ] The catalogue's naming, icons and rail groups, to follow.
+
+Stop: show the person the map, and agree what is reused, what is extended and what is new.
+
+## 2. Survey the domain
+
+Read the domain playbook with `openeng skill playbook <name>`, when there is one.
+`openeng help skill` lists the available playbooks. Then check it against the
+established tools and standards the team names, and where sources disagree, say what each choice
+costs.
+
+- [ ] The concepts most sources share.
+- [ ] Where sources disagree, and the cost of each choice.
+- [ ] Any standard the team follows, by name.
+
+Stop: a summary of no more than ten lines, and ask what the team does differently.
+
+## 3. Propose the core
+
+Propose five to ten object types and the edges between them. Say what one object of each type is, in
+one sentence, and what fact each edge records. Reuse and extend what step 1b agreed. Where the shape is
+a real choice, offer one or two alternatives with their cost, and recommend one.
+
+- [ ] Each type is a kind of thing, not a document or a state.
+- [ ] Each relationship is an edge; no property holds another object's identifier.
+- [ ] One edge type per meaning.
+- [ ] No new type is a near-copy of an existing one.
+- [ ] Every question from step 1 is answered by following edges and reading properties.
+
+Stop: the person chooses the core.
+
+## 4. Decide the edges and the trees
+
+For each edge type, decide what `openeng skill conventions` lists: kind, source and target, which end is upstream,
+labels for both ends, the parent end, and the read rule. Then decide each object type's ranked
+relationships and any named views.
+
+- [ ] One direction convention for the whole model, chosen with the person and written in the types'
+      descriptions: "flow of work" or "points at what is proved" (`openeng skill conventions`, section 3). Every
+      edge follows it; a model never mixes the two.
+- [ ] Every structural edge has a parent end.
+- [ ] If a type declares any named view, the tree the person uses most is declared as a view too, and
+      first, because declaring views replaces the relationship picker.
+
+Stop: show the person the tree each type will produce and the direction it gives the graph view, drawn as text.
+
+## 5. Decide properties, titles, icons and the rail
+
+- [ ] Scalars rather than arrays.
+- [ ] Few required keys: a later version cannot add one.
+- [ ] State as an enumeration whose members the team will keep: a member cannot be removed.
+- [ ] `presentationBindings.title`, a required string property that names the object.
+- [ ] `presentationBindings.typeIcon`, a Material Symbols glyph name.
+- [ ] The rail: the organisation's groups, and each type's group and order; or no rail entry for a type
+      that is the detail of another, not a destination.
+
+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.
+
+- [ ] For each view: its kind, its root component, and the properties and derived values it shows.
+
+## 7. Draft small and validate
+
+Propose a plan for the change set. Once it is approved, open the change set and save the core: the
+object types and the edge types between them, nothing more. Then validate until it answers no
+violations. Where the tool exists, try one realistic sample of each type, and one that lacks a required
+key.
+
+## 8. Iterate
+
+Add the rest in small saves, validating after each. Each save holds the whole set of changed types.
+When a save is refused as stale, read the change set again and build on it.
+
+Stop: walk the person through the draft, type by type, and take their changes.
+
+## 9. Hand over
+
+Tell the person, in a few lines: the types and edges drafted, the tree and the direction each produces,
+the rail, any choice you made that they did not ask for, and what a later version can and cannot
+change. Show the change set's diff. The person publishes; with `openeng`, accept only on their word naming
+this change set.

package/skill/openeng/SKILL.md

@@ -0,0 +1,340 @@
+---
+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
+  and submitting branches for review.
+---
+
+# Working with the platform through `openeng`
+
+`openeng` is the platform's command line. Install the public npm package:
+
+```
+npm install -g @openengio/cli
+```
+
+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.
+
+## 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`.
+
+- Designing a new use case: `openeng skill new-use-case`.
+- Building an object drawer or App view: `openeng skill build-ui`.
+- Field meanings, edge direction, trees and type versions: `openeng skill conventions`.
+- A domain model: `openeng skill playbook engineering-requirements`,
+  `openeng skill playbook product-lifecycle`, or `openeng skill playbook project-management`.
+
+## 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
+  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.
+- `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.
+  `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
+  `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
+  none. Leave it out unless you have a reason to send your own.
+- Generated commands take `--selector <json>` for what they act on and `--input <json>`,
+  `--input -` or `--input-file <path>` for what they send. Read the ids you need from `--json`
+  output and never invent one.
+
+## 1. Sign in and orient
+
+1. `openeng help` to see what exists.
+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
+   `openeng org create --name <name>`, then attach to the organisation it created.
+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
+   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
+   published version.
+
+For a generic open-cycle gas turbine demonstration project, run `openeng demo seed --project <project id> [--size standard|full]`.
+
+### 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.
+- 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
+  standard error when the platform answers them, as
+  `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 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
+  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,
+  `openeng org list` and `openeng org attach <id>`.
+
+## 2. Define or change object types
+
+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.
+
+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`.
+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.
+3. `openeng types draft open` opens a change set on your organisation's namespace. It prints the change
+   set id and a revision. If one is already open, `openeng types draft current` shows it.
+4. `openeng types draft revise --change-set <id> --revision <revision> --from draft.json` sends your
+   file. It prints the new revision. Use the newest revision in every later step.
+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.
+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`.
+
+To abandon a draft, `openeng types draft discard --change-set <id>`.
+
+`presentationBindings.typeIcon` is a Material Symbols Rounded name from the installed
+`@material-symbols/font-400` set, such as `memory` or `developer_board`, not an arbitrary label
+(for example, `cpu` is invalid). `openeng types icons <text>` lists valid names and needs no sign-in; the full list is at https://docs.openeng.io/reference/icons/.
+Publication refuses unknown or empty names. Existing unknown icons show an empty box and
+must be corrected before publishing that type again.
+
+An object type's `subscriptionRoles` field declares which roles it admits: owner, approver or watcher.
+Owner is limited to one; approver and watcher may have optional maxima. Without the field, only
+watchers are admitted; the publication validator decides whether a declaration is valid.
+
+## 3. Write data
+
+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. 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 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. 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.
+
+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
+or an address yourself. `openeng link <kind> --project <id> --ref <ref>` takes `explore`, `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, 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
+table or a tree in ASCII, or as a Mermaid diagram when the person's tool renders it. Draw only
+what the output holds.
+
+## 6. Connect an Onshape account
+
+The connector commands import an Onshape account's documents into a mirror project. Each
+command's help, such as `openeng help connector create` or `openeng help connector run`, names the
+capability it needs. Through the CLI you act with the signed-in person's user token, so you can do
+what that person may and nothing more.
+
+Before you create a connection, tell the person this, because create prints it on standard error
+and the person must know it: "Everyone with access to this project sees every document this
+Onshape account can see."
+
+The order, from no connection to a first imported document:
+
+1. `openeng connector create --system onshape --stack <stack> --name <text> [--company <id>]
+   [--team <id> | --owner <id>] [--label <text>]`. `--stack` is the Onshape stack label, as in
+   `cad`. At most one of `--team` and `--owner`. With neither, `--company` is required and must be the
+   company's own identifier, never a user's. It prints the connection identifier and the change
+   set it drafted for the connector's types, or the rule that stopped the drafting.
+2. `set-credential <connection>`: the command reads the access key and the secret key at a terminal
+   prompt only, with no flag and no environment variable. Do not ask for the Onshape keys, do not
+   accept them in the conversation, and do not type them on the person's behalf. Ask the person to
+   run `openeng connector set-credential <connection>` at their own terminal. Setting it again replaces
+   the stored credential. The person can cancel at either prompt with Control-C; the command then
+   says no keys were set.
+3. A person who holds `administer types` reviews the change set (`openeng types draft show
+   --change-set <id> --project <mirror project id>`) and accepts it (`openeng types draft accept
+   --change-set <id> --revision <token>`). Until then a run refuses with `types-not-approved`.
+   `openeng connector draft-types <connection>` drafts again.
+4. `openeng connector run <connection>` prints the run identifier. `openeng connector runs <connection>`
+   lists the runs newest first with state, counts and failure kind; read it until the state is
+   `succeeded` or `failed`.
+5. `openeng connector revoke <connection>` ends the connection.
+
+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:
+
+- `types-not-approved`: the connector's types wait for approval by a person who holds the
+  permission to administer types. Ask such a person to review and accept the connector's change
+  set; read it with `openeng types draft current`.
+- `import-running`: a run of this connection is already running. List the connection's runs with
+  `openeng connector runs <connection>`.
+- `connection-revoked`: the connection is revoked, so it takes no further change or run. A new
+  connection makes a new mirror project.
+- `not-permitted`: the operation was refused. What the request names may not exist, or the person
+  may not have permission for it; the answer is the same either way. Check that the request names
+  something the person can reach; if it does, the person must ask an administrator for the
+  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.
+- `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
+  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.

package/skill/playbooks/engineering-requirements.md

@@ -0,0 +1,121 @@
+# Playbook: an engineering requirements platform
+
+For a team that wants what DOORS or Jama gives it: requirements, their decomposition, how designs meet
+them, how they are verified, and the risks against them, all traced. Read `openeng skill conventions` first.
+
+## Reference products, and what sets them apart
+
+| product | organised around | what that means for a model |
+|---|---|---|
+| IBM DOORS (classic) and DOORS Next | **documents**: a module is a specification, an ordered outline of headings and "shall" statements; links run between objects in different modules | a document type and section headings, with order, become types of their own |
+| Jama Connect | **items** in a project tree organised by components (a system or subsystem), sets and folders; typed relationships with rules from an upstream item type to a downstream one; coverage from those rules | the system tree is the backbone and every item hangs off a system; a document is a view or an export, not a type |
+| SysML tools | **model elements** with «satisfy», «verify», «deriveReqt» relationships that point at the requirement | the same item model, with arrows drawn at what is proved |
+
+On this platform the item-centric shape fits best: every item is an object, every relationship an edge,
+and a specification document is a view of a system's subtree. Choose the document-centric shape only
+when the team's deliverable is the document itself and its order matters more than its traces.
+
+## The decisions that shape the model
+
+1. **Organised around systems or around documents.** Recommend systems. A document-centric model needs a
+   `document` and a `section` type, an `order` property, and one structural edge per pair of parent and
+   child types, because each edge end takes one type.
+2. **One requirement type, or one per level** (stakeholder need, system, subsystem). Recommend one type
+   whose level comes from where it sits in the system tree: one decomposition edge then serves every
+   level. One type per level gives each level its own fields, but every pair of levels needs its own
+   decomposition edge.
+3. **Requirement against specification.** The requirement is the need (what must be true); the
+   specification is the design's answer (a chosen value or standard), joined by a satisfaction edge. The
+   alternative, a specification as a stricter requirement, joins them by decomposition instead.
+4. **What a verification proves.** Recommend requirements only. Jama's design-control practice puts the
+   acceptance criteria in the requirement and links the test to it; the specification is proved through
+   the requirement it satisfies. Proving specifications directly takes a second verification edge.
+5. **How a risk relates.** Recommend the risk upstream of the requirement that mitigates it
+   (`mitigated-by`), as Jama's traceability runs "from risks to mitigation", so "a risk with no
+   mitigation" is a coverage question. The
+   alternative, a risk hanging downstream of the requirement it threatens, keeps the requirement as the
+   anchor.
+6. **The direction convention**, "flow of work" or "points at what is proved" (`openeng skill conventions`,
+   section 3). The two worked models below take one each.
+7. **Identifiers.** The platform keeps no counter, so a human-readable identifier such as `SYS-042` is a
+   string the author or agent sets, by a prefix per system or level.
+
+## Worked model A: flow of work
+
+Every edge's source is its upstream end.
+
+| object type | one object is | title | required |
+|---|---|---|---|
+| `system` | a system, subsystem or component; systems nest | `name` | `identifier`, `name`, `level` |
+| `requirement` | one "shall" statement, owned by one system | `title` | `identifier`, `title`, `statement`, `category`, `status`, `priority` |
+| `specification` | the design's answer to a requirement | `title` | `identifier`, `title`, `statement`, `status` |
+| `verification` | a planned test, analysis, inspection or demonstration | `title` | `identifier`, `title`, `method`, `status` |
+| `verification-result` | one execution of a verification | `identifier` | `identifier`, `outcome`, `runDate` |
+| `risk` | something that could go wrong | `title` | `identifier`, `title`, `severity`, `likelihood`, `status` |
+
+Enumerations: requirement `category` (functional, performance, interface, constraint, safety,
+regulatory), `status` (draft, in-review, approved, released, rejected, deprecated), `priority` (must,
+should, could), `verificationMethod` (test, analysis, inspection, demonstration); verification `status`
+(planned, ready, obsolete); result `outcome` (pass, fail, blocked, inconclusive); risk `severity`
+(negligible to catastrophic), `likelihood` (rare to almost-certain), `status` (open, mitigated, closed).
+Performance requirements carry optional `unit`, `targetValue` and `tolerance`.
+
+| edge type | source to target | kind | parent end | reads from the source / the target |
+|---|---|---|---|---|
+| `contains` | system to system | structural | source | contains / part of |
+| `has-requirement`, `has-specification`, `has-verification`, `has-risk` | system to each | structural | source | has … / … of |
+| `has-result` | verification to verification-result | structural | source | has result / result of |
+| `derives` | parent requirement to child requirement | traceability | source | derives / derived from |
+| `satisfied-by` | requirement to specification | traceability | null | satisfied by / satisfies |
+| `verified-by` | requirement to verification | traceability | null | verified by / verifies |
+| `mitigated-by` | risk to requirement | traceability | null | mitigated by / mitigates |
+
+Every edge reads `both-endpoints`. `requirement` lists `["has-requirement", "derives"]` and declares two
+views, "By system" (`has-requirement`) first and "Decomposition" (`derives`). The rail has one group,
+"Requirements management", in the order system, requirement, specification, verification, result, risk.
+The trace reads left to right: system, requirement, child requirement, specification, verification,
+result.
+
+## Worked model B: points at what is proved
+
+The platform's own agent's teaching example. The arrow points at the requirement.
+
+| edge type | source to target | kind | parent end |
+|---|---|---|---|
+| `contains` | system to system | structural | source |
+| `has-requirement`, `has-specification`, `has-verification`, `has-risk` | system to each | structural | source |
+| `derives` | child requirement to parent requirement | traceability | target |
+| `satisfies` | specification to requirement | traceability | null |
+| `verifies` | verification to requirement | traceability | null |
+| `threatens-requirement` | risk to requirement | traceability | null |
+
+Choose B for a team whose engineers read SysML or whose model will meet a SysML tool.
+
+## Questions the model answers, and how
+
+| question | how |
+|---|---|
+| which requirements have no verification | requirements with no `verified-by` edge (model A: outgoing; model B: no incoming `verifies`) |
+| which risks have no mitigation | risks with no `mitigated-by` edge |
+| what a requirement breaks down into | the "Decomposition" tree, or `derives` from it |
+| how a requirement is proved | the path requirement to verification to result |
+| what a system must do | the "By system" tree under that system |
+
+## Sensible hybrids
+
+- **Document views over the item model**: keep the system-centric types and give a system's subtree a
+  page that reads as a specification, rather than adding document and section types.
+- **Requirements beside a product structure**: where the organisation already has parts (a PLM model),
+  link requirements to the parts that meet them instead of duplicating systems as parts.
+
+## Joining an existing catalogue
+
+- Reuse an existing `system`, `part` or `component` type for the breakdown rather than add a second one.
+- Use the existing model's direction convention, even where this playbook recommends the other.
+- Follow its rail groups, naming and icons; add a "Requirements" group only when none fits.
+
+## 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.