@codiac.io/codiac-cli 1.3.245 → 1.3.247

package/dist/commands/skill/install.d.ts

@@ -0,0 +1,14 @@
+import { Command } from '@oclif/core';
+export default class SkillInstall extends Command {
+    static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static flags: {
+        help: import("@oclif/core/lib/interfaces").BooleanFlag<void>;
+        dir: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        force: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/skill/install.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const core_1 = require("@oclif/core");
+const skill_assets_1 = require("../../skill-assets");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+class SkillInstall extends core_1.Command {
+    run() {
+        var _a;
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            const { flags } = yield this.parse(SkillInstall);
+            const src = (0, skill_assets_1.skillDir)();
+            if (!fs.existsSync(src)) {
+                this.error(`Bundled skill directory not found at ${src}. This CLI build may be missing the shipped skill (package "files" should include /skill).`);
+            }
+            const parent = (_a = flags.dir) !== null && _a !== void 0 ? _a : path.join(os.homedir(), '.claude', 'skills');
+            const dest = path.join(parent, 'codiac');
+            if (fs.existsSync(dest) && !flags.force) {
+                this.error(`A codiac skill already exists at ${dest}. Re-run with --force to overwrite.`);
+            }
+            fs.mkdirSync(parent, { recursive: true });
+            if (fs.existsSync(dest) && flags.force)
+                fs.rmSync(dest, { recursive: true, force: true });
+            fs.cpSync(src, dest, { recursive: true });
+            this.log(`Installed the Codiac skill to ${dest}`);
+        });
+    }
+}
+exports.default = SkillInstall;
+SkillInstall.description = "Copies the bundled Codiac agent skill into a skills directory so a skill-aware harness (e.g. Claude Code) discovers it. Defaults to ~/.claude/skills/codiac. For runtimes that aren't skill-aware, use `cod skill show` to inject the content instead.";
+SkillInstall.examples = [
+    { description: 'Install into the default Claude Code skills dir (~/.claude/skills/codiac).', command: '<%= config.bin %> <%= command.id %>' },
+    { description: 'Install into a specific skills directory.', command: '<%= config.bin %> <%= command.id %> --dir /workspace/.claude/skills' },
+    { description: 'Overwrite an existing install.', command: '<%= config.bin %> <%= command.id %> --force' },
+];
+SkillInstall.flags = {
+    help: core_1.Flags.help({ char: 'h' }),
+    dir: core_1.Flags.string({ char: 'd', description: 'Parent skills directory to install into (the skill is placed in <dir>/codiac). Defaults to ~/.claude/skills.' }),
+    force: core_1.Flags.boolean({ char: 'f', description: 'Overwrite an existing codiac skill at the destination.' }),
+};
+//# sourceMappingURL=install.js.map

package/dist/commands/skill/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../../src/commands/skill/install.ts"],"names":[],"mappings":";;;AAAA,sCAA6C;AAC7C,qDAA8C;AAC9C,yBAAyB;AACzB,yBAAyB;AACzB,6BAA6B;AAE7B,MAAqB,YAAa,SAAQ,cAAO;IAgBlC,GAAG;;;YACd,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;YAEjD,MAAM,GAAG,GAAG,IAAA,uBAAQ,GAAE,CAAC;YACvB,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE;gBACvB,IAAI,CAAC,KAAK,CAAC,wCAAwC,GAAG,4FAA4F,CAAC,CAAC;aACrJ;YAED,MAAM,MAAM,GAAG,MAAA,KAAK,CAAC,GAAG,mCAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;YACzE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YAEzC,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE;gBACvC,IAAI,CAAC,KAAK,CAAC,oCAAoC,IAAI,qCAAqC,CAAC,CAAC;aAC3F;YAED,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1C,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,KAAK;gBAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1F,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAE1C,IAAI,CAAC,GAAG,CAAC,iCAAiC,IAAI,EAAE,CAAC,CAAC;;KACnD;;AApCH,+BAqCC;AApCiB,wBAAW,GACzB,wPAAwP,CAAC;AAE3O,qBAAQ,GAAG;IACzB,EAAE,WAAW,EAAE,4EAA4E,EAAE,OAAO,EAAE,qCAAqC,EAAE;IAC7I,EAAE,WAAW,EAAE,2CAA2C,EAAE,OAAO,EAAE,qEAAqE,EAAE;IAC5I,EAAE,WAAW,EAAE,gCAAgC,EAAE,OAAO,EAAE,6CAA6C,EAAE;CAC1G,CAAC;AAEc,kBAAK,GAAG;IACtB,IAAI,EAAE,YAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;IAC/B,GAAG,EAAE,YAAK,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,8GAA8G,EAAE,CAAC;IAC7J,KAAK,EAAE,YAAK,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,wDAAwD,EAAE,CAAC;CAC3G,CAAC"}

