askshepherd 0.1.42 → 0.1.44

package/README.md

@@ -1,274 +1,125 @@
-# AskShepherd Support CLI
+# AskShepherd CLI
 
-Support/developer CLI for Shepherd production onboarding and MCP. Normal
-customers should use the Shepherd macOS app; the app bundles this same engine
-and installs background sync/MCP without asking customers to run `npx`.
-
-The npm package is `askshepherd`. The installed binary also exposes `shepherd`,
-and the support CLI uses the package name:
-
-```sh
-claude "Run Shepherd customer onboarding with: npx -y askshepherd@latest agent. Ask me the onboarding questions, do not infer answers from local context, and continue through the follow-up commands it prints. After onboarding completes, ask whether to install Shepherd MCP for me into Codex, Claude Code, Cursor, any subset, or none; if I choose any, run npx -y askshepherd@latest mcp-login --install <targets>." --dangerously-skip-permissions
-```
-
-## Claude Code Onboarding Command
-
-Give this to Claude Code:
-
-```sh
-claude "Run Shepherd customer onboarding with: npx -y askshepherd@latest agent. Ask me the onboarding questions, do not infer answers from local context, and continue through the follow-up commands it prints. After onboarding completes, ask whether to install Shepherd MCP for me into Codex, Claude Code, Cursor, any subset, or none; if I choose any, run npx -y askshepherd@latest mcp-login --install <targets>." --dangerously-skip-permissions
-```
-
-The underlying `askshepherd agent` command defaults to the customer-facing production Shepherd cloud. In coding-agent shells, it gives the agent the public onboarding checklist and follow-up commands. In a normal interactive terminal, it does not print the checklist; it points the user to the direct terminal onboarding flow instead.
-Claude Code onboarding asks short selection questions first: existing/new org, sources to connect, Messages skip/provide-handle, and whether to sync Coding Sessions from Codex/Claude Code. 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. If Coding Sessions is selected, onboarding installs a local LaunchAgent that syncs redacted session summaries, not full raw transcripts. Account creation/relinking always starts with Shepherd WorkOS auth. After onboarding completes, the agent asks whether to install Shepherd MCP for the signed-in customer into Codex, Claude Code, Cursor, any subset, or none.
-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
-claude "Run Shepherd customer onboarding with: npx -y askshepherd@latest agent --api https://<non-prod-brain-api>. Ask me the onboarding questions, do not infer answers from local context, and continue through the follow-up commands it prints. After onboarding completes, ask whether to install Shepherd MCP for me into Codex, Claude Code, Cursor, any subset, or none; if I choose any, run npx -y askshepherd@latest mcp-login --install <targets> --api https://<non-prod-brain-api>." --dangerously-skip-permissions
-```
-
-## Human Terminal One-liner
+Self-serve Shepherd onboarding and memory CLI.
 
 ```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, including contact-name hydration for observed conversations
-- optionally sets up local Codex/Claude Code coding-session summary sync with a background LaunchAgent
-- 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.
-
-## Check Sync Status
+If the Shepherd skill is already installed, give this one line to a coding agent:
 
-Use this when the user asks "Check what I've enabled for Shepherd?":
-
-```sh
-npx -y askshepherd@latest status
-npx -y askshepherd@latest status --json
+```text
+Use the Shepherd skill to onboard me to this repository before coding.
 ```
 
-It reports the saved Shepherd account, connected cloud sources, downstream
-processing state, and local background sync health for Messages and Coding
-Sessions.
+If the agent does not already have the skill, give it this bootstrap line:
 
-Agents must not inspect the user's folders or repositories to answer setup
-status. Do not run `ls`, `find`, `rg`, `grep`, `cat`, `Read`, `Glob`, or
-`Explore` against the user's home directory, repositories, `~/.codex`,
-`~/.claude`, or `~/.shepherd` for Shepherd setup. Use the npm status command
-above; it performs the bounded local checks.
-
-## Set Up Coding Agent Sessions
-
-Use this when the user asks "Help me set up coding agent sessions" or "Enable
-coding agent sessions locally for Shepherd":
-
-```sh
-npx -y askshepherd@latest agent --login
-npx -y askshepherd@latest agent --add-sources coding-sessions --name "<name>" --org "<organization>"
-npx -y askshepherd@latest agent --continue
-npx -y askshepherd@latest status
+```text
+Set up Shepherd for me: run `npx -y askshepherd@latest agent-setup`, follow its prompts, ask me before connecting each source, then verify with `npx -y askshepherd@latest status`, `npx -y askshepherd@latest shepherd_wiki_status`, and `npx -y askshepherd@latest tools --json`.
 ```
 
-The coding agent should ask for consent before enabling this source. The local
-collector syncs redacted Codex and Claude Code summaries, not full transcripts.
-The agent should run only the commands above and should not search the local
-filesystem for a Shepherd agent implementation.
-
-## Customer MCP Login
+The default command starts onboarding. It authenticates the Shepherd account,
+creates or selects the customer org, connects selected sources, starts backend
+processing, saves local state, and prepares CLI tool auth.
 
-After raw onboarding creates the Shepherd customer account, customers can
-install the production MCP from the saved local onboarding session:
+After install, use the `shepherd` command:
 
 ```sh
-npx -y askshepherd@latest mcp-login
+npx -y askshepherd@latest agent-setup
+shepherd login
+shepherd onboard
+shepherd continue
+shepherd status
+shepherd shepherd_wiki_status
+shepherd tools --json
+shepherd <tool_name> --args '<json_object>'
+shepherd skill
 ```
 
