askshepherd 0.1.31 → 0.1.36

package/README.md

@@ -6,25 +6,25 @@ The npm package is `askshepherd`. The installed binary also exposes `shepherd`,
 but the public one-liner uses the package name:
 
 ```sh
-npx -y askshepherd@latest agent
+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
 ```
 
-## Coding Agent One-liner
+## Claude Code Onboarding Command
 
-Give this to a coding agent:
+Give this to Claude Code:
 
 ```sh
-npx -y askshepherd@latest agent
+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 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.
-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.
+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
-npx -y askshepherd@latest agent --api https://<non-prod-brain-api>
+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
@@ -47,7 +47,8 @@ The command:
 - 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
+- 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
 
@@ -110,6 +111,7 @@ 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
@@ -141,7 +143,7 @@ Shepherd must still enforce selected users and groups internally before imperson
 --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-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)
@@ -149,9 +151,41 @@ Shepherd must still enforce selected users and groups internally before imperson
 --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
 ```
 
+## Coding Sessions
+
+Customers can add coding-session sync during first onboarding by selecting
+Coding Sessions or by passing:
+
+```sh
+npx -y askshepherd@latest agent --sources coding-sessions --name "<name>" --org "<organization>"
+```
+
+Already-onboarded customers can add it later:
+
+```sh
+npx -y askshepherd@latest agent --add-sources coding-sessions --name "<name>" --org "<organization>"
+```
+
+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.
+
+Check local and production sync health:
+
+```sh
+npx -y askshepherd@latest coding-sessions-status
+npx -y askshepherd@latest coding-sessions-status --json
+```
+
 ## 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:
@@ -159,7 +193,7 @@ Local Messages sync on macOS needs Full Disk Access. During onboarding, Shepherd
 - 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.
+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:
 
@@ -169,7 +203,7 @@ 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.
+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.
 
 Pass the selected chat IDs when finishing onboarding:
 
@@ -177,6 +211,12 @@ Pass the selected chat IDs when finishing onboarding:
 npx -y askshepherd@latest agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<id1>,<id2>"
 ```
 
+Or, with explicit approval to sync all local Messages chats:
+
+```sh
+npx -y askshepherd@latest agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids all
+```
+
 ## Granola API Keys
 
 If Granola does not land on the API keys page, run: