@codemcp/ade 0.2.6 → 0.4.0

package/packages/cli/dist/index.js

@@ -11222,6 +11222,23 @@ var B = class {
     }
   }
 };
+var kt = class extends B {
+  get cursor() {
+    return this.value ? 0 : 1;
+  }
+  get _value() {
+    return this.cursor === 0;
+  }
+  constructor(e) {
+    super(e, false), this.value = !!e.initialValue, this.on("userInput", () => {
+      this.value = this._value;
+    }), this.on("confirm", (s) => {
+      this.output.write(import_sisteransi.cursor.move(0, -1)), this.value = s, this.state = "submit", this.close();
+    }), this.on("cursor", () => {
+      this.value = !this.value;
+    });
+  }
+};
 var Lt = class extends B {
   options;
   cursor = 0;
@@ -11556,6 +11573,33 @@ var X2 = ({ cursor: e, options: r2, style: s, output: i = process.stdout, maxIte
   for (const A3 of d3) for (const b of A3) C2.push(b);
   return $2 && C2.push(c), C2;
 };
+var Rt = (e) => {
+  const r2 = e.active ?? "Yes", s = e.inactive ?? "No";
+  return new kt({ active: r2, inactive: s, signal: e.signal, input: e.input, output: e.output, initialValue: e.initialValue ?? true, render() {
+    const i = e.withGuide ?? _.withGuide, a = `${i ? `${t("gray", h)}
+` : ""}${W2(this.state)}  ${e.message}
+`, o2 = this.value ? r2 : s;
+    switch (this.state) {
+      case "submit": {
+        const u2 = i ? `${t("gray", h)}  ` : "";
+        return `${a}${u2}${t("dim", o2)}`;
+      }
+      case "cancel": {
+        const u2 = i ? `${t("gray", h)}  ` : "";
+        return `${a}${u2}${t(["strikethrough", "dim"], o2)}${i ? `
+${t("gray", h)}` : ""}`;
+      }
+      default: {
+        const u2 = i ? `${t("cyan", h)}  ` : "", l = i ? t("cyan", x2) : "";
+        return `${a}${u2}${this.value ? `${t("green", z2)} ${r2}` : `${t("dim", H2)} ${t("dim", r2)}`}${e.vertical ? i ? `
+${t("cyan", h)}  ` : `
+` : ` ${t("dim", "/")} `}${this.value ? `${t("dim", H2)} ${t("dim", s)}` : `${t("green", z2)} ${s}`}
+${l}
+`;
+      }
+    }
+  } }).prompt();
+};
 var R2 = { message: (e = [], { symbol: r2 = t("gray", h), secondarySymbol: s = t("gray", h), output: i = process.stdout, spacing: a = 1, withGuide: o2 } = {}) => {
   const u2 = [], l = o2 ?? _.withGuide, n = l ? s : "", c = l ? `${r2}  ` : "", p2 = l ? `${s}  ` : "";
   for (let g2 = 0; g2 < a; g2++) u2.push(n);
@@ -11653,6 +11697,25 @@ ${t("cyan", x2)}
     }
   } }).prompt();
 };