package/dist/commands/skill/path.d.ts

@@ -0,0 +1,12 @@
+import { Command } from '@oclif/core';
+export default class SkillPath extends Command {
+    static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static flags: {
+        help: import("@oclif/core/lib/interfaces").BooleanFlag<void>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/skill/path.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const core_1 = require("@oclif/core");
+const skill_assets_1 = require("../../skill-assets");
+const fs = require("fs");
+class SkillPath extends core_1.Command {
+    run() {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            const dir = (0, skill_assets_1.skillDir)();
+            if (!fs.existsSync(dir)) {
+                this.error(`Bundled skill directory not found at ${dir}. This CLI build may be missing the shipped skill (package "files" should include /skill).`);
+            }
+            this.log(dir);
+        });
+    }
+}
+exports.default = SkillPath;
+SkillPath.description = "Prints the absolute path of the bundled Codiac agent skill directory (SKILL.md + references/) that ships with this CLI. Useful for scripting or pointing a skill-aware harness at it.";
+SkillPath.examples = [
+    { description: 'Print the skill directory path.', command: '<%= config.bin %> <%= command.id %>' },
+];
+SkillPath.flags = {
+    help: core_1.Flags.help({ char: 'h' }),
+};
+//# sourceMappingURL=path.js.map

package/dist/commands/skill/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../../../src/commands/skill/path.ts"],"names":[],"mappings":";;;AAAA,sCAA6C;AAC7C,qDAA8C;AAC9C,yBAAyB;AAEzB,MAAqB,SAAU,SAAQ,cAAO;IAY/B,GAAG;;YACd,MAAM,GAAG,GAAG,IAAA,uBAAQ,GAAE,CAAC;YACvB,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE;gBACvB,IAAI,CAAC,KAAK,CAAC,wCAAwC,GAAG,4FAA4F,CAAC,CAAC;aACrJ;YACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAChB,CAAC;KAAA;;AAlBH,4BAmBC;AAlBiB,qBAAW,GACzB,uLAAuL,CAAC;AAE1K,kBAAQ,GAAG;IACzB,EAAE,WAAW,EAAE,iCAAiC,EAAE,OAAO,EAAE,qCAAqC,EAAE;CACnG,CAAC;AAEc,eAAK,GAAG;IACtB,IAAI,EAAE,YAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;CAChC,CAAC"}

package/dist/commands/skill/show.d.ts

@@ -0,0 +1,14 @@
+import { Command } from '@oclif/core';
+export default class SkillShow extends Command {
+    static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static flags: {
+        help: import("@oclif/core/lib/interfaces").BooleanFlag<void>;
+        file: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        list: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/skill/show.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const core_1 = require("@oclif/core");
+const skill_assets_1 = require("../../skill-assets");
+const path = require("path");
+class SkillShow extends core_1.Command {
+    run() {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            const { flags } = yield this.parse(SkillShow);
+            if (flags.list) {
+                const root = (0, skill_assets_1.skillDir)();
+                for (const p of (0, skill_assets_1.skillFilePaths)())
+                    this.log(path.relative(root, p));
+                return;
+            }
+            if (flags.file) {
+                const content = (0, skill_assets_1.readSkillFile)(flags.file);
+                if (content == undefined) {
+                    this.error(`Skill file not found: ${flags.file}. Use \`cod skill show --list\` to see the available files.`);
+                }
+                // process.stdout so the raw doc pipes cleanly with no styling/prefix.
+                process.stdout.write(content.endsWith('\n') ? content : content + '\n');
+                return;
+            }
+            process.stdout.write((0, skill_assets_1.readFullSkill)() + '\n');
+        });
+    }
+}
+exports.default = SkillShow;
+SkillShow.description = 'Prints the Codiac agent skill — the canonical guidance for driving `cod` correctly (concepts + the read-`--help`-first discipline + the flag-collision map). AI agents: read this before using the CLI; a system prompt can inject it via `$(cod skill show)`.';
+SkillShow.examples = [
+    { description: 'Print the whole skill (SKILL.md + references) as one document.', command: '<%= config.bin %> <%= command.id %>' },
+    { description: 'Inject the skill into an agent system prompt.', command: 'SYSTEM="$(<%= config.bin %> <%= command.id %>)"' },
+    { description: 'Print just one file.', command: '<%= config.bin %> <%= command.id %> --file references/cli-reference.md' },
+    { description: 'List the files that make up the skill.', command: '<%= config.bin %> <%= command.id %> --list' },
+];
+SkillShow.flags = {
+    help: core_1.Flags.help({ char: 'h' }),
+    file: core_1.Flags.string({ char: 'f', description: 'Print a single skill file by its path relative to the skill root (e.g. SKILL.md, references/concepts.md).' }),
+    list: core_1.Flags.boolean({ char: 'l', description: 'List the files that make up the skill instead of printing their contents.' }),
+};
+//# sourceMappingURL=show.js.map

