inclusion-md 0.1.0 → 0.2.1

package/README.md

@@ -94,11 +94,51 @@ npx inclusion-md init --variant design-system    # start from a domain example
 npx inclusion-md init --out docs/INCLUSION.md    # write somewhere else
 npx inclusion-md init --yes                      # accept defaults, non-interactive
 npx inclusion-md init --force                    # overwrite without prompting
+npx inclusion-md update                          # re-run questionnaire on existing file
 npx inclusion-md --help
 ```
 
 Requires Node.js 16+. No dependencies.
 
+#### The Design Decisions questionnaire
+
+After the foundational questions, the CLI offers an opt-in **Design Decisions**
+questionnaire - 13 short, skippable questions across six groups:
+
+1. **Core assumptions** - who you primarily build for, and what "default user"
+   assumptions live inside your product
+2. **Authentication & access** - how people get in, who can't, why
+3. **Information collection** - what you ask for, what's required, why
+4. **Interaction model** - how people interact, what patterns you don't support
+5. **Communication & language** - languages and tone you optimize for
+6. **Edge cases & intersections** - where the product breaks, who shows up
+   in unexpected ways
+
+The questions are grounded in three sources:
+
+- _ABLEIST: Measuring Ableist Harms in LLMs_ ([arxiv.org/abs/2510.10998](https://arxiv.org/abs/2510.10998))
+- _Centering Disability Perspectives in LLM Research and Design_ (ACM)
+- Kat Holmes, _Mismatch: How Inclusion Shapes Design_ (MIT Press)
+
+The point isn't perfect answers. The point is **conscious, documented
+tradeoffs**. Skipping a question is a valid answer; the doc just won't speak
+to that dimension yet. Run `npx inclusion-md update` later to fill more in.
+
+Answers land in your `INCLUSION.md` as a `### 1.B Design Decisions` subsection
+under Project Context. Reviewers (human and AI) can flag generated output that
+contradicts the realities you've documented.
+
+#### Updating an existing INCLUSION.md
+
+```bash
+npx inclusion-md update
+```
+
+This re-runs the Project Context + Design Decisions + Maintenance questions
+and rewrites **only** Sections 1 and 12 in place. Any edits you've made to
+the rest of the file - your engineering guidance, your language heuristics,
+your custom sections - are preserved.
+
 ### Option B: Copy the file by hand
 
 ```bash
@@ -152,7 +192,7 @@ finalizing any generated output in this repository.
 **Continue / Windsurf / Cody / etc.** - add `INCLUSION.md` to your workspace
 context configuration.
 
-### 4. Treat it like the rest of your engineering docs
+### Treat it like the rest of your engineering docs
 
 - Name an owner.
 - Review on a cadence (quarterly recommended).
@@ -193,6 +233,37 @@ disabled people - with authority, budget, and time.
 
 ---
 
+## Troubleshooting
+
+**"`npx inclusion-md` does nothing / hangs."**
+Make sure you're on Node.js 16+ (`node --version`). The CLI uses only
+built-in modules - no install step is required.
+
+**"I can't find an existing `INCLUSION.md`" when running `update`.**
+By default the CLI looks at `./INCLUSION.md`. If yours lives elsewhere,
+pass `--out`:
+
+```bash
+npx inclusion-md update --out docs/INCLUSION.md
+```
+
+**The welcome animation looks weird in CI.**
+It's automatically skipped when stdout isn't a TTY, when `--no-color` is
+passed, or when `CI=1` is set. If you're piping output, pass `--no-color`
+explicitly to be safe.
+
+**I want to script this in a setup wizard.**
+Pass `--yes` to accept all defaults and skip the optional Design Decisions
+questionnaire. Combine with `--variant`, `--out`, and `--force` for a fully
+non-interactive run.
+
+**I edited my `INCLUSION.md` and I'm worried `update` will trash it.**
+`update` only touches Section 1 (Project Context) and Section 12
+(Maintenance). Everything else is preserved verbatim. The smoke tests
+([`test/smoke.test.js`](./test/smoke.test.js)) cover this contract.
+
+---
+
 ## Contributing
 
 Pull requests, issues, translations, domain-specific extensions, and critiques

package/bin/inclusion-md.js

@@ -1,24 +1,32 @@
 #!/usr/bin/env node
 /* eslint-disable no-console */
 
-const { init } = require("../lib/init");
+const { init, update } = require("../lib/init");
 
-const HELP = `inclusion-md - scaffold an INCLUSION.md for your repository.
+const HELP = `inclusion-md - scaffold and maintain an INCLUSION.md for your repository.
 
 Usage:
-  npx inclusion-md init [options]
+  npx inclusion-md <command> [options]
   npx inclusion-md --help
 
 Commands:
   init                 Interactively generate an INCLUSION.md.
+                       Includes an opt-in 13-question Design Decisions
+                       questionnaire that surfaces the real tradeoffs
+                       your product has made.
+  update               Re-run the questionnaire against an existing
+                       INCLUSION.md. Rewrites Section 1 (Project Context)
+                       and Section 12 (Maintenance) in place. Everything
+                       else - including your edits - is preserved.
 
 Options:
   -o, --out <path>     Output path (default: ./INCLUSION.md).
-      --variant <name> Start from a variant template:
+      --variant <name> Start from a variant template (init only):
                        generic (default) | frontend-app | design-system | backend-api
       --force          Overwrite an existing INCLUSION.md without prompting.
-      --yes            Accept defaults for any unanswered prompts.
-      --no-color       Disable ANSI color output.
+  -y, --yes            Accept defaults for any unanswered prompts.
+                       Skips the optional Design Decisions questionnaire.
+      --no-color       Disable ANSI color output and skip the welcome animation.
   -h, --help           Show this help.
   -v, --version        Show CLI version.
 
@@ -26,8 +34,18 @@ Examples:
   npx inclusion-md init
   npx inclusion-md init --variant design-system
   npx inclusion-md init --out docs/INCLUSION.md --force
+  npx inclusion-md update
+  npx inclusion-md update --out docs/INCLUSION.md
+
+Troubleshooting:
+  - "I can't find an existing INCLUSION.md" - run \`init\` first, or pass
+    --out to point at the right path.
+  - Animation looks off in CI - it's automatically skipped when stdout is
+    not a TTY, when --no-color is passed, or when CI=1 is set.
+  - Want to script this? Use --yes to skip prompts and accept defaults.
 
 Read more: https://github.com/BranonConor/inclusion.md
+Companion essay: https://branon.dev/blog/posts/the-need-for-inclusion-md
 `;
 
 function parseArgs(argv) {
@@ -74,14 +92,16 @@ async function main() {
   }
   if (!args.command) args.command = "init";
 
-  if (args.command !== "init") {
+  const COMMANDS = { init, update };
+  const handler = COMMANDS[args.command];
+  if (!handler) {
     console.error(`Unknown command: ${args.command}`);
     process.stdout.write("\n" + HELP);
     process.exit(2);
   }
 
   try {
-    await init(args);
+    await handler(args);
   } catch (err) {
     if (err && err.code === "USER_CANCELLED") {
       console.error("\nCancelled. No file was written.");
@@ -92,4 +112,8 @@ async function main() {
   }
 }
 
-main();
+if (require.main === module) {
+  main();
+}
+
+module.exports = { parseArgs, HELP };

package/lib/ascii.js

@@ -0,0 +1,60 @@
+"use strict";
+
+const c = require("./colors");
+
+/**
+ * Gentle 3-frame welcome animation. Conveys "coming together" via dots that
+ * gradually connect. ASCII-only, no flashing, no inverted colors, no Unicode.
+ *
+ * Accessibility:
+ * - Skipped automatically when stdout is not a TTY (CI, piped output).
+ * - Skipped when --no-color is passed (color is the cue, not motion).
+ * - Skipped when --yes is passed (non-interactive runs).
+ * - Frames change appearance gradually (dim -> normal -> bold), not flashing.
+ * - Total runtime under 1 second.
+ */
+
+const FRAMES = [
+  ["   .     .     .   ", "                   ", "   .     .     .   "],
+  ["   o     o     o   ", "                   ", "   o     o     o   "],
+  ["   o-----o-----o   ", "         |         ", "   o-----o-----o   "],
+];
+
+function renderFrame(frame, intensity) {
+  // intensity: 0 = dim, 1 = normal, 2 = bold
+  const stylize =
+    intensity === 0 ? c.dim : intensity === 2 ? c.bold : (s) => s;
+  return frame.map((line) => stylize(line)).join("\n");
+}
+
+function clearFrame(lineCount) {
+  for (let i = 0; i < lineCount; i++) {
+    process.stdout.write("\x1b[1A\x1b[2K");
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function play({ enabled = true, frameMs = 220 } = {}) {
+  if (!enabled) return;
+  for (let i = 0; i < FRAMES.length; i++) {
+    const intensity = i === FRAMES.length - 1 ? 2 : i;
+    process.stdout.write(renderFrame(FRAMES[i], intensity) + "\n");
+    if (i < FRAMES.length - 1) {
+      await sleep(frameMs);
+      clearFrame(FRAMES[i].length + 1);
+    }
+  }
+}
+
+function shouldAnimate({ noColor, yes }) {
+  if (yes) return false;
+  if (noColor) return false;
+  if (!process.stdout.isTTY) return false;
+  if (process.env.CI) return false;
+  return true;
+}
+
+module.exports = { play, shouldAnimate, FRAMES };

package/lib/init.js

@@ -6,33 +6,142 @@ const path = require("path");
 const c = require("./colors");
 const { createPrompter } = require("./prompt");
 const { loadTemplate, renderGeneric, VARIANTS } = require("./template");
+const ascii = require("./ascii");
+const { runQuestionnaire, TOTAL_QUESTIONS } = require("./questionnaire");
 
-const BANNER = `
-${c.magenta(c.bold("INCLUSION.md"))} ${c.dim("scaffolder")}
-${c.dim("An LLM/agent context convention for model biases - https://github.com/BranonConor/inclusion.md")}
-`;
+const REPO_URL = "https://github.com/BranonConor/inclusion.md";
+const ESSAY_URL = "https://branon.dev/blog/posts/the-need-for-inclusion-md";
 
-async function init(args) {
+async function welcome(args) {
   c.set(args.color);
+  await ascii.play({
+    enabled: ascii.shouldAnimate({ noColor: !args.color, yes: args.yes }),
+  });
+  process.stdout.write(
+    "\n" +
+      c.magenta(c.bold("Welcome to the INCLUSION.md CLI!")) +
+      " " +
+      c.dim("(v" + require("../package.json").version + ")") +
+      "\n\n",
+  );
+}
+
+async function askProjectContext(p) {
+  process.stdout.write(
+    "\n" +
+      c.bold("Project Context") +
+      "\n" +
+      c.dim(
+        "These fill in Section 1. Be specific - generic answers make for generic guidance.\n",
+      ) +
+      "\n",
+  );
+
+  const product = await p.text("What does this project do?", {
+    default: "A short description of what this software does.",
+  });
+  const primaryUsers = await p.text(
+    "Who have you intentionally designed for?",
+    { default: "Describe your primary users." },
+  );
+  const underservedUsers = await p.text(
+    "Who do you know you haven't designed for well yet?",
+    {
+      default:
+        "Document a real gap (e.g. screen reader users on the dashboard; Spanish-language onboarding).",
+    },
+  );
+  const distribution = await p.text(
+    "Where is this software used? (geography, devices, network, assistive tech)",
+    {
+      default:
+        "Web/iOS/Android, primary regions, languages, common assistive technologies.",
+    },
+  );
+  const stakes = await p.text(
+    "What happens when this software excludes someone?",
+    {
+      default:
+        "Describe the real-world cost (loss of access to healthcare, employment, civic services).",
+    },
+  );
+
+  return { product, primaryUsers, underservedUsers, distribution, stakes };
+}
+
+async function askMaintenance(p) {
+  process.stdout.write("\n" + c.bold("Maintenance") + "\n\n");
+  const owner = await p.text("Who owns this file? (person or team)", {
+    default: "An accountable person or team",
+  });
+  const cadence = await p.choice(
+    "How often will this file be reviewed?",
+    [
+      { value: "Monthly.", label: "Monthly" },
+      { value: "Quarterly.", label: "Quarterly", hint: "Recommended." },
+      { value: "Twice a year.", label: "Twice a year" },
+      { value: "Annually (minimum).", label: "Annually (minimum)" },
+    ],
+    { default: 1 },
+  );
+  const feedback = await p.text(
+    "How can users and contributors report exclusionary patterns?",
+    {
+      default:
+        "Open an issue on this repository, or contact the owner directly.",
+    },
+  );
+  return { owner, cadence, feedback };
+}
+
+async function init(args) {
+  await welcome(args);
 
-  process.stdout.write(BANNER + "\n");
   process.stdout.write(
-    c.dim(
-      "I'll ask a few questions about your project, then write a customized\n" +
-        "INCLUSION.md to disk. Press Ctrl+C any time to bail.\n"
-    ) + "\n"
+    "Let's generate an inclusion context document for your project. There are\n" +
+      "two simple parts to this:\n\n" +
+      `  ${c.cyan("Part 1")}  I'll start from a foundational template with general\n` +
+      `          inclusion guidance to help AI agents reason about their\n` +
+      `          training-data biases.\n\n` +
+      `  ${c.cyan("Part 2")}  Your turn. A short Project Context questionnaire (and an\n` +
+      `          optional, deeper Design Decisions one) so I can fold your\n` +
+      `          project-specific reality into the doc.\n\n` +
+      "Then we're done.\n\n",
   );
 
   const p = createPrompter({ acceptDefaults: !!args.yes });
 
   try {
+    const proceed = await p.confirm("Should we dive in?", { default: true });
+    if (!proceed) {
+      process.stdout.write(
+        "\n" +
+          c.cyan(
+            "No worries! Come back whenever you're ready. Your future users will thank you.",
+          ) +
+          "\n",
+      );
+      p.close();
+      return;
+    }
+
+    process.stdout.write(
+      "\n" +
+        c.green("✓ ") +
+        "Awesome. Step 1: loading the foundational template + general inclusion guidance...\n",
+    );
+
     // --- variant ----------------------------------------------------------
     let variant = args.variant;
     if (!variant) {
       variant = await p.choice(
         "Which template do you want to start from?",
         [
-          { value: "generic", label: "Generic", hint: "Default. Good for most repos." },
+          {
+            value: "generic",
+            label: "Generic",
+            hint: "Default. Good for most repos.",
+          },
           {
             value: "frontend-app",
             label: "Frontend web app",
@@ -49,145 +158,179 @@ async function init(args) {
             hint: "Schema, errors, auth, telemetry.",
           },
         ],
-        { default: 0 }
+        { default: 0 },
       );
     }
     if (!VARIANTS[variant]) {
       throw new Error(
-        `Unknown variant "${variant}". Choose one of: ${Object.keys(VARIANTS).join(", ")}.`
+        `Unknown variant "${variant}". Choose one of: ${Object.keys(VARIANTS).join(", ")}.`,
       );
     }
 
-    process.stdout.write("\n" + c.bold("Project context") + "\n");
+    const projectContext = await askProjectContext(p);
     process.stdout.write(
-      c.dim(
-        "These answers fill in Section 1. Be specific - generic answers make for generic guidance.\n"
-      ) + "\n"
+      "\n" +
+        c.green("✓ ") +
+        "Great, that's the foundational context.\n",
     );
 
-    const product = await p.text("What does this project do?", {
-      default: "A short description of what this software does.",
-    });
-    const primaryUsers = await p.text("Who have you intentionally designed for?", {
-      default: "Describe your primary users.",
-    });
-    const underservedUsers = await p.text(
-      "Who do you know you haven't designed for well yet?",
-      {
-        default:
-          "Document a real gap here (e.g. screen reader users on the dashboard; Spanish-language onboarding).",
-      }
-    );
-    const distribution = await p.text(
-      "Where is this software used? (geography, devices, network, assistive tech)",
-      {
-        default:
-          "Web/iOS/Android, primary regions, languages, common assistive technologies.",
-      }
-    );
-    const stakes = await p.text(
-      "What happens when this software excludes someone?",
-      {
-        default:
-          "Describe the real-world cost of exclusion (loss of access to healthcare, employment, civic services, etc.).",
-      }
-    );
+    // --- Design Decisions (opt-in) ---------------------------------------
+    let designDecisions = {};
+    const wantsDecisions = args.yes
+      ? false
+      : await p.confirm(
+          `Want to also fill in the Design Decisions questionnaire? (${TOTAL_QUESTIONS} short questions, all skippable)`,
+          { default: true },
+        );
 
-    process.stdout.write("\n" + c.bold("Maintenance") + "\n\n");
+    if (wantsDecisions) {
+      designDecisions = await runQuestionnaire(p);
+      process.stdout.write(
+        c.green("✓ ") + "Done. Folding your answers into the doc.\n",
+      );
+    }
 
-    const owner = await p.text("Who owns this file? (person or team)", {
-      default: "An accountable person or team",
-    });
-    const cadence = await p.choice(
-      "How often will this file be reviewed?",
-      [
-        { value: "Monthly.", label: "Monthly" },
-        { value: "Quarterly.", label: "Quarterly", hint: "Recommended." },
-        { value: "Twice a year.", label: "Twice a year" },
-        { value: "Annually (minimum).", label: "Annually (minimum)" },
-      ],
-      { default: 1 }
-    );
-    const feedback = await p.text(
-      "How can users and contributors report exclusionary patterns?",
-      {
-        default:
-          "Open an issue on this repository, or contact the owner directly.",
-      }
-    );
+    const maintenance = await askMaintenance(p);
 
     // --- output path ------------------------------------------------------
-    const outPath = path.resolve(
-      process.cwd(),
-      args.out || "INCLUSION.md"
-    );
+    const outPath = path.resolve(process.cwd(), args.out || "INCLUSION.md");
+    const allAnswers = { ...projectContext, ...maintenance, designDecisions };
 
     if (fs.existsSync(outPath) && !args.force) {
-      const overwrite = await p.confirm(
-        `${path.relative(process.cwd(), outPath) || outPath} already exists. Overwrite?`,
-        { default: false }
+      const choice = await p.choice(
+        `${path.relative(process.cwd(), outPath) || outPath} already exists. What now?`,
+        [
+          {
+            value: "update",
+            label: "Update it in place",
+            hint: "Keeps your edits; only rewrites Section 1 + Section 12.",
+          },
+          {
+            value: "overwrite",
+            label: "Overwrite with a fresh template",
+            hint: "Discards all existing content.",
+          },
+          { value: "abort", label: "Cancel" },
+        ],
+        { default: 0 },
       );
-      if (!overwrite) {
+      if (choice === "abort") {
         process.stdout.write(
-          c.yellow("\nAborted. ") + "Existing file left untouched.\n"
+          c.yellow("\nAborted. ") + "Existing file left untouched.\n",
         );
         p.close();
         return;
       }
+      if (choice === "update") {
+        const existing = fs.readFileSync(outPath, "utf8");
+        const rendered = renderGeneric(existing, allAnswers);
+        fs.writeFileSync(outPath, rendered, "utf8");
+        p.close();
+        printSuccess(outPath, rendered, "updated");
+        return;
+      }
     }
 
-    // --- render -----------------------------------------------------------
     const template = loadTemplate(variant);
-    const answers = {
-      product,
-      primaryUsers,
-      underservedUsers,
-      distribution,
-      stakes,
-      owner,
-      cadence,
-      feedback,
-    };
-
-    let rendered;
-    if (variant === "generic") {
-      rendered = renderGeneric(template, answers);
-    } else {
-      rendered = prependPersonalizedContext(template, answers);
-    }
+    const rendered = renderGeneric(template, allAnswers);
 
     fs.mkdirSync(path.dirname(outPath), { recursive: true });
     fs.writeFileSync(outPath, rendered, "utf8");
 
     p.close();
+    printSuccess(outPath, rendered, "wrote");
+  } finally {
+    p.close();
+  }
+}
 
-    const rel = path.relative(process.cwd(), outPath) || outPath;
+async function update(args) {
+  await welcome(args);
+
+  const outPath = path.resolve(process.cwd(), args.out || "INCLUSION.md");
+  if (!fs.existsSync(outPath)) {
     process.stdout.write(
-      "\n" +
-        c.green("✓ ") +
-        c.bold(`Wrote ${rel}`) +
-        c.dim(` (${formatBytes(Buffer.byteLength(rendered))})`) +
-        "\n\n"
+      c.yellow("Hmm, I can't find an INCLUSION.md at ") +
+        c.bold(path.relative(process.cwd(), outPath) || outPath) +
+        ".\n" +
+        c.dim("Run ") +
+        c.cyan("npx inclusion-md init") +
+        c.dim(" to create one, or pass ") +
+        c.cyan("--out <path>") +
+        c.dim(" to point at the right location.\n"),
     );
+    process.exit(1);
+  }
 
-    printNextSteps(rel);
+  process.stdout.write(
+    "Updating " +
+      c.bold(path.relative(process.cwd(), outPath) || outPath) +
+      ".\n" +
+      c.dim(
+        "I'll re-ask the questionnaire and rewrite Section 1 (Project Context) + Section 12 (Maintenance).\n" +
+          "Everything else - including any edits you've made - is preserved.\n",
+      ) +
+      "\n",
+  );
+
+  const p = createPrompter({ acceptDefaults: !!args.yes });
+
+  try {
+    const proceed = await p.confirm("Cool to proceed?", { default: true });
+    if (!proceed) {
+      process.stdout.write(c.yellow("\nAborted.\n"));
+      p.close();
+      return;
+    }
+
+    const projectContext = await askProjectContext(p);
+
+    let designDecisions = {};
+    const wantsDecisions = args.yes
+      ? false
+      : await p.confirm("Update the Design Decisions section too?", {
+          default: true,
+        });
+    if (wantsDecisions) {
+      designDecisions = await runQuestionnaire(p);
+    }
+
+    const maintenance = await askMaintenance(p);
+
+    const existing = fs.readFileSync(outPath, "utf8");
+    const rendered = renderGeneric(existing, {
+      ...projectContext,
+      ...maintenance,
+      designDecisions,
+    });
+
+    fs.writeFileSync(outPath, rendered, "utf8");
+    p.close();
+    printSuccess(outPath, rendered, "updated");
   } finally {
     p.close();
   }
 }
 
-function prependPersonalizedContext(template, answers) {
-  // For non-generic variants, the canonical template already has its own
-  // Section 1. We replace it with the user's answers.
-  return renderGeneric(template, answers);
-}
-
 function formatBytes(n) {
   if (n < 1024) return `${n} B`;
   if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
   return `${(n / 1024 / 1024).toFixed(2)} MB`;
 }
 
+function printSuccess(outPath, rendered, verb) {
+  const rel = path.relative(process.cwd(), outPath) || outPath;
+  process.stdout.write(
+    "\n" +
+      c.green("✓ ") +
+      c.bold(`${verb === "updated" ? "Updated" : "Wrote"} ${rel}`) +
+      c.dim(` (${formatBytes(Buffer.byteLength(rendered))})`) +
+      "\n\n",
+  );
+
+  printNextSteps(rel);
+}
+
 function printNextSteps(file) {
   process.stdout.write(
     c.bold("Next steps") +
@@ -200,11 +343,11 @@ function printNextSteps(file) {
       `     Always read and follow /INCLUSION.md.\n\n` +
       `     ${c.dim("# Claude Code - CLAUDE.md")}\n` +
       `     Read /INCLUSION.md and apply its review prompts.\n\n` +
-      `  3. Commit it. Treat it like the rest of your engineering docs.\n\n` +
-      c.dim(
-        "Companion essay: https://branon.dev/blog/posts/the-need-for-inclusion-md\n"
-      )
+      `  3. Commit it. Treat it like the rest of your engineering docs.\n` +
+      `  4. Run ${c.cyan("npx inclusion-md update")} on a cadence (quarterly is a good default).\n\n` +
+      c.dim(`Companion essay: ${ESSAY_URL}\n`) +
+      c.dim(`Repo:             ${REPO_URL}\n`),
   );
 }
 
-module.exports = { init };
+module.exports = { init, update };

package/lib/prompt.js

@@ -17,13 +17,26 @@ function createPrompter({ acceptDefaults = false } = {}) {
     throw err;
   });
 
+  // Track the in-flight ask() so a single 'close' listener can reject it.
+  // Registering rl.once("close", ...) inside ask() leaked one listener per
+  // prompt and triggered MaxListenersExceededWarning around question ~11.
+  let pendingReject = null;
+  rl.on("close", () => {
+    if (pendingReject) {
+      const err = new Error("Cancelled by user");
+      err.code = "USER_CANCELLED";
+      const reject = pendingReject;
+      pendingReject = null;
+      reject(err);
+    }
+  });
+
   function ask(question) {
     return new Promise((resolve, reject) => {
-      rl.question(question, (answer) => resolve(answer));
-      rl.once("close", () => {
-        const err = new Error("Cancelled by user");
-        err.code = "USER_CANCELLED";
-        reject(err);
+      pendingReject = reject;
+      rl.question(question, (answer) => {
+        pendingReject = null;
+        resolve(answer);
       });
     });
   }
@@ -36,7 +49,9 @@ function createPrompter({ acceptDefaults = false } = {}) {
   async function text(label, { default: def = "", required = false } = {}) {
     if (acceptDefaults) return def;
     while (true) {
-      const raw = await ask(`${c.cyan("?")} ${c.bold(label)}${fmtDefault(def)}: `);
+      const raw = await ask(
+        `${c.cyan("?")} ${c.bold(label)}${fmtDefault(def)}: `,
+      );
       const val = (raw || "").trim();
       if (val) return val;
       if (def) return def;
@@ -49,10 +64,12 @@ function createPrompter({ acceptDefaults = false } = {}) {
     if (acceptDefaults) return def;
     process.stdout.write(
       `${c.cyan("?")} ${c.bold(label)}\n` +
-        c.dim("  (one item per line; empty line to finish")
+        c.dim("  (one item per line; empty line to finish"),
     );
     if (def)
-      process.stdout.write(c.dim(`; press enter immediately to accept default`));
+      process.stdout.write(
+        c.dim(`; press enter immediately to accept default`),
+      );
     process.stdout.write(c.dim(")\n"));
     const lines = [];
     while (true) {
@@ -73,18 +90,24 @@ function createPrompter({ acceptDefaults = false } = {}) {
       process.stdout.write(
         `  ${marker} ${c.bold(String(i + 1))}) ${opt.label}` +
           (opt.hint ? c.dim(`  - ${opt.hint}`) : "") +
-          "\n"
+          "\n",
       );
     });
     while (true) {
-      const raw = await ask(c.dim(`  choose 1-${options.length} `) + fmtDefault(defIndex + 1) + ": ");
+      const raw = await ask(
+        c.dim(`  choose 1-${options.length} `) +
+          fmtDefault(defIndex + 1) +
+          ": ",
+      );
       const val = (raw || "").trim();
       if (val === "") return options[defIndex].value;
       const n = parseInt(val, 10);
       if (Number.isInteger(n) && n >= 1 && n <= options.length) {
         return options[n - 1].value;
       }
-      process.stdout.write(c.yellow(`  Please enter a number 1-${options.length}.\n`));
+      process.stdout.write(
+        c.yellow(`  Please enter a number 1-${options.length}.\n`),
+      );
     }
   }
 
@@ -92,7 +115,9 @@ function createPrompter({ acceptDefaults = false } = {}) {
     if (acceptDefaults) return def;
     const hint = def ? "Y/n" : "y/N";
     while (true) {
-      const raw = await ask(`${c.cyan("?")} ${c.bold(label)} ${c.dim(`(${hint})`)}: `);
+      const raw = await ask(
+        `${c.cyan("?")} ${c.bold(label)} ${c.dim(`(${hint})`)}: `,
+      );
       const val = (raw || "").trim().toLowerCase();
       if (val === "") return def;
       if (val === "y" || val === "yes") return true;

package/lib/questionnaire.js

@@ -0,0 +1,285 @@
+"use strict";
+
+const c = require("./colors");
+
+/**
+ * Design Decisions questionnaire. 13 questions across 6 groups, each
+ * skippable. Surfaces the real tradeoffs your product makes - who you've
+ * intentionally designed for, who you know is excluded, and why.
+ *
+ * Grounded in:
+ * - ABLEIST: Measuring Ableist Harms in LLMs (arxiv.org/abs/2510.10998)
+ * - Centering Disability Perspectives in LLM Research and Design (ACM)
+ * - Kat Holmes, Mismatch: How Inclusion Shapes Design (MIT Press)
+ *
+ * The point isn't perfect answers. It's conscious, documented tradeoffs.
+ */
+
+const GROUPS = [
+  {
+    title: "Group 1: Core Assumptions",
+    blurb:
+      "What you assume about the people using your product. These shape every other decision.",
+    questions: [
+      {
+        key: "primaryAudience",
+        label: "Who do you primarily build for?",
+        hint:
+          "Describe assumptions like language fluency, device type, network speed, technical expertise. " +
+          "Example: 'People with reliable internet, modern browsers, English fluency.'",
+      },
+      {
+        key: "implicitDefaults",
+        label:
+          "What 'default user' assumptions live inside your product today?",
+        hint:
+          "The non-disabled, English-fluent, neurotypical user with a fast connection is a statistical artifact, not a person. " +
+          "Where does that default show up in yours?",
+      },
+    ],
+  },
+  {
+    title: "Group 2: Authentication & Access",
+    blurb: "Where exclusion often happens first.",
+    questions: [
+      {
+        key: "authMethods",
+        label:
+          "How do people get into your product? What auth methods do you support?",
+        hint:
+          "Examples: email/password, email + SMS, social login, passkey, SSO, magic link.",
+      },
+      {
+        key: "authExcluded",
+        label:
+          "Is there anyone who can't use your authentication system right now?",
+        hint:
+          "Don't say 'no one' - there's always someone. Examples: people without reliable email, " +
+          "people without a phone, people in regions without SMS, people who share a device.",
+      },
+      {
+        key: "authReason",
+        label: "Why did you choose that authentication method?",
+        hint:
+          "Be honest: easiest to implement, most widely supported, security requirement, industry standard.",
+      },
+    ],
+  },
+  {
+    title: "Group 3: Information Collection",
+    blurb:
+      "What you ask for shapes who can show up. Required vs. optional matters.",
+    questions: [
+      {
+        key: "infoCollected",
+        label: "What personal information do you ask people to provide?",
+        hint:
+          "Examples: name, email, phone, DOB, location, video ID, gender (and what options?), disability status. " +
+          "Note required vs. optional.",
+      },
+      {
+        key: "infoRationale",
+        label: "For any required personal information, why is it required?",
+        hint:
+          "For each field: could we work without this? Example: 'Email required for notifications - could SMS work instead?'",
+      },
+    ],
+  },
+  {
+    title: "Group 4: Interaction Model",
+    blurb: "How people actually use the product.",
+    questions: [
+      {
+        key: "interactionModes",
+        label: "How do people interact with your product?",
+        hint:
+          "Pick all that apply: text, voice, visual/color-based, video, synchronous, asynchronous, " +
+          "touch, keyboard, motor coordination, screen reader.",
+      },
+      {
+        key: "unsupportedPatterns",
+        label: "Are there interaction patterns you consciously don't support?",
+        hint:
+          "Examples: video verification (cost), voice (bias concerns), offline mode, keyboard-only nav, " +
+          "text-to-speech, RTL languages, slow networks, mobile-only.",
+      },
+    ],
+  },
+  {
+    title: "Group 5: Communication & Language",
+    blurb: "Tone and language are inclusion choices, not aesthetic ones.",
+    questions: [
+      {
+        key: "languages",
+        label: "What language(s) do you currently support?",
+        hint:
+          "English only, English + [list], multilingual from day 1, plan to add languages in [timeframe].",
+      },
+      {
+        key: "communicationStyle",
+        label: "What communication style(s) are you optimizing for?",
+        hint:
+          "Formal/professional, casual/friendly, technical, plain-language, direct. " +
+          "Example: 'Casual + friendly, but avoid metaphors that might be ableist.'",
+      },
+    ],
+  },
+  {
+    title: "Group 6: Edge Cases & Intersections",
+    blurb:
+      "Specific scenarios where the product breaks - or where unexpected users show up.",
+    questions: [
+      {
+        key: "knownBreakage",
+        label: "What's one scenario where your product might not work?",
+        hint:
+          "Be specific, not vague. Example: 'People in rural areas with <1 Mbps internet' or 'Left-handed users on touch devices.'",
+      },
+      {
+        key: "unexpectedUsers",
+        label: "Who might use your product in ways you didn't expect?",
+        hint:
+          "Examples: older relatives, people in different countries, people with low vision zooming, " +
+          "screen reader users, people with limited energy, teams in different time zones, non-native speakers.",
+      },
+    ],
+  },
+];
+
+const TOTAL_QUESTIONS = GROUPS.reduce((n, g) => n + g.questions.length, 0);
+
+async function runQuestionnaire(p) {
+  process.stdout.write(
+    "\n" +
+      c.bold("Design Decisions") +
+      " " +
+      c.dim(`(${TOTAL_QUESTIONS} questions, all skippable)`) +
+      "\n" +
+      c.dim(
+        "These surface the real tradeoffs your product makes. Skip any with an empty answer.\n",
+      ) +
+      "\n",
+  );
+
+  const answers = {};
+  let asked = 0;
+
+  for (let g = 0; g < GROUPS.length; g++) {
+    const group = GROUPS[g];
+    process.stdout.write(
+      c.cyan(group.title) +
+        "\n" +
+        c.dim(`  ${group.blurb}`) +
+        "\n\n",
+    );
+
+    for (const q of group.questions) {
+      asked++;
+      process.stdout.write(
+        c.dim(`Question ${asked} of ${TOTAL_QUESTIONS}`) + "\n",
+      );
+      if (q.hint) {
+        process.stdout.write(c.dim(`  ${q.hint}`) + "\n");
+      }
+      const val = await p.text(q.label, { default: "", required: false });
+      if (val) {
+        answers[q.key] = val;
+      } else {
+        process.stdout.write(
+          c.dim("  (skipped - you can fill this in later)\n"),
+        );
+      }
+      process.stdout.write("\n");
+    }
+
+    if (g < GROUPS.length - 1) {
+      process.stdout.write(c.dim("  ---\n\n"));
+    }
+  }
+
+  return answers;
+}
+
+function hasAnyAnswers(designDecisions) {
+  return designDecisions && Object.keys(designDecisions).length > 0;
+}
+
+function renderDesignDecisionsMarkdown(answers) {
+  if (!hasAnyAnswers(answers)) return "";
+
+  const lines = [];
+  lines.push("### 1.B Design Decisions");
+  lines.push("");
+  lines.push(
+    "Conscious tradeoffs documented as part of this project's inclusion posture. " +
+      "These are not aspirations - they're current realities, surfaced so reviewers " +
+      "(human and AI) can flag when generated output assumes otherwise.",
+  );
+  lines.push("");
+
+  const sectionMap = [
+    {
+      heading: "**Core assumptions**",
+      keys: [
+        ["primaryAudience", "Primary audience"],
+        ["implicitDefaults", "Implicit defaults"],
+      ],
+    },
+    {
+      heading: "**Authentication & access**",
+      keys: [
+        ["authMethods", "Methods supported"],
+        ["authExcluded", "Known exclusion"],
+        ["authReason", "Reason for choice"],
+      ],
+    },
+    {
+      heading: "**Information collection**",
+      keys: [
+        ["infoCollected", "Information collected"],
+        ["infoRationale", "Why it's required"],
+      ],
+    },
+    {
+      heading: "**Interaction model**",
+      keys: [
+        ["interactionModes", "Interaction modes"],
+        ["unsupportedPatterns", "Patterns not supported"],
+      ],
+    },
+    {
+      heading: "**Communication & language**",
+      keys: [
+        ["languages", "Languages supported"],
+        ["communicationStyle", "Communication style"],
+      ],
+    },
+    {
+      heading: "**Edge cases & intersections**",
+      keys: [
+        ["knownBreakage", "Known breakage scenarios"],
+        ["unexpectedUsers", "Unexpected users"],
+      ],
+    },
+  ];
+
+  for (const section of sectionMap) {
+    const entries = section.keys.filter(([k]) => answers[k]);
+    if (entries.length === 0) continue;
+    lines.push(section.heading);
+    for (const [key, label] of entries) {
+      lines.push(`- _${label}:_ ${answers[key]}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+module.exports = {
+  runQuestionnaire,
+  renderDesignDecisionsMarkdown,
+  hasAnyAnswers,
+  GROUPS,
+  TOTAL_QUESTIONS,
+};

package/lib/template.js

@@ -3,6 +3,11 @@
 const fs = require("fs");
 const path = require("path");
 
+const {
+  renderDesignDecisionsMarkdown,
+  hasAnyAnswers,
+} = require("./questionnaire");
+
 const VARIANTS = {
   generic: "INCLUSION.md",
   "frontend-app": "examples/frontend-app/INCLUSION.md",
@@ -14,7 +19,7 @@ function loadTemplate(variant) {
   const rel = VARIANTS[variant];
   if (!rel) {
     throw new Error(
-      `Unknown variant "${variant}". Choose one of: ${Object.keys(VARIANTS).join(", ")}.`
+      `Unknown variant "${variant}". Choose one of: ${Object.keys(VARIANTS).join(", ")}.`,
     );
   }
   // Resolve relative to the package root (one level up from /lib).
@@ -36,17 +41,33 @@ function renderGeneric(template, answers) {
   let out = template;
 
   // --- Section 1: Project Context -----------------------------------------
+  const projectContextLines = [
+    `## 1. Project Context`,
+    ``,
+    `### 1.A Overview`,
+    ``,
+    `- **Product:** ${answers.product}`,
+    `- **Primary users:** ${answers.primaryUsers}`,
+    `- **Known underserved users:** ${answers.underservedUsers}`,
+    `- **Distribution context:** ${answers.distribution}`,
+    `- **Stakes:** ${answers.stakes}`,
+    ``,
+    `Generated code, copy, and interaction patterns should be evaluated against the`,
+    `context above before being merged.`,
+  ];
+
+  const designDecisionsBlock = hasAnyAnswers(answers.designDecisions)
+    ? "\n\n" + renderDesignDecisionsMarkdown(answers.designDecisions).trimEnd()
+    : "";
+
   const newProjectContext =
-    `## 1. Project Context\n\n` +
-    `- **Product:** ${answers.product}\n` +
-    `- **Primary users:** ${answers.primaryUsers}\n` +
-    `- **Known underserved users:** ${answers.underservedUsers}\n` +
-    `- **Distribution context:** ${answers.distribution}\n` +
-    `- **Stakes:** ${answers.stakes}\n\n` +
-    `Generated code, copy, and interaction patterns should be evaluated against the\n` +
-    `context above before being merged.`;
+    projectContextLines.join("\n") + designDecisionsBlock;
 
-  out = replaceSection(out, /^## 1\. Project Context[\s\S]*?(?=^---\s*$)/m, newProjectContext + "\n\n");
+  out = replaceSection(
+    out,
+    /^## 1\. Project Context[\s\S]*?(?=^---\s*$)/m,
+    newProjectContext + "\n\n",
+  );
 
   // --- Section 12: Maintenance --------------------------------------------
   const newMaintenance =
@@ -57,7 +78,11 @@ function renderGeneric(template, answers) {
     `  [\`CHANGELOG.md\`](./CHANGELOG.md) or in repository releases.\n` +
     `- **Feedback:** ${answers.feedback}`;
 
-  out = replaceSection(out, /^## 12\. Maintenance[\s\S]*?(?=^---\s*$)/m, newMaintenance + "\n\n");
+  out = replaceSection(
+    out,
+    /^## 12\. Maintenance[\s\S]*?(?=^---\s*$)/m,
+    newMaintenance + "\n\n",
+  );
 
   return out;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inclusion-md",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Scaffold an INCLUSION.md - a context engineering doc that gives AI coding assistants inclusion-oriented guidance during code generation.",
   "keywords": [
     "inclusion",
@@ -41,6 +41,7 @@
     "node": ">=16"
   },
   "scripts": {
-    "test": "node bin/inclusion-md.js --help"
+    "test": "node --test test/",
+    "help": "node bin/inclusion-md.js --help"
   }
 }