+var jt = (e) => t("dim", e);
+var kt2 = (e, r2, s) => {
+  const i = { hard: true, trim: false }, a = J2(e, r2, i).split(`
+`), o2 = a.reduce((n, c) => Math.max(D2(c), n), 0), u2 = a.map(s).reduce((n, c) => Math.max(D2(c), n), 0), l = r2 - (u2 - o2);
+  return J2(e, l, i);
+};
+var Vt2 = (e = "", r2 = "", s) => {
+  const i = s?.output ?? N2.stdout, a = s?.withGuide ?? _.withGuide, o2 = s?.format ?? jt, u2 = ["", ...kt2(e, rt(i) - 6, o2).split(`
+`).map(o2), ""], l = D2(r2), n = Math.max(u2.reduce((g2, E) => {
+    const $2 = D2(E);
+    return $2 > g2 ? $2 : g2;
+  }, 0), l) + 2, c = u2.map((g2) => `${t("gray", h)}  ${g2}${" ".repeat(n - D2(g2))}${t("gray", h)}`).join(`
+`), p2 = a ? `${t("gray", h)}
+` : "", f = a ? We : ge;
+  i.write(`${p2}${t("green", V)}  ${t("reset", r2)} ${t("gray", se.repeat(Math.max(n - l - 1, 1)) + pe)}
+${c}
+${t("gray", f + se.repeat(n + 2) + me)}
+`);
+};
 var ze = { light: I2("\u2500", "-"), heavy: I2("\u2501", "="), block: I2("\u2588", "#") };
 var oe = (e, r2) => e.includes(`
 `) ? e.split(`
@@ -11837,7 +11900,7 @@ function createDefaultRegistry() {
 var processFacet = {
   id: "process",
   label: "Process",
-  description: "How your AI agent receives and executes tasks",
+  description: "How will you guide your agent",
   required: true,
   options: [
     {
@@ -12312,7 +12375,7 @@ var architectureFacet = {
 var practicesFacet = {
   id: "practices",
   label: "Practices",
-  description: "Composable development practices \u2014 mix and match regardless of stack",
+  description: "Development practices \u2014 mix and match regardless of stack",
   required: false,
   multiSelect: true,
   options: [
@@ -12544,7 +12607,7 @@ var JAVA_UNIT_TEST_RECIPE = [
 var backpressureFacet = {
   id: "backpressure",
   label: "Backpressure",
-  description: "Install git hooks that enforce quality gates \u2014 silent on success, surface only relevant failures",
+  description: "Which automated quality gates to put in place. Translates to git hooks",
   required: false,
   multiSelect: true,
   dependsOn: ["architecture"],
@@ -12603,31 +12666,31 @@ var autonomyFacet = {
   multiSelect: false,
   options: [
     {
-      id: "rigid",
-      label: "Rigid",
-      description: "Keep built-in capabilities approval-gated and require confirmation before acting",
+      id: "sensible-defaults",
+      label: "Sensible defaults",
+      description: "Allow a curated built-in capabilities set while keeping potentially risky actions approval-gated",
       recipe: [
         {
           writer: "permission-policy",
-          config: { profile: "rigid" }
+          config: { profile: "sensible-defaults" }
         }
       ]
     },
     {
-      id: "sensible-defaults",
-      label: "Sensible defaults",
-      description: "Allow a curated low-risk built-in capability set while keeping web access approval-gated",
+      id: "rigid",
+      label: "Rigid",
+      description: "Keep built-in capabilities approval-gated and require confirmation before acting",
       recipe: [
         {
           writer: "permission-policy",
-          config: { profile: "sensible-defaults" }
+          config: { profile: "rigid" }
         }
       ]
     },
     {
       id: "max-autonomy",
       label: "Max autonomy",
-      description: "Allow broad local built-in autonomy while keeping web access approval-gated",
+      description: "Allow broad local built-in autonomy. Recommended for sandboxed environments only",
       recipe: [
         {
           writer: "permission-policy",
@@ -21824,7 +21887,7 @@ async function installSkills(skills, projectRoot) {
 }
 
 // ../harnesses/dist/util.js
-import { mkdir as mkdir3, readFile as readFile5, writeFile as writeFile4 } from "fs/promises";
+import { access as access2, mkdir as mkdir3, readFile as readFile5, writeFile as writeFile4 } from "fs/promises";
 import { dirname as dirname5, join as join9 } from "path";
 async function readJsonOrEmpty(path2) {
   try {
@@ -21891,10 +21954,19 @@ async function writeAgentMd(config, opts) {
   await writeFile4(opts.path, content, "utf-8");
 }
 async function writeGitHooks(hooks, projectRoot) {
-  if (!hooks)
+  if (!hooks || hooks.length === 0)
+    return;
+  const gitDir = join9(projectRoot, ".git");
+  try {
+    await access2(gitDir);
+  } catch {
+    R2.warn("Git hooks were configured but could not be installed: the project is not a git repository.\nRun `git init` and re-run setup to install the hooks.");
     return;
+  }
+  const hooksDir = join9(gitDir, "hooks");
+  await mkdir3(hooksDir, { recursive: true });
   for (const hook of hooks) {
-    const hookPath = join9(projectRoot, ".git", "hooks", hook.phase);
+    const hookPath = join9(hooksDir, hook.phase);
     await writeFile4(hookPath, hook.script, { mode: 493 });
   }
 }
@@ -22434,7 +22506,27 @@ function getKiroAgentMcpServers(servers) {
 
 // ../harnesses/dist/writers/opencode.js
 import { join as join18 } from "path";
+var APPLICABLE_TO_ALL = {
+  read: {
+    "*": "allow",
+    "*.env": "deny",
+    "*.env.*": "deny",
+    "*.env.example": "allow"
+  },
+  skill: "deny",
+  //we're using an own skills-mcp
+  todoread: "deny",
+  //no agent-proprieatry todo tools
+  todowrite: "deny",
+  task: "deny",
+  lsp: "allow",
+  glob: "allow",
+  grep: "allow",
+  list: "allow",
+  external_directory: "ask"
+};
 var RIGID_RULES = {
+  ...APPLICABLE_TO_ALL,
   "*": "ask",
   webfetch: "ask",
   websearch: "ask",
@@ -22443,31 +22535,17 @@ var RIGID_RULES = {
   doom_loop: "deny"
 };
 var SENSIBLE_DEFAULTS_RULES = {
-  read: {
-    "*": "allow",
-    "*.env": "deny",
-    "*.env.*": "deny",
-    "*.env.example": "allow"
-  },
+  ...APPLICABLE_TO_ALL,
   edit: "allow",
-  glob: "allow",
-  grep: "allow",
-  list: "allow",
-  lsp: "allow",
-  task: "allow",
-  todoread: "deny",
-  todowrite: "deny",
-  skill: "deny",
   webfetch: "ask",
   websearch: "ask",
   codesearch: "ask",
   bash: {
-    "*": "deny",
+    "*": "ask",
     "grep *": "allow",
     "rg *": "allow",
     "find *": "allow",
     "fd *": "allow",
-    ls: "allow",
     "ls *": "allow",
     "cat *": "allow",
     "head *": "allow",
@@ -22502,14 +22580,7 @@ var SENSIBLE_DEFAULTS_RULES = {
     "yq *": "allow",
     "mkdir *": "allow",
     "touch *": "allow",
-    "cp *": "ask",
-    "mv *": "ask",
-    "ln *": "ask",
-    "npm *": "ask",
-    "node *": "ask",
-    "pip *": "ask",
-    "python *": "ask",
-    "python3 *": "ask",
+    "kill *": "ask",
     "rm *": "deny",
     "rmdir *": "deny",
     "curl *": "deny",
@@ -22530,7 +22601,6 @@ var SENSIBLE_DEFAULTS_RULES = {
     "mkfs *": "deny",
     "mount *": "deny",
     "umount *": "deny",
-    "kill *": "deny",
     "killall *": "deny",
     "pkill *": "deny",
     "nc *": "deny",
@@ -22550,15 +22620,14 @@ var SENSIBLE_DEFAULTS_RULES = {
     "userdel *": "deny",
     "iptables *": "deny"
   },
-  external_directory: "deny",
   doom_loop: "deny"
 };
 var MAX_AUTONOMY_RULES = {
+  ...APPLICABLE_TO_ALL,
   "*": "allow",
   webfetch: "ask",
   websearch: "ask",
   codesearch: "ask",
-  external_directory: "deny",
   doom_loop: "deny"
 };
 function getPermissionRules(profile) {
@@ -22631,7 +22700,35 @@ function getHarnessIds() {
 
 // src/commands/setup.ts
 async function runSetup(projectRoot, catalog) {
-  Wt2("ade setup");
+  let lineIndex = 0;
+  const LOGO_LINES = [
+    "\n",
+    " \u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557    \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557   \u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2557 ",
+    "\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D    \u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D\u255A\u2550\u2550\u2588\u2588\u2554\u2550\u2550\u255D\u2588\u2588\u2551   \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557",
+    "\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2557      \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2557     \u2588\u2588\u2551   \u2588\u2588\u2551   \u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D",
+    "\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u255D      \u255A\u2550\u2550\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u255D     \u2588\u2588\u2551   \u2588\u2588\u2551   \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u255D ",
+    "\u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557    \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557   \u2588\u2588\u2551   \u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D\u2588\u2588\u2551     ",
+    "\u255A\u2550\u255D  \u255A\u2550\u255D\u255A\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D    \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D   \u255A\u2550\u255D    \u255A\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u2550\u255D     ",
+    "\n"
+  ];
+  for (const line of LOGO_LINES) {
+    lineIndex++;
+    if (lineIndex === 1) {
+      Wt2(line);
+    } else {
+      console.log(`\u2502  ${line}`);
+    }
+  }
+  Vt2(
+    [
+      "You're about to define how your team works with coding agents.",
+      "",
+      "Pick your facets \u2014 architecture, practices, process \u2014 and ADE",
+      "translates them into a shared information hierarchy your agents",
+      "read from the repo. One setup, consistent across the whole team."
+    ].join("\n"),
+    "ADE \u2014 Agentic Development Environment"
+  );
   const existingConfig = await readUserConfig(projectRoot);
   const existingChoices = existingConfig?.choices ?? {};
   for (const [facetId, value] of Object.entries(existingChoices)) {
@@ -22676,7 +22773,7 @@ async function runSetup(projectRoot, catalog) {
   let excludedDocsets;
   if (impliedDocsets.length > 0) {
     const selected = await Lt2({
-      message: "Documentation \u2014 deselect any you don't need",
+      message: "Documentation sources \u2014 Those will be pulled to your local disk for browsing on demand",
       options: impliedDocsets.map((d3) => ({
         value: d3.id,
         label: d3.label,
@@ -22705,7 +22802,7 @@ async function runSetup(projectRoot, catalog) {
     (h3) => allHarnessWriters.some((w2) => w2.id === h3)
   );
   const selectedHarnesses = await Lt2({
-    message: "Harnesses \u2014 which coding agents should receive config?",
+    message: "Which coding agents should receive config?\nADE generates config files for each agent you select.\n",
     options: harnessOptions,
     initialValues: validExistingHarnesses && validExistingHarnesses.length > 0 ? validExistingHarnesses : ["universal"],
     required: false
@@ -22746,7 +22843,27 @@ async function runSetup(projectRoot, catalog) {
 To use the latest defaults, remove .ade/skills/ and re-run setup.`
     );
   }
