@openengio/cli 0.0.0-stage → 0.23.3

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "@openengio/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.23.3",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "openeng": "bin/public/openeng.js"
+  },
+  "files": [
+    "bin/public/",
+    "skill/",
+    "README.md",
+    "LICENSE",
+    "THIRD-PARTY-NOTICES.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/skill/build-ui/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: build-ui
+description: Use when a person wants an object type's drawer (its object view) or its page (its App view) laid out, with the platform's own view components.
+---
+
+# 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
+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
+set; the host decides which components, props, bounds and bindings your version admits.
+
+Work through the steps in order, and stop where a step says so.
+
+## 1. Know what the view must answer
+
+Ask the person what someone opening this drawer or this page needs to see or find, in their words: "which
+requirements are still in review", "what is this part's target and its tolerance". Three to five questions.
+
+Stop: the person agrees the questions.
+
+## 2. Read the type
+
+Read the type's whole document: its properties and their kinds, its required keys, its enumerations, and its
+current views. A view names properties by key, and only properties the type defines. A derived value reads only
+the type's number and boolean properties.
+
+## 3. Choose the components
+
+For each question, choose the components that answer it. Use the reference for what each takes.
+
+| the view must | object view | App view |
+|---|---|---|
+| show this object's fields | `PropertyList`, `PropertyField`, `Value` | |
+| show a number with its unit, or two side by side | `MetricCard`, `Stat` | `MetricCard` (count), `Stat` |
+| show a state as a coloured label | `Badge` with `tones` | `Badge` |
+| list this object's links | `ConnectionList` | |
+| list the type's objects | | `Query` with `Table` and `Column`, or `List`, or `ObjectTable`, `ObjectList` |
+| let the reader filter | `Search`, `Select`, `Toggle` | `Search`, `Select`, `Toggle` |
+| 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.
+
+## 4. Bind the data
+
+- A page control's `value` binds two-way to page state: `{"$bindState": "/page/<name>"}`.
+- A `Query` names the type that owns the view, its `fields`, a `limit`, and filters whose value is a literal or
+  `{"$state": "/page/<name>"}`; a text filter searches named properties.
+- A `Table`, `Stat` or `List` names the `Query` element by its id in its `query` prop. Beneath a `Table` or a
+  `List`, a child reads the current row with `{"$item": "properties/<key>"}`, where the key is among the Query's
+  `fields`, or `{"$item": "objectId"}` for a `Link`.
+- A `List` also carries `repeat: {"statePath": "/queries/<queryId>/items", "key": "objectId"}`.
+
+## 5. Write, validate and show
+
+Write the whole document, save it as part of the type's next version, and validate. Then show the person the
+layout as an indented outline of element types and labels, and, where the platform's change-set preview is
+offered, ask them to look at it there.
+
+- [ ] Every property key the view names is one the type defines.
+- [ ] Every `$item` key is among its Query's `fields`.
+- [ ] No prop carries scope or styling (see "How this differs from json-render").
+
+Stop: the person agrees the layout before the change set is accepted.
+
+## How this differs from json-render
+
+The platform renders views with json-render, and the public json-render skills (`json-render-core`,
+`json-render-react` on skills.sh) teach features this catalogue refuses. If you know json-render, these are the
+differences:
+
+| json-render teaches | here | why |
+|---|---|---|
+| props naming a project, ref, organisation, namespace, object, type version, URL or path | refused, always | a view never chooses its own scope: the host derives the page's project and ref from its address, so a view cannot read or link outside it |
+| `className`, `style`, `html`, `color` | refused, always | a visual choice is a design-token name, such as a Badge's `tone`, so every view keeps the platform's look and carries no raw HTML |
+| defining your own catalog and components | not possible | a view is display data, not a capability: the web renders only the catalogue's components |
+| fetching data from json-render | not possible | data enters only through a `Query` element, which the host scopes |
+| `on` and actions | admits two checked actions | unchecked built-in state actions stay refused |
+| `$computed` | refused | a closed list of registered functions, such as the signed-in person, is planned, not built |
+| `$cond` / `$then` / `$else`, `visible`, `$template`, `$format` and other directives, `slots`, `$bindItem`, `watch` | refused | no reason is recorded yet; they are under review, and some may be admitted |
+
+Use `$state`, `$bindState`, `$item` and `$index` where the reference marks a prop bindable. When this skill is
+wired in, this table is printed from the catalogue's own list of refusals and their reasons.
+
+## Examples
+
+Both validate against the current catalogue for a `requirement` type with `identifier`, `title`, `statement`,
+`status`, `priority`, `category`, `targetValue`, `tolerance` and `unit`.
+
+An App view, the requirements page: a search box and a status filter over a table.
+
+```json
+{ "root": "body", "elements": {
+  "body": { "type": "AppBody", "props": {}, "children": ["controls", "requirements", "table"] },
+  "controls": { "type": "Stack", "props": { "direction": "row", "gap": "medium" }, "children": ["search", "status"] },
+  "search": { "type": "Search", "props": { "label": "Search", "value": { "$bindState": "/page/term" } }, "children": [] },
+  "status": { "type": "Select", "props": { "label": "Status", "value": { "$bindState": "/page/status" }, "property": "status" }, "children": [] },
+  "requirements": { "type": "Query", "props": { "typeKey": "requirement", "limit": 100,
+    "fields": ["identifier", "title", "status", "priority"],
+    "filters": [{ "kind": "text", "term": { "$state": "/page/term" }, "properties": ["identifier", "title", "statement"] }],
+    "sort": { "kind": "property", "property": "identifier", "direction": "asc" } }, "children": [] },
+  "table": { "type": "Table", "props": { "query": "requirements" }, "children": ["colId", "colTitle", "colStatus"] },
+  "colId": { "type": "Column", "props": { "header": "ID" }, "children": ["idValue"] },
+  "idValue": { "type": "Value", "props": { "value": { "$item": "properties/identifier" } }, "children": [] },
+  "colTitle": { "type": "Column", "props": { "header": "Requirement" }, "children": ["titleLink"] },
+  "titleLink": { "type": "Link", "props": { "object": { "$item": "objectId" }, "label": { "$item": "properties/title" } }, "children": [] },
+  "colStatus": { "type": "Column", "props": { "header": "Status" }, "children": ["statusBadge"] },
+  "statusBadge": { "type": "Badge", "props": { "label": { "$item": "properties/status" },
+    "tones": { "draft": "neutral", "in-review": "info", "approved": "success", "rejected": "danger" } }, "children": [] }
+} }
+```
+
+An object view, the requirement's drawer: the statement first, the acceptance values in a tab.
+
+```json
+{ "root": "body", "elements": {
+  "body": { "type": "ObjectBody", "props": {}, "children": ["header", "tabs", "links"] },
+  "header": { "type": "Stack", "props": { "direction": "row", "gap": "small" }, "children": ["status", "priority"] },
+  "status": { "type": "PropertyField", "props": { "field": "status" }, "children": [] },
+  "priority": { "type": "PropertyField", "props": { "field": "priority" }, "children": [] },
+  "tabs": { "type": "Tabs", "props": {}, "children": ["about", "acceptance"] },
+  "about": { "type": "TabPanel", "props": { "label": "Requirement" }, "children": ["fields"] },
+  "fields": { "type": "PropertyList", "props": { "fields": ["identifier", "title", "statement", "category"] }, "children": [] },
+  "acceptance": { "type": "TabPanel", "props": { "label": "Acceptance" }, "children": ["target"] },
+  "target": { "type": "PropertyList", "props": { "fields": ["targetValue", "tolerance", "unit"] }, "children": [] },
+  "links": { "type": "ConnectionList", "props": {}, "children": [] }
+} }
+```

package/skill/conventions/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: conventions
+description: Read before designing platform types, to understand field meanings, edge direction, trees, views and version constraints.
+---
+
+# Conventions of the type language
+
+This file explains what the fields of a type mean, how the platform draws them, and what can never
+change after a type is published. Field names, kinds and allowed values are in `openeng help`. Read this
+file before you design a type. Each section ends with what to check.
+
+## 1. Things and links
+
+- An **object type** is a kind of thing the team names, tracks and links: a system, a requirement, a
+  part. Do not make a type for a document that lists those things, such as a "system requirements
+  specification" whose text holds the requirements: each requirement would then be a paragraph that
+  nothing can link, count, verify or give a status. Make `requirement` a type, and show the document as
+  a view over the requirement objects. Put state such as status in an enumerated property.
+- An **edge type** is one kind of relationship between two object types. Every relationship is an edge;
+  a property never holds another object's identifier, because nothing checks, follows, protects or
+  counts an identifier in a property.
+- **One edge type per meaning.** Each edge has a label for each end, so one edge reads both ways.
+- **Reuse before you create.** Extend an existing type with an optional property in a new version
+  rather than make a near-copy under a new name.
+
+## 2. The fields of an edge type
+
+| field | means |
+|---|---|
+| `sourceObjectType`, `targetObjectType` | exactly one object type at each end. To link a third type, add another edge type. |
+| `kind` | `structural`: the object's one home. An object has at most one structural parent, and both ends are in one project. `traceability`: every other link, including links across projects. |
+| `sourceLabel`, `targetLabel` | how the edge reads from each end, as a sentence from that side: "verified by" from the source, "verifies" from the target. |
+| `parentEnd` | the end that is the parent in a tree: `source`, `target`, or `null` when the edge never shapes a tree. A structural edge must have one; the write is refused otherwise, and validate does not catch it. A traceability edge may have one, which lets an object sit under several parents. |
+| `subjectEnd` | no effect today. Set it to `"source"`. |
+| `readRule`, `writeRule` | `both-endpoints` unless the person accepts that a reader of one end learns the far end's identity and project (`either-endpoint`). The write rule is `both-endpoints`. |
+
+Check: every structural edge has a `parentEnd`; every label reads as a sentence from its own end.
+
+## 3. Direction
+
+The graph view draws an edge's source before its target: with the default left-to-right layout, the source
+is on the left. Which end is the source is therefore a choice about how the model reads. Two conventions
+are in use, and both are sound:
+
+- **Flow of work.** The source is the upstream end: the thing that comes first in the work. A
+  requirement is the source of its verification (`verified-by`: requirement to verification), a
+  verification the source of its result, a risk the source of the requirement that mitigates it. The
+  graph view reads left to right as the work proceeds, and a change to an object concerns everything to its
+  right. Jama Connect uses this direction ("upstream" and "downstream", with suspect links flowing
+  downstream).
+- **Points at what is proved.** The arrow points at the thing that is satisfied or verified: a
+  verification is the source and the requirement the target (`verifies`: verification to requirement).
+  SysML's «satisfy» and «verify» relationships read this way, so a model meant to meet SysML tools reads
+  naturally in it.
+
+Choose one convention for the whole model with the person, say which in the object types'
+descriptions, and make every edge follow it. A model that mixes them reads backwards in places, and
+because an edge's direction can never change once published (section 7), a mistake costs a new edge type
+and a reconnection of every edge.
+
+`parentEnd` is independent of direction. In "flow of work" a decomposition `derives` (parent requirement
+to child requirement) has its parent at the source; in "points at what is proved" a `derives` drawn from
+child to parent has its parent at the target. Both give the same tree.
+
+Check: the model's convention is written down, and every edge follows it.
+
+## 4. Trees
+
+- An object type lists the edge types it hangs from, in rank order, in
+  `structureDeclaration.relationships`. For each object the first rank that offers it a parent wins, so
+  a requirement with `["has-requirement", "derives"]` hangs under its system in the default tree, not
+  under its parent requirement.
+- Climbing up uses each type's own list: a requirement hangs under its system by the requirement's list,
+  and the system under its parent system by the system's list.
+- An object under several parents through a traceability edge with a parent end appears once under each.
+  Each placement is an occurrence.
+- "View" names two different things. A **named view** in `structureDeclaration.views` is a tree; an object
+  view or an App view in `presentationBindings.views` is a layout of the drawer or the page (section 5 and the
+  `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
+  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
+  the default.
+
+Check: each type's default tree is the one the person expects; a type with views has its main tree as
+the first view.
+
+## 5. The rail and the page
+
+- The organisation holds one list of rail groups, in the order the rail draws them; it is sent whole
+  with the revise (`--rail-groups`, `railGroups`). A type places itself with
+  `presentationBindings.rail: { group, order }`; the group must be one of the list. A type with no
+  `rail` is listed under "More types": leave it off for a type that is the detail of another, not a
+  destination.
+- `presentationBindings.title` names the property that titles the object in tables, trees and the graph view.
+  `presentationBindings.typeIcon` is a Material Symbols glyph name.
+- An **object view** (`presentationBindings.views.object`, root `ObjectBody`) lays out the object's
+  drawer; an **App view** (`.app`, root `AppBody`) lays out the type's page. Only components the view
+  catalogue admits may appear, each with the props it takes.
+
+## 6. Versions
+
+- A new type key starts at version 1. A changed type is sent at its published version plus one;
+  `openeng types export` writes every type at that next version, ready to send.
+- A change set holds only the types you change. A type sent unchanged publishes an identical new
+  version.
+- Objects take their type's current version for presentation; an update moves an object to it.
+
+## 7. What never changes
+
+| once published | why |
+|---|---|
+| a type's key | versions are append-only |
+| an edge's kind, endpoints, parent end, subject end, labels, read and write rules | existing edges were checked against them, and the read rule is written into every edge row and enforced below the API |
+| a property, a required key, an enumeration member | a later version may only widen: add an optional property, add an enumeration member, raise a bound |
+
+So keep required keys few, choose enumeration members the team will keep, and decide each edge with
+care.
+
+Three words are refused anywhere a key or an enumeration member may appear, from the first version on:
+`__proto__`, `constructor` and `prototype` (rule `prototype-key`). Use another word, such as `prototyping`
+for a lifecycle state. A wrong edge is replaced by a new edge type key and a reconnection, on a branch.
+
+## 8. Writing data
+
+- Data is written on a branch, submitted as a proposal, and merged. A merge names the branch and the
+  hash the reviewer reviewed (the proposal's `reviewedHash`), and lands on the project's trunk.
+- An update is a compare-and-set per property: `{"<property>": {"from": {"value": <what it holds now>}, "to":
+  {"value": <the new value>}}}`; `{"absent": true}` stands for no value on either side. A `from` that no
+  longer matches is refused, so read the object first.
+
+## 9. Examples
+
+A minimal object type and a structural edge, every key at version 1:
+
+```json
+{
+  "system": {
+    "typeCategory": "object", "typeKey": "system", "version": 1, "displayName": "System",
+    "description": "A system, subsystem or component; systems nest to form the product breakdown.",
+    "schemaLanguageVersion": "1",
+    "propertyDefinitions": { "identifier": { "kind": "string" }, "name": { "kind": "string" } },
+    "requiredPropertyKeys": ["identifier", "name"],
+    "presentationBindings": { "title": "name", "typeIcon": "account_tree", "rail": { "group": "Engineering", "order": 10 } },
+    "structureDeclaration": { "relationships": ["contains"] }
+  },
+  "contains": {
+    "typeCategory": "edge", "typeKey": "contains", "version": 1, "displayName": "Contains",
+    "sourceObjectType": "system", "targetObjectType": "system",
+    "kind": "structural", "subjectEnd": "source", "parentEnd": "source",
+    "sourceLabel": "contains", "targetLabel": "part of",
+    "schemaLanguageVersion": "1", "propertyDefinitions": {}, "requiredPropertyKeys": [],
+    "readRule": "both-endpoints", "writeRule": "both-endpoints"
+  }
+}
+```
+
+Send it with `--rail-groups '["Engineering"]'` when the organisation has no such group, or drop the
+`rail` entry.
+
+Two trees for one type, the main one first:
+
+```json
+"structureDeclaration": {
+  "relationships": ["has-requirement", "derives"],
+  "views": [
+    { "key": "by-system", "label": "By system", "steps": ["has-requirement"] },
+    { "key": "decomposition", "label": "Decomposition", "steps": ["derives"] }
+  ]
+}
+```
+
+An object view with a derived value, and an App view:
+
+```json
+"views": {
+  "object": { "root": "body", "elements": {
+    "body": { "type": "ObjectBody", "props": { "derived": [{ "id": "lowerBound", "label": "Lower bound", "result": "number",
+      "reads": ["targetValue", "tolerance"],
+      "expression": { "op": "-", "left": { "op": "property", "key": "targetValue" }, "right": { "op": "property", "key": "tolerance" } } }] },
+      "children": ["fields", "target", "links"] },
+    "fields": { "type": "PropertyList", "props": { "fields": ["identifier", "title", "statement", "status"] }, "children": [] },
+    "target": { "type": "MetricCard", "props": { "label": "Target", "values": [
+      { "source": "property", "field": "targetValue" }, { "source": "derived", "id": "lowerBound" }] }, "children": [] },
+    "links": { "type": "ConnectionList", "props": {}, "children": [] } } },
+  "app": { "root": "body", "elements": {
+    "body": { "type": "AppBody", "props": {}, "children": ["count", "table"] },
+    "count": { "type": "ObjectCount", "props": { "label": "Requirements" }, "children": [] },
+    "table": { "type": "ObjectTable", "props": { "fields": ["identifier", "title", "status"] }, "children": [] } } }
+}
+```
+
+These examples come from a requirements model;
+`openeng skill playbook engineering-requirements` gives the whole model.

package/skill/demo/SKILL.md

@@ -0,0 +1,112 @@
+---
+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.
+---
+
+# 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.
+
+## 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.

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

@@ -0,0 +1,132 @@
+---
+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 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.