askshepherd 0.1.25

package/README.md

@@ -0,0 +1,179 @@
+# AskShepherd
+
+Customer-facing raw sync onboarding for Shepherd.
+
+## Coding Agent One-liner
+
+Give this to a coding agent:
+
+```sh
+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.
+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:
+
+```sh
+npx -y askshepherd@latest agent --api https://<non-prod-brain-api>
+```
+
+## Human Terminal One-liner
+
+```sh
+npx -y askshepherd@latest
+```
+
+The command:
+
+- runs Shepherd WorkOS login/signup first
+- asks for name, organization, and an optional local Messages handle
+- creates or reuses the Shepherd customer account from the WorkOS-authenticated email
+- creates or reuses the organization, including case-insensitive and close-name matches
+- only reuses an existing organization when the authenticated account is allowed to join it
+- prints Google Workspace domain-wide delegation setup for a Workspace super admin
+- opens Slack authorization
+- opens the Granola desktop app to Settings -> Connectors -> API keys
+- collects the Granola API key after opening the Granola screen when Granola is enabled
+- asks the user to grant or confirm macOS Full Disk Access before local Messages sync
+- checks local Messages access and keeps prompting in interactive onboarding until Full Disk Access works
+- opens a minimal searchable local webpage with contact/group names and only syncs the chats selected by the user
+- sets up local macOS Messages raw sync with a background LaunchAgent scoped to the selected chats
+- starts raw polling/backfill for connected sources
+- asks the customer-facing production cloud to schedule downstream processing; wiki ingestion, memory artifacts, and document summaries run in separate brain services, not in the local CLI
+
+The command does not expose Railway, database, Redis, or internal service details to the user.
+
+## Customer MCP Login
+
+After raw onboarding creates the Shepherd customer account, customers can
+install the production MCP from the saved local onboarding session:
+
+```sh
+npx -y askshepherd@latest mcp-login
+```
+
+The command first verifies `~/.shepherd/raw-onboarding-agent.json` against the
+production API and mints an MCP token for that exact customer account. If the
+local onboarding session is unavailable, it falls back to Shepherd WorkOS auth
+and still links only an existing onboarded customer account. It writes
+`~/.shepherd/mcp.json` and asks where Shepherd MCP should be accessible. It can
+install the MCP into:
+
+- Codex CLI/app
+- Claude Code
+- Cursor IDE and Cursor Agent
+
+The saved MCP state includes:
+
+- `mcpUrl`: `https://brain-api-customer-facing.up.railway.app/mcp`
+- `token`: bearer token for MCP clients
+- `account`: linked customer account metadata
+- `authSource`: `local_onboarding` or `workos`
+- `localAuth`: raw onboarding state reference when local auth was used
+
+Use `--json` when an agent or setup script needs machine-readable endpoint and
+header details.
+
+Install an existing MCP login later:
+
+```sh
+npx -y askshepherd@latest mcp-install
+```
+
+`mcp-install` refreshes missing or near-expired MCP auth from the saved local
+onboarding session before configuring clients, so already-onboarded customers
+do not need to sign in again. Local Messages continues syncing through its
+LaunchAgent and cloud sources continue syncing through production pollers; MCP
+auth only controls read access to that customer's production memory/wiki data.
+
+Install targets can also be provided non-interactively:
+
+```sh
+npx -y askshepherd@latest mcp-login --install codex,claude,cursor
+npx -y askshepherd@latest mcp-install --install all
+```
+
+After install, customers can immediately ask their coding agent questions like:
+
+```text
+Use Shepherd to catch me up on what the team discussed yesterday.
+Use Shepherd to search Slack, Gmail, Messages, Granola, and the wiki for launch blockers.
+Use Shepherd to find the last meeting where we discussed the enterprise pilot.
+Use Shepherd to summarize open follow-ups from this week's memory.
+```
+
+The production MCP gives onboarded customers the same read/QA behavior that made
+the internal Shepherd MCP useful: summary-first answers, wiki search/read, and
+source drill-in. Internal local sync, admin, replay, write/delete, and cache
+maintenance tools are not exposed to customers.
+
+## Google Workspace Domain-wide Delegation
+
+Business customers connect Google Workspace once as an admin. Employees do not create service accounts and do not each complete Google OAuth for Gmail, Calendar, Drive, Docs, Sheets, Slides, Tasks, or Contacts.
+
+Customer-side setup in Google Admin Console:
+
+```text
+App name: Shepherd
+Service account email: gigabrain-delegation@shepherd-gigabrain.iam.gserviceaccount.com
+Domain-wide delegation OAuth Client ID: 118363960386741325727
+```
+
+The customer super admin authorizes that Client ID with the scopes printed by the CLI. The customer does not upload service account JSON; Shepherd stores its private service account JSON server-side in `GOOGLE_WORKSPACE_SERVICE_ACCOUNT_KEY_JSON` and requests delegated tokens with `sub=<allowed_employee_email>`.
+
+Shepherd must still enforce selected users and groups internally before impersonating or polling employee emails.
+
+## Options
+
+```sh
+--email <email>            Advanced: must match the WorkOS-authenticated email
+--name <name>              Full name
+--org <name>               Organization name
+--granola-api-key <key>    Granola API key
+--messages-handle <value>  Messages phone number or Apple ID email
+--messages-chat-ids <ids>  Comma-separated chat IDs selected from messages-chats
+--messages-backfill-days   Local Messages backfill window, default all selected chat history
+--api <url>                Advanced: Shepherd API URL. Use only for non-production experiments or local/staging testing.
+--no-google                Skip Google Workspace (Gmail/Drive/Docs/Calendar/Sheets/Slides/Tasks/Contacts)
+--no-slack                 Skip Slack
+--no-granola               Skip Granola
+--no-open-granola          Do not open the Granola API key screen
+--no-messages              Skip local Messages
+--no-open                  Print auth URLs instead of opening the browser
+```
+
+## Messages Chat Selection
+
+Local Messages sync on macOS needs Full Disk Access. During onboarding, Shepherd asks the user to grant or confirm Full Disk Access for:
+
+- the app running onboarding, such as Terminal, iTerm, Claude Code, or Codex
+- the Node.js binary used by the background LaunchAgent
+
+The Messages selector validates access to `~/Library/Messages/chat.db`, opens System Settings -> Privacy & Security -> Full Disk Access if access is missing, and keeps checking in interactive onboarding until access works. Background sync install also checks that launchd can start the Messages agent. Contacts permission may also appear when Shepherd resolves local contact names for selected chats.
+
+Open the local Messages chat selector:
+
+```sh
+npx -y askshepherd@latest messages-chats
+```
+
+Use `--json` for machine-readable chat metadata, or `--text` for a terminal list.
+
+The browser selector displays the first page of recent chats and lets the user search contacts or groups loaded from local Messages.
+
+Pass the selected chat IDs when finishing onboarding:
+
+```sh
+npx -y askshepherd@latest agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<id1>,<id2>"
+```
+
+## Granola API Keys
+
+If Granola does not land on the API keys page, run:
+
+```sh
+npx -y askshepherd@latest granola-api-keys
+```