-  await installSkills(logicalConfig.skills, projectRoot);
+  if (logicalConfig.skills.length > 0) {
+    const skillNames = logicalConfig.skills.map((s) => `  \u2022 ${s.name}`).join("\n");
+    const confirmInstall = await Rt({
+      message: `Install ${logicalConfig.skills.length} skill(s) now?
+` + skillNames + `
+You can also install them later with:
+  npx @codemcp/skills experimental_install`,
+      initialValue: true
+    });
+    if (typeof confirmInstall === "symbol") {
+      Nt("Setup cancelled.");
+      return;
+    }
+    if (confirmInstall) {
+      await installSkills(logicalConfig.skills, projectRoot);
+    } else {
+      R2.info(
+        "Skills not installed. Run manually when ready:\n  npx @codemcp/skills experimental_install"
+      );
+    }
+  }
   if (logicalConfig.knowledge_sources.length > 0) {
     R2.info(
       "Knowledge sources selected. Initialize them separately:\n  npx @codemcp/knowledge init"
@@ -22779,7 +22896,7 @@ function promptSelect(facet, existingChoices) {
   }
   const initialValue = getValidInitialValue(facet, existingChoices);
   return Jt({
-    message: facet.label,
+    message: `${facet.label} \u2014 ${facet.description}`,
     options: options2,
     ...initialValue !== void 0 && { initialValue }
   });
@@ -22792,7 +22909,7 @@ function promptMultiSelect(facet, existingChoices) {
   }));
   const initialValues = getValidInitialValues(facet, existingChoices);
   return Lt2({
-    message: facet.label,
+    message: `${facet.label} \u2014 ${facet.description}`,
     options: options2,
     required: false,
     ...initialValues !== void 0 && { initialValues }
@@ -22831,7 +22948,23 @@ async function runInstall(projectRoot, harnessIds) {
 To use the latest defaults, remove .ade/skills/ and re-run install.`
     );
   }
-  await installSkills(logicalConfig.skills, projectRoot);
+  if (logicalConfig.skills.length > 0) {
+    const confirmInstall = await Rt({
+      message: `Install ${logicalConfig.skills.length} skill(s) now?`,
+      initialValue: true
+    });
+    if (typeof confirmInstall === "symbol") {
+      Nt("Install cancelled.");
+      return;
+    }
+    if (confirmInstall) {
+      await installSkills(logicalConfig.skills, projectRoot);
+    } else {
+      R2.info(
+        "Skills not installed. Run manually when ready:\n  npx @codemcp/skills experimental_install"
+      );
+    }
+  }
   if (logicalConfig.knowledge_sources.length > 0) {
     R2.info(
       "Knowledge sources configured. Initialize them separately:\n  npx @codemcp/knowledge init"
@@ -22861,7 +22994,14 @@ if (command === "setup") {
   console.log(version);
 } else {
   const allIds = getHarnessIds();
-  console.log(`ade v${version}`);
+  console.log(`ade v${version} \u2014 Agentic Development Environment`);
+  console.log();
+  console.log(
+    "Define how your team works with coding agents \u2014 pick your facets,"
+  );
+  console.log(
+    "ADE translates them into a shared information hierarchy in your repo."
+  );
   console.log();
   console.log("Usage: ade <command> [options]");
   console.log();

package/packages/cli/package.json

@@ -39,5 +39,5 @@
     "typescript": "catalog:",
     "vitest": "catalog:"
   },
-  "version": "0.2.6"
+  "version": "0.4.0"
 }

package/packages/cli/src/commands/conventions.integration.spec.ts

@@ -6,11 +6,18 @@ import { join } from "node:path";
 vi.mock("@clack/prompts", () => ({
   intro: vi.fn(),
   outro: vi.fn(),
+  note: vi.fn(),
   select: vi.fn(),
   multiselect: vi.fn(),
-  confirm: vi.fn(),
+  confirm: vi.fn().mockResolvedValue(true),
   isCancel: vi.fn().mockReturnValue(false),
   cancel: vi.fn(),
+  log: {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    success: vi.fn()
+  },
   spinner: vi.fn().mockReturnValue({ start: vi.fn(), stop: vi.fn() })
 }));
 

package/packages/cli/src/commands/install.integration.spec.ts

@@ -7,6 +7,7 @@ import { join } from "node:path";
 vi.mock("@clack/prompts", () => ({
   intro: vi.fn(),
   outro: vi.fn(),
+  note: vi.fn(),
   log: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
   select: vi.fn(),
   multiselect: vi.fn(),

package/packages/cli/src/commands/install.ts

@@ -51,7 +51,25 @@ export async function runInstall(
     );
   }
 
-  await installSkills(logicalConfig.skills, projectRoot);
+  if (logicalConfig.skills.length > 0) {
+    const confirmInstall = await clack.confirm({
+      message: `Install ${logicalConfig.skills.length} skill(s) now?`,
+      initialValue: true
+    });
+
+    if (typeof confirmInstall === "symbol") {
+      clack.cancel("Install cancelled.");
+      return;
+    }
+
+    if (confirmInstall) {
+      await installSkills(logicalConfig.skills, projectRoot);
+    } else {
+      clack.log.info(
+        "Skills not installed. Run manually when ready:\n  npx @codemcp/skills experimental_install"
+      );
+    }
+  }
 
   if (logicalConfig.knowledge_sources.length > 0) {
     clack.log.info(

package/packages/cli/src/commands/knowledge.integration.spec.ts

@@ -6,6 +6,7 @@ import { join } from "node:path";
 vi.mock("@clack/prompts", () => ({
   intro: vi.fn(),
   outro: vi.fn(),
+  note: vi.fn(),
   select: vi.fn(),
   multiselect: vi.fn(),
   confirm: vi.fn(),

package/packages/cli/src/commands/setup.integration.spec.ts

@@ -7,11 +7,13 @@ import { join } from "node:path";
 vi.mock("@clack/prompts", () => ({
   intro: vi.fn(),
   outro: vi.fn(),
+  note: vi.fn(),
   select: vi.fn(),
   multiselect: vi.fn(),
   confirm: vi.fn(),
   isCancel: vi.fn().mockReturnValue(false),
   cancel: vi.fn(),
+  log: { info: vi.fn(), warn: vi.fn() },
   spinner: vi.fn().mockReturnValue({ start: vi.fn(), stop: vi.fn() })
 }));
 

package/packages/cli/src/commands/setup.spec.ts

@@ -6,6 +6,7 @@ import type { Catalog, LogicalConfig } from "@codemcp/ade-core";
 vi.mock("@clack/prompts", () => ({
   intro: vi.fn(),
   outro: vi.fn(),
+  note: vi.fn(),
   select: vi.fn(),
   multiselect: vi.fn(),
   confirm: vi.fn(),
@@ -298,7 +299,7 @@ describe("runSetup", () => {
       expect(clack.multiselect).toHaveBeenCalledTimes(1);
       expect(clack.multiselect).toHaveBeenCalledWith(
         expect.objectContaining({
-          message: expect.stringContaining("Harnesses")
+          message: expect.stringContaining("coding agents")
         })
       );
     });

package/packages/cli/src/commands/setup.ts

@@ -26,7 +26,35 @@ export async function runSetup(
   projectRoot: string,
   catalog: Catalog
 ): Promise<void> {
-  clack.intro("ade setup");
+  let lineIndex = 0;
+  const LOGO_LINES = [
+    "\n",
+    " █████╗ ██████╗ ███████╗    ███████╗███████╗████████╗██╗   ██╗██████╗ ",
+    "██╔══██╗██╔══██╗██╔════╝    ██╔════╝██╔════╝╚══██╔══╝██║   ██║██╔══██╗",
+    "███████║██║  ██║█████╗      ███████╗█████╗     ██║   ██║   ██║██████╔╝",
+    "██╔══██║██║  ██║██╔══╝      ╚════██║██╔══╝     ██║   ██║   ██║██╔═══╝ ",
+    "██║  ██║██████╔╝███████╗    ███████║███████╗   ██║   ╚██████╔╝██║     ",
+    "╚═╝  ╚═╝╚═════╝ ╚══════╝    ╚══════╝╚══════╝   ╚═╝    ╚═════╝ ╚═╝     ",
+    "\n"
+  ];
+  for (const line of LOGO_LINES) {
+    lineIndex++;
+    if (lineIndex === 1) {
+      clack.intro(line);
+    } else {
+      console.log(`│  ${line}`);
+    }
+  }
+  clack.note(
+    [
+      "You're about to define how your team works with coding agents.",
+      "",
+      "Pick your facets — architecture, practices, process — and ADE",
+      "translates them into a shared information hierarchy your agents",
+      "read from the repo. One setup, consistent across the whole team."
+    ].join("\n"),
+    "ADE — Agentic Development Environment"
+  );
 
   const existingConfig = await readUserConfig(projectRoot);
   const existingChoices = existingConfig?.choices ?? {};
@@ -83,7 +111,8 @@ export async function runSetup(
 
   if (impliedDocsets.length > 0) {
     const selected = await clack.multiselect({
-      message: "Documentation — deselect any you don't need",
+      message:
+        "Documentation sources — Those will be pulled to your local disk for browsing on demand",
       options: impliedDocsets.map((d) => ({
         value: d.id,
         label: d.label,
@@ -120,7 +149,9 @@ export async function runSetup(
   );
 
   const selectedHarnesses = await clack.multiselect({
-    message: "Harnesses — which coding agents should receive config?",
+    message:
+      "Which coding agents should receive config?\n" +
+      "ADE generates config files for each agent you select.\n",
     options: harnessOptions,
     initialValues:
       validExistingHarnesses && validExistingHarnesses.length > 0
@@ -172,7 +203,31 @@ export async function runSetup(
     );
   }
 
-  await installSkills(logicalConfig.skills, projectRoot);
+  if (logicalConfig.skills.length > 0) {
+    const skillNames = logicalConfig.skills
+      .map((s) => `  • ${s.name}`)
+      .join("\n");
+    const confirmInstall = await clack.confirm({
+      message:
+        `Install ${logicalConfig.skills.length} skill(s) now?\n` +
+        skillNames +
+        `\nYou can also install them later with:\n  npx @codemcp/skills experimental_install`,
+      initialValue: true
+    });
+
+    if (typeof confirmInstall === "symbol") {
+      clack.cancel("Setup cancelled.");
+      return;
+    }
+
+    if (confirmInstall) {
+      await installSkills(logicalConfig.skills, projectRoot);
+    } else {
+      clack.log.info(
+        "Skills not installed. Run manually when ready:\n  npx @codemcp/skills experimental_install"
+      );
+    }
+  }
 
   if (logicalConfig.knowledge_sources.length > 0) {
     clack.log.info(
@@ -225,7 +280,7 @@ function promptSelect(
   const initialValue = getValidInitialValue(facet, existingChoices);
 
   return clack.select({
-    message: facet.label,
+    message: `${facet.label} — ${facet.description}`,
     options,
     ...(initialValue !== undefined && { initialValue })
   });
@@ -244,7 +299,7 @@ function promptMultiSelect(
   const initialValues = getValidInitialValues(facet, existingChoices);
 
   return clack.multiselect({
-    message: facet.label,
+    message: `${facet.label} — ${facet.description}`,
     options,
     required: false,
     ...(initialValues !== undefined && { initialValues })

package/packages/cli/src/index.ts

@@ -31,7 +31,14 @@ if (command === "setup") {
   console.log(version);
 } else {
   const allIds = getHarnessIds();
-  console.log(`ade v${version}`);
+  console.log(`ade v${version} — Agentic Development Environment`);
+  console.log();
+  console.log(
+    "Define how your team works with coding agents — pick your facets,"
+  );
+  console.log(
+    "ADE translates them into a shared information hierarchy in your repo."
+  );
   console.log();
   console.log("Usage: ade <command> [options]");
   console.log();

package/packages/core/package.json

@@ -38,5 +38,5 @@
     "typescript": "catalog:",
     "vitest": "catalog:"
   },
-  "version": "0.2.6"
+  "version": "0.4.0"
 }

package/packages/core/src/catalog/catalog.spec.ts

@@ -470,8 +470,8 @@ describe("catalog", () => {
       expect(autonomy!.required).toBe(false);
       expect(autonomy!.multiSelect).toBe(false);
       expect(autonomy!.options.map((option) => option.id)).toEqual([
-        "rigid",
         "sensible-defaults",
+        "rigid",
         "max-autonomy"
       ]);
     });