package/dist/commands/skill/show.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"show.js","sourceRoot":"","sources":["../../../src/commands/skill/show.ts"],"names":[],"mappings":";;;AAAA,sCAA6C;AAC7C,qDAA4F;AAC5F,6BAA6B;AAE7B,MAAqB,SAAU,SAAQ,cAAO;IAiB/B,GAAG;;YACd,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YAE9C,IAAI,KAAK,CAAC,IAAI,EAAE;gBACd,MAAM,IAAI,GAAG,IAAA,uBAAQ,GAAE,CAAC;gBACxB,KAAK,MAAM,CAAC,IAAI,IAAA,6BAAc,GAAE;oBAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;gBACnE,OAAO;aACR;YAED,IAAI,KAAK,CAAC,IAAI,EAAE;gBACd,MAAM,OAAO,GAAG,IAAA,4BAAa,EAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBAC1C,IAAI,OAAO,IAAI,SAAS,EAAE;oBACxB,IAAI,CAAC,KAAK,CAAC,yBAAyB,KAAK,CAAC,IAAI,6DAA6D,CAAC,CAAC;iBAC9G;gBACD,sEAAsE;gBACtE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;gBACxE,OAAO;aACR;YAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAA,4BAAa,GAAE,GAAG,IAAI,CAAC,CAAC;QAC/C,CAAC;KAAA;;AArCH,4BAsCC;AArCiB,qBAAW,GACzB,gQAAgQ,CAAC;AAEnP,kBAAQ,GAAG;IACzB,EAAE,WAAW,EAAE,gEAAgE,EAAE,OAAO,EAAE,qCAAqC,EAAE;IACjI,EAAE,WAAW,EAAE,+CAA+C,EAAE,OAAO,EAAE,iDAAiD,EAAE;IAC5H,EAAE,WAAW,EAAE,sBAAsB,EAAE,OAAO,EAAE,wEAAwE,EAAE;IAC1H,EAAE,WAAW,EAAE,wCAAwC,EAAE,OAAO,EAAE,4CAA4C,EAAE;CACjH,CAAC;AAEc,eAAK,GAAG;IACtB,IAAI,EAAE,YAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;IAC/B,IAAI,EAAE,YAAK,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,2GAA2G,EAAE,CAAC;IAC3J,IAAI,EAAE,YAAK,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,2EAA2E,EAAE,CAAC;CAC7H,CAAC"}

package/dist/skill-assets.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Locators + readers for the bundled Codiac agent skill (SKILL.md + references/), shipped inside
+ * this package so the CLI can advertise and serve its own usage guidance.
+ *
+ * The skill is the canonical "how to drive `cod` without hallucinating" doc; it lives in the CLI
+ * repo (`<repo>/skill/`) so a change to a command/flag updates the guidance in the same PR — no
+ * drift. `package.json` ships it via the `files` array (`/skill`).
+ *
+ * Path resolution: this module compiles to `<pkg>/dist/skill-assets.js`, so `../skill` resolves to
+ * `<pkg>/skill` both in local dev (`<repo>/dist/…` -> `<repo>/skill`) and in the published package.
+ */
+export declare function skillDir(): string;
+/** The skill files in read order: SKILL.md first, then its references. Returns absolute paths that
+ *  actually exist (so a partial install or a renamed reference never crashes the command). */
+export declare function skillFilePaths(): string[];
+/** The whole skill as one document — SKILL.md then each reference, each under a clear delimiter.
+ *  This is the payload a non-skill-aware agent (hermes/openclaw/etc.) injects into its system
+ *  prompt via `cod skill show`. */
+export declare function readFullSkill(): string;
+/** Read a single skill file by its path relative to the skill root (e.g. "SKILL.md" or
+ *  "references/concepts.md"). Returns undefined if it isn't present. */
+export declare function readSkillFile(relative: string): string | undefined;

