yarkr-cli 0.1.5 → 1.0.1

package/README.md

@@ -4,20 +4,60 @@ Install skills, agents and MCP toolsets from [Yarkr](https://yarkr.com) into the
 Claude Code, Codex, opencode, Cursor and more.
 
 ```sh
-npx yarkr-cli add posterus-ltd/code-review-checklist     # a public package, no account needed
-npx yarkr-cli add posterus-ltd/github --harness codex   # pick the harnesses to write
+npm install -g yarkr-cli                                 # Node 22 or newer; or run any command with `npx yarkr-cli …`
+yarkr add posterus-ltd/code-review-checklist            # a public package, no account needed
+yarkr add posterus-ltd/github --harness codex           # pick the harnesses to write
 ```
 
-In a project, `yarkr init` creates `yarkr.json`; `yarkr add` and `yarkr sync` then pin every package in `yarkr.lock`:
+## Sync an ark to your machine
+
+An ark is a curated set of skills, agents and toolsets hosted in the registry. `yarkr sync` writes each one into the
+harness's own layout (`~/.claude/skills/…`, `~/.agents/…`, MCP configs and so on):
+
+```sh
+yarkr arks                                    # list public arks
+yarkr sync acme/starter                       # install one into your home directory
+yarkr sync acme/starter --harness claude-code # only write Claude Code's files
+yarkr ark                                     # what your arks give you, and which version
+```
+
+Signed in, a bare `yarkr sync` installs every ark you're a member of, plus your personal ark. Run it again to pick up
+whatever an admin added or removed; `yarkr sync --check` exits 1 when you're behind.
+
+## Set up an existing repo
+
+In a project, `yarkr init` creates `yarkr.json` (and `.yarkrrc`), detecting the harnesses already used there.
+`yarkr add` and `yarkr sync` then pin every package in `yarkr.lock`, so teammates and CI get the same releases:
 
 ```sh
-npm install -g yarkr-cli
-yarkr init
+cd my-repo
+yarkr init --ark acme/engineering            # optional: install a team's ark into this project
 yarkr add posterus-ltd/playwright-test-authoring
-yarkr sync --check   # in CI: exit 1 when anything is out of date
+git add yarkr.json yarkr.lock .yarkrrc .claude AGENTS.md && git commit
+yarkr sync --check                           # in CI: exit 1 when anything is out of date
+```
+
+To publish from the repo instead, there's nothing to init: Yarkr finds `SKILL.md` folders, `agents/*.md` and
+`.mcp.json` on its own. Anything else (a skill that's a single markdown file, or a folder with a README instead of
+SKILL.md) goes in one `yarkr.index.yaml` at the root, and nothing has to move. Lint it before you push:
+
+```sh
+yarkr lint                                               # what will be published, and what the hub would refuse
+yarkr lint --strict                                      # in CI: fail on warnings too
+yarkr guide index-repo -o ~/.claude/skills/index-repo/   # a skill your agent uses to write the index
+```
+
+## Sign in for private packages
+
+Public packages and public arks work signed out. Your org's private packages and arks need a token:
+
+```sh
+yarkr login                  # signs in in the browser; the token goes to your keychain (or ~/.yarkrrc)
+yarkr login --no-browser     # over SSH: open the printed link anywhere, then paste the token
+yarkr whoami                 # check who you're signed in as
 ```
 
-`yarkr` uses the public hub at `https://yarkr.com` unless you point it at your own instance with
-`yarkr login --registry <url>`. Node 22 or newer.
+In CI, store a read-only token as a secret and set `YARKR_TOKEN`. `yarkr` uses the public hub at `https://yarkr.com`
+unless you point it at your own instance with `yarkr login --registry <url>`.
 
 Docs: [docs/cli.md](https://github.com/posterus-ltd/yarkr-public/blob/main/docs/cli.md) · Source: [github.com/posterus-ltd/yarkr-public](https://github.com/posterus-ltd/yarkr-public) · MIT

package/dist/yarkr.js

@@ -1206,7 +1206,7 @@ var require_command = __commonJS({
     "use strict";
     var EventEmitter = __require("events").EventEmitter;
     var childProcess = __require("child_process");
-    var path17 = __require("path");
+    var path18 = __require("path");
     var fs = __require("fs");
     var process2 = __require("process");
     var { Argument: Argument2, humanReadableArgName } = require_argument();
@@ -2219,9 +2219,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
         let launchWithNode = false;
         const sourceExt = [".js", ".ts", ".tsx", ".mjs", ".cjs"];
         function findFile(baseDir, baseName) {
-          const localBin = path17.resolve(baseDir, baseName);
+          const localBin = path18.resolve(baseDir, baseName);
           if (fs.existsSync(localBin)) return localBin;
-          if (sourceExt.includes(path17.extname(baseName))) return void 0;
+          if (sourceExt.includes(path18.extname(baseName))) return void 0;
           const foundExt = sourceExt.find(
             (ext) => fs.existsSync(`${localBin}${ext}`)
           );
@@ -2239,17 +2239,17 @@ Expecting one of '${allowedValues.join("', '")}'`);
           } catch {
             resolvedScriptPath = this._scriptPath;
           }
-          executableDir = path17.resolve(
-            path17.dirname(resolvedScriptPath),
+          executableDir = path18.resolve(
+            path18.dirname(resolvedScriptPath),
             executableDir
           );
         }
         if (executableDir) {
           let localFile = findFile(executableDir, executableFile);
           if (!localFile && !subcommand._executableFile && this._scriptPath) {
-            const legacyName = path17.basename(
+            const legacyName = path18.basename(
               this._scriptPath,
-              path17.extname(this._scriptPath)
+              path18.extname(this._scriptPath)
             );
             if (legacyName !== this._name) {
               localFile = findFile(
@@ -2260,7 +2260,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
           }
           executableFile = localFile || executableFile;
         }
-        launchWithNode = sourceExt.includes(path17.extname(executableFile));
+        launchWithNode = sourceExt.includes(path18.extname(executableFile));
         let proc;
         if (process2.platform !== "win32") {
           if (launchWithNode) {
@@ -3175,7 +3175,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @return {Command}
        */
       nameFromFilename(filename) {
-        this._name = path17.basename(filename, path17.extname(filename));
+        this._name = path18.basename(filename, path18.extname(filename));
         return this;
       }
       /**
@@ -3189,9 +3189,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @param {string} [path]
        * @return {(string|null|Command)}
        */
-      executableDir(path18) {
-        if (path18 === void 0) return this._executableDir;
-        this._executableDir = path18;
+      executableDir(path19) {
+        if (path19 === void 0) return this._executableDir;
+        this._executableDir = path19;
         return this;
       }
       /**
@@ -3547,17 +3547,17 @@ var require_visit = __commonJS({
     visit2.BREAK = BREAK;
     visit2.SKIP = SKIP2;
     visit2.REMOVE = REMOVE;
-    function visit_(key, node2, visitor, path17) {
-      const ctrl = callVisitor(key, node2, visitor, path17);
+    function visit_(key, node2, visitor, path18) {
+      const ctrl = callVisitor(key, node2, visitor, path18);
       if (identity.isNode(ctrl) || identity.isPair(ctrl)) {
-        replaceNode(key, path17, ctrl);
-        return visit_(key, ctrl, visitor, path17);
+        replaceNode(key, path18, ctrl);
+        return visit_(key, ctrl, visitor, path18);
       }
       if (typeof ctrl !== "symbol") {
         if (identity.isCollection(node2)) {
-          path17 = Object.freeze(path17.concat(node2));
+          path18 = Object.freeze(path18.concat(node2));
           for (let i = 0; i < node2.items.length; ++i) {
-            const ci = visit_(i, node2.items[i], visitor, path17);
+            const ci = visit_(i, node2.items[i], visitor, path18);
             if (typeof ci === "number")
               i = ci - 1;
             else if (ci === BREAK)
@@ -3568,13 +3568,13 @@ var require_visit = __commonJS({
             }
           }
         } else if (identity.isPair(node2)) {
-          path17 = Object.freeze(path17.concat(node2));
-          const ck = visit_("key", node2.key, visitor, path17);
+          path18 = Object.freeze(path18.concat(node2));
+          const ck = visit_("key", node2.key, visitor, path18);
           if (ck === BREAK)
             return BREAK;
           else if (ck === REMOVE)
             node2.key = null;
-          const cv = visit_("value", node2.value, visitor, path17);
+          const cv = visit_("value", node2.value, visitor, path18);
           if (cv === BREAK)
             return BREAK;
           else if (cv === REMOVE)
@@ -3595,17 +3595,17 @@ var require_visit = __commonJS({
     visitAsync.BREAK = BREAK;
     visitAsync.SKIP = SKIP2;
     visitAsync.REMOVE = REMOVE;
-    async function visitAsync_(key, node2, visitor, path17) {
-      const ctrl = await callVisitor(key, node2, visitor, path17);
+    async function visitAsync_(key, node2, visitor, path18) {
+      const ctrl = await callVisitor(key, node2, visitor, path18);
       if (identity.isNode(ctrl) || identity.isPair(ctrl)) {
-        replaceNode(key, path17, ctrl);
-        return visitAsync_(key, ctrl, visitor, path17);
+        replaceNode(key, path18, ctrl);
+        return visitAsync_(key, ctrl, visitor, path18);
       }
       if (typeof ctrl !== "symbol") {
         if (identity.isCollection(node2)) {
-          path17 = Object.freeze(path17.concat(node2));
+          path18 = Object.freeze(path18.concat(node2));
           for (let i = 0; i < node2.items.length; ++i) {
-            const ci = await visitAsync_(i, node2.items[i], visitor, path17);
+            const ci = await visitAsync_(i, node2.items[i], visitor, path18);
             if (typeof ci === "number")
               i = ci - 1;
             else if (ci === BREAK)
@@ -3616,13 +3616,13 @@ var require_visit = __commonJS({
             }
           }
         } else if (identity.isPair(node2)) {
-          path17 = Object.freeze(path17.concat(node2));
-          const ck = await visitAsync_("key", node2.key, visitor, path17);
+          path18 = Object.freeze(path18.concat(node2));
+          const ck = await visitAsync_("key", node2.key, visitor, path18);
           if (ck === BREAK)
             return BREAK;
           else if (ck === REMOVE)
             node2.key = null;
-          const cv = await visitAsync_("value", node2.value, visitor, path17);
+          const cv = await visitAsync_("value", node2.value, visitor, path18);
           if (cv === BREAK)
             return BREAK;
           else if (cv === REMOVE)
@@ -3649,23 +3649,23 @@ var require_visit = __commonJS({
       }
       return visitor;
     }
-    function callVisitor(key, node2, visitor, path17) {
+    function callVisitor(key, node2, visitor, path18) {
       if (typeof visitor === "function")
-        return visitor(key, node2, path17);
+        return visitor(key, node2, path18);
       if (identity.isMap(node2))
-        return visitor.Map?.(key, node2, path17);
+        return visitor.Map?.(key, node2, path18);
       if (identity.isSeq(node2))
-        return visitor.Seq?.(key, node2, path17);
+        return visitor.Seq?.(key, node2, path18);
       if (identity.isPair(node2))
-        return visitor.Pair?.(key, node2, path17);
+        return visitor.Pair?.(key, node2, path18);
       if (identity.isScalar(node2))
-        return visitor.Scalar?.(key, node2, path17);
+        return visitor.Scalar?.(key, node2, path18);
       if (identity.isAlias(node2))
-        return visitor.Alias?.(key, node2, path17);
+        return visitor.Alias?.(key, node2, path18);
       return void 0;
     }
-    function replaceNode(key, path17, node2) {
-      const parent = path17[path17.length - 1];
+    function replaceNode(key, path18, node2) {
+      const parent = path18[path18.length - 1];
       if (identity.isCollection(parent)) {
         parent.items[key] = node2;
       } else if (identity.isPair(parent)) {
@@ -4277,10 +4277,10 @@ var require_Collection = __commonJS({
     var createNode = require_createNode();
     var identity = require_identity();
     var Node = require_Node();
-    function collectionFromPath(schema, path17, value) {
+    function collectionFromPath(schema, path18, value) {
       let v = value;
-      for (let i = path17.length - 1; i >= 0; --i) {
-        const k = path17[i];
+      for (let i = path18.length - 1; i >= 0; --i) {
+        const k = path18[i];
         if (typeof k === "number" && Number.isInteger(k) && k >= 0) {
           const a = [];
           a[k] = v;
@@ -4299,7 +4299,7 @@ var require_Collection = __commonJS({
         sourceObjects: /* @__PURE__ */ new Map()
       });
     }
-    var isEmptyPath = (path17) => path17 == null || typeof path17 === "object" && !!path17[Symbol.iterator]().next().done;
+    var isEmptyPath = (path18) => path18 == null || typeof path18 === "object" && !!path18[Symbol.iterator]().next().done;
     var Collection = class extends Node.NodeBase {
       constructor(type, schema) {
         super(type);
@@ -4329,11 +4329,11 @@ var require_Collection = __commonJS({
        * be a Pair instance or a `{ key, value }` object, which may not have a key
        * that already exists in the map.
        */
-      addIn(path17, value) {
-        if (isEmptyPath(path17))
+      addIn(path18, value) {
+        if (isEmptyPath(path18))
           this.add(value);
         else {
-          const [key, ...rest] = path17;
+          const [key, ...rest] = path18;
           const node2 = this.get(key, true);
           if (identity.isCollection(node2))
             node2.addIn(rest, value);
@@ -4347,8 +4347,8 @@ var require_Collection = __commonJS({
        * Removes a value from the collection.
        * @returns `true` if the item was found and removed.
        */
-      deleteIn(path17) {
-        const [key, ...rest] = path17;
+      deleteIn(path18) {
+        const [key, ...rest] = path18;
         if (rest.length === 0)
           return this.delete(key);
         const node2 = this.get(key, true);
@@ -4362,8 +4362,8 @@ var require_Collection = __commonJS({
        * scalar values from their surrounding node; to disable set `keepScalar` to
        * `true` (collections are always returned intact).
        */
-      getIn(path17, keepScalar) {
-        const [key, ...rest] = path17;
+      getIn(path18, keepScalar) {
+        const [key, ...rest] = path18;
         const node2 = this.get(key, true);
         if (rest.length === 0)
           return !keepScalar && identity.isScalar(node2) ? node2.value : node2;
@@ -4381,8 +4381,8 @@ var require_Collection = __commonJS({
       /**
        * Checks if the collection includes a value with the key `key`.
        */
-      hasIn(path17) {
-        const [key, ...rest] = path17;
+      hasIn(path18) {
+        const [key, ...rest] = path18;
         if (rest.length === 0)
           return this.has(key);
         const node2 = this.get(key, true);
@@ -4392,8 +4392,8 @@ var require_Collection = __commonJS({
        * Sets a value in this collection. For `!!set`, `value` needs to be a
        * boolean to add/remove the item from the set.
        */
-      setIn(path17, value) {
-        const [key, ...rest] = path17;
+      setIn(path18, value) {
+        const [key, ...rest] = path18;
         if (rest.length === 0) {
           this.set(key, value);
         } else {
@@ -6908,9 +6908,9 @@ var require_Document = __commonJS({
           this.contents.add(value);
       }
       /** Adds a value to the document. */
-      addIn(path17, value) {
+      addIn(path18, value) {
         if (assertCollection(this.contents))
-          this.contents.addIn(path17, value);
+          this.contents.addIn(path18, value);
       }
       /**
        * Create a new `Alias` node, ensuring that the target `node` has the required anchor.
@@ -6985,14 +6985,14 @@ var require_Document = __commonJS({
        * Removes a value from the document.
        * @returns `true` if the item was found and removed.
        */
-      deleteIn(path17) {
-        if (Collection.isEmptyPath(path17)) {
+      deleteIn(path18) {
+        if (Collection.isEmptyPath(path18)) {
           if (this.contents == null)
             return false;
           this.contents = null;
           return true;
         }
-        return assertCollection(this.contents) ? this.contents.deleteIn(path17) : false;
+        return assertCollection(this.contents) ? this.contents.deleteIn(path18) : false;
       }
       /**
        * Returns item at `key`, or `undefined` if not found. By default unwraps
@@ -7007,10 +7007,10 @@ var require_Document = __commonJS({
        * scalar values from their surrounding node; to disable set `keepScalar` to
        * `true` (collections are always returned intact).
        */
-      getIn(path17, keepScalar) {
-        if (Collection.isEmptyPath(path17))
+      getIn(path18, keepScalar) {
+        if (Collection.isEmptyPath(path18))
           return !keepScalar && identity.isScalar(this.contents) ? this.contents.value : this.contents;
-        return identity.isCollection(this.contents) ? this.contents.getIn(path17, keepScalar) : void 0;
+        return identity.isCollection(this.contents) ? this.contents.getIn(path18, keepScalar) : void 0;
       }
       /**
        * Checks if the document includes a value with the key `key`.
@@ -7021,10 +7021,10 @@ var require_Document = __commonJS({
       /**
        * Checks if the document includes a value at `path`.
        */
-      hasIn(path17) {
-        if (Collection.isEmptyPath(path17))
+      hasIn(path18) {
+        if (Collection.isEmptyPath(path18))
           return this.contents !== void 0;
-        return identity.isCollection(this.contents) ? this.contents.hasIn(path17) : false;
+        return identity.isCollection(this.contents) ? this.contents.hasIn(path18) : false;
       }
       /**
        * Sets a value in this document. For `!!set`, `value` needs to be a
@@ -7041,13 +7041,13 @@ var require_Document = __commonJS({
        * Sets a value in this document. For `!!set`, `value` needs to be a
        * boolean to add/remove the item from the set.
        */
-      setIn(path17, value) {
-        if (Collection.isEmptyPath(path17)) {
+      setIn(path18, value) {
+        if (Collection.isEmptyPath(path18)) {
           this.contents = value;
         } else if (this.contents == null) {
-          this.contents = Collection.collectionFromPath(this.schema, Array.from(path17), value);
+          this.contents = Collection.collectionFromPath(this.schema, Array.from(path18), value);
         } else if (assertCollection(this.contents)) {
-          this.contents.setIn(path17, value);
+          this.contents.setIn(path18, value);
         }
       }
       /**
@@ -9008,9 +9008,9 @@ var require_cst_visit = __commonJS({
     visit2.BREAK = BREAK;
     visit2.SKIP = SKIP2;
     visit2.REMOVE = REMOVE;
-    visit2.itemAtPath = (cst, path17) => {
+    visit2.itemAtPath = (cst, path18) => {
       let item = cst;
-      for (const [field, index2] of path17) {
+      for (const [field, index2] of path18) {
         const tok = item?.[field];
         if (tok && "items" in tok) {
           item = tok.items[index2];
@@ -9019,23 +9019,23 @@ var require_cst_visit = __commonJS({
       }
       return item;
     };
-    visit2.parentCollection = (cst, path17) => {
-      const parent = visit2.itemAtPath(cst, path17.slice(0, -1));
-      const field = path17[path17.length - 1][0];
+    visit2.parentCollection = (cst, path18) => {
+      const parent = visit2.itemAtPath(cst, path18.slice(0, -1));
+      const field = path18[path18.length - 1][0];
       const coll = parent?.[field];
       if (coll && "items" in coll)
         return coll;
       throw new Error("Parent collection not found");
     };
-    function _visit(path17, item, visitor) {
-      let ctrl = visitor(item, path17);
+    function _visit(path18, item, visitor) {
+      let ctrl = visitor(item, path18);
       if (typeof ctrl === "symbol")
         return ctrl;
       for (const field of ["key", "value"]) {
         const token = item[field];
         if (token && "items" in token) {
           for (let i = 0; i < token.items.length; ++i) {
-            const ci = _visit(Object.freeze(path17.concat([[field, i]])), token.items[i], visitor);
+            const ci = _visit(Object.freeze(path18.concat([[field, i]])), token.items[i], visitor);
             if (typeof ci === "number")
               i = ci - 1;
             else if (ci === BREAK)
@@ -9046,10 +9046,10 @@ var require_cst_visit = __commonJS({
             }
           }
           if (typeof ctrl === "function" && field === "key")
-            ctrl = ctrl(item, path17);
+            ctrl = ctrl(item, path18);
         }
       }
-      return typeof ctrl === "function" ? ctrl(item, path17) : ctrl;
+      return typeof ctrl === "function" ? ctrl(item, path18) : ctrl;
     }
     exports.visit = visit2;
   }
@@ -16023,8 +16023,8 @@ var require_utils = __commonJS({
       }
       return ind;
     }
-    function removeDotSegments(path17) {
-      let input2 = path17;
+    function removeDotSegments(path18) {
+      let input2 = path18;
       const output3 = [];
       let nextSlash = -1;
       let len = 0;
@@ -16433,8 +16433,8 @@ var require_schemes = __commonJS({
       }
       if (wsComponent.resourceName) {
         const queryIndex = wsComponent.resourceName.indexOf("?");
-        const path17 = queryIndex === -1 ? wsComponent.resourceName : wsComponent.resourceName.slice(0, queryIndex);
-        wsComponent.path = path17 && path17 !== "/" ? path17 : void 0;
+        const path18 = queryIndex === -1 ? wsComponent.resourceName : wsComponent.resourceName.slice(0, queryIndex);
+        wsComponent.path = path18 && path18 !== "/" ? path18 : void 0;
         wsComponent.query = queryIndex === -1 ? void 0 : wsComponent.resourceName.slice(queryIndex + 1);
         wsComponent.resourceName = void 0;
       }
@@ -20476,10 +20476,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema) {
   return mergeDefs(schema._zod.def);
 }
-function getElementAtPath(obj, path17) {
-  if (!path17)
+function getElementAtPath(obj, path18) {
+  if (!path18)
     return obj;
-  return path17.reduce((acc, key) => acc?.[key], obj);
+  return path18.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -20819,11 +20819,11 @@ function explicitlyAborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path17, issues) {
+function prefixIssues(path18, issues) {
   return issues.map((iss) => {
     var _a3;
     (_a3 = iss).path ?? (_a3.path = []);
-    iss.path.unshift(path17);
+    iss.path.unshift(path18);
     return iss;
   });
 }
@@ -21273,16 +21273,16 @@ function flattenError(error62, mapper = (issue2) => issue2.message) {
 }
 function formatError(error62, mapper = (issue2) => issue2.message) {
   const fieldErrors = { _errors: [] };
-  const processError = (error63, path17 = []) => {
+  const processError = (error63, path18 = []) => {
     for (const issue2 of error63.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path17, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path18, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path17, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path18, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path17, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path18, ...issue2.path]);
       } else {
-        const fullpath = [...path17, ...issue2.path];
+        const fullpath = [...path18, ...issue2.path];
         if (fullpath.length === 0) {
           fieldErrors._errors.push(mapper(issue2));
         } else {
@@ -21321,17 +21321,17 @@ function formatError(error62, mapper = (issue2) => issue2.message) {
 }
 function treeifyError(error62, mapper = (issue2) => issue2.message) {
   const result = { errors: [] };
-  const processError = (error63, path17 = []) => {
+  const processError = (error63, path18 = []) => {
     var _a3;
     for (const issue2 of error63.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path17, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path18, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path17, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path18, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path17, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path18, ...issue2.path]);
       } else {
-        const fullpath = [...path17, ...issue2.path];
+        const fullpath = [...path18, ...issue2.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue2));
           continue;
@@ -21370,8 +21370,8 @@ function treeifyError(error62, mapper = (issue2) => issue2.message) {
 }
 function toDotPath(_path) {
   const segs = [];
-  const path17 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path17) {
+  const path18 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path18) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -38473,13 +38473,13 @@ function resolveRef(ref, ctx) {
   if (!ref.startsWith("#")) {
     throw new Error("External $ref is not supported, only local refs (#/...) are allowed");
   }
-  const path17 = ref.slice(1).split("/").filter(Boolean);
-  if (path17.length === 0) {
+  const path18 = ref.slice(1).split("/").filter(Boolean);
+  if (path18.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path17[0] === defsKey) {
-    const key = path17[1] === void 0 ? void 0 : decodeJSONPointerSegment(path17[1]);
+  if (path18[0] === defsKey) {
+    const key = path18[1] === void 0 ? void 0 : decodeJSONPointerSegment(path18[1]);
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref}`);
     }
@@ -39342,6 +39342,7 @@ var HARNESSES = {
 
 // ../../packages/schema/dist/manifest.js
 var MANIFEST_FILE = "yarkr.yaml";
+var INDEX_FILE = "yarkr.index.yaml";
 var PackageKind = external_exports.enum(["skill", "agent", "toolset"]);
 var Classification = external_exports.enum(["public", "internal", "restricted"]);
 var PackageName = external_exports.string().regex(/^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/, "Use namespace/name in lowercase, e.g. finance/invoice-extraction");
@@ -39573,7 +39574,7 @@ var EffectiveArkQuery = external_exports.object({
   /** Comma-separated ark refs to narrow to; omit for all. */
   arks: external_exports.string().optional()
 });
-var PersonalItemBody = external_exports.object({ package: PackageName, range: external_exports.string().nullable().optional() });
+var PersonalItemBody = external_exports.object({ package: PackageName, range: external_exports.string().nullable().optional(), channel: external_exports.string().nullable().optional() });
 var ExclusionBody = external_exports.object({ ark: external_exports.string(), package: PackageName });
 
 // src/commands/auth.ts
@@ -39742,8 +39743,8 @@ var Api = class {
     this.conn = conn;
   }
   conn;
-  async request(method, path17, body, { allow404 = false } = {}) {
-    const url2 = `${this.conn.server}/api/v1${path17}`;
+  async request(method, path18, body, { allow404 = false } = {}) {
+    const url2 = `${this.conn.server}/api/v1${path18}`;
     let res;
     try {
       res = await fetch(url2, {
@@ -39765,7 +39766,7 @@ var Api = class {
         payload = await res.json();
       } catch {
       }
-      const msg = payload.message ?? `${method} ${path17} failed with HTTP ${res.status}.`;
+      const msg = payload.message ?? `${method} ${path18} failed with HTTP ${res.status}.`;
       if (res.status === 401) {
         throw new CliError(
           msg,
@@ -39856,17 +39857,17 @@ function parseManifest(text) {
   }
   return manifest;
 }
-function parseEvalSuite(text, path17 = "suite") {
+function parseEvalSuite(text, path18 = "suite") {
   let raw;
   try {
     raw = import_yaml.default.parse(text);
   } catch (err) {
-    throw new ManifestError(`${path17} is not valid YAML: ${err.message}`);
+    throw new ManifestError(`${path18} is not valid YAML: ${err.message}`);
   }
   const res = EvalSuite.safeParse(raw);
   if (!res.success) {
     const issues = res.error.issues.map((i) => ({ path: i.path.join("."), message: i.message }));
-    throw new ManifestError(`${path17} is invalid: ${issues.map((i) => `${i.path}: ${i.message}`).join("; ")}`, issues);
+    throw new ManifestError(`${path18} is invalid: ${issues.map((i) => `${i.path}: ${i.message}`).join("; ")}`, issues);
   }
   return res.data;
 }
@@ -39923,8 +39924,8 @@ function asText(content) {
     return null;
   return typeof content === "string" ? content : new TextDecoder().decode(content);
 }
-function isYarkrOnly(path17) {
-  return path17 === MANIFEST_FILE || path17.startsWith("evals/") || path17.startsWith("fixtures/");
+function isYarkrOnly(path18) {
+  return path18 === MANIFEST_FILE || path18 === INDEX_FILE || path18.startsWith("evals/") || path18.startsWith("fixtures/");
 }
 function skillEntryPath(m) {
   return m.entry ?? "SKILL.md";
@@ -39952,10 +39953,10 @@ ${body.replace(/^\n+/, "")}`);
 function skillFolderFiles(pkg, dir, folderName) {
   const entry = skillEntryPath(pkg.manifest);
   const files = [{ package: pkg.manifest.name, path: join(dir, folderName, "SKILL.md"), content: renderSkillMd(pkg, folderName) }];
-  for (const [path17, content] of Object.entries(pkg.files)) {
-    if (path17 === entry || path17 === "SKILL.md" || isYarkrOnly(path17))
+  for (const [path18, content] of Object.entries(pkg.files)) {
+    if (path18 === entry || path18 === "SKILL.md" || isYarkrOnly(path18))
       continue;
-    files.push({ package: pkg.manifest.name, path: join(dir, folderName, path17), content });
+    files.push({ package: pkg.manifest.name, path: join(dir, folderName, path18), content });
   }
   return files;
 }
@@ -40049,13 +40050,13 @@ function nativeFolderHarness(o) {
     ...o.mcp ? {
       toolsets(servers, ctx) {
         const mcp = o.mcp;
-        const path17 = ctx.layout[slot];
-        if (!path17) {
+        const path18 = ctx.layout[slot];
+        if (!path18) {
           if (mcp.unavailable)
             ctx.out.notes.push(mcp.unavailable(servers));
           return;
         }
-        ctx.out.mcp.push({ path: path17, key: mcp.key, servers: Object.fromEntries(servers.map(({ pkg, server }) => [server.name, mcp.entry(pkg, server, ctx.out.notes)])) });
+        ctx.out.mcp.push({ path: path18, key: mcp.key, servers: Object.fromEntries(servers.map(({ pkg, server }) => [server.name, mcp.entry(pkg, server, ctx.out.notes)])) });
       }
     } : {}
   });
@@ -40240,10 +40241,10 @@ var cursor = defineHarness({
     const entry = skillEntryPath(pkg.manifest);
     const { data, body } = splitFrontmatter(asText(pkg.files[entry]) ?? "");
     const extra = [];
-    for (const [path17, content] of Object.entries(pkg.files)) {
-      if (path17 === entry || isYarkrOnly(path17))
+    for (const [path18, content] of Object.entries(pkg.files)) {
+      if (path18 === entry || isYarkrOnly(path18))
         continue;
-      const p = join(l.assets, name, path17);
+      const p = join(l.assets, name, path18);
       ctx.out.files.push({ package: pkg.manifest.name, path: p, content });
       extra.push(`- \`${p}\``);
     }
@@ -40314,9 +40315,9 @@ function folderExportHarness(id, rootDefault, opts = {}) {
       for (const pkg of byKind(input2, "agent")) {
         const name = names.get(pkg.manifest.name);
         const parts = agentParts(pkg, id, names, out);
-        for (const [path17, content] of Object.entries(pkg.files))
-          if (!isYarkrOnly(path17))
-            out.files.push({ package: pkg.manifest.name, path: join(root, "agents", name, path17), content });
+        for (const [path18, content] of Object.entries(pkg.files))
+          if (!isYarkrOnly(path18))
+            out.files.push({ package: pkg.manifest.name, path: join(root, "agents", name, path18), content });
         index2.push({ kind: "agent", name, package: pkg.manifest.name, version: pkg.manifest.version, description: pkg.manifest.description, model: parts.model, tools: parts.tools, skills: parts.skills, subagents: parts.subagents, system_prompt: join("agents", name, pkg.manifest.agent?.system_prompt ?? "") });
       }
       for (const pkg of byKind(input2, "toolset")) {
@@ -41125,17 +41126,41 @@ var dirname = (p) => p.includes("/") ? p.slice(0, p.lastIndexOf("/")) : "";
 var basename = (p) => p.slice(p.lastIndexOf("/") + 1);
 var under = (dir, p) => dir ? p.startsWith(`${dir}/`) : true;
 var rel = (dir, p) => dir ? p.slice(dir.length + 1) : p;
-function parseOverrides(text, path17, problems) {
+function parseOverrides(text, path18, problems) {
   if (text === null)
     return null;
   try {
     const raw = import_yaml3.default.parse(text);
     return raw && typeof raw === "object" ? raw : null;
   } catch (err) {
-    problems.push({ path: path17, message: `${MANIFEST_FILE} isn't valid YAML: ${err.message}` });
+    problems.push({ path: path18, message: `${MANIFEST_FILE} isn't valid YAML: ${err.message}` });
     return null;
   }
 }
+function parseIndex(text, path18, problems) {
+  let raw;
+  try {
+    raw = import_yaml3.default.parse(text ?? "");
+  } catch (err) {
+    problems.push({ path: path18, message: `isn't valid YAML: ${err.message}` });
+    return null;
+  }
+  const entries = (key) => {
+    const list = raw?.[key] ?? [];
+    if (!Array.isArray(list)) {
+      problems.push({ path: path18, message: `\`${key}\` must be a list.` });
+      return [];
+    }
+    return list.flatMap((e, i) => {
+      const entry = typeof e === "string" ? { path: e } : e;
+      if (entry && typeof entry === "object" && typeof entry.path === "string" && entry.path.trim())
+        return [{ ...entry, path: entry.path.replace(/^\.?\/+|\/+$/g, "") }];
+      problems.push({ path: path18, message: `${key}[${i}] needs a \`path\`.` });
+      return [];
+    });
+  };
+  return { skills: entries("skills"), agents: entries("agents"), toolsets: entries("toolsets"), detect: raw?.detect !== false };
+}
 var asList = (v) => Array.isArray(v) ? v.map(String) : typeof v === "string" ? v.split(",").map((s) => s.trim()).filter(Boolean) : [];
 async function detectAssets(input2) {
   const root = (input2.root ?? "").replace(/^\/+|\/+$/g, "");
@@ -41146,7 +41171,7 @@ async function detectAssets(input2) {
   const claimed = [];
   const isClaimed = (p) => claimed.some((d) => d ? p === d || p.startsWith(`${d}/`) : true);
   const filesBelow = (dir) => new Map(paths.filter((p) => under(dir, p)).map((p) => [rel(dir, p), p]));
-  const make = (name, kind, path17, files, o, extra) => {
+  const make = (name, kind, path18, files, o, extra) => {
     const suites = [...files.keys()].filter((p) => SUITE.test(p));
     const raw = {
       name: `${input2.namespace}/${slugify2(name)}`,
@@ -41165,19 +41190,109 @@ async function detectAssets(input2) {
     };
     const res = Manifest.safeParse(raw);
     if (!res.success) {
-      problems.push({ path: path17, message: res.error.issues.map((i) => `${i.path.join(".") || "manifest"}: ${i.message}`).join("; ") });
+      problems.push({ path: path18, message: res.error.issues.map((i) => `${i.path.join(".") || "manifest"}: ${i.message}`).join("; ") });
       return null;
     }
-    return { name: slugify2(name), kind, path: path17, manifest: res.data, files };
+    return { name: slugify2(name), kind, path: path18, manifest: res.data, files };
   };
   const manifestNear = async (dir, from) => {
     const mp = dir ? `${dir}/${MANIFEST_FILE}` : MANIFEST_FILE;
     return paths.includes(mp) ? parseOverrides(await input2.read(mp), from, problems) ?? {} : {};
   };
+  const readFrontmatter = async (p) => {
+    try {
+      return splitFrontmatter(await input2.read(p) ?? "").data;
+    } catch (err) {
+      problems.push({ path: p, message: `frontmatter isn't valid YAML: ${err.message}` });
+      return null;
+    }
+  };
+  const agentAsset = (p, fm, e = {}) => {
+    const name = e.name ?? (typeof fm.name === "string" && fm.name.trim() ? fm.name : basename(p).replace(/\.md$/, ""));
+    const skills = asList(e.skills ?? fm.skills);
+    const depends = skills.length ? { skills: Object.fromEntries(skills.map((s) => [s.includes("/") ? s : `${input2.namespace}/${slugify2(s)}`, "*"])) } : {};
+    const model = e.model ?? fm.model;
+    return make(name, "agent", p, /* @__PURE__ */ new Map([["AGENT.md", p]]), { targets: e.targets, tags: e.tags, evals: e.evals }, {
+      description: e.description ?? String(fm.description),
+      depends,
+      agent: { system_prompt: "AGENT.md", model: typeof model === "string" ? model : void 0, tools: asList(e.tools ?? fm.tools), subagents: [] }
+    });
+  };
+  const indexPath = root ? `${root}/${INDEX_FILE}` : INDEX_FILE;
+  const index2 = paths.includes(indexPath) ? parseIndex(await input2.read(indexPath), indexPath, problems) : null;
+  const listed = /* @__PURE__ */ new Set();
+  const at = (e) => root ? `${root}/${e.path}` : e.path;
+  const missing = (p, what) => problems.push({ path: indexPath, message: `${p} isn't in the repo (listed under ${what}).` });
+  for (const e of index2?.skills ?? []) {
+    const p = at(e);
+    const isFile = paths.includes(p);
+    if (!isFile && !paths.some((x) => x.startsWith(`${p}/`))) {
+      missing(p, "skills");
+      continue;
+    }
+    const entry = isFile ? basename(p) : e.entry ?? (paths.includes(`${p}/SKILL.md`) ? "SKILL.md" : "README.md");
+    const entryPath = isFile ? p : `${p}/${entry}`;
+    if (!paths.includes(entryPath)) {
+      problems.push({ path: indexPath, message: `${p} has no ${entry}. Set \`entry\` to the file with the skill's instructions.` });
+      continue;
+    }
+    const fm = await readFrontmatter(entryPath);
+    if (!fm)
+      continue;
+    const description = e.description ?? (typeof fm.description === "string" ? fm.description : "");
+    if (!description) {
+      problems.push({ path: indexPath, message: `${p} needs a \`description\` (here or in its frontmatter): harnesses use it to decide when to load the skill.` });
+      continue;
+    }
+    listed.add(entryPath);
+    if (!isFile)
+      claimed.push(p);
+    const name = e.name ?? (typeof fm.name === "string" && fm.name.trim() ? fm.name : basename(p).replace(/\.mdc?$/, ""));
+    const near = isFile ? {} : await manifestNear(p, entryPath);
+    const o = { ...near, ...e.targets && { targets: e.targets }, ...e.tags && { tags: e.tags }, ...e.evals && { evals: e.evals }, ...entry !== "SKILL.md" && { entry } };
+    const asset = make(name, "skill", p, isFile ? /* @__PURE__ */ new Map([[entry, p]]) : filesBelow(p), o, { description });
+    if (asset)
+      found.push(asset);
+  }
+  for (const e of index2?.agents ?? []) {
+    const p = at(e);
+    if (!paths.includes(p)) {
+      missing(p, "agents");
+      continue;
+    }
+    const fm = await readFrontmatter(p);
+    if (!fm)
+      continue;
+    if (!e.description && typeof fm.description !== "string") {
+      problems.push({ path: indexPath, message: `${p} needs a \`description\` (here or in its frontmatter): it says when to hand work to the agent.` });
+      continue;
+    }
+    listed.add(p);
+    const asset = agentAsset(p, fm, e);
+    if (asset)
+      found.push(asset);
+  }
+  for (const e of index2?.toolsets ?? []) {
+    const p = at(e);
+    if (!paths.includes(p)) {
+      missing(p, "toolsets");
+      continue;
+    }
+    listed.add(p);
+    const servers = toolsetServers2(await input2.read(p), p, problems);
+    if (!servers)
+      continue;
+    const description = e.description ?? `MCP servers: ${servers.map((s) => s.name).join(", ")}`;
+    const o = { targets: e.targets, tags: e.tags, evals: e.evals };
+    const asset = make(e.name ?? input2.repoName, "toolset", p, /* @__PURE__ */ new Map([[".mcp.json", p]]), o, { description, toolset: { servers, tool_schemas: [] } });
+    if (asset)
+      found.push(asset);
+  }
+  const detect = index2?.detect ?? true;
   const depth = (p) => p.split("/").length;
-  for (const p of paths.filter((x) => basename(x) === "SKILL.md").sort((a, b) => depth(a) - depth(b) || a.localeCompare(b))) {
+  for (const p of paths.filter((x) => detect && basename(x) === "SKILL.md").sort((a, b) => depth(a) - depth(b) || a.localeCompare(b))) {
     const dir = dirname(p);
-    if (isClaimed(dir))
+    if (isClaimed(dir) || listed.has(p))
       continue;
     let fm;
     try {
@@ -41197,7 +41312,7 @@ async function detectAssets(input2) {
     if (asset)
       found.push(asset);
   }
-  for (const p of paths.filter((x) => basename(x) === MANIFEST_FILE)) {
+  for (const p of paths.filter((x) => detect && basename(x) === MANIFEST_FILE)) {
     const dir = dirname(p);
     if (isClaimed(dir))
       continue;
@@ -41210,34 +41325,15 @@ async function detectAssets(input2) {
     if (asset)
       found.push(asset);
   }
-  for (const p of paths.filter((x) => AGENT_FILE.test(x) && !isClaimed(dirname(x)))) {
-    const text = await input2.read(p) ?? "";
-    let fm;
-    try {
-      fm = splitFrontmatter(text).data;
-    } catch (err) {
-      problems.push({ path: p, message: `frontmatter isn't valid YAML: ${err.message}` });
+  for (const p of paths.filter((x) => detect && AGENT_FILE.test(x) && !listed.has(x) && !isClaimed(dirname(x)))) {
+    const fm = await readFrontmatter(p);
+    if (!fm || typeof fm.description !== "string")
       continue;
-    }
-    if (typeof fm.description !== "string")
-      continue;
-    const name = typeof fm.name === "string" && fm.name.trim() ? fm.name : basename(p).replace(/\.md$/, "");
-    const skills = asList(fm.skills);
-    const depends = skills.length ? { skills: Object.fromEntries(skills.map((s) => [s.includes("/") ? s : `${input2.namespace}/${slugify2(s)}`, "*"])) } : {};
-    const asset = make(name, "agent", p, /* @__PURE__ */ new Map([["AGENT.md", p]]), {}, {
-      description: fm.description,
-      depends,
-      agent: {
-        system_prompt: "AGENT.md",
-        model: typeof fm.model === "string" ? fm.model : void 0,
-        tools: asList(fm.tools),
-        subagents: []
-      }
-    });
+    const asset = agentAsset(p, fm);
     if (asset)
       found.push(asset);
   }
-  for (const p of paths.filter((x) => TOOLSET_FILE.test(rel(root, x)) && !isClaimed(dirname(x)))) {
+  for (const p of paths.filter((x) => detect && TOOLSET_FILE.test(rel(root, x)) && !listed.has(x) && !isClaimed(dirname(x)))) {
     const dir = dirname(p);
     const name = TOOLSET_FILE.exec(rel(root, p))[1] ?? input2.repoName;
     const servers = toolsetServers2(await input2.read(p), p, problems);
@@ -41260,16 +41356,16 @@ async function detectAssets(input2) {
   }
   return { assets: [...byName.values()], problems };
 }
-function toolsetServers2(text, path17, problems) {
+function toolsetServers2(text, path18, problems) {
   let doc;
   try {
     doc = JSON.parse(text ?? "");
   } catch (err) {
-    problems.push({ path: path17, message: `isn't valid JSON: ${err.message}` });
+    problems.push({ path: path18, message: `isn't valid JSON: ${err.message}` });
     return null;
   }
   const out = [];
-  for (const [name, s] of Object.entries(doc.mcpServers ?? {})) {
+  for (const [name, s] of Object.entries(doc.mcpServers ?? doc.servers ?? {})) {
     const http = s.type === "http" || s.type === "sse" || typeof s.url === "string" && !s.command;
     const refs = (field) => {
       const map2 = s[field] ?? {};
@@ -41278,7 +41374,7 @@ function toolsetServers2(text, path17, problems) {
         const ref = String(v).replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-[^}]*)?\}/g, "${env:$1}");
         const plain = ref.replace(/^Bearer /, "");
         if (!SECRET_REF.test(plain)) {
-          problems.push({ path: path17, message: `${name}.${field}.${k} is a literal value. Use \${${k.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}} or \${vault:path#key} so no secret lives in the repo.` });
+          problems.push({ path: path18, message: `${name}.${field}.${k} is a literal value. Use \${${k.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}} or \${vault:path#key} so no secret lives in the repo.` });
           return null;
         }
         res[k] = ref;
@@ -41298,7 +41394,7 @@ function toolsetServers2(text, path17, problems) {
     });
   }
   if (!out.length) {
-    problems.push({ path: path17, message: "has no mcpServers." });
+    problems.push({ path: path18, message: "has no mcpServers." });
     return null;
   }
   return out;
@@ -41422,8 +41518,8 @@ function verifyBundle(b, key, requireSignature) {
   return { manifest: b.manifest, files, content_hash: b.content_hash };
 }
 var TEXT_EXT = /\.(md|mdc|mdx|markdown|txt|ya?ml|json|toml|py|sh|bash|js|mjs|cjs|ts|tsx|csv|html|css|xml|sql|rb|go|rs|java|ini|cfg|env)$/i;
-function looksText(path17, bytes) {
-  if (TEXT_EXT.test(path17)) return true;
+function looksText(path18, bytes) {
+  if (TEXT_EXT.test(path18)) return true;
   const n = Math.min(bytes.length, 4096);
   for (let i = 0; i < n; i++) if (bytes[i] === 0) return false;
   try {
@@ -41991,16 +42087,16 @@ var Diff = class {
       }
     }
   }
-  addToPath(path17, added, removed, oldPosInc, options) {
-    const last = path17.lastComponent;
+  addToPath(path18, added, removed, oldPosInc, options) {
+    const last = path18.lastComponent;
     if (last && !options.oneChangePerToken && last.added === added && last.removed === removed) {
       return {
-        oldPos: path17.oldPos + oldPosInc,
+        oldPos: path18.oldPos + oldPosInc,
         lastComponent: { count: last.count + 1, added, removed, previousComponent: last.previousComponent }
       };
     } else {
       return {
-        oldPos: path17.oldPos + oldPosInc,
+        oldPos: path18.oldPos + oldPosInc,
         lastComponent: { count: 1, added, removed, previousComponent: last }
       };
     }
@@ -42642,10 +42738,10 @@ async function loadSuites(candidate, candFiles, shared) {
   }
   return out;
 }
-function parseSuite(bytes, ref, path17, source) {
+function parseSuite(bytes, ref, path18, source) {
   const text = bytes.toString("utf8");
   try {
-    return { suite: parseEvalSuite(text, path17), ref, path: path17, source, hash: sha256(text) };
+    return { suite: parseEvalSuite(text, path18), ref, path: path18, source, hash: sha256(text) };
   } catch (err) {
     throw new SuiteError(err.message);
   }
@@ -44146,7 +44242,7 @@ async function registrySnapshot(api, name, opts = {}) {
   const rel2 = await api.resolve(name, { channel: opts.channel ?? "stable", range: opts.range });
   const bundle = await api.bundle(name, rel2.version);
   const files = new Map(bundle.files.map((f) => [f.path, Buffer.from(f.content, "base64")]));
-  const tree = buildTree([...files].map(([path17, bytes]) => ({ path: path17, bytes })));
+  const tree = buildTree([...files].map(([path18, bytes]) => ({ path: path18, bytes })));
   return { snapshot: { name, label: bundle.version, contentHash: bundle.content_hash, manifest: bundle.manifest, tree }, files };
 }
 function registrySuiteResolver(getApi) {
@@ -44716,7 +44812,8 @@ import path16 from "path";
 
 // ../../packages/core/dist/guides/content.generated.js
 var GUIDE_CONTENT = {
-  "create-ark": '---\nname: create-ark\ndescription: Build a Yarkr ark (a set of skills, agents or MCP configs handed to a team) for a given topic and type. Use when asked to create, assemble or curate an ark, or to collect a topic\'s skills, agents or MCP servers for a team in Yarkr.\n---\n\n# Creating an ark from a topic and a type\n\nYou get two inputs and build one [ark](https://github.com/posterus-ltd/yarkr-public/blob/main/docs/arks.md) that hands out packages on that topic.\n\n| Input | Example | Meaning |\n| --- | --- | --- |\n| **topic** | `invoice processing`, `frontend testing` | what the ark is about |\n| **type** | `skill`, `agent` or `mcp` | the kind of package it holds. `mcp` is a **toolset** in Yarkr (`--kind toolset`, `kind: toolset`) |\n\nPlus, from the user or their config: the **org** (its slug is its GitHub login, lowercased), and whether the ark should\nbe **public**. Ask for the org if you can\'t tell; default to private.\n\nAn ark only points at packages. Packages come from GitHub ([github.md](https://github.com/posterus-ltd/yarkr-public/blob/main/docs/github.md)): there is no way to upload content to\nYarkr directly. So the work is: find what exists, write what\'s missing in a repo, then assemble the ark.\n\n```\n1. plan \u2500\u2500\u25B6 2. find existing \u2500\u2500\u25B6 3. author missing (PR) \u2500\u2500\u25B6 4. wait for index \u2500\u2500\u25B6 5. create ark + items \u2500\u2500\u25B6 6. verify\n```\n\n---\n\n## 1. Plan\n\n- **Ark name:** a slug, `^[a-z0-9][a-z0-9-]*$`, short and named after the topic: `invoice-processing`, not\n  `ark-for-invoices`. It must be unique in the org.\n- **Description:** one sentence, at most 500 characters, saying who it\'s for and what they get.\n- **Scope:** aim for 3 to 8 packages. Every skill in an ark goes into every member\'s context; too many makes agents\n  worse. Split a broad topic into several arks rather than one big one.\n- List the packages you expect to need, each with a one-line purpose, before searching.\n\n## 2. Find what already exists\n\nReuse beats writing. Search the registry for each planned package:\n\n```bash\nyarkr search "<topic words>" --kind <skill|agent|toolset> --json\nyarkr info <namespace>/<name>        # source repo, targets, releases, eval results\n```\n\nOver MCP, `search_packages` with `scope: "all"`, then `get_skill` / `get_agent` / `get_toolset` to read one.\n\nKeep a package when:\n\n- its description and body actually cover the planned purpose (read it, don\'t trust the name);\n- the org can put it in an ark: **the org\'s own namespace, or any public package**;\n- for a public ark: **it is public**. A public ark can hold nothing else;\n- it isn\'t yanked or archived, and has evals that pass if any are shown.\n\n## 3. Author what\'s missing\n\nWrite each missing package in one of the org\'s **connected** repos (check **Settings \u2192 GitHub** / `/orgs/<org>/github`;\na repo that isn\'t connected is never indexed). For a public ark the repo must be public. Open **one pull request** with\nall new packages, and describe the ark they\'re for. Merging is publishing; don\'t push to the default branch yourself\nunless the user tells you to.\n\nPackage names come from the folder or `name:` frontmatter, slugified, and publish as `<org>/<name>`. Check that the name\ndoesn\'t already exist in the org.\n\n### Type `skill`\n\nA folder with `SKILL.md`. Everything in the folder ships with it. This guide is itself one.\n\n```\nskills/<name>/\n  SKILL.md\n  references/\u2026      # optional: long docs the skill loads on demand\n  scripts/\u2026         # optional\n  evals/core.yaml   # optional but recommended, see https://github.com/posterus-ltd/yarkr-public/blob/main/docs/evals.md\n```\n\n```markdown\n---\nname: <name>\ndescription: <what it does and when to use it. Harnesses decide whether to load the skill from this line alone, so name the trigger situations.>\n---\n\n# <Title>\n\n<Steps the agent follows. Concrete and imperative. Point to references/ for anything long.>\n```\n\n`description` is required; without it the skill isn\'t indexed.\n\n### Type `agent`\n\nOne markdown file under `agents/` (or `.claude/agents/`).\n\n```markdown\n---\nname: <name>\ndescription: <when to hand work to this agent>\nmodel: <optional>\ntools: Read, Grep, Bash          # optional\nskills: <skill-name>, other-org/skill   # optional: dependencies, installed with the agent\n---\n\n<System prompt: role, what it does, how it decides, what it returns.>\n```\n\n- `description` is required; a file without it is treated as a plain doc.\n- A bare name in `skills:` means a skill in the same org. Use `ns/name` for another namespace. A skill the agent needs\n  that doesn\'t exist yet is part of this same PR.\n- Add the agent\'s skills to the ark too, or leave them to the dependency: `yarkr sync` installs dependencies either way.\n\n### Type `mcp` (toolset)\n\nOne toolset per folder, in Claude Code\'s `.mcp.json` format:\n\n```\ntoolsets/<name>/\n  .mcp.json\n  README.md         # first paragraph becomes the description\n```\n\n```json\n{\n  "mcpServers": {\n    "<server>": {\n      "type": "http",\n      "url": "https://mcp.example.com/mcp",\n      "headers": { "Authorization": "Bearer ${EXAMPLE_TOKEN}" }\n    }\n  }\n}\n```\n\n- **No literal secrets.** Values in `env` and `headers` must be `${VAR}` (becomes `${env:VAR}`), `${VAR:-default}`\n  or `${vault:path#key}`. A literal value is refused.\n- Prefer servers you can verify exist: the vendor\'s official server, or a well-known package for `stdio` (`npx -y \u2026`).\n  Never invent a URL or package name. If you can\'t confirm one, stop and ask.\n- Document in the README which variables each user must set.\n\n### Optional `yarkr.yaml`\n\nNext to any asset, for what can\'t be inferred:\n\n```yaml\ntargets: [claude-code, codex]   # default: every harness\ntags: [<topic>, \u2026]              # helps search; use the topic\nevals: [evals/core.yaml]\n```\n\n## 4. Wait for the index\n\nAfter the PR merges, the push is indexed in the background, usually within a minute. Each package\'s first release is a\nsnapshot of the default branch (`0.0.0-main.\u2026`) unless a tag says otherwise.\n\n```bash\nyarkr info <org>/<name>     # repeat until it shows a stable version\n```\n\nIf it never appears, check the repo\'s row on the org\'s GitHub page: detection problems (missing description, literal\nsecret, name clash) are listed there. Fix them in a new PR.\n\n## 5. Create the ark and add items\n\nArk changes need an **org admin** and a **read and write** token. There\'s no CLI command for this; use the web app\n(**Arks \u2192 your org**) or the API. The base URL is the registry (`yarkr whoami` prints it; the hub is\n`https://api.yarkr.com/functions/v1/api`).\n\n```bash\nAPI=https://api.yarkr.com/functions/v1/api/api/v1\nAUTH="Authorization: Bearer $YARKR_TOKEN"\n\n# Create\ncurl -sf -X POST "$API/arks/<org>" -H "$AUTH" -H \'content-type: application/json\' \\\n  -d \'{"name":"<ark>","description":"<one sentence>"}\'\n\n# One call per package\ncurl -sf -X PUT "$API/arks/<org>/<ark>/items/<ns>/<name>" -H "$AUTH" -H \'content-type: application/json\' \\\n  -d \'{"range":"^1","required":true}\'\n```\n\nItem body:\n\n| Field | Use |\n| --- | --- |\n| `range` | Semver range. Use `^<major>` for tagged packages. Omit it (and `channel`) to follow `stable`, which suits new snapshot-only packages |\n| `channel` | Instead of a range, e.g. `stable` |\n| `required` | `true` for the core of the topic; `false` for extras members may exclude |\n| `config` | Toolsets only: per-ark overrides, `{"servers": {"<server>": {"env": {\u2026}, "headers": {\u2026}, "args": [\u2026], "url": "\u2026"}}}`. Secret values must be `${env:\u2026}` or `${vault:\u2026}` |\n\nThe server rejects an item that the org can\'t use, a private package in a public ark, a bad range, a literal secret,\nor a range that conflicts with another ark sharing a member. Read the error and fix the cause; don\'t retry blindly.\n\nThen, only if asked:\n\n```bash\n# Make it public (public packages only)\ncurl -sf -X PATCH "$API/arks/<org>/<ark>" -H "$AUTH" -H \'content-type: application/json\' -d \'{"public":true}\'\n\n# Add members (they must already belong to the org)\ncurl -sf -X POST "$API/arks/<org>/<ark>/members" -H "$AUTH" -H \'content-type: application/json\' -d \'{"email":"\u2026"}\'\n```\n\n## 6. Verify\n\n```bash\ncurl -sf "$API/arks/<org>/<ark>" -H "$AUTH"           # items, ranges, description\nyarkr ark lint <org>/<ark> --strict                     # fix every error and warning it reports\nyarkr sync <org>/<ark> --dry-run --harness claude-code  # resolves every item without writing files\n```\n\nFor a public ark, also check `yarkr arks` lists it.\n\n## Report back\n\nTell the user:\n\n- the ark (`<org>/<ark>`), its description and whether it\'s public;\n- each item: reused or new, range, required or optional, one line on why it\'s there;\n- the PR link for new packages, and whether it\'s merged;\n- what\'s left for them: merging the PR, adding members, setting the toolset variables listed in the READMEs, and how\n  people get it (`yarkr sync <org>/<ark>`, or `yarkr mcp add <org>/<ark>`).\n\n## Don\'ts\n\n- Don\'t put literal secrets anywhere: repo, ark config or PR description.\n- Don\'t add packages you haven\'t read.\n- Don\'t make an ark public, add members, or merge a PR unless the user asked.\n- Don\'t pad the ark to reach a number. Three good packages beat eight vague ones.\n'
+  "create-ark": '---\nname: create-ark\ndescription: Build a Yarkr ark (a set of skills, agents or MCP configs handed to a team) for a given topic and type. Use when asked to create, assemble or curate an ark, or to collect a topic\'s skills, agents or MCP servers for a team in Yarkr.\n---\n\n# Creating an ark from a topic and a type\n\nYou get two inputs and build one [ark](https://github.com/posterus-ltd/yarkr-public/blob/main/docs/arks.md) that hands out packages on that topic.\n\n| Input | Example | Meaning |\n| --- | --- | --- |\n| **topic** | `invoice processing`, `frontend testing` | what the ark is about |\n| **type** | `skill`, `agent` or `mcp` | the kind of package it holds. `mcp` is a **toolset** in Yarkr (`--kind toolset`, `kind: toolset`) |\n\nPlus, from the user or their config: the **org** (its slug is its GitHub login, lowercased), and whether the ark should\nbe **public**. Ask for the org if you can\'t tell; default to private.\n\nAn ark only points at packages. Packages come from GitHub ([github.md](https://github.com/posterus-ltd/yarkr-public/blob/main/docs/github.md)): there is no way to upload content to\nYarkr directly. So the work is: find what exists, write what\'s missing in a repo, then assemble the ark.\n\n```\n1. plan \u2500\u2500\u25B6 2. find existing \u2500\u2500\u25B6 3. author missing (PR) \u2500\u2500\u25B6 4. wait for index \u2500\u2500\u25B6 5. create ark + items \u2500\u2500\u25B6 6. verify\n```\n\n---\n\n## 1. Plan\n\n- **Ark name:** a slug, `^[a-z0-9][a-z0-9-]*$`, short and named after the topic: `invoice-processing`, not\n  `ark-for-invoices`. It must be unique in the org.\n- **Description:** one sentence, at most 500 characters, saying who it\'s for and what they get.\n- **Scope:** aim for 3 to 8 packages. Every skill in an ark goes into every member\'s context; too many makes agents\n  worse. Split a broad topic into several arks rather than one big one.\n- List the packages you expect to need, each with a one-line purpose, before searching.\n\n## 2. Find what already exists\n\nReuse beats writing. Search the registry for each planned package:\n\n```bash\nyarkr search "<topic words>" --kind <skill|agent|toolset> --json\nyarkr info <namespace>/<name>        # source repo, targets, releases, eval results\n```\n\nOver MCP, `search_packages` with `scope: "all"`, then `get_skill` / `get_agent` / `get_toolset` to read one.\n\nKeep a package when:\n\n- its description and body actually cover the planned purpose (read it, don\'t trust the name);\n- the org can put it in an ark: **the org\'s own namespace, or any public package**;\n- for a public ark: **it is public**. A public ark can hold nothing else;\n- it isn\'t yanked or archived, and has evals that pass if any are shown.\n\n## 3. Author what\'s missing\n\nWrite each missing package in one of the org\'s **connected** repos (check **Settings \u2192 GitHub** / `/orgs/<org>/github`;\na repo that isn\'t connected is never indexed). For a public ark the repo must be public. Open **one pull request** with\nall new packages, and describe the ark they\'re for. Merging is publishing; don\'t push to the default branch yourself\nunless the user tells you to.\n\nPackage names come from the folder or `name:` frontmatter, slugified, and publish as `<org>/<name>`. Check that the name\ndoesn\'t already exist in the org.\n\n### Type `skill`\n\nA folder with `SKILL.md`. Everything in the folder ships with it. This guide is itself one.\n\n```\nskills/<name>/\n  SKILL.md\n  references/\u2026      # optional: long docs the skill loads on demand\n  scripts/\u2026         # optional\n  evals/core.yaml   # optional but recommended, see https://github.com/posterus-ltd/yarkr-public/blob/main/docs/evals.md\n```\n\n```markdown\n---\nname: <name>\ndescription: <what it does and when to use it. Harnesses decide whether to load the skill from this line alone, so name the trigger situations.>\n---\n\n# <Title>\n\n<Steps the agent follows. Concrete and imperative. Point to references/ for anything long.>\n```\n\n`description` is required; without it the skill isn\'t indexed.\n\n### Type `agent`\n\nOne markdown file under `agents/` (or `.claude/agents/`).\n\n```markdown\n---\nname: <name>\ndescription: <when to hand work to this agent>\nmodel: <optional>\ntools: Read, Grep, Bash          # optional\nskills: <skill-name>, other-org/skill   # optional: dependencies, installed with the agent\n---\n\n<System prompt: role, what it does, how it decides, what it returns.>\n```\n\n- `description` is required; a file without it is treated as a plain doc.\n- A bare name in `skills:` means a skill in the same org. Use `ns/name` for another namespace. A skill the agent needs\n  that doesn\'t exist yet is part of this same PR.\n- Add the agent\'s skills to the ark too, or leave them to the dependency: `yarkr sync` installs dependencies either way.\n\n### Type `mcp` (toolset)\n\nOne toolset per folder, in Claude Code\'s `.mcp.json` format:\n\n```\ntoolsets/<name>/\n  .mcp.json\n  README.md         # first paragraph becomes the description\n```\n\n```json\n{\n  "mcpServers": {\n    "<server>": {\n      "type": "http",\n      "url": "https://mcp.example.com/mcp",\n      "headers": { "Authorization": "Bearer ${EXAMPLE_TOKEN}" }\n    }\n  }\n}\n```\n\n- **No literal secrets.** Values in `env` and `headers` must be `${VAR}` (becomes `${env:VAR}`), `${VAR:-default}`\n  or `${vault:path#key}`. A literal value is refused.\n- Prefer servers you can verify exist: the vendor\'s official server, or a well-known package for `stdio` (`npx -y \u2026`).\n  Never invent a URL or package name. If you can\'t confirm one, stop and ask.\n- Document in the README which variables each user must set.\n\n### Optional `yarkr.yaml`\n\nNext to any asset, for what can\'t be inferred:\n\n```yaml\ntargets: [claude-code, codex]   # default: every harness\ntags: [<topic>, \u2026]              # helps search; use the topic\nevals: [evals/core.yaml]\n```\n\n## 4. Wait for the index\n\nAfter the PR merges, the push is indexed in the background, usually within a minute. Each package\'s first release is a\nsnapshot of the default branch (`0.0.0-main.\u2026`) unless a tag says otherwise.\n\n```bash\nyarkr info <org>/<name>     # repeat until it shows a stable version\n```\n\nIf it never appears, check the repo\'s row on the org\'s GitHub page: detection problems (missing description, literal\nsecret, name clash) are listed there. Fix them in a new PR.\n\n## 5. Create the ark and add items\n\nArk changes need an **org admin** and a **read and write** token. There\'s no CLI command for this; use the web app\n(**Arks \u2192 your org**) or the API. The base URL is the registry (`yarkr whoami` prints it; the hub is\n`https://api.yarkr.com/functions/v1/api`).\n\n```bash\nAPI=https://api.yarkr.com/functions/v1/api/api/v1\nAUTH="Authorization: Bearer $YARKR_TOKEN"\n\n# Create\ncurl -sf -X POST "$API/arks/<org>" -H "$AUTH" -H \'content-type: application/json\' \\\n  -d \'{"name":"<ark>","description":"<one sentence>"}\'\n\n# One call per package\ncurl -sf -X PUT "$API/arks/<org>/<ark>/items/<ns>/<name>" -H "$AUTH" -H \'content-type: application/json\' \\\n  -d \'{"range":"^1","required":true}\'\n```\n\nItem body:\n\n| Field | Use |\n| --- | --- |\n| `range` | Semver range. Use `^<major>` for tagged packages. Omit it (and `channel`) to follow `stable`, which suits new snapshot-only packages |\n| `channel` | Instead of a range, e.g. `stable` |\n| `required` | `true` for the core of the topic; `false` for extras members may exclude |\n| `config` | Toolsets only: per-ark overrides, `{"servers": {"<server>": {"env": {\u2026}, "headers": {\u2026}, "args": [\u2026], "url": "\u2026"}}}`. Secret values must be `${env:\u2026}` or `${vault:\u2026}` |\n\nThe server rejects an item that the org can\'t use, a private package in a public ark, a bad range, a literal secret,\nor a range that conflicts with another ark sharing a member. Read the error and fix the cause; don\'t retry blindly.\n\nThen, only if asked:\n\n```bash\n# Make it public (public packages only)\ncurl -sf -X PATCH "$API/arks/<org>/<ark>" -H "$AUTH" -H \'content-type: application/json\' -d \'{"public":true}\'\n\n# Add members (they must already belong to the org)\ncurl -sf -X POST "$API/arks/<org>/<ark>/members" -H "$AUTH" -H \'content-type: application/json\' -d \'{"email":"\u2026"}\'\n```\n\n## 6. Verify\n\n```bash\ncurl -sf "$API/arks/<org>/<ark>" -H "$AUTH"           # items, ranges, description\nyarkr ark lint <org>/<ark> --strict                     # fix every error and warning it reports\nyarkr sync <org>/<ark> --dry-run --harness claude-code  # resolves every item without writing files\n```\n\nFor a public ark, also check `yarkr arks` lists it.\n\n## Report back\n\nTell the user:\n\n- the ark (`<org>/<ark>`), its description and whether it\'s public;\n- each item: reused or new, range, required or optional, one line on why it\'s there;\n- the PR link for new packages, and whether it\'s merged;\n- what\'s left for them: merging the PR, adding members, setting the toolset variables listed in the READMEs, and how\n  people get it (`yarkr sync <org>/<ark>`, or `yarkr mcp add <org>/<ark>`).\n\n## Don\'ts\n\n- Don\'t put literal secrets anywhere: repo, ark config or PR description.\n- Don\'t add packages you haven\'t read.\n- Don\'t make an ark public, add members, or merge a PR unless the user asked.\n- Don\'t pad the ark to reach a number. Three good packages beat eight vague ones.\n',
+  "index-repo": "---\nname: index-repo\ndescription: Make an existing repo a Yarkr source by adding one yarkr.index.yaml that points at the skills, agents and MCP configs already in it, in whatever layout they have, without moving or rewriting files. Use when asked to publish a repo's skills to Yarkr, make a repo Yarkr-compatible or conforming, or when lint or the hub doesn't find skills that are in the repo.\n---\n\n# Making a repo a Yarkr source\n\nYarkr publishes skills, agents and MCP configs (toolsets) from GitHub repos\n([github.md](https://github.com/posterus-ltd/yarkr-public/blob/main/docs/github.md)). It already finds assets in their\nusual layouts. Skills kept any other way (a single markdown file, a folder with a README instead of `SKILL.md`, no\nfrontmatter) are listed in one file at the repo root, `yarkr.index.yaml`, which says where each one lives and adds the\nname and description the file itself lacks. Agents and MCP configs work the same way.\n\n**The goal is the smallest possible diff:** ideally one new file. Don't move, rename or reformat existing files, and\ndon't add frontmatter to them: the index carries it. The only edits to existing files you may need are removing literal\nsecrets from MCP configs (step 5).\n\n```\n1. lint \u2500\u2500\u25B6 2. survey \u2500\u2500\u25B6 3. choose \u2500\u2500\u25B6 4. write yarkr.index.yaml \u2500\u2500\u25B6 5. fix secrets \u2500\u2500\u25B6 6. lint clean \u2500\u2500\u25B6 7. PR\n```\n\n---\n\n## 1. See what Yarkr already finds\n\nFrom the repo root:\n\n```bash\nnpx yarkr-cli lint            # or `yarkr lint`; --json for machine-readable output\n```\n\nIt lists every asset that would be published (name, kind, path, description), using the same detector as the hub,\nthen **errors** (what the hub would refuse) and **warnings** (unknown index keys, descriptions that don't say when to\nuse the asset, agent skills missing from the repo). These are found without an index:\n\n| Layout | Becomes |\n| --- | --- |\n| `<dir>/SKILL.md` with `description` frontmatter | a skill; the whole folder ships with it |\n| `agents/<name>.md`, `.claude/agents/<name>.md` with `description` frontmatter | an agent |\n| `.mcp.json` at the root, `toolsets/<name>/.mcp.json` | a toolset |\n\nAnything listed here needs no index entry. Fix what it reports in step 4 or 5.\n\n## 2. Find the skills Yarkr misses\n\nLook for skills, agents and MCP configs that step 1 didn't list. They're usually there, just in a different shape:\n\n| You find | It is | In the index |\n| --- | --- | --- |\n| A folder of instructions plus scripts or references, with `README.md` (or another `.md`) instead of `SKILL.md` | a skill | `path` to the folder, `entry` to its instructions file |\n| A single markdown file with a skill's instructions (`ai/skills/code-review.md`) | a skill | `path` to the file |\n| A `SKILL.md` without `description` frontmatter | a skill | `path` plus `description`, instead of editing the file |\n| Skills under a folder that Yarkr ignores, or nested inside another skill | skills | one entry each |\n| An agent definition outside `agents/` or `.claude/agents/`, or without `description` | an agent | `path`, `description`, and its `skills` |\n| An MCP config other than a root `.mcp.json` or `toolsets/<name>/.mcp.json` (`.cursor/mcp.json`, `.vscode/mcp.json`) | a toolset | `path` and `name` |\n\nSearch by content as well as by name: skills tend to have imperative steps for a task and a \"when to use\" line.\nIgnore `node_modules`, vendored code, test fixtures, generated files, and examples that show a format rather than\nbeing a skill.\n\n## 3. Choose what to publish\n\nPublish a skill only if **someone outside this repo would load it** for a recognisable task. For each one, decide:\n\n- **Kind.** Steps for a task are a **skill**. A role the main agent delegates to (with its own system prompt, tools,\n  maybe model) is an **agent**. MCP server config is a **toolset**.\n- **Keep out:** `CLAUDE.md`, `AGENTS.md` and other files that only describe this codebase (its layout, commands,\n  conventions). They're project context, not skills.\n- **Description.** One or two sentences: what it does, then *when to use it* (\"Use when \u2026\"). Harnesses decide whether\n  to load a skill from this line alone, so name the trigger situations. Read the file; don't guess from its name.\n- **Name.** A short slug, unique in the repo, `<org>/<name>` once published. Defaults to the frontmatter `name`, else the\n  file or folder name. Set `name` when the default is vague (`README`, `howto`).\n- **A file or a folder.** A lone markdown file is a skill on its own. If it relies on scripts, templates or references\n  next to it, point at the folder instead, with `entry` naming the instructions file.\n\nIf unsure whether something belongs, ask the user with your shortlist rather than publishing everything.\n\n## 4. Write `yarkr.index.yaml`\n\nAt the repo root (or at the **root folder** set when the repo was connected). Paths are relative to the index file.\nList only what step 1 didn't already find.\n\n```yaml\n# Assets Yarkr publishes from this repo, in addition to the usual layouts.\n# https://github.com/posterus-ltd/yarkr-public/blob/main/docs/github.md#yarkrindexyaml\nskills:\n  - path: ai/skills/code-review.md          # one file: the whole skill\n    description: Review a diff for bugs, security issues and missing tests. Use when asked to review a PR or a change.\n  - path: ai/skills/pdf                     # a folder: everything in it ships\n    entry: README.md                        # its instructions file (default SKILL.md, else README.md)\n    name: pdf-forms\n    description: Fill and read PDF forms with the bundled scripts. Use for any PDF form task.\n  - ai/skills/release/howto.md              # a bare path works when the file has description frontmatter\n\nagents:\n  - path: ai/triage-agent.md\n    description: Triages new GitHub issues into labels and owners. Hand it any untriaged issue.\n    skills: [code-review]                   # skills it uses: a name here, or <org>/<name> elsewhere\n    tools: [Read, Grep]                     # optional\n    model: sonnet                           # optional\n\ntoolsets:\n  - path: .cursor/mcp.json\n    name: github\n    description: GitHub's MCP server for issues and PRs. Needs GITHUB_TOKEN.\n```\n\nEvery entry takes `path` and, optionally, `name`, `description`, `tags`, `targets` (harness ids) and `evals` (suite\npaths). Values in the index win over the file's frontmatter.\n\nAdd `detect: false` at the top level when the repo has `SKILL.md` or `agents/*.md` files you don't want published\n(fixtures, examples, drafts): then only the index is published.\n\n## 5. Remove literal secrets from MCP configs\n\nA toolset with a literal value in `env` or `headers` is refused. Replace each with `${VAR}` (or `${vault:path#key}`)\nand tell the user which variables to set. This is the one case where you edit an existing file; mention it in the PR.\nIf the file is also used locally with real values, it's leaking a secret already: say so.\n\n## 6. Lint until clean\n\n```bash\nnpx yarkr-cli lint --strict\n```\n\nIt exits 1 on errors, and with `--strict` on warnings too. Fix warnings unless there's a reason not to (say, an agent's\nskill published from another repo). Check that every asset you chose appears once, with the name and description you\nmeant, and nothing you left out appears. Suggest adding `npx yarkr-cli lint` to CI so the index can't drift from the\nfiles it points at.\n\n## 7. Hand it over\n\n- Open a PR with `yarkr.index.yaml` (and any secret fixes). The description lists what will be published and why the\n  rest was left out.\n- After merge, an org admin connects the repo in Yarkr (**the org's GitHub page \u2192 Connect**). Every push to the default\n  branch publishes a new release of each asset whose files changed.\n- To change an asset later, edit its file where it is. Moving it means updating its `path` in the index.\n\n## Rules\n\n- Never invent an asset, a description that the file doesn't support, or an MCP server URL or package.\n- Never move, rename or rewrite existing files to fit Yarkr. The index exists so you don't have to.\n- One asset per entry; names unique. Don't list the same file twice or a file inside a listed folder.\n"
 };
 
 // ../../packages/core/dist/guides/index.js
@@ -44867,8 +44964,82 @@ async function arkLint(ref, opts) {
   return findings;
 }
 
+// src/commands/repo-lint.ts
+var import_yaml5 = __toESM(require_dist(), 1);
+import { readFile as readFile10 } from "fs/promises";
+import path17 from "path";
+var INDEX_KEYS = /* @__PURE__ */ new Set(["skills", "agents", "toolsets", "detect"]);
+var ENTRY_KEYS = {
+  skills: /* @__PURE__ */ new Set(["path", "name", "description", "tags", "targets", "evals", "entry"]),
+  agents: /* @__PURE__ */ new Set(["path", "name", "description", "tags", "targets", "evals", "skills", "tools", "model"]),
+  toolsets: /* @__PURE__ */ new Set(["path", "name", "description", "tags", "targets", "evals"])
+};
+var TRIGGER = /\b(use (it )?(when|for|to|if)|when (the user|asked|you)|whenever|hand it|for any)\b/i;
+var MIN_DESCRIPTION = 40;
+async function lintRepo(dir, opts = {}) {
+  const res = await scanFolder(dir, { namespace: opts.namespace, fallbackNamespace: await gitOwner(dir) ?? void 0, label: "working tree" });
+  const findings = [];
+  const add2 = (severity, rule, message, pkg) => findings.push({ severity, rule, message, ...pkg ? { package: pkg } : {} });
+  for (const p of res.problems) add2("error", "detect", `${p.path}: ${p.message}`);
+  const indexText = await readFile10(path17.join(res.root, INDEX_FILE), "utf8").catch(() => null);
+  if (indexText !== null) {
+    let raw = null;
+    try {
+      raw = import_yaml5.default.parse(indexText);
+    } catch {
+    }
+    if (raw && typeof raw === "object") {
+      for (const [key, list] of Object.entries(raw)) {
+        if (!INDEX_KEYS.has(key)) add2("warning", "index-key", `${INDEX_FILE}: unknown key \`${key}\` is ignored. Expected ${[...INDEX_KEYS].join(", ")}.`);
+        if (!ENTRY_KEYS[key] || !Array.isArray(list)) continue;
+        list.forEach((e, i) => {
+          if (!e || typeof e !== "object") return;
+          for (const k of Object.keys(e)) if (!ENTRY_KEYS[key].has(k)) add2("warning", "index-key", `${INDEX_FILE}: ${key}[${i}] has unknown key \`${k}\`, which is ignored.`);
+          const targets = e.targets;
+          for (const t of Array.isArray(targets) ? targets : []) {
+            if (!HARNESS_IDS.includes(String(t))) add2("warning", "target", `${INDEX_FILE}: ${key}[${i}] targets unknown harness \`${t}\`. Known: ${HARNESS_IDS.join(", ")}.`);
+          }
+        });
+      }
+    }
+  }
+  const assets = res.packages.map(({ asset }) => ({ name: asset.manifest.name, kind: asset.kind, path: asset.path, description: asset.manifest.description, manifest: asset.manifest }));
+  if (!assets.length && !res.problems.length) add2("error", "empty", `Nothing to publish. List assets in ${INDEX_FILE}; \`yarkr guide index-repo\` explains how.`);
+  const names = new Set(assets.map((a) => a.name));
+  for (const a of assets) {
+    if (a.kind !== "toolset" && a.description.length < MIN_DESCRIPTION) add2("warning", "description", `The description is very short. Say what it does and when to use it.`, a.name);
+    else if (a.kind !== "toolset" && !TRIGGER.test(a.description)) add2("warning", "description", `The description doesn't say when to use it ("Use when \u2026"), so harnesses may not load it.`, a.name);
+    if (a.description.length >= 500) add2("warning", "description", "The description is cut at 500 characters.", a.name);
+    const ns = a.name.split("/")[0];
+    for (const dep of Object.keys(a.manifest.depends.skills ?? {})) {
+      if (dep.startsWith(`${ns}/`) && !names.has(dep)) add2("warning", "dependency", `Uses skill ${dep}, which isn't in this repo. Fine if another repo in the org publishes it.`, a.name);
+    }
+  }
+  return { assets: assets.map(({ manifest: _, ...a }) => a), findings };
+}
+async function repoLint(dir, opts) {
+  const { assets, findings } = await lintRepo(dir, opts);
+  const errors = findings.filter((f) => f.severity === "error").length;
+  const warnings = findings.length - errors;
+  if (opts.json) console.log(JSON.stringify({ assets, errors, warnings, findings }, null, 2));
+  else {
+    if (assets.length) ui.table(assets.map((a) => [ui.bold(a.name), a.kind, a.path, a.description.slice(0, 60)]), ["package", "kind", "path", "description"]);
+    for (const f of findings) {
+      const line = `${f.package ? `${ui.bold(f.package)} ` : ""}${f.message} ${ui.dim(`[${f.rule}]`)}`;
+      if (f.severity === "error") ui.error(line);
+      else ui.warn(line);
+    }
+    if (!findings.length) ui.ok(`Ready: ${assets.length} asset(s) will be published.`);
+  }
+  if (errors || opts.strict && warnings) {
+    throw new CliError(`${errors} error(s), ${warnings} warning(s).`, errors ? "Assets with errors aren't published until they're fixed." : "Warnings fail the lint because of --strict.");
+  }
+  if (warnings && !opts.json) ui.info(`${warnings} warning(s). Pass --strict to fail on them.`);
+  return { assets, findings };
+}
+
 // src/index.ts
-var VERSION = true ? "0.1.5" : "0.0.0-dev";
+var VERSION = true ? "1.0.1" : "0.0.0-dev";
 var act = (fn) => async (...a) => {
   await fn(...a);
 };
@@ -44886,6 +45057,7 @@ function buildProgram() {
   const arkCmd = program2.command("ark").argument("[arks...]", "limit to these arks, e.g. acme/finance or @me").description("show what your arks give you").option("--json").action(act((refs, o) => showArk(refs, o)));
   arkCmd.command("lint").argument("<ark>", "an ark you can read, e.g. acme/finance").description("check an ark's items: missing or private packages, ranges that resolve to nothing, literal secrets, failing evals").option("--strict", "exit 1 on warnings too").option("--json").action(act((ref, o) => arkLint(ref, { ...o, json: o.json || !!arkCmd.opts().json })));
   program2.command("arks").description("list public arks: curated sets anyone can sync or connect over MCP").option("--json").action(act(publicArks));
+  program2.command("lint").argument("[dir]", "a repo checkout", ".").description("check a repo is set up as a Yarkr source: what it publishes, problems the hub would refuse, and index typos or weak descriptions").option("--namespace <ns>", "namespace to show names in (default: the git owner)").option("--strict", "exit 1 on warnings too").option("--json").action(act(repoLint));
   program2.command("guide").argument("[name]", "a guide, e.g. create-ark; omit to list them").description("print instructions for your agent, e.g. how to build an ark for a topic").option("-o, --out <path>", "write to a file, or <dir>/SKILL.md for a directory (e.g. ~/.claude/skills/create-ark/)").option("--topic <topic>", "create-ark: what the ark is about").addOption(new Option("--type <type>", "create-ark: the kind of package it holds").choices(["skill", "agent", "mcp"])).action(act(guide));
   syncFlags(program2.command("add").argument("<packages...>", "namespace/name[@range]").description("add packages to yarkr.json (outside a project: to your personal ark, or your user config when signed out) and sync").option("--no-sync", "only edit yarkr.json")).action(act((pkgs, o) => add(pkgs, { ...o, noSync: o.sync === false })));
   syncFlags(program2.command("remove").argument("<packages...>", "packages, or arks listed in yarkr.json").description("remove packages or arks (or opt out of optional ark items) and delete their files").option("--no-sync", "only edit yarkr.json")).action(act((pkgs, o) => remove(pkgs, { ...o, noSync: o.sync === false })));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarkr-cli",
-  "version": "0.1.5",
+  "version": "1.0.1",
   "description": "Install skills, agents and MCP toolsets from Yarkr into Claude Code, Codex, opencode, Cursor and more",
   "license": "MIT",
   "homepage": "https://yarkr.com",
@@ -48,8 +48,8 @@
     "vitest": "^3.2.4",
     "yaml": "^2.8.1",
     "@yarkr/core": "0.1.0",
-    "@yarkr/schema": "0.1.0",
-    "@yarkr/evals": "0.1.0"
+    "@yarkr/evals": "0.1.0",
+    "@yarkr/schema": "0.1.0"
   },
   "scripts": {
     "build": "tsup",