askshepherd 0.1.28 → 0.1.29

package/README.md

@@ -17,8 +17,8 @@ Give this to a coding agent:
 npx -y askshepherd@latest agent
 ```
 
-The command defaults to the customer-facing production Shepherd cloud. It prints the exact prompt the agent should follow, then the exact follow-up commands to open Shepherd WorkOS login/signup, guide Google Workspace Admin Console delegation, open source auth for non-Google sources, open Granola's API key page, finalize, start cloud raw polling/backfills, request downstream production processing, and install local Messages sync.
-The agent prompt tells coding agents to ask short selection questions first: existing/new org, sources to connect, and Messages skip/provide-handle. If Messages is selected, the agent runs `messages-chats`, opens a minimal searchable local webpage, and has the user select which contacts/groups to sync. Account creation/relinking always starts with Shepherd WorkOS auth.
+The command defaults to the customer-facing production Shepherd cloud. In coding-agent shells, it gives the agent the onboarding contract and follow-up commands. In a normal interactive terminal, it does not print the agent contract; it points the user to the direct terminal onboarding flow instead.
+Coding-agent onboarding asks short selection questions first: existing/new org, sources to connect, and Messages skip/provide-handle. If Messages is selected, the agent runs `messages-chats`, opens a minimal searchable local webpage, and has the user select which contacts/groups to sync. Account creation/relinking always starts with Shepherd WorkOS auth.
 Existing-organization joins are verified from Shepherd login and company email domain; the typed org name is not trusted by itself.
 
 For experiments, pass a separate non-production API explicitly:

package/bin/shepherd-onboard.js

@@ -11,7 +11,7 @@ import { fileURLToPath } from "node:url";
 const DEFAULT_API_URL = "https://brain-api-customer-facing.up.railway.app";
 const PACKAGE_NAME = "askshepherd";
 const PACKAGE_SPEC = `${PACKAGE_NAME}@latest`;
-const PACKAGE_VERSION = "0.1.28";
+const PACKAGE_VERSION = "0.1.29";
 const MCP_SERVER_NAME = "shepherd";
 const PACKAGE_DIR = dirname(dirname(fileURLToPath(import.meta.url)));
 const DEFAULT_AGENT_STATE_PATH = join(homedir(), ".shepherd", "raw-onboarding-agent.json");
@@ -283,7 +283,11 @@ async function runAgentOnboarding() {
   );
 
   if (!wantsStart) {
-    printAgentContract();
+    if (shouldPrintAgentContract()) {
+      printAgentContract();
+    } else {
+      printAgentTerminalHandoff();
+    }
     return;
   }
   if (!workosAuth) {
@@ -1053,19 +1057,19 @@ function parseArgs(argv) {
 
 function printHelp(which) {
   if (which === "agent") {
-    console.log(`Shepherd coding-agent onboarding
+    console.log(`Shepherd coding-agent setup
 
 Usage:
   npx -y ${PACKAGE_NAME}@latest agent
   npx -y ${PACKAGE_NAME}@latest agent --login
   npx -y ${PACKAGE_NAME}@latest agent --name <name> --org <organization>
-  npx -y ${PACKAGE_NAME}@latest messages-chats
   npx -y ${PACKAGE_NAME}@latest agent --continue --granola-api-key <key> --messages-handle <value> --messages-chat-ids <ids>
   npx -y ${PACKAGE_NAME}@latest agent --status
+  npx -y ${PACKAGE_NAME}@latest messages-chats
   npx -y ${PACKAGE_NAME}@latest granola-api-keys
 
-Agent mode is non-interactive. It prints the user prompt and exact commands a coding agent should run.
-Always run --login first. WorkOS login/signup creates or relinks the Shepherd account before source setup; Google Workspace uses Admin Console domain-wide delegation, not WorkOS OAuth.
+The bare agent command is intended for coding-agent shells. For direct terminal setup, run:
+  npx -y ${PACKAGE_NAME}@latest
 `);
     return;
   }
@@ -1209,6 +1213,26 @@ Options:
 `);
 }
 
+function shouldPrintAgentContract() {
+  return Boolean(args.prompt || args.json || !isInteractiveTerminal());
+}
+
+function isInteractiveTerminal() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+function printAgentTerminalHandoff() {
+  console.log(`Shepherd raw sync setup
+
+This command is meant for coding-agent shells. To set up Shepherd directly in this terminal, run:
+  ${agentCommand()}
+
+If a coding agent asked you to onboard Shepherd, ask the agent to run:
+  ${agentCommand()} agent
+
+No source setup has started.`);
+}
+
 function printAgentContract() {
   const command = agentCommand();
   const payload = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "askshepherd",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "description": "Customer-facing Shepherd production onboarding and MCP CLI",
   "type": "module",
   "bin": {