@grainulation/wheat 1.0.4 → 1.0.6

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@grainulation/wheat"><img src="https://img.shields.io/npm/v/@grainulation/wheat" alt="npm version"></a> <a href="https://www.npmjs.com/package/@grainulation/wheat"><img src="https://img.shields.io/npm/dm/@grainulation/wheat" alt="npm downloads"></a> <a href="https://github.com/grainulation/wheat/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license"></a> <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/@grainulation/wheat" alt="node"></a> <a href="https://github.com/grainulation/wheat/actions"><img src="https://github.com/grainulation/wheat/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@grainulation/wheat"><img src="https://img.shields.io/npm/v/@grainulation/wheat?label=%40grainulation%2Fwheat" alt="npm version"></a> <a href="https://www.npmjs.com/package/@grainulation/wheat"><img src="https://img.shields.io/npm/dm/@grainulation/wheat" alt="npm downloads"></a> <a href="https://github.com/grainulation/wheat/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license"></a> <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/@grainulation/wheat" alt="node"></a> <a href="https://github.com/grainulation/wheat/actions"><img src="https://github.com/grainulation/wheat/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://deepwiki.com/grainulation/wheat"><img src="https://deepwiki.com/badge.svg" alt="Explore on DeepWiki"></a>
 </p>
 
@@ -15,118 +15,99 @@ The migration will take months. It will cost real money. And right now, the deci
 
 You'd never ship code without tests. Why ship a decision without validated evidence?
 
-Wheat is a continuous planning pipeline. Every finding is a typed assertion. A compiler validates them. You can't ship with contradictions, same as you can't merge with failing tests.
-
-## Install
+## Quick start
 
 ```bash
-npx @grainulation/wheat init
+npx @grainulation/wheat "Should we migrate to GraphQL?"
 ```
 
-No dependencies are added to your project. No `node_modules` pollution. Wheat is a tool you run, not a library you import.
+One command. Zero prompts. Sprint ready in under 3 seconds.
 
-## See it in 30 seconds
+Then open your AI coding tool and start investigating:
 
-```bash
-npx @grainulation/wheat quickstart
+```
+/research "GraphQL performance vs REST"
+/challenge r003
+/blind-spot
+/brief
 ```
 
-Creates a demo build with pre-seeded assertions, an intentional conflict, compiles everything, and opens a dashboard. You'll see the compiler flag the conflict and block output until it's resolved.
+Works with [Claude Code](https://claude.com/claude-code), [Cursor](https://cursor.com), [GitHub Copilot](https://github.com/features/copilot), or standalone via CLI.
 
-## Start a real investigation
+## Full MCP integration (optional)
+
+For native tool access in Claude Code:
 
 ```bash
-npx @grainulation/wheat init
+claude mcp add wheat -- npx -y @grainulation/wheat mcp
 ```
 
-Wheat asks a few questions -- what you're investigating, who needs the answer, what constraints exist. Then it scaffolds the investigation in your repo:
-
-```
-claims.json          # Typed assertions (the test suite for your decision)
-CLAUDE.md            # AI assistant configuration
-.claude/commands/    # 18 slash commands
-output/              # Where compiled artifacts land
-```
+This gives Claude direct access to wheat's claims engine — add-claim, compile, search, status — without shelling out.
 
-Open Claude Code and start investigating:
+## See it in 30 seconds
 
-```
-/research "Postgres migration risks"
-/prototype                              # build something testable
-/challenge r003                         # stress-test a finding
-/blind-spot                             # what are we missing?
-/brief                                  # compile the decision document
+```bash
+npx @grainulation/wheat quickstart
 ```
 
+Creates a demo sprint with pre-seeded claims, an intentional conflict, compiles everything, and opens a dashboard. The compiler flags the conflict and blocks output until it's resolved.
+
 ## How it works
 
-Wheat is a continuous planning pipeline. Findings are validated as they come in, not after the fact:
+Wheat is a continuous planning pipeline. Findings are validated as they come in:
 
 ```
-You investigate  -->  Assertions accumulate  -->  Compiler validates  -->  Artifacts compile
-   /research          claims.json                 wheat compile            /brief, /present
-   /prototype         (typed, evidence-graded)    (7-pass pipeline)        (backed by evidence)
-   /challenge
+You investigate  →  Claims accumulate  →  Compiler validates  →  Brief compiles
+  /research          typed, evidence-graded   7-pass pipeline       backed by evidence
+  /prototype
+  /challenge
 ```
 
-**Assertion types:** constraint, factual, estimate, risk, recommendation, feedback
+**Claim types:** constraint, factual, estimate, risk, recommendation, feedback
 
-**Evidence tiers** (like test coverage): stated (untested) > web > documented > tested > production (battle-hardened)
+**Evidence tiers:** stated → web → documented → tested → production
 
-The compiler catches conflicts, warns about weak evidence, and blocks the build when issues exist. You cannot ship a brief built on unresolved contradictions — same as you can't merge with failing tests.
+The compiler catches conflicts, flags weak evidence, and blocks the build when issues exist. You can't ship a brief built on contradictions — same as you can't merge with failing tests.
 
 ## Commands
 
-| Command               | What it does                                      |
-| --------------------- | ------------------------------------------------- |
-| `/init`               | Bootstrap a new research sprint                   |
-| `/research <topic>`   | Deep dive on a topic, creates claims              |
-| `/prototype`          | Build something testable                          |
-| `/challenge <id>`     | Adversarial stress-test of a claim                |
-| `/witness <id> <url>` | External corroboration                            |
-| `/blind-spot`         | Find gaps in your investigation                   |
-| `/status`             | Sprint dashboard                                  |
-| `/brief`              | Compile the decision document                     |
-| `/present`            | Generate a stakeholder presentation               |
-| `/feedback`           | Incorporate stakeholder input                     |
-| `/resolve`            | Adjudicate conflicts between claims               |
-| `/replay`             | Time-travel through sprint history                |
-| `/calibrate`          | Score predictions against actual outcomes         |
-| `/handoff`            | Package sprint for knowledge transfer             |
-| `/merge <path>`       | Combine findings across sprints                   |
-| `/connect <type>`     | Link external tools (Jira, docs, etc.)            |
-| `/evaluate`           | Test claims against reality, resolve conflicts    |
-| `/next`               | Route next steps through Farmer (mobile feedback) |
+| Command | What it does |
+|---------|-------------|
+| `/research <topic>` | Deep dive on a topic, creates claims |
+| `/prototype` | Build something testable |
+| `/challenge <id>` | Adversarial stress-test of a claim |
+| `/witness <id> <url>` | External corroboration |
+| `/blind-spot` | Find gaps in your investigation |
+| `/brief` | Compile the decision document |
+| `/status` | Sprint dashboard |
+| `/present` | Generate a stakeholder presentation |
+| `/resolve` | Adjudicate conflicts between claims |
 
 ## Guard rails
 
-Wheat installs two guard mechanisms:
-
-1. **Git pre-commit hook** -- prevents committing broken `claims.json`
-2. **Claude Code guard hook** -- prevents generating output artifacts from stale or blocked compilations
-
-Both are optional and can be removed.
-
-## Works in any repo
+Wheat installs two optional guard mechanisms:
 
-Wheat doesn't care what language you use. Your Scala project, your Python monorepo, your Flutter app -- wheat works the same everywhere. Node 18+ is the only requirement.
+1. **Git pre-commit hook** — prevents committing broken claims
+2. **Claude Code guard hook** — prevents generating output from stale compilations
 
-## Zero dependencies
+## Works everywhere
 
-Node built-in modules only. No npm install waterfall. No supply chain anxiety.
+Wheat doesn't care what language you use or what AI tool you run. Your Scala project, your Python monorepo, your Flutter app — wheat works the same everywhere. Node 20+ is the only requirement. Zero npm dependencies.
 
 ## Part of the grainulation ecosystem
 
-| Tool                                                         | Role                                                                           |
-| ------------------------------------------------------------ | ------------------------------------------------------------------------------ |
-| **wheat**                                                    | Research engine -- grow structured evidence                                    |
-| [farmer](https://github.com/grainulation/farmer)             | Permission dashboard -- approve AI actions in real time (admin + viewer roles) |
-| [barn](https://github.com/grainulation/barn)                 | Shared tools -- templates, validators, sprint detection                        |
-| [mill](https://github.com/grainulation/mill)                 | Format conversion -- export to PDF, CSV, slides, 24 formats                    |
-| [silo](https://github.com/grainulation/silo)                 | Knowledge storage -- reusable claim libraries and packs                        |
-| [harvest](https://github.com/grainulation/harvest)           | Analytics -- cross-sprint patterns and prediction scoring                      |
-| [orchard](https://github.com/grainulation/orchard)           | Orchestration -- multi-sprint coordination and dependencies                    |
-| [grainulation](https://github.com/grainulation/grainulation) | Unified CLI -- single entry point to the ecosystem                             |
+| Tool | Role |
+|------|------|
+| **wheat** | Research engine — grow structured evidence |
+| [farmer](https://github.com/grainulation/farmer) | Permission dashboard — approve AI actions in real time |
+| [barn](https://github.com/grainulation/barn) | Shared tools — templates, validators, sprint detection |
+| [mill](https://github.com/grainulation/mill) | Format conversion — export to PDF, CSV, slides |
+| [silo](https://github.com/grainulation/silo) | Knowledge storage — reusable claim libraries |
+| [harvest](https://github.com/grainulation/harvest) | Analytics — cross-sprint patterns and prediction scoring |
+| [orchard](https://github.com/grainulation/orchard) | Orchestration — multi-sprint coordination |
+| [grainulation](https://github.com/grainulation/grainulation) | Unified CLI — single entry point to the ecosystem |
+
+**You don't need all eight.** Start with wheat. That's it.
 
 ## License
 

package/bin/wheat.js

@@ -67,7 +67,8 @@ if (!subcommand || subcommand === "--help" || subcommand === "-h") {
   console.log(`wheat v${VERSION} — Research-driven development framework
 
 Usage:
-  wheat <command> [options]
+  wheat "your question"          Start a sprint instantly (recommended)
+  wheat <command> [options]      Run a specific command
 
 Commands:
   init       Bootstrap a new research sprint in this repo
@@ -90,11 +91,9 @@ Global options:
   --help         Show this help
 
 Examples:
-  npx @grainulation/wheat quickstart
+  npx @grainulation/wheat "Should we migrate to Postgres?"
   npx @grainulation/wheat init
   npx @grainulation/wheat compile --summary
-  npx @grainulation/wheat init --question "Should we migrate to Postgres?"
-  npx @grainulation/wheat init --non-interactive --question "..." --audience "..." --done "..."
 
 Documentation: https://github.com/grainulation/wheat`);
   process.exit(0);
@@ -189,6 +188,19 @@ Run "wheat disconnect farmer --help" for options.`);
 }
 
 if (!commands[subcommand]) {
+  // Verb-less mode: wheat "my question" → dispatch to init with auto defaults
+  const compoundCmds = ["connect", "disconnect", "migrate"];
+  if (subcommand && !subcommand.startsWith("-") && !compoundCmds.includes(subcommand)) {
+    vlog("dispatch", `verb-less mode: treating "${subcommand}" as question`);
+    const initPath = new URL(commands.init, import.meta.url).href;
+    const initHandler = await import(initPath);
+    await initHandler.run(targetDir, ["--question", subcommand, "--auto"]).catch((err) => {
+      console.error(`\nwheat failed:`, err.message);
+      if (process.env.WHEAT_DEBUG) console.error(err.stack);
+      process.exit(1);
+    });
+    process.exit(0);
+  }
   console.error(`wheat: unknown command: ${subcommand}\n`);
   console.error('Run "wheat --help" for available commands.');
   process.exit(1);

package/compiler/wheat-compiler.js

@@ -19,6 +19,7 @@ import crypto from "crypto";
 import path from "path";
 
 import { fileURLToPath } from "url";
+import { maybeHint } from "../lib/hints.js";
 
 // Sprint detection — git-based, no config pointer needed (p013/f001)
 import { detectSprints } from "./detect-sprints.js";
@@ -1195,6 +1196,17 @@ Options:
       `Certificate: ${c.compilation_certificate.input_hash.slice(0, 20)}...`
     );
 
+    if (!jsonFlag) {
+      try {
+        const hint = maybeHint(compilation, { context: "compile" });
+        if (hint) {
+          process.stderr.write("\n" + hint + "\n");
+        }
+      } catch {
+        // hints are non-critical — fail silently
+      }
+    }
+
     if (jsonFlag) {
       console.log(JSON.stringify(c, null, 2));
     }

package/lib/defaults.js

@@ -0,0 +1,32 @@
+/**
+ * Smart defaults and environment detection for wheat CLI.
+ * Zero dependencies — Node built-ins only.
+ */
+
+export const DEFAULTS = {
+  audience: ["engineers"],
+  constraints: [],
+  doneCriteria: "Decision-ready brief with evidence",
+};
+
+export function isTTY() {
+  return Boolean(process.stdout.isTTY) && !isCI();
+}
+
+export function isCI() {
+  return Boolean(
+    process.env.CI ||
+      process.env.GITHUB_ACTIONS ||
+      process.env.GITLAB_CI ||
+      process.env.CIRCLECI ||
+      process.env.JENKINS_URL ||
+      process.env.BUILDKITE,
+  );
+}
+
+export function outputMode() {
+  if (process.argv.includes("--quiet")) return "quiet";
+  if (process.argv.includes("--json")) return "json";
+  if (!isTTY()) return "json";
+  return "tty";
+}

package/lib/hints.js

@@ -0,0 +1,214 @@
+/**
+ * hints.js — Ecosystem cross-promotion hints
+ *
+ * Contextual, one-line, non-blocking hints that surface Grainulation
+ * ecosystem tools at the moment the user's workflow makes them relevant.
+ *
+ * Shows max 1 hint per invocation on stderr.
+ * Tracks shown hints in ~/.grainulation/hints.json
+ * Fails silently on any I/O error — never blocks the CLI.
+ *
+ * Zero dependencies.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import path from "path";
+import { homedir } from "os";
+
+const HINTS_DIR = path.join(homedir(), ".grainulation");
+const HINTS_FILE = path.join(HINTS_DIR, "hints.json");
+const MAX_SHOWS = 3;
+const COOLDOWN_MS = 24 * 60 * 60 * 1000; // 24h
+
+// ─── State I/O (sync, fail-silent) ──────────────────────────────────────────
+
+function readHints() {
+  try {
+    return JSON.parse(readFileSync(HINTS_FILE, "utf8"));
+  } catch {
+    return { shown: {}, dismissed: [], installed: [] };
+  }
+}
+
+function writeHints(data) {
+  try {
+    mkdirSync(HINTS_DIR, { recursive: true });
+    writeFileSync(HINTS_FILE, JSON.stringify(data, null, 2) + "\n");
+  } catch {
+    // fail silently
+  }
+}
+
+function shouldSuppress(product, state) {
+  if ((state.dismissed || []).includes(product)) return true;
+  if ((state.installed || []).includes(product)) return true;
+  const record = (state.shown || {})[product];
+  if (!record) return false;
+  if (record.count >= MAX_SHOWS) return true;
+  if (record.last && Date.now() - new Date(record.last).getTime() < COOLDOWN_MS) return true;
+  return false;
+}
+
+// ─── Triggers (ordered by priority, first match wins) ────────────────────────
+
+const TRIGGERS = [
+  // 1. >20 claims → harvest
+  function detectHarvestFromClaims(compilation) {
+    const count = compilation?.claims?.length || 0;
+    if (count > 20) {
+      return {
+        product: "harvest",
+        message: "btw: harvest can visualize claim growth across sprints (npx @grainulation/harvest)",
+      };
+    }
+    return null;
+  },
+
+  // 2. >3 topics → orchard
+  function detectOrchardFromTopics(compilation) {
+    const claims = compilation?.claims || [];
+    const topics = new Set(claims.map((c) => c.topic).filter(Boolean));
+    if (topics.size > 3) {
+      return {
+        product: "orchard",
+        message: "btw: orchard can run multiple research sprints in parallel (npx @grainulation/orchard)",
+      };
+    }
+    return null;
+  },
+
+  // 3. brief/present context → mill
+  function detectMillFromBrief(compilation, context) {
+    if (context === "brief" || context === "present") {
+      return {
+        product: "mill",
+        message: "btw: mill can export this as PDF, slides, or Confluence (npx @grainulation/mill)",
+      };
+    }
+    return null;
+  },
+
+  // 4. first ever compile → farmer
+  function detectFarmerFirstCompile(compilation, context) {
+    if (context !== "compile") return null;
+    // Check if this looks like a first compile (no prior hint state)
+    try {
+      const state = readHints();
+      const totalShows = Object.values(state.shown || {}).reduce(
+        (sum, r) => sum + (r.count || 0),
+        0
+      );
+      if (totalShows === 0) {
+        return {
+          product: "farmer",
+          message: "btw: farmer gives you a mobile dashboard for AI permissions (npx @grainulation/farmer)",
+        };
+      }
+    } catch {
+      // fail silently
+    }
+    return null;
+  },
+
+  // 5. >5 sprints → silo
+  function detectSiloFromSprints(compilation) {
+    const sprintCount = compilation?.sprints?.length || 0;
+    if (sprintCount > 5) {
+      return {
+        product: "silo",
+        message: "btw: silo stores reusable claim libraries across projects (npx @grainulation/silo)",
+      };
+    }
+    return null;
+  },
+];
+
+// ─── Format ──────────────────────────────────────────────────────────────────
+
+function formatHint(message) {
+  return `  \x1b[2m${message}\x1b[0m`;
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Evaluate trigger conditions and return a formatted hint string,
+ * or null if no hint should be shown.
+ *
+ * @param {object} compilation - The compilation.json data
+ * @param {object} opts
+ * @param {string} opts.context - "compile" | "init" | "brief" | "present"
+ * @returns {string|null} Formatted hint for stderr, or null
+ */
+export function maybeHint(compilation, opts = {}) {
+  try {
+    // Global suppression
+    if (process.env.WHEAT_BTW === "off") return null;
+    if (process.env.WHEAT_NO_HINTS === "1") return null;
+    if (process.env.CI) return null;
+    if (process.argv.includes("--quiet")) return null;
+    if (process.argv.includes("--json")) return null;
+    if (!process.stderr.isTTY) return null;
+
+    const state = readHints();
+
+    for (const trigger of TRIGGERS) {
+      const result = trigger(compilation, opts.context);
+      if (!result) continue;
+      if (shouldSuppress(result.product, state)) continue;
+
+      // Record the show
+      if (!state.shown) state.shown = {};
+      if (!state.shown[result.product]) state.shown[result.product] = { count: 0 };
+      state.shown[result.product].count++;
+      state.shown[result.product].last = new Date().toISOString();
+      writeHints(state);
+
+      return formatHint(result.message);
+    }
+  } catch {
+    // fail silently — never block the main output
+  }
+  return null;
+}
+
+/**
+ * Record that a product has been installed/connected.
+ * @param {string} product
+ */
+export function markInstalled(product) {
+  try {
+    const state = readHints();
+    if (!state.installed) state.installed = [];
+    if (!state.installed.includes(product)) {
+      state.installed.push(product);
+      writeHints(state);
+    }
+  } catch {
+    // fail silently
+  }
+}
+
+/**
+ * Record that the user dismissed hints for a product.
+ * @param {string} product
+ */
+export function dismiss(product) {
+  try {
+    const state = readHints();
+    if (!state.dismissed) state.dismissed = [];
+    if (!state.dismissed.includes(product)) {
+      state.dismissed.push(product);
+      writeHints(state);
+    }
+  } catch {
+    // fail silently
+  }
+}
+
+/**
+ * Reset all hint state (for testing).
+ */
+export function reset() {
+  writeHints({ shown: {}, dismissed: [], installed: [] });
+}

package/lib/init.js

@@ -9,7 +9,7 @@
  * Creates in the TARGET repo:
  *   - claims.json (seeded with constraint claims)
  *   - CLAUDE.md (sprint configuration for Claude Code)
- *   - .claude/commands/*.md (slash commands)
+ *   - .claude/commands/wheat/*.md (slash commands)
  *   - wheat.config.json (local config pointing back to package)
  *
  * Zero npm dependencies.
@@ -20,6 +20,8 @@ import path from "path";
 import readline from "readline";
 import { execFileSync } from "child_process";
 import { fileURLToPath } from "url";
+import { DEFAULTS, outputMode } from "./defaults.js";
+import { maybeHint } from "./hints.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -232,9 +234,9 @@ function buildClaudeMd(meta) {
 
 function copyCommands(dir) {
   const srcDir = path.join(packageRoot(), "templates", "commands");
-  const destDir = target(dir, ".claude", "commands");
+  const destDir = target(dir, ".claude", "commands", "wheat");
 
-  // Create .claude/commands/ if it doesn't exist
+  // Create .claude/commands/wheat/ if it doesn't exist
   fs.mkdirSync(destDir, { recursive: true });
 
   let copied = 0;
@@ -247,7 +249,7 @@ function copyCommands(dir) {
 
       // Don't overwrite existing commands (user may have customized)
       if (fs.existsSync(dest)) {
-        console.log(`  Skipped .claude/commands/${file} (already exists)`);
+        console.log(`  Skipped .claude/commands/wheat/${file} (already exists)`);
         continue;
       }
 
@@ -336,6 +338,86 @@ fi
   }
 }
 
+// ─── .mcp.json & AGENTS.md ──────────────────────────────────────────────────
+
+function writeMcpJson(dir) {
+  const mcpPath = target(dir, ".mcp.json");
+  const wheatEntry = {
+    command: "npx",
+    args: ["-y", "@grainulation/wheat", "mcp"],
+  };
+
+  let config = { mcpServers: {} };
+  if (fs.existsSync(mcpPath)) {
+    try {
+      config = JSON.parse(fs.readFileSync(mcpPath, "utf8"));
+      if (!config.mcpServers) config.mcpServers = {};
+    } catch {
+      // Corrupted file — overwrite with fresh config
+      config = { mcpServers: {} };
+    }
+  }
+
+  config.mcpServers.wheat = wheatEntry;
+  fs.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n");
+  console.log(
+    "  \x1b[32m+\x1b[0m .mcp.json              (Claude Code MCP auto-discovery)"
+  );
+}
+
+function writeAgentsMd(dir, meta) {
+  const agentsPath = target(dir, "AGENTS.md");
+  const constraintList =
+    meta.constraints.length > 0
+      ? meta.constraints.map((c) => `- ${c}`).join("\n")
+      : "- (none specified)";
+
+  const section = `# Wheat Research Sprint
+
+**Question:** ${meta.question}
+
+**Audience:** ${meta.audience.join(", ")}
+
+**Constraints:**
+${constraintList}
+
+**Done looks like:** ${meta.doneCriteria || "A recommendation with evidence"}
+
+## Claims System
+
+All findings are tracked as typed claims in \`claims.json\`. Claim types: constraint, factual, estimate, risk, recommendation, feedback. Evidence tiers (low to high): stated, web, documented, tested, production.
+
+## Key Commands
+
+- \`wheat init\` — bootstrap a research sprint
+- \`wheat compile\` — validate and compile claims
+- \`wheat status\` — sprint health dashboard
+- \`wheat search <query>\` — search claims
+- \`wheat add-claim\` — add a new claim
+- \`wheat resolve <id>\` — resolve a conflicting claim
+`;
+
+  if (fs.existsSync(agentsPath)) {
+    const existing = fs.readFileSync(agentsPath, "utf8");
+    if (existing.includes("# Wheat Research Sprint")) {
+      console.log(
+        "  \x1b[34m-\x1b[0m AGENTS.md              (wheat section already present)"
+      );
+      return;
+    }
+    // Append wheat section
+    fs.appendFileSync(agentsPath, "\n" + section);
+    console.log(
+      "  \x1b[32m+\x1b[0m AGENTS.md              (appended wheat section)"
+    );
+  } else {
+    fs.writeFileSync(agentsPath, section);
+    console.log(
+      "  \x1b[32m+\x1b[0m AGENTS.md              (universal AI instructions)"
+    );
+  }
+}
+
 // ─── Main ────────────────────────────────────────────────────────────────────
 
 export async function run(dir, args) {
@@ -357,7 +439,26 @@ export async function run(dir, args) {
 
   let meta;
 
-  if (flags.headless || flags["non-interactive"]) {
+  if (flags.auto) {
+    // ── Auto mode — question only, smart defaults for everything else ──
+    if (!flags.question) {
+      console.error("  wheat: no question provided");
+      process.exit(1);
+    }
+    meta = {
+      question: flags.question,
+      audience: flags.audience
+        ? flags.audience.split(",").map((s) => s.trim())
+        : DEFAULTS.audience,
+      constraints: flags.constraints
+        ? flags.constraints
+            .split(";")
+            .map((s) => s.trim())
+            .filter(Boolean)
+        : DEFAULTS.constraints,
+      doneCriteria: flags.done || DEFAULTS.doneCriteria,
+    };
+  } else if (flags.headless || flags["non-interactive"]) {
     // ── Headless mode — all flags required ──
     const missing = [];
     if (!flags.question) missing.push("--question");
@@ -481,12 +582,18 @@ export async function run(dir, args) {
   fs.writeFileSync(claudePath, claudeMd);
   console.log("  \x1b[32m+\x1b[0m CLAUDE.md");
 
-  // .claude/commands/
+  // .claude/commands/wheat/
   const copied = copyCommands(dir);
   console.log(
-    `  \x1b[32m+\x1b[0m .claude/commands/ (${copied} commands installed)`
+    `  \x1b[32m+\x1b[0m .claude/commands/wheat/ (${copied} commands installed)`
   );
 
+  // .mcp.json (Claude Code MCP auto-discovery)
+  writeMcpJson(dir);
+
+  // AGENTS.md (universal AI instructions)
+  writeAgentsMd(dir, meta);
+
   // Create output directories
   const dirs = ["output", "research", "prototypes", "evidence"];
   for (const d of dirs) {
@@ -510,7 +617,7 @@ export async function run(dir, args) {
         constraints: meta.constraints.length,
         done_criteria: meta.doneCriteria || null,
         claims_seeded: claims.claims.length,
-        files_created: ["claims.json", "CLAUDE.md", ".claude/commands/"],
+        files_created: ["claims.json", "CLAUDE.md", ".claude/commands/wheat/", ".mcp.json", "AGENTS.md"],
         dir,
       })
     );
@@ -518,6 +625,33 @@ export async function run(dir, args) {
   }
 
   console.log();
+  // Auto mode: compact output, no tutorial
+  if (flags.auto) {
+    const mode = outputMode();
+    if (mode === "quiet") {
+      return;
+    } else if (mode === "json") {
+      console.log(JSON.stringify({
+        question: meta.question,
+        audience: meta.audience,
+        claims: claims.claims.length,
+        dir,
+      }));
+      return;
+    } else {
+      console.log();
+      console.log(`  \x1b[1m\x1b[33mwheat\x1b[0m — sprint created`);
+      console.log(`  ${meta.question}`);
+      console.log(`  ${claims.claims.length} constraint(s) seeded`);
+      try {
+        const hint = maybeHint({ claims: claims.claims }, { context: "init" });
+        if (hint) process.stderr.write(hint + "\n");
+      } catch { /* non-critical */ }
+      console.log();
+      return;
+    }
+  }
+
   console.log("  ─────────────────────────────────────────");
   console.log(`  \x1b[1m\x1b[33mSprint ready.\x1b[0m`);
   console.log();
@@ -528,7 +662,9 @@ export async function run(dir, args) {
   console.log("  Created:");
   console.log("    claims.json           Your evidence database");
   console.log("    CLAUDE.md             AI assistant configuration");
-  console.log("    .claude/commands/     18 slash commands for Claude Code");
+  console.log("    .claude/commands/wheat/  slash commands for Claude Code");
+  console.log("    .mcp.json             Claude Code MCP auto-discovery");
+  console.log("    AGENTS.md             Universal AI instructions");
   console.log("    output/               Where compiled artifacts land");
   console.log();
   console.log("  Next steps:");
@@ -539,5 +675,9 @@ export async function run(dir, args) {
   );
   console.log();
   console.log("  Trust the process. The evidence will compound.");
+  try {
+    const hint = maybeHint({ claims: claims.claims }, { context: "init" });
+    if (hint) process.stderr.write(hint + "\n");
+  } catch { /* non-critical */ }
   console.log();
 }

package/lib/update.js

@@ -1,8 +1,8 @@
 /**
- * wheat update — Copy/update slash commands to .claude/commands/
+ * wheat update — Copy/update slash commands to .claude/commands/wheat/
  *
  * Copies command templates from the installed package into the user's
- * .claude/commands/ directory. Existing files can be overwritten with --force.
+ * .claude/commands/wheat/ directory. Existing files can be overwritten with --force.
  *
  * Zero npm dependencies.
  */
@@ -21,7 +21,7 @@ function packageRoot() {
 export async function run(dir, args) {
   const force = args.includes("--force");
   const srcDir = path.join(packageRoot(), "templates", "commands");
-  const destDir = path.join(dir, ".claude", "commands");
+  const destDir = path.join(dir, ".claude", "commands", "wheat");
 
   fs.mkdirSync(destDir, { recursive: true });
 
@@ -34,7 +34,7 @@ export async function run(dir, args) {
   }
 
   console.log();
-  console.log(`  Updating .claude/commands/ (${files.length} commands)`);
+  console.log(`  Updating .claude/commands/wheat/ (${files.length} commands)`);
   console.log();
 
   let updated = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grainulation/wheat",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Research-driven development framework — structured claims, compiled evidence, deterministic output",
   "license": "MIT",
   "author": "grainulation contributors",