askshepherd 0.1.32 → 0.1.37

package/README.md

@@ -18,7 +18,7 @@ claude "Run Shepherd customer onboarding with: npx -y askshepherd@latest agent.
 ```
 
 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, 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. 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.
+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:
@@ -47,12 +47,40 @@ 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
 
 The command does not expose Railway, database, Redis, or internal service details to the user.
 
+## Check Sync Status
+
+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
+```
+
+It reports the saved Shepherd account, connected cloud sources, downstream
+processing state, and local background sync health for Messages and Coding
+Sessions.
+
+## Set Up Coding Agent Sessions
+
+Use this when the user asks "Help me set up coding agent sessions":
+
+```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
+```
+
+The coding agent should ask for consent before enabling this source. The local
+collector syncs redacted Codex and Claude Code summaries, not full transcripts.
+
 ## Customer MCP Login
 
 After raw onboarding creates the Shepherd customer account, customers can
@@ -81,6 +109,13 @@ The saved MCP state includes:
 - `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` and `shepherd_setup_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.
+
 Use `--json` when an agent or setup script needs machine-readable endpoint and
 header details.
 
@@ -110,6 +145,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 +177,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 +185,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 +227,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 +237,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 +245,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: