docs(skill): refresh ornn-agent-manual-cli to v1.4 — trigger description + skillset lifecycle + api-reference drift

.changeset/ornn-manual-cli-skillset-refresh.md

@@ -0,0 +1,10 @@
+---
+---
+
+docs(skill): refresh the `ornn-agent-manual-cli` skill to v1.4.
+
+- Trigger-oriented frontmatter `description` so Claude Code reliably auto-invokes the skill (covers skills **and** skillsets, plugin export, ownership transfer, etc.).
+- Full skillset lifecycle across `SKILL.md` §2.16 and `api-reference.md` §5a: remove the phantom `PUT /skillsets/:id/permissions`, add plugin-export + transfer-ownership, document derived visibility, auto-revision, the real response/closure shapes, and the error-code table.
+- Broader api-reference drift fixed against current `ornn-api`: skill transfer-ownership + dist-tags, assistant SSE, manifest JSON Schema, public/admin `github/repo` mirror coords, launch-promo, the per-model `assistant` surface flags, and the phantom `ornn:quota:admin` scope (real scope is `ornn:admin:skill`).
+
+Docs-only: no `ornn-api` / `ornn-web` runtime change (the skill is registry-sourced, not bundled into either package image). The skill's own registry version bumps 1.3 → 1.4; publishing the refreshed content to the live registry is a separate operational step.

skills/ornn-agent-manual-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ornn-agent-manual-cli
-description: Operational manual for AI agents using the Ornn skill-lifecycle API via the NyxID CLI (`nyxid proxy request ornn-api …`). Once loaded, the host agent can search / pull / execute / build / upload / share skills end-to-end without further setup. Authoritative contract between Ornn and the agent. Pair this file with references/api-reference.md (the full per-endpoint catalogue + error legend) — both ship together as one Ornn skill.
+description: The manual an AI agent loads to operate Ornn, the model-agnostic skill-lifecycle API (an npm-style registry + CLI for agent skills), through the NyxID CLI (`nyxid proxy request ornn-api …`). Load and follow this skill WHENEVER the user asks to work with Ornn skills or skillsets, e.g. search Ornn / find a skill, pull or install a skill or a specific version, run or execute a skill, build and upload a new skill, publish a new version, make a skill public / private / shared, run a security audit or read audit history, deprecate or delete a skill or version, diff two versions, check usage analytics, bind a skill to a NyxID service, link a skill to GitHub or sync from source, or check your quota / pick an LLM model before an SSE call — and for every SKILLSET request: bundle skills into a set, create or publish a skillset (a curated multi-skill package with a required master prompt), resolve a skillset closure in one call, export a skillset as a Claude Code marketplace plugin, transfer skill or skillset ownership, or work out why others can't see a skillset you shared (visibility is derived from member skills). Once loaded the agent runs the whole search → pull → execute → build → upload → share lifecycle with no further setup. Authoritative Ornn↔agent contract; pair with references/api-reference.md (the full per-endpoint catalogue + error legend), shipped together as one Ornn skill.
 metadata:
   category: plain
   tag:
@@ -9,8 +9,8 @@ metadata:
     - manual
     - skill-lifecycle
     - cli
-version: "1.3"
-lastUpdated: 2026-06-11
+version: "1.4"
+lastUpdated: 2026-07-01
 ---
 
 # Agent Manual (NyxID CLI variant)
@@ -48,7 +48,7 @@ lastUpdated: 2026-06-11
 > - **Pull your Ornn notifications** (audit fan-out, broadcasts, etc.) — §2.13.
 > - **Link a skill to GitHub** or **trigger a sync** from the linked source — §2.14.
 > - **Check your monthly quota** or **pick a valid LLM model** before calling an SSE endpoint — §2.15.
-> - **Work with skillsets** (curated bundles + required master prompt / instructions, one-call closure) — §2.16.
+> - **Work with skillsets** — create / publish a curated multi-skill bundle with its required master prompt, resolve the one-call closure, **export a skillset as a Claude Code plugin**, or transfer skillset ownership — §2.16.
 >
 > Without this manual loaded, you do not know which endpoint to call, how to authenticate, or how to read the response shapes.
 >
