@forwardimpact/outpost 3.12.0 → 3.13.0

package/templates/.claude/skills/req-workday/scripts/parse-workday.mjs

@@ -2,8 +2,8 @@
 /**
  * Parse a Workday requisition export (.xlsx) and output structured JSON.
  *
- * Reads Sheet1 for requisition metadata and the "Candidates" sheet for
- * candidate data. Outputs a JSON object to stdout with:
+ * The script reads Sheet1 for requisition metadata. It reads the "Candidates"
+ * sheet for candidate data. It outputs a JSON object to stdout with:
  *   - requisition: { id, title, startDate, targetHireDate, location,
  *                     hiringManager, recruiter }
  *   - candidates:  [ { name, cleanName, stage, step, resumeFile, dateApplied,
@@ -54,20 +54,56 @@ try {
 const filePath = process.argv[2];
 const summaryMode = process.argv.includes("--summary");
 
-/** Read a sheet by number (1-indexed) or name, returning rows as arrays of strings. */
-async function readSheet(file, sheet) {
-  const rows = await readXlsxFile(file, { sheet });
+/**
+ * Read a workbook. Tolerate Workday's ZIP container.
+ *
+ * Workday exports .xlsx via Apache POI's streaming writer. That writer sets
+ * the ZIP "data descriptor" flag (bit 0x08) on every entry, so the sizes live
+ * in a trailer after each entry, not in the local header. read-excel-file's
+ * streaming unzipper trusts the (zeroed) local-header sizes, loses alignment,
+ * and throws `invalid signature: 0x…`. fflate reads the authoritative ZIP
+ * central directory, so on failure we re-pack into a clean container (sizes
+ * in the local headers, no data descriptors) and retry. Files that already
+ * parse take the original path unchanged.
+ */
+async function readWorkbook(path) {
+  try {
+    return await readXlsxFile(path);
+  } catch (err) {
+    let fflate;
+    try {
+      fflate = await import("fflate");
+    } catch {
+      throw err; // fflate unavailable — surface the original parse error
+    }
+    const { readFileSync } = await import("node:fs");
+    const raw = readFileSync(path);
+    const normalized = Buffer.from(
+      fflate.zipSync(fflate.unzipSync(new Uint8Array(raw))),
+    );
+    return await readXlsxFile(normalized);
+  }
+}
+
+// read-excel-file v9 returns the whole workbook as [{ sheet, data }] —
+// read it once and index sheets from that.
+const workbook = await readWorkbook(filePath);
+const sheetNames = workbook.map((s) => s.sheet);
+
+/** Read a sheet by number (1-indexed) or name. Rows are arrays of strings. */
+function readSheet(_file, sheet) {
+  const entry =
+    typeof sheet === "number"
+      ? workbook[sheet - 1]
+      : workbook.find((s) => s.sheet === sheet);
+  const rows = entry ? entry.data : [];
   // Normalise null cells to empty strings to match previous behaviour
   return rows.map((row) => row.map((cell) => (cell == null ? "" : cell)));
 }
 
-// Get sheet names to find the candidates sheet
-const sheets = await readXlsxFile(filePath, { getSheets: true });
-const sheetNames = sheets.map((s) => s.name);
-
 // --- Sheet 1: Requisition metadata ---
 
-const sheet1Rows = await readSheet(filePath, 1);
+const sheet1Rows = readSheet(filePath, 1);
 
 /** Extract the requisition ID and title from the header row. */
 function parseReqHeader(headerText) {
@@ -120,9 +156,9 @@ const requisition = {
 const candSheetName =
   sheetNames.find((n) => n.toLowerCase() === "candidates") ||
   sheetNames[Math.min(2, sheetNames.length - 1)];
-const candRows = await readSheet(filePath, candSheetName);
+const candRows = readSheet(filePath, candSheetName);
 
-// Find the header row dynamically — look for a row containing "Stage"
+// Find the header row dynamically. Look for a row that contains "Stage".
 // Old format: row 3 (index 2). New format: row 8 (index 7).
 let HEADER_ROW = 2;
 for (let i = 0; i < Math.min(15, candRows.length); i++) {
@@ -134,8 +170,9 @@ for (let i = 0; i < Math.min(15, candRows.length); i++) {
 const DATA_START = HEADER_ROW + 1;
 
 // --- Build header-driven column index map ---
-// Column layout varies between Workday exports (extra columns like "Jobs Applied to"
-// or "Referred by" shift indices). Map by header name to be resilient.
+// Column layout varies between Workday exports. Extra columns like "Jobs
+// Applied to" or "Referred by" shift the indices. Map by header name to be
+// resilient.
 
 const headerRow = candRows[HEADER_ROW] || [];
 const colMap = {};
@@ -174,16 +211,17 @@ for (let i = 0; i < headerRow.length; i++) {
   const hdr = String(headerRow[i]).trim().toLowerCase();
   const field = HEADER_ALIASES[hdr];
   if (field) {
-    // "Job Application" appears twice (cols A and B) — always take the latest
-    // occurrence so we end up with the second one (index 1) which has the name
+    // "Job Application" appears twice (cols A and B). Always take the latest
+    // occurrence. We then end up with the second one (index 1), which has the
+    // name.
     colMap[field] = i;
   }
 }
 
-// Fallback: if "name" wasn't mapped, use index 0 (new format) or 1 (old format)
+// Fallback: with no "name" column, use index 0 (new format) or 1 (old format)
 if (colMap.name === undefined) colMap.name = 1;
-// In new format there's only one "Job Application" column (index 0) — the
-// "always take latest" logic already handles this correctly.
+// In the new format there is only one "Job Application" column (index 0).
+// The "always take latest" logic already handles this correctly.
 
 /** Get a cell value by field name, with fallback to empty string. */
 function col(row, field) {
@@ -192,38 +230,78 @@ function col(row, field) {
   return row[idx] ?? "";
 }
 
+// Any character outside the Latin script blocks (Basic Latin + Latin-1
+// Supplement + Latin Extended-A/B + Latin Extended Additional). Accented Latin
+// (é, ñ, ø, ç, Vietnamese, …) stays; Greek, Cyrillic, CJK, Arabic, Hebrew,
+// etc. count as native-alphabet text to drop.
+const NON_LATIN = /[^\u0020-\u024F\u1E00-\u1EFF]/;
+const HAS_LATIN_LETTER = /[A-Za-z\u00C0-\u024F\u1E00-\u1EFF]/;
+
 /**
- * Clean a candidate name by stripping annotations like (Prior Worker),
- * (Internal), etc. Returns { cleanName, internalExternal }.
+ * Clean a candidate name into the canonical Latin name.
+ *
+ * Workday encodes several things in the name cell as parentheticals:
+ *   - Employment annotations: `(Internal)`, `(Prior Worker)`, `(External)`.
+ *   - A native-alphabet transliteration of the name, e.g.
+ *     `Nikos Papadopoulos (ΝΙΚΟΣ ΠΑΠΑΔΟΠΟΥΛΟΣ)` or `Wei Zhang （张伟）`.
+ * A name may carry both, in either paren style. Normalise on the Latin name:
+ * strip every trailing parenthetical (classify employment ones into
+ * `internalExternal`, discard native-alphabet ones), then drop any residual
+ * non-Latin-script tokens. Returns { cleanName, internalExternal }.
  */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: annotation peel loop classifies employment vs transliteration cases
 function parseName(raw) {
-  const name = String(raw).trim();
+  // Normalise full-width parens （） to ASCII so both styles strip uniformly.
+  let name = String(raw).replace(/（/g, "(").replace(/）/g, ")").trim();
   if (!name) return { cleanName: "", internalExternal: "" };
 
-  const match = name.match(/^(.+?)\s*\(([^)]+)\)\s*$/);
-  if (match) {
-    const annotation = match[2].trim();
-    let ie;
-    if (/prior\s*worker/i.test(annotation)) ie = "External (Prior Worker)";
-    else if (/internal/i.test(annotation)) ie = "Internal";
-    else ie = annotation;
-    return { cleanName: match[1].trim(), internalExternal: ie };
+  let internalExternal = "";
+  // Repeatedly peel a trailing parenthetical group (allowing one level of
+  // nesting so `(External (Prior Worker))` is captured whole).
+  const trailing = /\s*\(([^()]*(?:\([^()]*\)[^()]*)*)\)\s*$/;
+  let m;
+  while ((m = name.match(trailing)) !== null) {
+    const annotation = m[1].trim();
+    if (/prior\s*worker/i.test(annotation)) {
+      if (!internalExternal) internalExternal = "External (Prior Worker)";
+    } else if (/internal/i.test(annotation)) {
+      if (!internalExternal) internalExternal = "Internal";
+    } else if (/external/i.test(annotation)) {
+      if (!internalExternal) internalExternal = "External";
+    } else if (NON_LATIN.test(annotation)) {
+      // Native-alphabet transliteration of the name — drop, no IE signal.
+    } else if (!internalExternal && annotation) {
+      // Unknown Latin annotation — preserve prior behaviour (first one wins).
+      internalExternal = annotation;
+    }
+    name = name.slice(0, name.length - m[0].length).trim();
   }
-  return { cleanName: name, internalExternal: "" };
+
+  // Drop any residual whole-word tokens that are purely non-Latin script
+  // (e.g. a native name appended without parentheses). Keep Latin tokens
+  // and pure punctuation/digits.
+  name = name
+    .split(/\s+/)
+    .filter((tok) => HAS_LATIN_LETTER.test(tok) || !NON_LATIN.test(tok))
+    .join(" ")
+    .replace(/\s{2,}/g, " ")
+    .trim();
+
+  return { cleanName: name, internalExternal };
 }
 
-/** Detect source-based internal/external when name annotation is absent. */
+/** Detect source-based internal/external when the name annotation is absent. */
 function inferInternalExternal(source, nameAnnotation) {
   if (nameAnnotation) return nameAnnotation;
   if (/internal/i.test(source)) return "Internal";
   return "External";
 }
 
-/** Format a date value (may be Date object or string). */
+/** Format a date value (it may be a Date object or a string). */
 function fmtDate(val) {
   if (!val) return "";
   if (val instanceof Date) {
-    // Use local date parts to avoid UTC offset shifting the day
+    // Use local date parts so a UTC offset does not shift the day
     const y = val.getFullYear();
     const m = String(val.getMonth() + 1).padStart(2, "0");
     const d = String(val.getDate()).padStart(2, "0");
@@ -253,7 +331,7 @@ for (let i = DATA_START; i < candRows.length; i++) {
   const rawName = String(col(row, "name") || "").trim();
   const stage = String(col(row, "stage") || "").trim();
 
-  // Skip empty rows; stop at stage-summary rows (name present but no stage)
+  // Skip empty rows. Stop at stage-summary rows (name present but no stage)
   if (!rawName) continue;
   if (!stage) break;
 

package/templates/.claude/skills/send-chat/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: send-chat
-description: Send messages to people via chat platforms (e.g. Microsoft Teams, Slack) using browser automation. Resolves people by name using the knowledge graph, drafts messages for approval, and sends via the web app. Use when the user asks to message, ping, or chat with someone.
+description: Send messages to people through chat platforms (e.g. Microsoft Teams, Slack) with browser automation. Resolves people by name from the knowledge graph, drafts messages for approval, and sends them through the web app. Use when the user asks to message, ping, or chat with someone.
 compatibility:
   requires:
     - browser-automation
@@ -8,10 +8,13 @@ compatibility:
 
 # Send Chat
 
-Send chat messages to people using browser automation against a web-based chat
-platform (Microsoft Teams, Slack, or similar). Resolves recipients by name from
-the knowledge graph so the user can say "message Sarah about the standup"
-without needing exact display names.
+Write tier: `0-Draft` (sending is an export)
+Frontmatter: none
+
+Send chat messages to people with browser automation against a web-based chat
+platform (Microsoft Teams, Slack, or similar). This skill resolves recipients by
+name from the knowledge graph. The user can say "message Sarah about the
+standup" without an exact display name.
 
 ## Trigger
 
@@ -19,61 +22,62 @@ Run when the user asks to:
 
 - Send a message on Teams / Slack / chat
 - Ping / chat / DM someone
-- Follow up with someone via chat
+- Follow up with someone through chat
 - Send a message about a topic
 
 ## Prerequisites
 
-- Chat platform web app open and authenticated in the browser
+- The web app for the chat platform, open and authenticated in the browser
 - Browser automation available (e.g. Chrome MCP, Playwright)
 - Knowledge base populated with people notes
 
 ## Critical: Always Look Up Context First
 
-**BEFORE messaging anyone, you MUST look up the person in the knowledge base.**
+**BEFORE you message anyone, you MUST look up the person in the knowledge
+base.**
 
 When the user mentions ANY person:
 
 1. **STOP** — Do not open the chat platform yet
-2. **SEARCH** — Look them up: `rg -l "{name}" Knowledge/People/`
+2. **SEARCH** — Look them up: `rg -l "{name}" 3-Team/People/`
 3. **READ** — Read their note to understand context, role, recent interactions
-4. **UNDERSTAND** — Know who they are, what you've been working on together
+4. **UNDERSTAND** — Know who they are and what you work on together
 5. **THEN PROCEED** — Only now compose the message and use browser automation
 
-This context is essential for:
+You need this context to:
 
-- Finding the right person if the name is ambiguous
-- Drafting an appropriate message if the user gave a loose prompt
-- Knowing the person's role and relationship for tone
+- Find the right person if the name is ambiguous
+- Draft an appropriate message if the user gave a loose prompt
+- Know the person's role and relationship for tone
 
-## Resolving People
+## Resolve People
 
-The user will refer to people by first name, last name, or nickname. Resolve to
-a full name using the knowledge graph:
+The user will refer to people by first name, last name, or nickname. Resolve the
+reference to a full name with the knowledge graph:
 
 ```bash
 # Find person by partial name
-rg -l -i "{name}" Knowledge/People/
+rg -l -i "{name}" 3-Team/People/
 
 # If ambiguous, read candidates to disambiguate
-cat "Knowledge/People/{Candidate}.md"
+cat "3-Team/People/{Candidate}.md"
 ```
 
-**If ambiguous** (multiple matches), ask the user which person they mean — list
+**If ambiguous** (multiple matches), ask the user which person they mean. List
 the matches with roles/orgs to help them pick.
 
-**If no match**, tell the user you don't have this person in the knowledge base
-and ask for their full name as it appears in the chat platform.
+**If no match**, tell the user this person is not in the knowledge base. Ask for
+their full name as it appears in the chat platform.
 
-## Composing the Message
+## Compose the Message
 
-**Every message MUST be drafted as a text file first.** This ensures the user
-can review and edit the exact message before it's sent.
+**You MUST draft every message as a text file first.** This makes sure the user
+can review and edit the exact message before you send it.
 
 ### Draft Workflow
 
 1. **Compose the message** based on context and user intent.
-2. **Write it to a draft file** at `Drafts/chat-{recipient-slug}-{date}.md`
+2. **Write it to a draft file** at `0-Draft/chat-{recipient-slug}-{date}.md`
    - `{recipient-slug}` = lowercase, hyphenated full name (e.g. `sarah-chen`)
    - `{date}` = ISO date (e.g. `2026-02-19`)
 3. **Show the user the draft** — display the file path and contents.
@@ -92,32 +96,33 @@ Date: {YYYY-MM-DD}
 {message body}
 ```
 
-The message body (everything below the `---` separator) is what gets pasted into
+The message body is everything below the `---` separator. Paste that body into
 the chat.
 
 **Message guidelines:**
 
-- Match the user's usual tone — casual for peers, professional for leadership
-- Keep it concise — chat is informal, not email
+- Match the user's usual tone. Use casual tone for peers and professional tone
+  for leadership
+- Keep it concise. Chat is informal. It is not email
 - Reference specific context naturally (project names, recent decisions)
-- If the user provides exact wording, use it verbatim
+- If the user gives exact words, use them verbatim
 - If the user said "ping {name}" without detail, ask what they want to say
-- Draft one message based on context — don't offer multiple options
+- Draft one message based on context. Do not offer multiple options
 - **Keep messages on a single line with no formatting.** No line breaks, no
   markdown. Use inline separators (e.g. `•`, `—`) to keep structure. Multi-line
-  formatting is unreliable via browser automation.
+  formatting is unreliable through browser automation.
 
 ## Browser Automation Flow
 
-Once the user has approved the draft, send it as a **single submission** — paste
-the entire message at once rather than typing line by line.
+After the user approves the draft, send it as a **single submission**. Paste the
+entire message at once. Do not type it line by line.
 
 ### Step 1: Identify the Chat Platform
 
 Check which platform is available:
 
-- Look for an open tab matching the configured chat URL
-- If no tab is open, ask the user which platform to use and navigate to it
+- Look for an open tab that matches the configured chat URL
+- If no tab is open, ask the user which platform to use. Then navigate to it
 
 ### Step 2: Open a Chat with the Recipient
 
@@ -126,7 +131,7 @@ Check which platform is available:
 3. Wait for search results to populate (take a screenshot to verify)
 4. Click the correct person from the results
 
-If the person doesn't appear in search, inform the user — they may not be in the
+If the person does not appear in search, tell the user. They may not be in the
 same organization.
 
 ### Step 3: Send the Approved Message
@@ -137,34 +142,33 @@ same organization.
 4. Press Enter or click Send
 5. Take a screenshot to confirm the message was sent
 
-### Step 4: Update Knowledge Graph (Optional)
-
-If the message is substantive (not just "hey" or "thanks"), note the interaction
-on the person's knowledge note:
+### Step 4: Keep the Draft as the Record
 
-```markdown
-- {YYYY-MM-DD}: Messaged on {Platform} re: {topic}
-```
+Do not write the interaction to the person's note. This skill writes only to
+`0-Draft/`. The chat sync (`sync-teams`) and `extract-entities` record the
+interaction when the messages sync.
 
 ## Error Handling
 
 - **Platform not loaded / auth required:** Tell the user to sign in first, then
   retry
-- **Person not found in search:** Report back — they may be external or using a
-  different display name. Ask the user for the exact name
+- **Person not found in search:** Report back. They may be external, or they may
+  use a different display name. Ask the user for the exact name
 - **Chat already open:** If a chat with this person is already visible, use it
   directly
-- **UI not as expected:** Take a screenshot and describe what you see. Don't
+- **UI not as expected:** Take a screenshot and describe what you see. Do not
   click blindly
 
 ## Constraints
 
-- **Always confirm before sending.** Never send a message without explicit user
-  approval — this is a hard requirement
-- **One message at a time.** Don't batch-send to multiple people without
-  confirming each one
+- **Always confirm before you send.** Never send a message without explicit user
+  approval. This is a hard requirement
+- **One message at a time.** Do not batch-send to multiple people. Confirm each
+  one first
 - **No file attachments.** This skill handles text messages only
-- **No group chats.** Targets 1:1 chats only
-- **No message deletion or editing.** Once sent, it's sent
+- **No group chats.** This skill targets 1:1 chats only
+- **No message deletion or editing.** After you send a message, you cannot
+  delete it or edit it
 - **Respect ethics rules.** Never send messages that contain personal judgments,
-  gossip, or sensitive information per the knowledge base ethics policy
+  gossip, or sensitive information. The ethics policy of the knowledge base
+  requires this

package/templates/.claude/skills/sync-apple-calendar/SKILL.md

@@ -6,9 +6,12 @@ compatibility: Requires macOS with Apple Calendar configured and Full Disk Acces
 
 # Sync Apple Calendar
 
+Write tier: none (cache only)
+Frontmatter: none
+
 Sync calendar events from the macOS Calendar app's local SQLite database into
-`~/.cache/fit/outpost/apple_calendar/` as JSON files. This is an automated data
-pipeline skill — it ingests raw calendar data that other skills (like
+`~/.cache/fit/outpost/apple_calendar/` as JSON files. This is an automated skill
+in the data pipeline. It ingests raw calendar data that other skills (like
 `extract-entities` and `meeting-prep`) consume downstream.
 
 ## Trigger
@@ -38,8 +41,8 @@ their calendar.
 ## Implementation
 
 Run the sync as a single Node.js script with embedded SQLite. This avoids N+1
-process invocations (one per event for attendees) and handles all data
-transformation in one pass:
+process invocations (one per event for attendees). It also transforms all the
+data in one pass:
 
 ```text
 node scripts/sync.mjs [--days N]
@@ -60,8 +63,9 @@ The script:
 ## Database Schema
 
 See [references/SCHEMA.md](references/SCHEMA.md) for the complete Apple Calendar
-SQLite schema including table structures, column names, and important caveats
-(e.g., Identity uses `address` not `email`, Participant has no `display_name`).
+SQLite schema. It gives the table structures, the column names, and the
+important caveats. For example, Identity uses `address` and has no `email`
+column. Participant has no `display_name`.
 
 ## Output Format
 
@@ -98,10 +102,10 @@ Each `{event_id}.json` file:
 - Database locked → wait 2 seconds, retry once
 - Skip events with no summary (likely cancelled or placeholder)
 
-## Querying Events
+## Query Events
 
-After syncing, use the query script to filter events by date or time window.
-**Agents should use this script instead of writing bespoke calendar parsers.**
+After the sync, use the query script to filter events by date or time window.
+**Agents should use this script. Do not write bespoke calendar parsers.**
 
 ```text
 node scripts/query.mjs [options]
@@ -109,13 +113,13 @@ node scripts/query.mjs [options]
 
 ### Time filters (combinable)
 
-| Flag                            | Description                                               |
-| ------------------------------- | --------------------------------------------------------- |
-| `--today`                       | Events starting today (default if no filter given)        |
-| `--tomorrow`                    | Events starting tomorrow                                  |
-| `--upcoming 2h`                 | Events starting within interval (e.g., `2h`, `30m`, `1d`) |
-| `--date 2026-03-09`             | Events on a specific date                                 |
-| `--range 2026-03-09 2026-03-11` | Events between two dates (inclusive)                      |
+| Flag                            | Description                                                     |
+| ------------------------------- | --------------------------------------------------------------- |
+| `--today`                       | Events that start today (default if no filter given)            |
+| `--tomorrow`                    | Events that start tomorrow                                      |
+| `--upcoming 2h`                 | Events that start within the interval (e.g., `2h`, `30m`, `1d`) |
+| `--date 2026-03-09`             | Events on a specific date                                       |
+| `--range 2026-03-09 2026-03-11` | Events between two dates (inclusive)                            |
 
 ### Output options
 
@@ -144,6 +148,6 @@ node scripts/query.mjs --today --json | node -e "process.stdin.on('data',d=>cons
 ## Constraints
 
 - Open database read-only (`readOnly: true`)
-- This sync is stateless — always queries the current sliding window
-- All-day events may have null end times — use start date as end date
-- All-day events have timezone `_float` — omit timezone from output
+- This sync is stateless. It always queries the current sliding window
+- All-day events may have null end times. Use the start date as the end date
+- All-day events have timezone `_float`. Omit the timezone from the output

package/templates/.claude/skills/sync-apple-calendar/references/SCHEMA.md

@@ -19,7 +19,7 @@ column names (verified on macOS Sonoma+).
 | `organizer_id`   | INTEGER | FK → Identity.ROWID                                        |
 | `calendar_id`    | INTEGER | FK → Calendar.ROWID                                        |
 | `has_attendees`  | INTEGER | 1 = event has attendees                                    |
-| `conference_url` | TEXT    | Video call URL (often null — check description too)        |
+| `conference_url` | TEXT    | Video call URL (often null). Check description too         |
 | `entity_type`    | INTEGER | 2 = calendar event                                         |
 
 ## Identity (organizer info)
@@ -28,12 +28,12 @@ column names (verified on macOS Sonoma+).
 | -------------- | ---- | ------------------------------------------------------------- |
 | `display_name` | TEXT | Full name (e.g., `"Chen, Sarah"`)                             |
 | `address`      | TEXT | Email with `mailto:` prefix (e.g., `"mailto:sarah@acme.com"`) |
-| `first_name`   | TEXT | Usually null — `display_name` is the reliable field           |
-| `last_name`    | TEXT | Usually null — `display_name` is the reliable field           |
+| `first_name`   | TEXT | Usually null. `display_name` is the reliable field            |
+| `last_name`    | TEXT | Usually null. `display_name` is the reliable field            |
 
 **IMPORTANT:** Identity does NOT have an `email` column. Use `address` and strip
-the `mailto:` prefix. Use `display_name` for the name (not
-`first_name`/`last_name`, which are typically null).
+the `mailto:` prefix. Use `display_name` for the name. Do not use `first_name`
+or `last_name`. They are typically null.
 
 ## Participant (attendees and organizer)
 
@@ -49,8 +49,8 @@ the `mailto:` prefix. Use `display_name` for the name (not
 | `is_self`     | INTEGER | 1 = this is the calendar owner                     |
 
 **IMPORTANT:** Participant does NOT have `display_name`, `first_name`, or
-`last_name` columns. To get the attendee's name, JOIN with Identity via
-`identity_id`. There is NO `Attendee` table — only use `Participant`.
+`last_name` columns. To get the attendee's name, JOIN with Identity through
+`identity_id`. There is NO `Attendee` table. Use `Participant` only.
 
 ### EKParticipantStatus mapping
 

package/templates/.claude/skills/sync-apple-calendar/scripts/query.mjs

@@ -3,8 +3,8 @@
  * Query synced Apple Calendar events by date/time window.
  *
  * Reads JSON event files from ~/.cache/fit/outpost/apple_calendar/ and filters
- * them by date range, time window, or upcoming interval. Designed to eliminate
- * the need for agents to write bespoke calendar-parsing scripts.
+ * them by date range, time window, or upcoming interval. Agents then do not
+ * need to write their own calendar-parsing scripts.
  *
  * Usage:
  *   node scripts/query.mjs --today                  Today's events
@@ -31,9 +31,9 @@ Usage:
   node scripts/query.mjs [options]
 
 Time filters (combinable):
-  --today                 Events starting today
-  --tomorrow              Events starting tomorrow
-  --upcoming <interval>   Events starting within interval (e.g., 2h, 30m, 1d)
+  --today                 Events that start today
+  --tomorrow              Events that start tomorrow
+  --upcoming <interval>   Events that start within interval (e.g., 2h, 30m, 1d)
   --date <YYYY-MM-DD>     Events on a specific date
   --range <start> <end>   Events between two dates (inclusive)
 
@@ -42,7 +42,7 @@ Output options:
   --include-all-day       Include all-day events (excluded by default)
   --no-attendees          Omit attendee names from output
 
-Defaults to --today if no time filter is specified.`);
+Defaults to --today when you give no time filter.`);
   process.exit(0);
 }
 

package/templates/.claude/skills/sync-apple-calendar/scripts/sync.mjs

@@ -2,10 +2,11 @@
 /**
  * Sync Apple Calendar events to ~/.cache/fit/outpost/apple_calendar/ as JSON.
  *
- * Queries the macOS Calendar SQLite database (via node:sqlite) for events in a
- * sliding window — N days in the past through 14 days in the future. Writes one
- * JSON file per event and removes files for events that fall outside the window.
- * Attendee details (name, email, status, role) are batch-fetched and included.
+ * Queries the macOS Calendar SQLite database (through node:sqlite) for events
+ * in a sliding window. The window runs from N days in the past to 14 days in
+ * the future. Writes one JSON file per event. Removes the files for events
+ * outside the window. Fetches attendee details (name, email, status, role) in
+ * one batch and includes them.
  *
  * Requires macOS with Calendar app configured and Full Disk Access granted.
  */
@@ -74,7 +75,7 @@ function findDb() {
   const db = DB_PATHS.find((p) => existsSync(p));
   if (!db) {
     console.error(
-      "Error: Apple Calendar database not found. Is Calendar configured?",
+      "Error: Apple Calendar database not found. Check that Calendar is configured.",
     );
     process.exit(1);
   }
@@ -82,7 +83,7 @@ function findDb() {
 }
 
 /**
- * Open the database in read-only mode with retry on lock.
+ * Open the database in read-only mode. Retry once if the database is locked.
  * @param {string} dbPath
  * @returns {import("node:sqlite").DatabaseSync}
  */
@@ -114,7 +115,7 @@ function query(db, sql) {
 }
 
 /**
- * Convert Core Data timestamp to ISO 8601.
+ * Convert a Core Data timestamp to ISO 8601.
  * @param {number | null} ts - Seconds since 2001-01-01
  * @param {string | null} tzName
  * @returns {string | null}
@@ -138,7 +139,7 @@ function coredataToIso(ts, tzName) {
 }
 
 /**
- * Get UTC offset string for a timezone at a given instant.
+ * Get the UTC offset string for a timezone at a given instant.
  * @param {Date} dt
  * @param {string} tzName
  * @returns {string} e.g. "+02:00" or "-05:00"