@openengio/cli 0.24.3 → 0.27.0

package/bin/public/openeng.js

@@ -289,6 +289,11 @@ function doc(does, refuses) {
   return Object.freeze({ does, refuses: Object.freeze([...refuses]) });
 }
 var ROUTE_DOCS = Object.freeze({
+  createObjectSet: doc("Saves a named set of 1 to 200 object addresses in the caller's organisation. Concurrent retries with one key return the same saved set and revision.", [...SCOPED, "head-moved"]),
+  listObjectSets: doc("Lists the organisation's saved sets, newest update first, without members or counts.", SIGNED_IN),
+  readObjectSet: doc("Reads a saved set's visible objects on the selected ref, a count of missing visible members and one bit for members outside the caller's scope.", [...SCOPED, "head-moved"]),
+  updateObjectSet: doc("Renames a saved set or replaces its readable members at the expected revision. Members outside the caller's scope remain. A success raises the revision by one.", [...SCOPED, "stale-revision", "head-moved"]),
+  deleteObjectSet: doc("Deletes a saved set and every member at the expected revision.", [...SCOPED, "stale-revision"]),
   health: doc("Answers whether the host is running.", PUBLIC),
   signInStart: doc("Starts a sign-in with the identity provider and redirects the browser to it.", PUBLIC),
   signInCallback: doc("Receives the identity provider's answer and returns a one-time code for the client.", [...PUBLIC, "kind", "lifecycle", "invitation", "token-shape", "signature", "issuer", "audience", "expiry", "algorithm", "claims"]),
@@ -472,6 +477,11 @@ function deepFreeze(value) {
   return value;
 }
 var SCHEMAS = {
+  createObjectSet: { "type": "object", "properties": { "name": { "type": "string" }, "members": { "type": "array", "items": { "type": "object", "properties": { "objectId": { "type": "string" }, "projectId": { "type": "string" } }, "required": ["objectId", "projectId"], "additionalProperties": false } } }, "required": ["name", "members"], "additionalProperties": false },
+  listObjectSets: { "type": "object", "properties": {}, "required": [], "additionalProperties": false },
+  readObjectSet: { "type": "object", "properties": { "setId": { "type": "string" } }, "required": ["setId"], "additionalProperties": false },
+  updateObjectSet: { "type": "object", "properties": { "setId": { "type": "string" }, "revision": { "type": "number" }, "name": { "type": "string" }, "members": { "type": "array", "items": { "type": "object", "properties": { "objectId": { "type": "string" }, "projectId": { "type": "string" } }, "required": ["objectId", "projectId"], "additionalProperties": false } } }, "required": ["setId", "revision"], "additionalProperties": false },
+  deleteObjectSet: { "type": "object", "properties": { "setId": { "type": "string" }, "revision": { "type": "number" } }, "required": ["setId", "revision"], "additionalProperties": false },
   health: { "type": "object", "properties": {}, "required": [], "additionalProperties": false },
   signInStart: { "type": "object", "properties": { "state": { "type": "string" }, "loopback": { "type": "string" }, "code_challenge": { "type": "string" }, "code_challenge_method": { "const": "S256" } }, "required": ["state", "loopback", "code_challenge", "code_challenge_method"], "additionalProperties": false },
   signInCallback: { "oneOf": [{ "type": "object", "properties": { "state": { "type": "string" }, "code": { "type": "string" } }, "required": ["state", "code"], "additionalProperties": false }, { "type": "object", "properties": { "state": { "type": "string" }, "error": { "type": "string" } }, "required": ["state", "error"], "additionalProperties": false }] },
@@ -613,6 +623,11 @@ var SELECTORS = {
 };
 var SELECTOR_SCHEMAS = deepFreeze(SELECTORS);
 var EXAMPLES = {
+  createObjectSet: { "name": "Saved set", "members": [{ "objectId": "obj_aaaaaaaaaaaaaaaaaaaaaaaaaa", "projectId": "<projectId>" }] },
+  listObjectSets: {},
+  readObjectSet: { "setId": "ost_aaaaaaaaaaaaaaaaaaaaaaaaaa" },
+  updateObjectSet: { "setId": "ost_aaaaaaaaaaaaaaaaaaaaaaaaaa", "revision": 1, "name": "Renamed set" },
+  deleteObjectSet: { "setId": "ost_aaaaaaaaaaaaaaaaaaaaaaaaaa", "revision": 1 },
   health: {},
   signInStart: { "state": "<state>", "loopback": "<loopback>", "code_challenge": "<code_challenge>", "code_challenge_method": "S256" },
   signInCallback: { "state": "<state>", "code": "<code>" },
@@ -749,7 +764,7 @@ var EXAMPLES = {
 var ROUTE_INPUT_EXAMPLES = deepFreeze(EXAMPLES);
 
 // packages/api-contract/dist/routes.js
-var PROTOCOL_VERSION = 24;
+var PROTOCOL_VERSION = 27;
 var VERSION_HEADER = "oe2-protocol-version";
 var TOKEN_HEADER = "authorization";
 var IDEMPOTENCY_HEADER = "oe2-idempotency-key";
@@ -775,6 +790,11 @@ function route(entry2) {
   return Object.freeze({ ...entry2, doc: documented });
 }
 var ROUTES = Object.freeze({
+  createObjectSet: route({ name: "createObjectSet", method: "POST", path: "/object-sets", group: "write", selector: "object", subject: "project", idempotent: true, admission: admitting("user"), versioned: true, module: "objects-sdk", capability: "objects.createObjectSet" }),
+  listObjectSets: route({ name: "listObjectSets", method: "POST", path: "/object-sets/list", group: "read", selector: "none", subject: "none", idempotent: false, admission: admitting("user"), versioned: true, module: "objects-sdk", capability: "objects.listObjectSets" }),
+  readObjectSet: route({ name: "readObjectSet", method: "POST", path: "/object-sets/read", group: "read", selector: "object", subject: "project", idempotent: false, admission: admitting("user"), versioned: true, module: "objects-sdk", capability: "objects.readObjectSet" }),
+  updateObjectSet: route({ name: "updateObjectSet", method: "POST", path: "/object-sets/update", group: "write", selector: "object", subject: "project", idempotent: false, admission: admitting("user"), versioned: true, module: "objects-sdk", capability: "objects.updateObjectSet" }),
+  deleteObjectSet: route({ name: "deleteObjectSet", method: "POST", path: "/object-sets/delete", group: "write", selector: "none", subject: "none", idempotent: false, admission: admitting("user"), versioned: true, module: "objects-sdk", capability: "objects.deleteObjectSet" }),
   health: route({ name: "health", method: "GET", path: "/health", group: "platform", selector: "none", subject: "platform", idempotent: false, admission: NO_ACCESS_TOKEN, versioned: false, module: "sdk-core", capability: "core.health" }),
   signInStart: route({ name: "signInStart", method: "GET", path: "/auth/sign-in", group: "platform", selector: "none", subject: "platform", idempotent: false, admission: NO_ACCESS_TOKEN, versioned: false, module: "sdk-core", capability: "core.signInStart" }),
   signInCallback: route({ name: "signInCallback", method: "GET", path: "/auth/callback", group: "platform", selector: "none", subject: "platform", idempotent: false, admission: NO_ACCESS_TOKEN, versioned: false, module: "sdk-core", capability: "core.signInCallback" }),
@@ -909,6 +929,11 @@ var ROUTES = Object.freeze({
   closeImportRun: route({ name: "closeImportRun", method: "POST", path: "/import-run-closes", group: "write", selector: "connection", subject: "connection", idempotent: false, admission: admitting("service", "user"), versioned: true, module: "admin-sdk", capability: "admin.importRunClose" })
 });
 var ROUTE_CARRIES_CREDENTIAL = Object.freeze({
+  createObjectSet: false,
+  listObjectSets: false,
+  readObjectSet: false,
+  updateObjectSet: false,
+  deleteObjectSet: false,
   health: false,
   signInStart: false,
   signInCallback: true,
@@ -1057,7 +1082,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 +1162,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 +1195,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 +1490,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 +1595,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 +1632,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 +1651,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 +1723,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);
 }
@@ -1887,6 +1912,9 @@ function exploreViewAddress(address, state) {
   const split = subject.indexOf("?");
   const path = split === -1 ? subject : subject.slice(0, split);
   const query2 = new URLSearchParams(split === -1 ? "" : subject.slice(split + 1));
+  if (state.setId !== void 0 && state.setId !== null && state.setId.length > 0) {
+    query2.set("set", state.setId);
+  }
   if (state.typeKey !== null) {
     query2.set("type", state.typeKey);
   }
@@ -2021,6 +2049,11 @@ function linkPath(organisationId, projectId, subject, ref) {
 // packages/objects-sdk/dist/transport-client.js
 var OBJECTS_ROUTE_ENTRIES = routeEntriesOf("objects-sdk");
 var OBJECTS_ROUTE_NAMES = [
+  "createObjectSet",
+  "listObjectSets",
+  "readObjectSet",
+  "updateObjectSet",
+  "deleteObjectSet",
   "readObject",
   "queryObjects",
   "aggregateObjects",
@@ -8531,7 +8564,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 +8879,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 +9104,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 {
@@ -9701,12 +9734,13 @@ var IDENTIFIER_FIELD = Object.freeze({
   "app-draft": "appKey"
 });
 var PROJECT_REF_USAGE = "openeng link <explore|branch-diff|project> --project <id> --ref <ref>";
+var SET_USAGE = "openeng link explore --project <id> --ref <ref> --object-set <id>";
 var REF_USAGE = "openeng link <ontology|change-set> --ref <ref>";
 var DRAFT_USAGE = "openeng link app-draft <appKey> --ref <ref>";
 var IDENTIFIED_USAGE = "openeng link <object|type|proposal|app> <identifier> --project <id> --ref <ref>";
 var APP_PAGE_USAGE = "openeng link app-page <appKey> <pageKey> --project <id> --ref <ref>";
 var PAGE_USAGE = "openeng link organisation-page <page>";
-var LINK_HELP = [PROJECT_REF_USAGE, REF_USAGE, DRAFT_USAGE, IDENTIFIED_USAGE, APP_PAGE_USAGE, PAGE_USAGE];
+var LINK_HELP = [PROJECT_REF_USAGE, SET_USAGE, REF_USAGE, DRAFT_USAGE, IDENTIFIED_USAGE, APP_PAGE_USAGE, PAGE_USAGE];
 var refusal = (message) => ({ kind: "client-refusal", message });
 var SCOPE_OF_KIND = Object.freeze({
   object: "project-and-ref",
@@ -9837,12 +9871,21 @@ async function link(context) {
   if (typeof scope === "string") {
     return refusal(`openeng link ${subject.kind} ${scope}`);
   }
-  const path = linkPath(organisation.id, scope.project, subject, scope.ref);
+  if (options.objectSet !== void 0 && (subject.kind !== "explore" || options.objectSet.length === 0)) {
+    return refusal("--object-set needs a saved set identifier and the explore page");
+  }
+  const objectSet = options.objectSet;
+  const path = options.objectSet === void 0 ? linkPath(organisation.id, scope.project, subject, scope.ref) : exploreViewAddress({ organisationId: organisation.id, projectId: scope.project, ref: scope.ref, q: null }, { typeKey: null, objectId: null, setId: options.objectSet });
   const run2 = await runAuthenticated(host, deps, async (clients) => {
-    const [origin, checks] = await Promise.all([
+    const [origin, checks, saved] = await Promise.all([
       clients.admin.readWebOrigin({ input: {} }),
-      Promise.all(subjectReads(clients, subject, scope))
+      Promise.all(subjectReads(clients, subject, scope)),
+      objectSet === void 0 ? Promise.resolve(null) : clients.objects.readObjectSet({
+        selector: { projectId: scope.project, ref: scope.ref },
+        input: { setId: objectSet }
+      })
     ]);
+    if (saved !== null && ("refusal" in saved || saved.replayed === true)) return saved;
     const blocked = checks.find((check) => check.missing === null && ("refusal" in check.answer || check.answer.replayed === true));
     if (blocked !== void 0) return blocked.answer;
     if ("refusal" in origin) {
@@ -10876,6 +10919,7 @@ import { parseArgs } from "node:util";
 
 // packages/cli/src/cli-options.ts
 var CLI_OPTIONS = {
+  "object-set": { type: "string" },
   host: { type: "string" },
   "sign-in-origin": { type: "string" },
   json: { type: "boolean" },
@@ -10912,7 +10956,7 @@ var CLI_OPTIONS = {
 };
 
 // packages/cli/src/cli-version.ts
-var PATCH_VERSION = 3;
+var PATCH_VERSION = 0;
 var CLI_VERSION = `0.${PROTOCOL_VERSION}.${PATCH_VERSION}`;
 
 // packages/cli/src/environment.ts
@@ -11026,6 +11070,7 @@ function parseInvocation(argv) {
         json: values.json === true,
         open: values["no-open"] !== true,
         project: values.project,
+        objectSet: values["object-set"],
         organisation: values.organisation === true,
         readOnly: values["read-only"] === true,
         object: values.object,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openengio/cli",
-  "version": "0.24.3",
+  "version": "0.27.0",
   "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.

package/skill/openeng/SKILL.md

@@ -263,6 +263,18 @@ project. `openeng link ontology --ref <ref>` and `openeng link change-set --ref
 project, and `openeng link organisation-page <page>` takes neither flag. The organisation is the one
 your session is attached to.
 
+### Save an object set and link to its canvas
+
+1. Run `openeng help objects-sdk createObjectSet` and `openeng help objects-sdk readObjectSet`.
+2. Query the objects you need with `openeng objects-sdk queryObjects --json`. Keep each object's
+   project with its identifier; one set may contain objects of several projects in your organisation.
+3. Call `openeng objects-sdk createObjectSet` with a name and the selected addresses, following its
+   help. Keep the returned set identifier and revision. Retrying with the same idempotency key
+   returns that original answer.
+4. Run `openeng link explore --project <page project> --ref <ref> --object-set <set id>` and give the
+   person the address it prints. It reads the set first; a refused read prints no link. The set
+   stores no ref, so the link's ref chooses which version of its objects opens.
+
 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;