@@ -182,7 +182,7 @@ Expected output includes `user_id`, `email`, `roles`, and `permissions`. Confirm
 | Use the Playground (`POST /playground/chat`) | `ornn:playground:use` |
 | Trigger an audit (`POST /skills/:idOrName/audit`) | none (owner or `ornn:admin:skill`) |
 | Admin operations (`/admin/*`, force-audit, sectioned platform settings) | `ornn:admin:skill` |
-| Admin quota / redemption-codes operations (`/admin/quota/*`, `/admin/redemption-codes/*`, `/admin/dashboard/stats`) | `ornn:quota:admin` |
+| Admin quota / redemption-codes operations (`/admin/quota/*`, `/admin/redemption-codes/*`, `/admin/dashboard/stats`) | `ornn:admin:skill` |
 
 Most read operations — browsing public skills, version listings, skill format rules, audit verdicts on visible skills, notifications, your own quota — **need no scalar permission**; they're open to any authenticated caller (and some are anonymous). The exact gates for every endpoint live in `references/api-reference.md`.
 
@@ -198,7 +198,7 @@ The response lists every service the authenticated user can reach through NyxID.
 
 ## §2. Core Workflows
 
-You (the agent) are **highly encouraged to connect with Ornn for any skill-related operations**, including but not limited to the thirteen use cases below. Each one is a recipe — read the matching subsection top-to-bottom and execute the API calls in order. The per-endpoint contract (request / response shapes, every error code, full auth + authorization rules) lives in `references/api-reference.md` — pull it into context whenever you need the underlying API specifics.
+You (the agent) are **highly encouraged to connect with Ornn for any skill-related operations**, including but not limited to the sixteen use cases below. Each one is a recipe — read the matching subsection top-to-bottom and execute the API calls in order. The per-endpoint contract (request / response shapes, every error code, full auth + authorization rules) lives in `references/api-reference.md` — pull it into context whenever you need the underlying API specifics.
 
 ### 2.1 Performing a task — find or build the right skill — *spec: `api-reference.md` §3 Skills CRUD, §5 Skill search, §6 Skill format, §7 Skill generation, §8 Playground*
 
@@ -694,6 +694,65 @@ nyxid proxy request ornn-api "/api/v1/me/models?surface=skillGen" \
 
 Quota refills automatically at `nextMonthlyResetAt`. If a user is low and needs more before then, they can redeem a code via `POST /api/v1/me/redemption-codes/redeem` with `{"code":"<token>"}` — the response carries the updated grants. Don't redeem codes the user hasn't given you.
 
