@openengio/cli 0.24.3 → 0.24.4

package/bin/public/openeng.js

@@ -1057,7 +1057,7 @@ var CLIENT_SCOPES = Object.freeze({
   offline_access: Object.freeze({ capabilities: Object.freeze([]), consentLine: "Stay connected when you are away, until you disconnect it." })
 });
 
-// packages/sdk-core/dist/explain.js
+// packages/sdk-dispatch/dist/explain.js
 function explainKind(kind) {
   if (!Object.hasOwn(BY_KIND, kind)) {
     throw new Error(`the refusal kind ${JSON.stringify(kind)} has no entry in the refusal catalogue`);
@@ -1137,10 +1137,10 @@ function unauthenticatedEnvelope() {
   return { version: PROTOCOL_VERSION, refusal: explainedRefusalOf({ kind: "unauthenticated" }), correlationId: null };
 }
 
-// packages/sdk-core/dist/socket-transport.js
+// packages/sdk-dispatch/dist/socket-transport.js
 import { request } from "node:http";
 
-// packages/sdk-core/dist/response.js
+// packages/sdk-dispatch/dist/response.js
 function responseOf(status, text, reason) {
   let read = false;
   const members = {
@@ -1170,7 +1170,7 @@ function responseOf(status, text, reason) {
   });
 }
 
-// packages/sdk-core/dist/socket-transport.js
+// packages/sdk-dispatch/dist/socket-transport.js
 var REQUEST_DEADLINE_MS = 1e4;
 var HostOutcomeUnknown = class extends Error {
   path;
@@ -1465,7 +1465,7 @@ function createHostStreamFetch(socketPath, headDeadlineMs = REQUEST_DEADLINE_MS)
   };
 }
 
-// packages/sdk-core/dist/call.js
+// packages/sdk-dispatch/dist/call.js
 function isEnvelope(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     return false;
@@ -1570,7 +1570,7 @@ async function* callStreamed(transport, origin, route2, body, token, signal) {
   }
 }
 
-// packages/sdk-core/dist/module-factory.js
+// packages/sdk-dispatch/dist/module-factory.js
 function freezeDoc(doc2) {
   return Object.freeze({ does: doc2.does, refuses: Object.freeze([...doc2.refuses]) });
 }
@@ -1607,7 +1607,7 @@ function createModuleFactory(entries6, transport, origin, token) {
   return Object.freeze(Object.fromEntries(Object.entries(byCapability).map(([capability, methods]) => [capability, Object.freeze(methods)])));
 }
 
-// packages/sdk-core/dist/typed-client.js
+// packages/sdk-dispatch/dist/typed-client.js
 function createTypedClient(names, entries6, transport, origin, token) {
   const factory = createModuleFactory(entries6, transport, origin, token);
   const byName = new Map(entries6.map((entry2) => [entry2.name, entry2]));
@@ -1626,7 +1626,7 @@ function createTypedClient(names, entries6, transport, origin, token) {
   return Object.freeze(client);
 }
 
-// packages/sdk-core/dist/https-transport.js
+// packages/sdk-dispatch/dist/https-transport.js
 import { request as request2 } from "node:https";
 function createHttpsTransport(origin, options = {}, deadlineMs = REQUEST_DEADLINE_MS) {
   const originUrl = new URL(origin);
@@ -1698,7 +1698,7 @@ function createHttpsTransport(origin, options = {}, deadlineMs = REQUEST_DEADLIN
   };
 }
 
-// packages/sdk-core/dist/token-routes.js
+// packages/sdk-dispatch/dist/token-routes.js
 async function redeem(transport, origin, body) {
   return call(transport, origin, "redeem", body, null, null);
 }
@@ -8531,7 +8531,7 @@ var typesIcons = {
   }
 };
 
-// packages/demo-seed/dist/definition.js
+// packages/demo-player/dist/definition.js
 var STRING = { kind: "string" };
 var NUMBER = { kind: "number" };
 var PERSON = { kind: "person" };
@@ -8846,7 +8846,7 @@ function worldSteps(size, ownerPersonId, data) {
 }
 var DEMO_TYPE_VERSION = 1;
 
-// packages/demo-seed/dist/ocgt-world.js
+// packages/demo-player/dist/ocgt-world.js
 var SYSTEM_TREE = [
   { identifier: "OCGT", name: "Open Cycle Gas Turbine Plant", parent: null },
   { identifier: "GT", name: "Gas Turbine", parent: "OCGT" },
@@ -9071,7 +9071,7 @@ var OCGT_WORLD = {
   })
 };
 
-// packages/demo-seed/dist/player.js
+// packages/demo-player/dist/player.js
 var TRUNK_REF = "main";
 var IDEMPOTENCY_PREFIX = "demo-seed";
 var DemoRouteRefusedError = class extends Error {
@@ -10912,7 +10912,7 @@ var CLI_OPTIONS = {
 };
 
 // packages/cli/src/cli-version.ts
-var PATCH_VERSION = 3;
+var PATCH_VERSION = 4;
 var CLI_VERSION = `0.${PROTOCOL_VERSION}.${PATCH_VERSION}`;
 
 // packages/cli/src/environment.ts

package/package.json

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

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.