-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:
+## Onboarding
 
-- 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
-
-The installed MCP server is local npm first, remote brain second. For questions
-like "what do I have set up on Shepherd?", "is Shepherd syncing?", or "help me
-set up coding agent sessions", the MCP exposes local tools such as
-`shepherd_status`, `shepherd_setup_coding_sessions`, and
-`shepherd_enable_coding_sessions` that route agents to the local
-`askshepherd status` / add-source flow. Production memory and wiki tools remain
-remote Railway-backed tools for source recall and company-memory answers.
-Those local MCP tools are also the permission boundary: an MCP client should not
-use shell or file tools to inspect the user's folders or repositories for setup.
-
-Use `--json` when an agent or setup script needs machine-readable endpoint and
-header details.
-
-Install an existing MCP login later:
+One-line agent setup:
 
 ```sh
-npx -y askshepherd@latest mcp-install
+npx -y askshepherd@latest agent-setup
 ```
 
-`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:
+Interactive first run:
 
 ```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.
-Use Shepherd to tell me what coding agents already worked on in this repo.
-```
-
-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
+npx -y askshepherd@latest
 ```
 
-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
+Agent-led setup:
 
 ```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, or `all` to watch every current and future chat
---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
---coding-sessions          Opt in to local Codex/Claude Code session summary sync
---sources <list>           Exact sources to connect: google,slack,granola,messages,coding-sessions,all
---add-sources <list>       Same as --sources, named for second-time onboarding
---no-open                  Print auth URLs instead of opening the browser
+shepherd login
+shepherd onboard --name "<full_name>" --org "<organization>" --sources google,notion,slack,granola,messages,coding-sessions
+shepherd continue
+shepherd status
 ```
 
-## Coding Sessions
+`shepherd continue` resumes after browser auth, Google Workspace delegation,
+Granola key entry, Messages chat selection, or local sync setup.
+
+## Tool Calls
 
-Customers can add coding-session sync during first onboarding by selecting
-Coding Sessions or by passing:
+List tools:
 
 ```sh
-npx -y askshepherd@latest agent --sources coding-sessions --name "<name>" --org "<organization>"
+shepherd tools --json
 ```
 
-Already-onboarded customers can add it later:
+Call an exact Shepherd MCP tool:
 
 ```sh
-npx -y askshepherd@latest agent --add-sources coding-sessions --name "<name>" --org "<organization>"
+shepherd <tool_name> --args '<json_object>'
 ```
 
-The local collector reads Codex session JSONL under `~/.codex/sessions` and
-Claude Code JSONL under `~/.claude/projects`, redacts sensitive values locally,
-and uploads bounded summaries with repo, command, file, verification, and
-follow-up metadata. It does not upload full raw transcripts. In production,
-Shepherd writes a concise `building/index.md` recent-work ledger plus detailed
-session pages under `coding-sessions/` for MCP drill-in.
+The CLI dynamically lists/calls the same production MCP memory/wiki/evidence
+tools available to the authenticated customer, plus local setup/status tools.
+Do not pass `--env` for normal customer setup or tool calls; the default is the
+Production Customer `deploy` lane.
 
-Check local and production sync health:
+For authenticated `askshepherd.ai` accounts only, target another deployed
+environment for tool listing, tool execution, and backend data together:
 
 ```sh
-npx -y askshepherd@latest coding-sessions-status
-npx -y askshepherd@latest coding-sessions-status --json
+shepherd mcp-login --env canary --no-install
+shepherd tools --env canary --json
+shepherd <tool_name> --env customer-facing --args '<json_object>'
 ```
 
-## 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. The background agent reloads Contacts on startup, watches AddressBook changes when available, and runs a periodic fallback sync so renamed contacts can hydrate prior ingested Messages rows for that customer account.
-
-Open the local Messages chat selector:
+Check wiki readiness explicitly before memory/wiki answers when setup just
+finished or readiness is uncertain:
 
 ```sh
-npx -y askshepherd@latest messages-chats
+shepherd shepherd_wiki_status
 ```
 
-Use `--json` for machine-readable chat metadata, or `--text` for a terminal list.
+If it returns `status: "wiki_not_ready"`, agents should report progress/ETA and
+wait instead of answering from incomplete memory.
 
-The browser selector displays the first page of recent chats and lets the user search contacts or groups loaded from local Messages. It also has an explicit "Sync all current and future chats" option for users who want Shepherd to backfill every current local Messages chat and keep watching chats that appear later. Do not use this option by default; it is for explicit user approval.
+## Skill
 
-Pass the selected chat IDs when finishing onboarding:
+Print the bundled agent skill:
 
 ```sh
-npx -y askshepherd@latest agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<id1>,<id2>"
+shepherd skill
 ```
 
-Or, with explicit approval to sync all local Messages chats:
+Install it into Codex:
 
 ```sh
-npx -y askshepherd@latest agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids all
+shepherd skill --install codex
 ```
 
-## Granola API Keys
+The skill teaches agents how to onboard users, check setup and wiki readiness,
+use exact Shepherd tools, avoid local filesystem probing for Shepherd setup,
+and handle broad memory questions with iMessage-agent-style evidence behavior.
 
-If Granola does not land on the API keys page, run:
+## Runtime Internals
 
-```sh
-npx -y askshepherd@latest granola-api-keys
-```
+The package still ships the `shepherd-onboard` engine binary for local runtime
+entrypoints used by MCP clients, Messages sync, Coding Sessions sync, and the
+macOS app. The public user-facing CLI is `shepherd`.