package/dist/skill-assets.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSkillFile = exports.readFullSkill = exports.skillFilePaths = exports.skillDir = void 0;
+const fs = require("fs");
+const path = require("path");
+/**
+ * Locators + readers for the bundled Codiac agent skill (SKILL.md + references/), shipped inside
+ * this package so the CLI can advertise and serve its own usage guidance.
+ *
+ * The skill is the canonical "how to drive `cod` without hallucinating" doc; it lives in the CLI
+ * repo (`<repo>/skill/`) so a change to a command/flag updates the guidance in the same PR — no
+ * drift. `package.json` ships it via the `files` array (`/skill`).
+ *
+ * Path resolution: this module compiles to `<pkg>/dist/skill-assets.js`, so `../skill` resolves to
+ * `<pkg>/skill` both in local dev (`<repo>/dist/…` -> `<repo>/skill`) and in the published package.
+ */
+function skillDir() {
+    return path.resolve(__dirname, "..", "skill");
+}
+exports.skillDir = skillDir;
+/** The skill files in read order: SKILL.md first, then its references. Returns absolute paths that
+ *  actually exist (so a partial install or a renamed reference never crashes the command). */
+function skillFilePaths() {
+    const root = skillDir();
+    const ordered = [
+        path.join(root, "SKILL.md"),
+        path.join(root, "references", "concepts.md"),
+        path.join(root, "references", "cli-reference.md"),
+    ];
+    // Include any other references not explicitly listed, so new files ship without a code change.
+    const refsDir = path.join(root, "references");
+    if (fs.existsSync(refsDir)) {
+        for (const f of fs.readdirSync(refsDir)) {
+            const full = path.join(refsDir, f);
+            if (f.endsWith(".md") && !ordered.includes(full))
+                ordered.push(full);
+        }
+    }
+    return ordered.filter(p => fs.existsSync(p));
+}
+exports.skillFilePaths = skillFilePaths;
+/** The whole skill as one document — SKILL.md then each reference, each under a clear delimiter.
+ *  This is the payload a non-skill-aware agent (hermes/openclaw/etc.) injects into its system
+ *  prompt via `cod skill show`. */
+function readFullSkill() {
+    const root = skillDir();
+    const parts = [];
+    for (const p of skillFilePaths()) {
+        const rel = path.relative(root, p);
+        parts.push(`===== BEGIN ${rel} =====\n${fs.readFileSync(p, "utf8").trimEnd()}\n===== END ${rel} =====`);
+    }
+    return parts.join("\n\n");
+}
+exports.readFullSkill = readFullSkill;
+/** Read a single skill file by its path relative to the skill root (e.g. "SKILL.md" or
+ *  "references/concepts.md"). Returns undefined if it isn't present. */
+function readSkillFile(relative) {
+    const full = path.join(skillDir(), relative);
+    // Guard against path traversal outside the skill dir.
+    if (!path.resolve(full).startsWith(path.resolve(skillDir())))
+        return undefined;
+    return fs.existsSync(full) ? fs.readFileSync(full, "utf8") : undefined;
+}
+exports.readSkillFile = readSkillFile;
+//# sourceMappingURL=skill-assets.js.map

package/dist/skill-assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-assets.js","sourceRoot":"","sources":["../src/skill-assets.ts"],"names":[],"mappings":";;;AAAA,yBAAyB;AACzB,6BAA6B;AAE7B;;;;;;;;;;GAUG;AACH,SAAgB,QAAQ;IACtB,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AAChD,CAAC;AAFD,4BAEC;AAED;8FAC8F;AAC9F,SAAgB,cAAc;IAC5B,MAAM,IAAI,GAAG,QAAQ,EAAE,CAAC;IACxB,MAAM,OAAO,GAAG;QACd,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC;QAC3B,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,EAAE,aAAa,CAAC;QAC5C,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,EAAE,kBAAkB,CAAC;KAClD,CAAC;IACF,+FAA+F;IAC/F,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAC9C,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE;QAC1B,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE;YACvC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YACnC,IAAI,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;SACtE;KACF;IACD,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/C,CAAC;AAhBD,wCAgBC;AAED;;mCAEmC;AACnC,SAAgB,aAAa;IAC3B,MAAM,IAAI,GAAG,QAAQ,EAAE,CAAC;IACxB,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,cAAc,EAAE,EAAE;QAChC,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACnC,KAAK,CAAC,IAAI,CAAC,eAAe,GAAG,WAAW,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,OAAO,EAAE,eAAe,GAAG,QAAQ,CAAC,CAAC;KACzG;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC;AARD,sCAQC;AAED;wEACwE;AACxE,SAAgB,aAAa,CAAC,QAAgB;IAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,QAAQ,CAAC,CAAC;IAC7C,sDAAsD;IACtD,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/E,OAAO,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACzE,CAAC;AALD,sCAKC"}

package/oclif.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.3.245",
+  "version": "1.3.247",
   "commands": {
     "branch": {
       "id": "branch",
@@ -9037,6 +9037,132 @@
       },
       "args": {}
     },
+    "skill:install": {
+      "id": "skill:install",
+      "description": "Copies the bundled Codiac agent skill into a skills directory so a skill-aware harness (e.g. Claude Code) discovers it. Defaults to ~/.claude/skills/codiac. For runtimes that aren't skill-aware, use `cod skill show` to inject the content instead.",
+      "strict": true,
+      "pluginName": "@codiac.io/codiac-cli",
+      "pluginAlias": "@codiac.io/codiac-cli",
+      "pluginType": "core",
+      "aliases": [],
+      "hiddenAliases": [],
+      "examples": [
+        {
+          "description": "Install into the default Claude Code skills dir (~/.claude/skills/codiac).",
+          "command": "<%= config.bin %> <%= command.id %>"
+        },
+        {
+          "description": "Install into a specific skills directory.",
+          "command": "<%= config.bin %> <%= command.id %> --dir /workspace/.claude/skills"
+        },
+        {
+          "description": "Overwrite an existing install.",
+          "command": "<%= config.bin %> <%= command.id %> --force"
+        }
+      ],
+      "flags": {
+        "help": {
+          "name": "help",
+          "type": "boolean",
+          "char": "h",
+          "description": "Show CLI help.",
+          "allowNo": false
+        },
+        "dir": {
+          "name": "dir",
+          "type": "option",
+          "char": "d",
+          "description": "Parent skills directory to install into (the skill is placed in <dir>/codiac). Defaults to ~/.claude/skills.",
+          "multiple": false
+        },
+        "force": {
+          "name": "force",
+          "type": "boolean",
+          "char": "f",
+          "description": "Overwrite an existing codiac skill at the destination.",
+          "allowNo": false
+        }
+      },
+      "args": {}
+    },
+    "skill:path": {
+      "id": "skill:path",
+      "description": "Prints the absolute path of the bundled Codiac agent skill directory (SKILL.md + references/) that ships with this CLI. Useful for scripting or pointing a skill-aware harness at it.",
+      "strict": true,
+      "pluginName": "@codiac.io/codiac-cli",
+      "pluginAlias": "@codiac.io/codiac-cli",
+      "pluginType": "core",
+      "aliases": [],
+      "hiddenAliases": [],
+      "examples": [
+        {
+          "description": "Print the skill directory path.",
+          "command": "<%= config.bin %> <%= command.id %>"
+        }
+      ],
+      "flags": {
+        "help": {
+          "name": "help",
+          "type": "boolean",
+          "char": "h",
+          "description": "Show CLI help.",
+          "allowNo": false
+        }
+      },
+      "args": {}
+    },
+    "skill:show": {
+      "id": "skill:show",
+      "description": "Prints the Codiac agent skill — the canonical guidance for driving `cod` correctly (concepts + the read-`--help`-first discipline + the flag-collision map). AI agents: read this before using the CLI; a system prompt can inject it via `$(cod skill show)`.",
+      "strict": true,
+      "pluginName": "@codiac.io/codiac-cli",
+      "pluginAlias": "@codiac.io/codiac-cli",
+      "pluginType": "core",
+      "aliases": [],
+      "hiddenAliases": [],
+      "examples": [
+        {
+          "description": "Print the whole skill (SKILL.md + references) as one document.",
+          "command": "<%= config.bin %> <%= command.id %>"
+        },
+        {
+          "description": "Inject the skill into an agent system prompt.",
+          "command": "SYSTEM=\"$(<%= config.bin %> <%= command.id %>)\""
+        },
+        {
+          "description": "Print just one file.",
+          "command": "<%= config.bin %> <%= command.id %> --file references/cli-reference.md"
+        },
+        {
+          "description": "List the files that make up the skill.",
+          "command": "<%= config.bin %> <%= command.id %> --list"
+        }
+      ],
+      "flags": {
+        "help": {
+          "name": "help",
+          "type": "boolean",
+          "char": "h",
+          "description": "Show CLI help.",
+          "allowNo": false
+        },
+        "file": {
+          "name": "file",
+          "type": "option",
+          "char": "f",
+          "description": "Print a single skill file by its path relative to the skill root (e.g. SKILL.md, references/concepts.md).",
+          "multiple": false
+        },
+        "list": {
+          "name": "list",
+          "type": "boolean",
+          "char": "l",
+          "description": "List the files that make up the skill instead of printing their contents.",
+          "allowNo": false
+        }
+      },
+      "args": {}
+    },
     "snapshot:deploy": {
       "id": "snapshot:deploy",
       "description": "Deploys all assets in a snapshot to a target cabinet.",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@codiac.io/codiac-cli",
   "description": "Local command line interface for managing enterprise assets and environments.",
-  "version": "1.3.245",
+  "version": "1.3.247",
   "author": "Codiac",
   "bin": {
     "codiac": "./bin/run",
@@ -142,7 +142,8 @@
     "codiac.json",
     "/npm-shrinkwrap.json",
     "/oclif.manifest.json",
-    "/scaffolding"
+    "/scaffolding",
+    "/skill"
   ],
   "homepage": "codiac.io",
   "keywords": [
@@ -188,7 +189,12 @@
       "win32-arm64",
       "darwin-x64",
       "darwin-arm64"
-    ]
+    ],
+    "topics": {
+      "skill": {
+        "description": "The Codiac agent skill — how to drive `cod` correctly (concepts + read-`--help`-first discipline + flag traps). AI agents: run `cod skill show` and follow it before using the CLI; `cod skill install` for a skill-aware harness."
+      }
+    }
   },
   "repository": "codiac/codiac-cli",
   "types": "dist/index.d.ts"

package/skill/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: codiac
+description: >-
+  Operate the Codiac platform through the `cod` CLI (and, secondarily, the NATS relay API).
+  Use this whenever a task touches Codiac at all: deploying or managing assets/workloads,
+  editing scoped configuration or secrets, working with enterprises, environments, cabinets,
+  clusters, image registries, CSP/cloud profiles, hosts/ingress, or agents — or any time you
+  are about to type a `cod ...` command or reason about how Codiac deploys things. Reach for it
+  even when the user doesn't say "Codiac" but names a Codiac concept (asset, cabinet, scoped
+  setting, enterprise, environment, cluster, CSP profile, EVC). Its whole job is to stop you
+  guessing cod commands, subcommands, args, and flags — the CLI is self-documenting, and this
+  skill gives you the concept model plus the one habit that prevents almost every mistake:
+  read `cod <topic> <verb> --help` before you call a command you are not certain of.
+---
+
+# Codiac
+
+You are operating **Codiac** — a platform that deploys and manages workloads on Kubernetes
+clusters. Your tool is the **`cod` CLI**. Data operations also flow over a **NATS relay API**,
+but the CLI is the primary, safe surface and you should prefer it.
+
+## The one thing that matters most
+
+**`cod` is self-documenting, and guessing is the failure mode.** Every command carries a
+description, every flag has its own description, and commands ship titled, copy-pasteable
+examples. So the fast path is never to recall a command from memory — it is:
+
+> **Before you run any `cod` command you are not 100% certain of, run `cod <topic> <verb> --help` and read it.**
+
+This is faster, not slower, than guessing. A guessed flag fails (or worse, silently does the
+wrong thing against a real cluster), costs a round-trip, and erodes trust. Reading `--help`
+costs one cheap call and makes the very next command correct.
+
+Why this is non-negotiable and not just good manners: **Codiac's flag characters collide across
+commands.** `-e` means *enterprise* in `cod asset list` and `cod config view`, but *environment*
+in `cod cabinet create`, `cod config add`, and `cod config settings get` (where enterprise is
+`-n`). Asset version is `-u`, not `-v`. On `cod asset deploy`, `-n` is a cloud username and `-t`
+is a cabinet tag. Several primary inputs (tenant code, cluster, provider, cabinet name) are
+**positional args, not flags**. There is no convention you can lean on — only `--help` is truth.
+See `references/cli-reference.md` for the collision map, but treat even that as orientation:
+`--help` on the specific command is the authority.
+
+## When you're working in this skill
+
+Most tasks are one of:
+- **Deploy / manage a workload** — `cod asset deploy`, `asset list`, `asset view`, `asset undeploy`, `asset recycle`.
+- **Read or change configuration / secrets** — `cod config view` (preview the resolved doc), `config add` (set a value), `config settings get` (inspect raw settings), scoped-setting work.
+- **Work with the topology** — enterprises, environments, cabinets, clusters, hosts/ingress.
+- **Cloud/registry auth** — `cod csp login` for a provider (Azure/AWS/DockerHub).
+- **Install an agent** — `cod ai agent install`.
+
+If you don't know which command a task maps to, skim the command tree in
+`references/cli-reference.md`, then `--help` the candidate.
+
+## Hold the concept model before you touch a command
+
+Codiac's mental model is small but easy to conflate. Get it wrong and you'll pass the wrong
+flag values even with perfect flag names. The essentials:
+
+- **tenant → enterprise → environment → cabinet → cluster.** A **tenant** is the account. An
+  **enterprise** is a workspace inside it (two *types* exist: normal/`sdlc` and `infrx` for
+  infrastructure — some commands enforce the type). An **environment** is a stage (dev/prod/…)
+  that **maps to a cluster** (the mapping is data-driven in the DB). A **cabinet** is a concrete
+  deployment target that lives **in an environment** — so it inherits that environment's cluster.
+- **Therefore `cod cabinet create` takes `--environment`, never `--cluster`.** Cabinets and
+  clusters are ephemeral over an underlying namespace; the env→cluster link is the source of truth.
+- **Asset** = a deployable workload (a `helm` chart or a `service`/container). Registered once,
+  versioned (AssetVersionConfig), then deployed into a cabinet.
+- **Scoped settings / config** are values attached at a **scope** — `enterprise`, `environment`,
+  or `cabinet` — where **cabinet overrides environment overrides enterprise**. Shareable config
+  belongs at the *highest* scope that makes sense (set once, inherited), with narrower scopes as
+  optional overrides. Cabinet-scoping something that should be shared is an anti-pattern.
+- The **EVC** (EnterpriseVersionConfig) is the versioned snapshot the platform actually reads;
+  deploys write it. Config can be a **literal value** or a **sourced** reference into a vault.
+
+That's enough to choose the right command and fill it correctly. For depth — targetFile types
+(`[helm]`/`[env]`/`[label]`/…), dotted-key/escaped-period behavior, `@{...}` templates, CSP
+profiles, the NATS API, and the full hierarchy — read `references/concepts.md`.
+
+## Authenticating (you may wake up logged out)
+
+You may start **not logged in** — that's expected, and it's your job to get logged in before you
+act. Operating Codiac needs **two** logins:
+- **Codiac** — `cod login` for your tenant (`$CODIAC_TENANT` if it's set in your env; otherwise
+  you'll be told which tenant you belong to).
+- **Cloud + registry** — `cod csp login <provider>` for each provider you use (typically `azure`
+  for the cluster and `docker` for images).
+
+Check first with **`cod whoami`**. If it shows you're not logged in — or any command fails with an
+auth / "not logged in" / "no credentials" error — you're missing one of those logins.
+
+**You do not hold these credentials by design.** Never guess, fabricate, or hard-code them, and
+never attempt a deploy/undeploy/config change while unauthenticated. Instead, **ask your operator
+for what you need** — a Codiac login (username + password, or a token) and cloud creds (a login or a
+token per provider) — then authenticate. Read `cod login --help` and `cod csp login --help` for the
+exact accepted forms; both take secrets on stdin so nothing lands in a command string, e.g.:
+
+```
+printf '%s' "<password>" | cod login -u <user> --tenantCode "$CODIAC_TENANT" --passwordIn
+cod csp login <provider>          # supply the login/token as --help shows (stdin under --silent)
+```
+
+Then re-check `cod whoami` and continue. If your session lapses later, you'll see auth errors again
+— ask and re-login the same way.
+
+## Running a `cod` command safely
+
+1. **Establish context.** Enterprise-scoped commands need a tenant (and often an enterprise).
+   `cod tenant switch <code>` sets the tenant; many commands take `--enterprise`. A deployed agent
+   usually already runs inside its tenant's context.
+2. **`--help` the exact command** unless you have literally just read it. Read the flag
+   descriptions and the examples — copy an example and adapt it rather than composing from scratch.
+3. **In automation / non-interactive shells, pass `--silent` and every required arg.** `--silent`
+   (and piped stdin, which auto-switches to silent) has **no prompt fallback** — a missing or
+   invalid required value throws instead of asking. Secrets that would normally be prompted are
+   fed via stdin (e.g. `cod csp login` password, `cod config add --value-stdin`).
+4. **Preview only in a real terminal — never headless.** `--echo`/`--to-script` render the
+   equivalent `--silent` command, but they run the *interactive* build first, so in a non-TTY they
+   **prompt and hang**. Headless, `--silent` is your safe mode: it validates and **throws** on a
+   missing/invalid arg (fast, never hangs) instead of prompting. To preview a command without
+   running it headless, build it from `--help` and simply don't execute — don't reach for
+   `--to-script`.
+5. **Reading a list?** List commands take `--output/-o` (`tree` default; `json`/`yaml`/… for
+   machines) and usually `--query/-q` (JMESPath). `-q` implies JSON; `tree`/`text` reject `-q`.
+
+## Operating a running workload (logs, status, events, exec, config)
+
+Almost everything about a live workload comes from **`cod asset view`** (and `cod cabinet contents`
+/ `cod asset list`) — reach for these first; read-only `kubectl` is only a fallback. `cod asset
+view` flags: `-e` enterprise, `-a` asset, `-n` environment, `-c` cabinet, `-r` replica (`any` =
+first, no prompt), `-t` content type.
+
+- **What's deployed** (returns + exits, headless-safe): `cod cabinet contents -e <ent> -c <cab>` and `cod asset list -e <ent> -o json`.
+- **Logs** (headless-safe): `cod asset view -t logs -e <ent> -a <asset> -n <env> -c <cab> -r any -l 50 --silent` — pass `-l N` for N lines (or `-l -1` for all); **omit `-f`** (follow streams forever).
+- **Exec / env / config**: `cod asset view -t exec|env|config …` (config also takes `-T <helm|env|label|annotation|…>`).
+- **Live status + events**: `cod asset view -t status` (aka `asset mon`) is an **interactive
+  streaming monitor** — great in a real terminal, but it does **not** return in a non-TTY/`--silent`
+  shell, so don't use it in automation. For a headless status snapshot, use `cabinet contents` /
+  `asset list` above. (For headless one-shot *events*, use `cod asset view -t events` — a
+  returns-and-exits events dump; `-l N` for count.)
+
+## Hard rules (each earns its place)
+
+- **Never invent a command, subcommand, or flag.** If it's not confirmed by `--help` or
+  `references/cli-reference.md`, verify before running. The grammar is strictly **noun-then-verb**
+  (`cod asset deploy`, `cod config settings get`) — never verb-first, never reordered.
+- **`cod` first — don't lead with `kubectl`.** Almost everything about a running workload is
+  available through `cod asset view` (logs, exec, env, config, live status+events) and
+  `cod cabinet contents` / `cod asset list` (what's deployed) — reach for those before the cluster.
+  Read-only `kubectl get`/`describe`/`logs` is a fine fallback for diagnosis (and the user may
+  explicitly okay it); the point is to rely on Codiac's own calls first, not to ban `kubectl`. The
+  one firm line: **never make a *write* through raw `kubectl`/`helm`** against a Codiac-managed
+  asset — that corrupts Codiac's tracked view (stale rootmap/UI); make changes through `cod`.
+- **Set `CODIAC_SESSION_ID` for a multi-step sequence** so every `cod` call shares one session
+  (otherwise steps can land in different sessions and lose context).
+- **Treat prod as prod.** Deploys, undeploys, and config changes act on real clusters. In doubt,
+  **read first** — `cod config view`, `cod cabinet contents`, `cod asset view` — before you write.
+
+## When something's missing
+
+If a task seems to have no `cod` command, the first instinct to resist is **hallucinating a flag**.
+Instead:
+1. Re-check `--help` on the most relevant command (especially `cod asset view --help` — logs,
+   exec, env, config, live status, and events all live there under `-t`).
+2. Check the command tree in `references/cli-reference.md` for a topic you haven't considered.
+3. If it's genuinely absent, **name the gap** so it can be added to `cod` — that's the durable fix.
+   A **read-only** `kubectl get`/`describe` check is an acceptable stopgap in the meantime (and the
+   user may okay it outright); just never a raw `kubectl`/`helm` *write* against a Codiac-managed
+   asset, and prefer getting the capability into `cod` over a standing `kubectl` habit.
+
+## Reference files
+
+- `references/cli-reference.md` — the command tree (every topic → verbs), the flag-character
+  collision map, the list/output (`-o`/`-q`) pattern, positional-arg gotchas, and the `--silent`
+  rules. Orientation only; `--help` on the specific command is authoritative.
+- `references/concepts.md` — the full Codiac mental model: the hierarchy and enterprise types,
+  assets and versioning, scoped configuration (scope/inheritance, targetFile types, sourced vs
+  literal, dotted keys and escaped periods, `@{...}` templates), the EVC/deploy model, CSP/cloud
+  auth, and the NATS relay API surface. Read it whenever a task goes past a single obvious command.