+### 2.16 Work with skillsets (curated bundles + master prompts) — *spec: `references/api-reference.md` §5a*
+
+A **skillset** bundles 2..100 member skills under one name plus a required **master prompt** (`instructions`) that tells you HOW to orchestrate them. The full contract is the *local* `references/api-reference.md` §5a — no external fetch. Two rules differ from skills: **you never send a `version`** (revisions auto-bump `<major>.<minor>` from `1.0`), and **a skillset has no owner-set visibility** — reach is derived from its members.
+
+**Discover + resolve (the common path).** `/closure` is the one call that hands you everything — the master prompt plus every member and its dependency closure, deps-first:
+
+```bash
+# Find candidate sets
+nyxid proxy request ornn-api \
+  "/api/v1/skillset-search?q=review&kind=consensus-supported&scope=mixed&pageSize=20" \
+  --method GET --output json
+
+# Resolve one → { data: { instructions, items: [{ ref, name, version, depth, … }] } }
+nyxid proxy request ornn-api \
+  "/api/v1/skillsets/<name-or-guid>/closure" \
+  --method GET --output json
+```
+
+Run `instructions` as your master prompt, then pull/execute each `items[]` node deps-first (§2.1 step 3 per node). Before re-resolving, compare `GET /api/v1/skillsets/<id>/versions` against your recorded revision, exactly as you version-check a skill (§0.5).
+
+**Create a set** — no `version` field; it starts at `1.0`:
+
+```bash
+nyxid proxy request ornn-api "/api/v1/skillsets" \
+  --method POST \
+  --data '{
+    "name": "review-set",
+    "description": "Curated comparison set.",
+    "instructions": "Run pdf-tools first, then feed its output to csv-tools…",
+    "kind": "consensus-supported",
+    "members": ["pdf-tools@1.0", "csv-tools@2.1"]
+  }' \
+  --output json
+```
+
+**Publish a new revision** — the minor auto-bumps; `members` + `instructions` are required every time (no carry-forward for the prompt):
+
+```bash
+nyxid proxy request ornn-api "/api/v1/skillsets/<id>" \
+  --method PUT \
+  --data '{"members":["pdf-tools@1.1","csv-tools@2.1"],"instructions":"…"}' \
+  --output json
+```
+
+**Export as a Claude Code plugin** — requires the set be `all-public` with ≥2 public members (else `skillset_too_few_public_members`):
+
+```bash
+nyxid proxy request ornn-api "/api/v1/skillsets/<id>/plugin-export" \
+  --method PUT \
+  --data '{"enabled":true,"displayName":"Review Set","keywords":["review","pdf"]}' \
+  --output json
+```
+
+**Transfer ownership** (ADMIN-tier; prior owner kept as READ): `POST /api/v1/skillsets/<id>/transfer-ownership` with `{"newOwnerUserId":"user_…"}`. **Delete:** `DELETE /api/v1/skillsets/<id>` (cascades every version).
+
+**Troubleshoot "why can't my teammate see the skillset I shared?"** There is **no** skillset permissions endpoint. A skillset is readable only by callers who can read **every** member. Read the detail and check `memberVisibilityState`: `all-public` = everyone; `restricted` = only people who can read all members; `unresolvable` = a member ref broke (owner-only — see `unreadableMembers`). **To widen reach, expose the underlying member skills** to that audience (§2.2) — never the skillset itself.
+
+`kind: "consensus-supported"` is an author claim only; Ornn just validates member existence + a conflict-free union closure. After operating on a skillset you authored, update `~/.ornn/installed-skills.json` as you would for a skill.
+
 ---
 
 ## §3. Conventions & Pitfalls
@@ -723,20 +782,3 @@ Quota refills automatically at `nextMonthlyResetAt`. If a user is low and needs
 - `GET /api/v1/announcements/active` — public, anonymous platform-wide notice (separate from `/notifications`). Useful when you want to know about maintenance windows or pricing changes before kicking off long workflows.
 
 If you find a discrepancy between this manual and the actual API behaviour, the API is right and the manual is stale — re-pull the skill (§0) before assuming a bug.
-
-### 2.16 Work with skillsets (curated bundles + master prompts)
-
-See the authoritative recipes and examples in the preferred unified manual `chrono-ai-service-manual` §2.15 (or pull its `references/ornn-api-reference.md` §5a for the exact contract).
-
-Quick hits (all via `nyxid proxy request ornn-api` or direct HTTPS with NyxID bearer):
-
-- Search: `/api/v1/skillset-search?kind=consensus-supported&tags=...&scope=mixed`
-- Detail (includes current `instructions`): `GET /api/v1/skillsets/<name-or-guid>`
-- One-call closure (the main agent payload): `GET /api/v1/skillsets/<name-or-guid>/closure` → `{ instructions: "…", items: [...] }`
-- Create: `POST /api/v1/skillsets` (body requires `instructions`; members 2..N using the same ref grammar as `depends-on`).
-- Publish new version: `PUT /api/v1/skillsets/<id>` (re-supply `instructions` — no carry-forward).
-- Permissions and delete mirror the skill endpoints exactly (reuse `ornn:skill:*` scopes today).
-
-`kind: "consensus-supported"` is an author claim only. Ornn validates member existence + conflict-free union closure at publish time and on `/closure`.
-
-After operating on a skillset you authored, update `~/.ornn/installed-skills.json` exactly as you would for a skill.